Codespaces pt 4 (#689)

* feat: Add ngrok to flake so we can run ngrok binary in the devenv This allow for testing things like bindings within the development environment Signed-off-by: Jonathan Stacks <jonstacks@users.noreply.github.com> * feat: Add recommended extensions for devenv Signed-off-by: Jonathan Stacks <jonstacks@users.noreply.github.com> * feat: Add hostRequirements for devcontainer Signed-off-by: Jonathan Stacks <jonstacks@users.noreply.github.com> * feat: Add devhelp message to the nix flake Signed-off-by: Jonathan Stacks <jonstacks@users.noreply.github.com> * docs: Add documentation for the Codespaces developer environment --------- Signed-off-by: Jonathan Stacks <jonstacks@users.noreply.github.com>
2026-05-17 16:50:44 +00:00 · 2025-10-21 00:13:17 -05:00
parent 7336222fcb
commit 1fc35be6a6
7 changed files with 139 additions and 10 deletions
@@ -12,5 +12,10 @@
    },
    "./features/direnv-hook": {}
  },
+  "hostRequirements": {
+    "cpus": 4,
+    "memory": "16gb",
+    "storage": "32gb"
+  },
  "postCreateCommand": ".devcontainer/post-create.sh"
 }
@@ -0,0 +1,22 @@
+---
+name: Devenv Issue
+description: Report an issue with the development environment setup
+labels: ["area/devenv", "needs-triage"]
+body:
+- type: markdown
+  attributes:
+    value: |
+      Thanks for taking the time to report an issue with the Codespaces devenv!
+
+      We really appreciate the community efforts to improve the ngrok Kubernetes Operator.
+- type: textarea
+  attributes:
+    label: Description
+    description: A description of the issue
+- type: textarea
+  attributes:
+    label: Related issues
+    description: Are there any related issues?
+- type: markdown
+  attributes:
+    value: "Thank you for help in improving the ngrok Kubernetes Operator!"
@@ -23,7 +23,6 @@ coverage/
 *.swp
 *.swo
 *~
