@dooer/dooer-test-env 1.11.2 → 1.12.0

package/docs/getting-access.md

@@ -0,0 +1,239 @@
+# 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.
+
+The VPN part is self-service. The kubectl part needs an admin to sign your certificate — see
+[issuing-access.md](./issuing-access.md) for their side.
+
+---
+
+## 0. Prerequisites
+
+```bash
+brew install wireguard-tools go jq kubernetes-cli
+```
+
+`openssl` ships with macOS. Check everything is there:
+
+```bash
+wg --version && go version && jq --version && kubectl version --client && openssl version
+```
+
+---
+
+## 1. VPN
+
+### 1a. Get a Robo10 token
+
+The VPN API is authenticated with a Robo10 access token. This opens a browser — **log in with your
+`@robo10.com` email**.
+
+```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?"
+```
+
+Keep using **this same terminal** for the next steps: `$TOKEN` only exists in this shell.
+
+<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 your tunnel
+
+One tunnel per person per machine. Name it after yourself so admins can tell them apart:
+
+```bash
+NAME="$(whoami)-$(hostname -s)"
+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** — you need it next. To find it again later:
+
+```bash
+curl -sS -H "Authorization: Bearer $TOKEN" https://vpn.api.staging.roboten-dev.com/v1/vpn-tunnels
+```
+
+### 1c. Download the tunnel config
+
+```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 \
+  > ~/roboten.conf
+```
+
+> This file contains your **private key**. Treat it like a password: never commit it, never paste it into
+> chat or a ticket.
+
+### 1d. Install it
+
+`wg-quick` takes the interface name from the **filename**, so the name you choose here is the name you use
+in every later command. Pick something that will not collide with a tunnel you already have:
+
+```bash
+sudo mkdir -p /opt/homebrew/etc/wireguard
+sudo cp ~/roboten.conf /opt/homebrew/etc/wireguard/roboten.conf
+sudo chmod 600 /opt/homebrew/etc/wireguard/roboten.conf
+rm ~/roboten.conf          # the copy under /opt/homebrew is the one wg-quick reads
+```
+
+Check first whether that name is already taken — **do not overwrite someone else's tunnel**:
+
+```bash
+ls /opt/homebrew/etc/wireguard/
+```
+
+### 1e. 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 a 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`.
+
+### 1f. 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 (1e). Until this passes, no
+amount of kubectl configuration will help.
+
+---
+
+## 2. kubectl access
+
+Authentication is a **client certificate**. You generate the key and the signing request; only the request
+leaves your machine. Your private key never does.
+
+### 2a. Generate your key and CSR
+
+Use `<firstname>-admin` as the name — that string becomes your username in the cluster, and it is what the
+admin binds permissions to.
+
+```bash
+USER_NAME=<firstname>-admin
+mkdir -p ~/.kube/roboten && cd ~/.kube/roboten
+
+openssl genrsa -out "$USER_NAME.key" 2048
+openssl req -new -key "$USER_NAME.key" -out "$USER_NAME.csr" -subj "/CN=$USER_NAME"
+chmod 600 "$USER_NAME.key"
+```
+
+### 2b. Send the CSR to an admin
+
+Send **only** `<firstname>-admin.csr`. It is not secret — but the `.key` next to it is, and must never
+leave your machine.
+
+Ask them for three things back:
+
+| | |
+| --- | --- |
+| `<firstname>-admin.crt` | your signed certificate |
+| `ca.crt` | the cluster CA certificate |
+| the API server URL | currently `https://k8s.roboten-infra.com:64430` |
+
+### 2c. Assemble your kubeconfig
+
+Put the two `.crt` files next to your key in `~/.kube/roboten`, then:
+
+```bash
+cd ~/.kube/roboten
+USER_NAME=<firstname>-admin
+SERVER=https://k8s.roboten-infra.com:64430
+
+KUBECONFIG=~/.kube/config kubectl config set-cluster kubernetes \
+  --server="$SERVER" --certificate-authority=ca.crt --embed-certs=true
+
+KUBECONFIG=~/.kube/config kubectl config set-credentials "$USER_NAME" \
+  --client-certificate="$USER_NAME.crt" --client-key="$USER_NAME.key" --embed-certs=true
+
+KUBECONFIG=~/.kube/config kubectl config set-context "$USER_NAME@kubernetes" \
+  --cluster=kubernetes --user="$USER_NAME"
+
+KUBECONFIG=~/.kube/config kubectl config use-context "$USER_NAME@kubernetes"
+```
+
+`--embed-certs=true` copies the certificates *into* `~/.kube/config`, so the files in `~/.kube/roboten` are
+only a backup after this point. Keep the `.key` anyway — you need it if you ever rebuild the config.
+
+### 2d. 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 (1e) |
+| `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)` | Certificate is wrong/expired, or the cluster does not know that CN — back to 2b |
+| `Error from server (Forbidden)` | You *are* authenticated; your user has no permissions bound yet — ask the admin to complete their step 3 |
+| `no token — did the browser login complete?` | The OIDC flow did not finish; make sure you used your `@robo10.com` account |
+| `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 you repeat section 2 — the admin only has to
+re-sign; your permissions (step 3 on their side) stay in place.

package/docs/issuing-access.md

@@ -0,0 +1,180 @@
+# Issuing access (admin)
+
+The other side of [getting-access.md](./getting-access.md). Two independent things:
+
+| | Who does it | What you do |
+| --- | --- | --- |
+| **VPN tunnel** | self-service | make sure they have a Robo10 login; nothing to hand out |
+| **kubectl credential** | needs you | sign their CSR and bind their permissions |
+
+You need `kubectl` with cluster-admin (`system:masters`) and the VPN up.
+
+---
+
+## 1. VPN — what you actually have to do
+
+Tunnels are **self-service**: any valid Robo10 token can create one, and the config is generated on demand
+by the VPN API. So there is no artefact for you to produce or send.
+
+Your only job is to make sure the person can log in at <https://chat.roboten.com> with their
+**`@robo10.com`** account — that same identity is what the token flow authenticates. If they cannot log in,
+that is an account-provisioning issue in Robo10, not something this guide covers.
+
+Then point them at [getting-access.md § 1](./getting-access.md#1-vpn).
+
+**Never** create the tunnel on their behalf and send them the config: the config embeds a private key, so a
+tunnel they generated themselves is the only one only they hold.
+
+To see who has tunnels (with your own token, as in the dev guide):
+
+```bash
+curl -sS -H "Authorization: Bearer $TOKEN" https://vpn.api.staging.roboten-dev.com/v1/vpn-tunnels
+```
+
+To revoke one — `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's key 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 — sign their certificate
+
+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 never see their private key. They send you a `.csr`; you send back a `.crt`.
+
+### 2a. Submit their CSR to the cluster
+
+```bash
+USER_NAME=<firstname>-admin          # must match the CN in their CSR
+CSR_FILE=~/Downloads/$USER_NAME.csr  # what they sent you
+
+cat <<EOF | kubectl apply -f -
+apiVersion: certificates.k8s.io/v1
+kind: CertificateSigningRequest
+metadata:
+  name: $USER_NAME
+spec:
+  request: $(base64 -i "$CSR_FILE" | tr -d '\n')
+  signerName: kubernetes.io/kube-apiserver-client
+  expirationSeconds: 31536000   # 1 year
+  usages:
+  - client auth
+EOF
+```
+
+Sanity-check the CN is what you expect before approving — the CN is the identity you are about to grant
+admin to:
+
+```bash
+openssl req -in "$CSR_FILE" -noout -subject
+# subject=CN=<firstname>-admin
+```
+
+### 2b. 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, the CSR was approved but not signed; check `kubectl describe csr "$USER_NAME"`.
+
+### 2c. Extract the cluster CA
+
+The same file for everyone:
+
+```bash
+kubectl config view --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d > ca.crt
+```
+
+### 2d. 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.
+
+### 2e. Hand back
+
+Send them three things (none are secret — the secret half never left their machine):
+
+1. `<firstname>-admin.crt`
+2. `ca.crt`
+3. the API server URL — currently `https://k8s.roboten-infra.com:64430`
+
+Then they follow [getting-access.md § 2c](./getting-access.md#2c-assemble-your-kubeconfig).
+
+### 2f. Verify before you tell them it is done
+
+```bash
+kubectl get clusterrolebinding | grep "$USER_NAME"     # expect 5 rows
+kubectl auth can-i get pods -n dooer-production --as "$USER_NAME"
+kubectl auth can-i get secrets -n dooer-staging --as "$USER_NAME"
+```
+
+`--as` impersonates the user, so you are testing the real RBAC without needing their certificate.
+
+---
+
+## 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: the user repeats [getting-access.md § 2a–2c](./getting-access.md#2a-generate-your-key-and-csr)
+and you repeat **2a–2c and 2e** here. Skip 2d — their 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.12.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)**.