@dooer/dooer-test-env 1.11.2 → 1.13.0

package/docs/getting-access.md

@@ -0,0 +1,175 @@
+# Getting access (new developer)
+
+`dooer-test-env` reads the staging cluster to build its compose file, log in to the image registries and
+fetch the BankID cert. That needs two things, in this order:
+
+1. **VPN** — the cluster API is not reachable from the open internet.
+2. **kubectl access** — a client certificate identifying you to the cluster.
+
+**Both come from an admin**: they create your VPN tunnel and your cluster credential, and send you two
+files — a WireGuard `.conf` and a `kubeconfig`. You install them and check they work. See
+[issuing-access.md](./issuing-access.md) for their side.
+
+---
+
+## 0. Prerequisites
+
+```bash
+brew install wireguard-tools kubernetes-cli
+```
+
+`openssl` ships with macOS. Check everything is there:
+
+```bash
+wg --version && kubectl version --client && openssl version
+```
+
+---
+
+## 1. VPN
+
+**Your admin creates the tunnel and sends you a `.conf` file.** You do not create it yourself and you do
+not need a Robo10 token for this — ask an admin, who follows
+[issuing-access.md § 1](./issuing-access.md#1-vpn--create-and-hand-over-a-tunnel).
+
+The file they send you contains a **private key**. Treat it like a password: keep it out of chat, tickets
+and git, install it, and delete the copy they sent you.
+
+### 1a. Install the config
+
+`wg-quick` takes the interface name from the **filename**, so the name you pick here is the name you use in
+every later command. Check first what is already there — **do not overwrite an existing tunnel**:
+
+```bash
+ls /opt/homebrew/etc/wireguard/
+```
+
+Then install it (using `roboten` as the interface name):
+
+```bash
+sudo mkdir -p /opt/homebrew/etc/wireguard
+sudo cp ~/Downloads/<the-file-they-sent>.conf /opt/homebrew/etc/wireguard/roboten.conf
+sudo chmod 600 /opt/homebrew/etc/wireguard/roboten.conf
+rm ~/Downloads/<the-file-they-sent>.conf     # the copy under /opt/homebrew is the one wg-quick reads
+```
+
+### 1b. Connect, disconnect, restart
+
+```bash
+sudo wg-quick up roboten       # connect
+sudo wg-quick down roboten     # disconnect
+sudo wg-quick down roboten && sudo wg-quick up roboten   # restart (after a config change or sleep/wake)
+
+sudo wg show                   # status: handshake time + transfer counters
+```
+
+`wg-quick` is not a daemon: the tunnel does **not** survive a reboot, and after a laptop sleep it sometimes
+needs the restart above. If `wg show` reports a `latest handshake` older than a couple of minutes while you
+are actively using the cluster, restart it.
+
+To start it automatically at boot:
+
+```bash
+sudo brew services start wireguard-tools   # starts wg0 by default
+```
+
+That service is hard-wired to the `wg0` interface, so it only helps if you named your file `wg0.conf`.
+
+### 1c. Verify the VPN works
+
+```bash
+sudo wg show                                    # expect a recent "latest handshake"
+nc -vz k8s.roboten-infra.com 64430              # expect: succeeded / open
+```
+
+If `nc` hangs or is refused, the tunnel is not carrying traffic — restart it (1b). Until this passes, no
+amount of kubectl configuration will help.
+
+> The tunnel routes the cluster network (including the API server) through WireGuard. If you already have
+> another VPN claiming those ranges, they will fight over the routes — bring only one up at a time.
+
+---
+
+## 2. kubectl access
+
+**Your admin sends you a ready-made `kubeconfig` file.** You do not generate keys or assemble anything —
+they create the credential and hand it over
+([issuing-access.md § 2](./issuing-access.md#2-kubectl--create-their-credential)).
+
+Like the VPN config, that file contains a **private key**. Same handling: install it, then delete the copy
+they sent you.
+
+### 2a. Install it
+
+**If you have no other clusters** — simplest, just put it in place:
+
+```bash
+mkdir -p ~/.kube
+cp ~/Downloads/<yourname>.kubeconfig ~/.kube/config
+chmod 600 ~/.kube/config
+rm ~/Downloads/<yourname>.kubeconfig
+```
+
+**If you already use kubectl for something else**, merge instead of overwriting:
+
+```bash
+cp ~/.kube/config ~/.kube/config.backup            # always back up first
+KUBECONFIG=~/.kube/config:~/Downloads/<yourname>.kubeconfig \
+  kubectl config view --flatten > /tmp/merged && mv /tmp/merged ~/.kube/config
+chmod 600 ~/.kube/config
+rm ~/Downloads/<yourname>.kubeconfig
+```
+
+Then select the context (the admin will tell you its name, `<firstname>-admin@kubernetes`):
+
+```bash
+kubectl config get-contexts
+kubectl config use-context <firstname>-admin@kubernetes
+```
+
+### 2b. Verify
+
+With the VPN up:
+
+```bash
+kubectl auth whoami
+# Username  <firstname>-admin
+# Groups    [system:authenticated]
+
+kubectl get pods -n dooer-staging | head -3
+kubectl get pods -n dooer-production | head -3
+```
+
+Then the two checks `dooer-test-env` actually depends on:
+
+```bash
+kubectl auth can-i get secrets -n dooer-staging     # yes — registry pull secrets + BankID cert
+kubectl get svc dooer-database -n dooer-staging     # the database service the base-DB build reads
+```
+
+All of those must succeed before `dooer-test-env setup` will work.
+
+---
+
+## 3. You are done
+
+```bash
+npx @dooer/dooer-test-env@latest setup
+```
+
+`setup` re-checks all of the above and tells you exactly which piece is missing if something is wrong.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause |
+| --- | --- |
+| `dial tcp … i/o timeout` from kubectl | VPN is down — `sudo wg show`, then restart it (1b) |
+| `nc` to the API server hangs | Tunnel is up but not carrying traffic; restart it |
+| `error: You must be logged in to the server (Unauthorized)` | The certificate in your kubeconfig is expired or unknown to the cluster — ask for a re-issue |
+| `Error from server (Forbidden)` | You *are* authenticated; your user has no permissions bound yet — ask the admin to complete their § 2e (bind permissions) |
+| `wg-quick: 'roboten' already exists` | The interface is already up — `sudo wg-quick down roboten` first |
+
+Certificates are issued for **one year**. When yours expires, ask your admin for a new kubeconfig and
+repeat section 2 — your permissions stay in place, so they only have to re-issue the credential.

package/docs/issuing-access.md

@@ -0,0 +1,271 @@
+# Issuing access (admin)
+
+The other side of [getting-access.md](./getting-access.md). Two independent things:
+
+| | Who does it | What you do |
+| --- | --- | --- |
+| **VPN tunnel** | you | create it and send them the config |
+| **kubectl credential** | you | create the certificate, bind permissions, send a kubeconfig |
+
+You need a Robo10 token (§1a), `kubectl` with cluster-admin (`system:masters`), and your own VPN up.
+
+---
+
+## 1. VPN — create and hand over a tunnel
+
+You create the tunnel and send the developer its config. They do not need a Robo10 token, which matters:
+a brand-new joiner often has no working login yet, and the VPN API generates the keypair **server-side**
+anyway — the config comes back with the private key in it either way, so there is no custody advantage to
+making them do it.
+
+### 1a. Get a Robo10 token (yours)
+
+Opens a browser — log in with **your `@robo10.com` account**:
+
+```bash
+TOKEN="$(go run github.com/strehle/cmdline-openid-client/openid-client@latest \
+  -issuer https://oidc-provider-backend.api.staging.roboten-dev.com \
+  -client_id ro_authentication_cl_id \
+  -port 34466 | awk '/===/ { if (start) nextfile; start = 1; next } start { print }' | jq -r .access_token)"
+
+[ -n "$TOKEN" ] && echo "token acquired" || echo "no token — did the browser login complete?"
+```
+
+Needs `go` and `jq` (`brew install go jq`). Keep using **this same terminal**: `$TOKEN` lives only in this
+shell, and everything below needs it.
+
+<details>
+<summary>Alternative if the Go client will not run</summary>
+
+1. Open <https://chat.roboten.com> and log in.
+2. DevTools → **Application** → **Storage → Cookies**.
+3. Copy the value of the `x-op-token` cookie.
+4. In your terminal: `TOKEN=<the-cookie-value>`
+</details>
+
+### 1b. Create their tunnel
+
+Name it after the person (and their machine if they need more than one) so the list stays readable:
+
+```bash
+NAME="Firstname Lastname"
+curl -sS -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d "{ \"name\": \"$NAME\" }" \
+  https://vpn.api.staging.roboten-dev.com/v1/vpn-tunnels
+```
+
+The response contains the tunnel's **id**. To find it again later, list them (1d).
+
+### 1c. Download the config and hand it over
+
+```bash
+ID=<the id from the previous step>
+curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
+  https://vpn.api.staging.roboten-dev.com/v1/vpn-tunnels/$ID/actions/get-config \
+  > ~/Downloads/$NAME.conf
+```
+
+> **This file contains a private key.** Send it over a channel you would send a password over — a shared
+> vault entry or an expiring secure link — not email, Slack or a ticket. Tell them to install it and delete
+> the copy you sent, and delete your own copy once they confirm.
+
+Then point them at [getting-access.md § 1](./getting-access.md#1-vpn).
+
+One tunnel per person per machine: two devices sharing one config will fight over the session, so create a
+second tunnel rather than re-sending the first.
+
+### 1d. List tunnels
+
+```bash
+curl -sS -H "Authorization: Bearer $TOKEN" https://vpn.api.staging.roboten-dev.com/v1/vpn-tunnels
+```
+
+### 1e. Revoke a tunnel
+
+`DELETE` is not in the VPN service's own docs, but it works (verified 2026-09-04 — returns `204` and the
+tunnel disappears from the list):
+
+```bash
+curl -sS -X DELETE -H "Authorization: Bearer $TOKEN" \
+  https://vpn.api.staging.roboten-dev.com/v1/vpn-tunnels/$ID
+```
+
+That invalidates the tunnel server-side, so it is the real off-switch for VPN access when someone leaves —
+do it *and* revoke their kubectl permissions (§3).
+
+---
+
+## 2. kubectl — create their credential
+
+The cluster authenticates users with **x509 client certificates** signed by the cluster CA. The username is
+the certificate's **Common Name (CN)**; RBAC is bound to that string.
+
+You do all of it and hand over a finished `kubeconfig`.
+
+> Everything below was verified end to end against the live cluster (2026-09-04) with a throwaway
+> `guidetest-admin`: the resulting kubeconfig read `dooer-production` and `dooer-staging`, including
+> secrets. The test user was then removed.
+
+```bash
+USER_NAME=<firstname>-admin        # becomes their cluster username
+WORKDIR=$(mktemp -d) && cd "$WORKDIR"
+```
+
+Work in a temp directory — it holds their private key until you hand it over, and you delete it at the end.
+
+### 2a. Generate their key and CSR
+
+```bash
+openssl genrsa -out "$USER_NAME.key" 2048
+openssl req -new -key "$USER_NAME.key" -out "$USER_NAME.csr" -subj "/CN=$USER_NAME"
+```
+
+### 2b. Submit it as a CertificateSigningRequest
+
+```bash
+cat <<EOF | kubectl apply -f -
+apiVersion: certificates.k8s.io/v1
+kind: CertificateSigningRequest
+metadata:
+  name: $USER_NAME
+spec:
+  request: $(base64 -i "$USER_NAME.csr" | tr -d '\n')
+  signerName: kubernetes.io/kube-apiserver-client
+  expirationSeconds: 31536000   # 1 year
+  usages:
+  - client auth
+EOF
+```
+
+If the name already exists (a renewal), delete the old object first:
+`kubectl delete csr "$USER_NAME" --ignore-not-found`.
+
+### 2c. Approve and extract the certificate
+
+```bash
+kubectl certificate approve "$USER_NAME"
+
+kubectl get csr "$USER_NAME" -o jsonpath='{.status.certificate}' | base64 -d > "$USER_NAME.crt"
+openssl x509 -in "$USER_NAME.crt" -noout -subject -issuer -dates
+```
+
+Expect `subject=CN=<firstname>-admin`, `issuer=CN=kubernetes`, and a one-year window.
+
+If `.status.certificate` is empty the signer has not run yet — wait a couple of seconds and repeat. If it
+stays empty, check `kubectl describe csr "$USER_NAME"`.
+
+### 2d. Extract the cluster CA
+
+```bash
+kubectl config view --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d > ca.crt
+```
+
+### 2e. Bind permissions
+
+This is what makes the certificate useful — without it they authenticate but can do nothing. These are the
+same five ClusterRoles the existing admins (`jimmy-admin`, `sam-admin`, `trajko-admin`) hold:
+
+```bash
+for r in admin gateway-creator namespace-service-role clusterissuer-admin network-admin; do
+  kubectl create clusterrolebinding "${r}-user-${USER_NAME}" --clusterrole="$r" --user="$USER_NAME"
+done
+```
+
+| ClusterRole | Grants |
+| --- | --- |
+| `admin` | full read/write inside namespaces (the built-in Kubernetes role) |
+| `gateway-creator` | Gateway API resources |
+| `namespace-service-role` | namespace-scoped service management |
+| `clusterissuer-admin` | cert-manager ClusterIssuers (cluster-scoped) |
+| `network-admin` | NetworkAttachmentDefinitions (Multus), cluster-wide |
+
+The declarative equivalent lives in
+`rosopr7102-roboten-hosting-services/clusterrole-admin.yaml`. Creating the bindings with `kubectl` as above
+is enough for the cluster, but that file is the record of who has access — **add the new user there and
+commit it**, or the next person reading it will get a false picture.
+
+On a renewal, skip this step: the bindings are attached to the username, not to the certificate.
+
+### 2f. Assemble the kubeconfig
+
+`--embed-certs=true` inlines the key and certificates, so the file you hand over is self-contained:
+
+```bash
+SERVER=https://k8s.roboten-infra.com:64430
+KC="$WORKDIR/$USER_NAME.kubeconfig"
+
+KUBECONFIG="$KC" kubectl config set-cluster kubernetes \
+  --server="$SERVER" --certificate-authority=ca.crt --embed-certs=true
+
+KUBECONFIG="$KC" kubectl config set-credentials "$USER_NAME" \
+  --client-certificate="$USER_NAME.crt" --client-key="$USER_NAME.key" --embed-certs=true
+
+KUBECONFIG="$KC" kubectl config set-context "$USER_NAME@kubernetes" \
+  --cluster=kubernetes --user="$USER_NAME"
+
+KUBECONFIG="$KC" kubectl config use-context "$USER_NAME@kubernetes"
+```
+
+### 2g. Verify it before handing it over
+
+Test the actual file, not just the RBAC — with your own VPN up:
+
+```bash
+KUBECONFIG="$KC" kubectl auth whoami                                  # Username: <firstname>-admin
+KUBECONFIG="$KC" kubectl get pods -n dooer-staging | head -3
+KUBECONFIG="$KC" kubectl get pods -n dooer-production | head -3
+KUBECONFIG="$KC" kubectl auth can-i get secrets -n dooer-staging      # yes
+```
+
+If `whoami` works but the reads say `Forbidden`, step 2e did not take.
+
+### 2h. Hand it over, then clean up
+
+> **The kubeconfig contains their private key.** Send it the same way as the VPN config — a shared vault
+> entry or an expiring secure link, never email, Slack or a ticket.
+
+Tell them the context name (`<firstname>-admin@kubernetes`) and point them at
+[getting-access.md § 2](./getting-access.md#2-kubectl-access).
+
+Once they confirm it works, destroy your copy — you are holding their key until you do:
+
+```bash
+rm -rf "$WORKDIR"
+```
+
+---
+
+## 3. Revoking access
+
+```bash
+for r in admin gateway-creator namespace-service-role clusterissuer-admin network-admin; do
+  kubectl delete clusterrolebinding "${r}-user-${USER_NAME}"
+done
+kubectl delete csr "$USER_NAME"     # tidiness only; the CSR object is just a record
+```
+
+Also remove them from `clusterrole-admin.yaml` and commit.
+
+> **A signed certificate cannot be revoked.** Kubernetes has no CRL or OCSP: until it expires, that
+> certificate still *authenticates* — deleting the bindings only removes what it is *allowed to do*, which
+> leaves the holder as an authenticated user with no permissions. That is the real control, and it is why
+> certificates are issued for one year rather than indefinitely. If a key is actually compromised, removing
+> the bindings is the immediate mitigation; rotating the cluster CA is the only complete one, and that
+> invalidates **everyone's** certificate at once — do not do it without planning the re-issue for all users.
+
+---
+
+## Renewals
+
+A certificate expiring is routine. Repeat **§2a–2d and 2f–2h** and send them a fresh kubeconfig; they
+re-run [getting-access.md § 2](./getting-access.md#2-kubectl-access).
+
+Skip **2e** — ClusterRoleBindings are bound to the username, not to the certificate, so they survive a
+re-issue untouched.
+
+Delete the old CSR object first, or the new one collides on the name:
+
+```bash
+kubectl delete csr "$USER_NAME" --ignore-not-found
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dooer/dooer-test-env",
-  "version": "1.11.2",
+  "version": "1.13.0",
   "description": "Run the whole Dooer backend locally (staging DB minus customers), copy/purge customers between environments, and shred — one CLI.",
   "license": "UNLICENSED",
   "repository": "Dooer/cli-dooer-test-env",
@@ -13,6 +13,7 @@
   "files": [
     "bin/",
     "lib/",
+    "docs/",
     "local-postgres/",
     "discovery-router/"
   ],

package/readme.md

@@ -12,11 +12,23 @@ See **[ENVIRONMENT-PLAN.md](./ENVIRONMENT-PLAN.md)** for the full design and rat
 npx @dooer/dooer-test-env <command>
 ```
 
+## First time here?
+
+`setup` needs **VPN access** and a **kubectl credential** for the cluster — the compose file, the registry
+logins and the BankID cert all come from there.
+
+- **[Getting access](./docs/getting-access.md)** — new developer: set up the VPN, get your kubectl
+  certificate, and verify both actually work.
+- **[Issuing access](./docs/issuing-access.md)** — admin: sign someone's certificate, bind their
+  permissions, and revoke them again.
+
+Already have both? Straight to the quick start.
+
 ## Quick start
 
 ```bash
 # 1. One-time: prereq checks, registry login, compose generation, BankID cert → keychain.
-#    Needs the VPN + kubectl access to dooer-staging.
+#    Needs the VPN + kubectl access to dooer-staging (see "First time here?" above).
 npx @dooer/dooer-test-env setup
 
 # 2. Bring the whole stack up (all staging services + frontends)
@@ -272,3 +284,5 @@ Inbound *input* validation always runs — this only affects response validation
 ## Prerequisites
 
 Docker (Desktop), `kubectl` with access to the `dooer-staging` namespace (VPN), and Node 18+.
+
+Don't have the VPN or a kubectl credential yet? → **[Getting access](./docs/getting-access.md)**.