-.vscode
 .DS_Store

 e2e-fixtures/*/config*.yaml
@@ -0,0 +1,8 @@
+{
+    "recommendations": [
+        "bbenoist.nix",
+        "golang.go",
+        "ms-kubernetes-tools.vscode-kubernetes-tools",
+        "ms-vscode.makefile-tools",
+    ]
+}
@@ -2,13 +2,64 @@

 While this project is new and we don't have full contribution guidelines yet, we are open to any PRs and or issues raised. Feel free to reach out to us on slack as well!

+- [In the weeds architecture](#in-the-weeds-architecture)
+- [Local Development](#local-development)
+    - [Codespaces](#codespaces)
+    - [Non-Codespaces](#non-codespaces)
+        - [Prerequisites](#prerequisites)
+        - [Bootstrap repo-managed tools](#bootstrap-repo-managed-tools)
+        - [Create a local kind cluster](#create-a-local-kind-cluster)
+        - [Setup](#setup)
+        - [Using the E2E Fixtures](#using-the-e2e-fixtures)
+        - [E2E Tests](#e2e-tests)
+- [Releasing](#releasing)
+
 ## In the weeds architecture

 Have a look at the architecture guide on the internal workings of the ingress controller [here](./architecture.md)

 ## Local Development

-### Prerequisites
+### Codespaces
+
+The ngrok-operator project includes a devcontainer configuration for GitHub Codespaces. The goal is to make contributing as easy as possible and to codify our development environment. If you open the repository in a codespace, all of the necessary tools will be pre-installed and available.
+
+#### Set up Codespaces Secrets
+
+The following environment variable secrets are required to develop and test the ngrok-operator in Codespaces:
+
+* NGROK_API_KEY
+* NGROK_AUTHTOKEN
+
+You can create a ngrok API key in the ngrok Dashboard [here](https://dashboard.ngrok.com).
+You can find your ngrok auth token [here](https://dashboard.ngrok.com/get-started/your-authtoken).
+
+Follow [this guide](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces) to add these secrets
+to your GitHub Account and allow them to be used with this repo.
+
+When you are done, your [Codespaces Settings](https://github.com/settings/codespaces) should look something like this:
+
+![Codespaces Settings](./codespaces-secrets.png)
+
+Make sure that the ngrok-operator repository, or your fork of it, is selected in the Visible Repositories list.
+
+#### Start a Codespace
+
+Once you've set up your Codespaces secrets, you can create a new Codespace for the repository by clicking the following button:
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/ngrok/ngrok-operator)
+
+This should open a new Codespace with all the necessary tools installed and print a welcome message in the terminal
+explaining how to get started.
+
+#### Issues
+
+If you run into any issues with the Codespace setup, please open an issue in the repository using the
+devenv template so we can address it.
+
+### Non-Codespaces
+
+#### Prerequisites

 - [Docker Desktop](https://www.docker.com/products/docker-desktop/) (or any other container runtime that can run kind)
 - [Go](https://go.dev/dl/)
@@ -16,7 +67,7 @@ Have a look at the architecture guide on the internal workings of the ingress co

 If you prefer declarative environments, the repository includes a `.envrc` that works with [nix-direnv](https://github.com/nix-community/nix-direnv); run `direnv allow` after installing it and the tooling above will be provided automatically.

-### Bootstrap repo-managed tools
+#### Bootstrap repo-managed tools

 ```sh
 make bootstrap-tools
@@ -24,7 +75,7 @@ make bootstrap-tools

 This downloads the Go-based utilities the repo expects (kind, Helm, controller-gen, envtest, golangci-lint) into `./bin`. Make targets always invoke those exact binaries, so you don’t need to add `./bin` to your global `$PATH`; stick with the provided make commands. Install `helm`/`kubectl` separately if you want them available for manual use.

-### Create a local kind cluster
+#### Create a local kind cluster

 By default we create a cluster named `ngrok-operator` and our CI and Makefiles are configured to load images into this specific cluster.

@@ -36,7 +87,7 @@ This installs kind (if necessary) and provisions the cluster. Use `make kind-del

 > NOTE: `kind create cluster` requires Docker to be running. If you prefer a different Kubernetes distribution (e.g. minikube), ensure your `kubectl` context points at it and that locally-built images are visible to the cluster before deploying.

-### Setup
+#### Setup

 ```sh
 export NGROK_API_KEY=<YOUR Secret API KEY>
@@ -50,7 +101,7 @@ make deploy

 > Note: `make deploy*` loads the freshly built controller image into your kind cluster and sets a `redeployTimestamp` pod annotation each run, so Docker must be running locally and the controller pods always pick up the new image.

-### Using the E2E Fixtures
+#### Using the E2E Fixtures

 Several examples are provided in the [`e2e-fixtures` folder](https://github.com/ngrok/ngrok-operator/tree/main/e2e-fixtures). To use an example, make a copy of the included `EXAMPLE*config.yaml` in the same directory, like this:

@@ -62,7 +113,7 @@ Then, you need to update the `value` field in that new file.
 You can then apply the given example via `kubectl apply -k e2e-fixtures/<example in question>`, i.e.
 `kubectl apply -k e2e-fixtures/hello-world-ingress`.

-### E2E Tests
+#### E2E Tests

 If you run the script `./scripts/e2e.sh` it will run the e2e tests against your current kubectl context. These tests tear down any existing ingress controller and examples, re-installs them, and then runs the tests. It creates a set of different ingresses and verifies that they all behave as expected

@@ -3,7 +3,6 @@
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };
-
  outputs =
    {
      self,
@@ -13,7 +12,47 @@
    (flake-utils.lib.eachDefaultSystem (
      system:
      let
-        pkgs = nixpkgs.legacyPackages.${system};
+        pkgs = import nixpkgs {
+          inherit system;
+          config = {
+            allowUnfreePredicate = pkg: pkg.pname == "ngrok";
+          };
+        };
+
+        mkScript = name: text: let
+          script = pkgs.writeShellScriptBin name text;
+        in script;
+
+        scripts = [
+          (mkScript "devhelp" ''
+cat <<'EOF'
+
+Welcome to the ngrok-operator development environment!
+
+Please make sure you have the following environment variables set:
+
+  NGROK_API_KEY      - Your ngrok API key
+  NGROK_AUTHTOKEN    - Your ngrok authtoken
+
+If you are using GitHub Codespaces, a kind cluster should
+already be running. You can verify this by running:
+
+  kind get clusters
+
+Common commands:
+  make build          - Build the operator
+  make test           - Run tests
+  make lint           - Run linters
+  make deploy         - Deploy to the kind cluster
+
+For more information, see the development documentation in
+
+  ./docs/developer-guide/README.md
+
+You can also run "devhelp" at any time to see this message again.
+EOF
+          '')
+        ];
      in
      {
        devShells.default = pkgs.mkShell {
@@ -28,15 +67,20 @@
            kubectl
            kubernetes-helm
            kyverno-chainsaw
+            ngrok
            nixfmt-rfc-style
            tilt
            yq
-          ];
+          ] ++ scripts;

          CGO_ENABLED = "0";
          # GitHub Codespaces sets GOROOT in /etc/environment. However, we are managing
          # go via nix, so we need to unset it to avoid conflicts. See also: https://dave.cheney.net/2013/06/14/you-dont-need-to-set-goroot-really
          GOROOT = "";
+
+          shellHook = ''
+            devhelp
+          '';
        };
      }
    ));