sdtk-ops-kit 0.3.4 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/README.md +2 -1
  2. package/assets/manifest/toolkit-bundle.manifest.json +133 -13
  3. package/assets/manifest/toolkit-bundle.sha256.txt +31 -7
  4. package/assets/toolkit/toolkit/AGENTS.md +2 -1
  5. package/assets/toolkit/toolkit/SDTKOPS_TOOLKIT.md +4 -2
  6. package/assets/toolkit/toolkit/scripts/install-claude-skills.ps1 +4 -4
  7. package/assets/toolkit/toolkit/scripts/install-codex-skills.ps1 +4 -4
  8. package/assets/toolkit/toolkit/scripts/uninstall-claude-skills.ps1 +2 -2
  9. package/assets/toolkit/toolkit/scripts/uninstall-codex-skills.ps1 +2 -2
  10. package/assets/toolkit/toolkit/skills/ops-discover/SKILL.md +2 -0
  11. package/assets/toolkit/toolkit/skills/ops-local-env/SKILL.md +172 -0
  12. package/assets/toolkit/toolkit/skills/ops-local-env/references/CLUSTER_CA.md +83 -0
  13. package/assets/toolkit/toolkit/skills/ops-local-env/references/GOTCHAS.md +17 -0
  14. package/assets/toolkit/toolkit/skills/ops-local-env/references/K3D_CILIUM_BOOTSTRAP.md +39 -0
  15. package/assets/toolkit/toolkit/skills/ops-local-env/references/PROFILE.md +44 -0
  16. package/assets/toolkit/toolkit/skills/ops-local-env/references/bootstrap/cilium-values.yaml +37 -0
  17. package/assets/toolkit/toolkit/skills/ops-local-env/references/bootstrap/k3d-cluster.yaml +37 -0
  18. package/assets/toolkit/toolkit/skills/ops-local-env/references/profile.example.json +80 -0
  19. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/admin_creds.py +212 -0
  20. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/cilium_heal.py +136 -0
  21. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/ensure_repos.py +69 -0
  22. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/envprofile.py +139 -0
  23. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/explain_config.py +116 -0
  24. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/health.py +109 -0
  25. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/hosts_entry.py +158 -0
  26. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/init_profile.py +217 -0
  27. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/k3d_images.py +70 -0
  28. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/preflight.py +96 -0
  29. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/registry_secret.py +64 -0
  30. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/shared_config.py +178 -0
  31. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/stack_plan.py +94 -0
  32. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/teardown.py +86 -0
  33. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/test_local_env.py +307 -0
  34. package/assets/toolkit/toolkit/skills/ops-local-env/scripts/trust_ca.py +153 -0
  35. package/package.json +1 -1
  36. package/src/lib/scope.js +1 -0
@@ -0,0 +1,83 @@
1
+ # One local CA for the whole stack
2
+
3
+ The bootstrap step creates `ca.crt` / `ca.key` (the profile's `ca.dir`) once per machine. That CA is
4
+ the only root: it signs the Ingress leaf (`tls.crt`, one `<base_domain>-tls` Secret per namespace) and,
5
+ loaded as a cert-manager ClusterIssuer (`ca.cluster_issuer`), every certificate issued inside the
6
+ cluster (database, broker, internal service planes). Trusting it on this machine trusts all of them.
7
+
8
+ ## Name constraints
9
+
10
+ The CA must be name-constrained to the names it is meant to sign: `<base_domain>`, `*.svc`,
11
+ `*.cluster.local`, `<apps_namespace>` (for `<svc>.<ns>`) and any bare in-cluster names cert-manager
12
+ issues. OpenSSL, Go and browsers reject the **whole** certificate when one SAN is outside the
13
+ constraints, and an unconstrained local CA trusted by the OS could sign any site. `trust_ca.py
14
+ --apply` refuses one.
15
+
16
+ Constraints are fixed when the CA is made: a new namespace, database name or bare name means a new CA.
17
+
18
+ ## Re-issue (CA and leaf)
19
+
20
+ When the CA has no constraints, lacks a needed name (`openssl x509 -in ca.crt -noout -ext
21
+ nameConstraints`), or a value in the SAN list changed:
22
+
23
+ 1. Ask first. Move the folder aside (`mv <ca.dir> <ca.dir>.old-<yyyymmdd>`; leaf only: move `tls.*`).
24
+ Never delete it; it is gitignored and per machine.
25
+ 2. Re-run the profile's render / bootstrap command; check `Name Constraints` and the new leaf's SANs.
26
+ 3. Keep the old CA's SHA-1 (`openssl x509 -noout -fingerprint -sha1`) to remove it from the trust store.
27
+ 4. Every component re-deploys so it copies the new files; existing `<base_domain>-tls` Secrets are
28
+ overwritten; the ClusterIssuer is rotated (below); the new CA is trusted and the old one removed.
29
+
30
+ ## Load the CA as the ClusterIssuer (after cert-manager exists)
31
+
32
+ `ca.issuer_after` names the component that installs cert-manager. Right after it deploys — before its
33
+ health check when its own pods wait for a certificate from this issuer:
34
+
35
+ ```bash
36
+ kubectl get crd certificates.cert-manager.io # missing: that component has not run
37
+ openssl x509 -in $CA/ca.crt -noout -fingerprint -sha256
38
+ kubectl -n cert-manager get secret <issuer> -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -noout -fingerprint -sha256
39
+ kubectl get clusterissuer <issuer> -o jsonpath='{.spec.ca.secretName} {.status.conditions[?(@.type=="Ready")].status}'
40
+ ```
41
+
42
+ Same fingerprint and issuer Ready: nothing to do. No Secret: create it and the issuer, no question.
43
+ **A different root** on a cluster that already has certificates: ask — rotating replaces every
44
+ certificate it signed at once.
45
+
46
+ ```bash
47
+ kubectl -n cert-manager create secret generic <issuer> --type=kubernetes.io/tls \
48
+ --from-file=ca.crt=$CA/ca.crt --from-file=ca.key=$CA/ca.key \
49
+ --from-file=tls.crt=$CA/ca.crt --from-file=tls.key=$CA/ca.key \
50
+ --dry-run=client -o yaml | kubectl apply -f - >/dev/null # piped, never printed: it holds the key
51
+ kubectl apply -f - <<'EOF'
52
+ apiVersion: cert-manager.io/v1
53
+ kind: ClusterIssuer
54
+ metadata:
55
+ name: <issuer>
56
+ spec:
57
+ ca:
58
+ secretName: <issuer>
59
+ EOF
60
+ kubectl wait --for=condition=Ready clusterissuer/<issuer> --timeout=60s
61
+ ```
62
+
63
+ A `Certificate` named like the issuer in `cert-manager` (a self-signed layout) owns the Secret and
64
+ would rewrite it: delete that Certificate, its self-signed issuer and the Secret first.
65
+
66
+ ### Rotation
67
+
68
+ Re-issue every Certificate of the issuer by deleting its Secret, then restart what mounts them:
69
+
70
+ ```bash
71
+ kubectl get certificate -A -o jsonpath='{range .items[?(@.spec.issuerRef.name=="<issuer>")]}{.metadata.namespace} {.spec.secretName}{"\n"}{end}' \
72
+ | while read ns sec; do kubectl -n "$ns" delete secret "$sec"; done
73
+ kubectl wait --for=condition=Ready certificate -A --all --timeout=120s
74
+ ```
75
+
76
+ Then `kubectl rollout restart` every Deployment / StatefulSet mounting a re-issued Secret (operators
77
+ such as PGO have their own restart annotation), re-run any step that copied the CA into a ConfigMap,
78
+ and check each re-issued Secret's `ca.crt` equals the new root (`openssl sha256`).
79
+
80
+ ## Never
81
+
82
+ Print, copy, commit or share `ca.key`; copy the issuer Secret to another namespace; trust a CA without
83
+ name constraints.
@@ -0,0 +1,17 @@
1
+ # Gotchas of local Kubernetes test environments
2
+
3
+ | Symptom | Cause | Do |
4
+ |---|---|---|
5
+ | After a reboot every pod is Running but Services / Ingresses are dead | Docker gave the k3d node containers new IPs; Cilium keeps the old ones in its CiliumNode objects | Run the profile's `cluster.heal` script, else `scripts/cilium_heal.py --cluster <name>` (`--check` first): it mounts bpffs, restarts Cilium, then deletes a CiliumNode still carrying an old IP so its agent recreates it |
6
+ | `helm upgrade --wait` never returns, clustermesh-apiserver stuck in `Init` | ClusterMesh enabled without `clustermesh.config.enabled: true` (the chart does not render `clustermesh-remote-users`) | Stop the upgrade, fix the values, upgrade again; check `helm get values` has nothing the values file lacks before upgrading |
7
+ | New Ingress routes silently never appear | Two Ingresses on one host with different `secretName`s: Envoy rejects the whole config and keeps the last good one | One TLS Secret per host name (`<base_domain>-tls`); `kubectl -n kube-system logs ds/cilium-envoy --since=2m \| grep -c rejected` must be 0 |
8
+ | One of two routes unreachable | Two Ingresses with the same host and path: one silently wins (`--dry-run=server` does not catch it) | `kubectl get ingress -A` and look for duplicates of host + path |
9
+ | A certificate is rejected although cert-manager issued it | One SAN outside the CA's name constraints | `openssl verify -x509_strict -CAfile ca.crt <cert>`; add the name and re-issue the CA (CLUSTER_CA.md) |
10
+ | `000` from curl although the name resolves elsewhere | Hosts file not updated or DNS cache | `hosts_entry.py --show`; `curl --resolve <host>:443:127.0.0.1` to tell them apart |
11
+ | TLS error with `curl -s` but not `-k` | CA not in the store this client reads | `trust_ca.py --show`; Firefox, Java (`cacerts`) and Node (`NODE_EXTRA_CA_CERTS`) have their own stores; Homebrew curl has its own bundle; WSL has its own hosts and store |
12
+ | Changing the namespace "renamed" nothing | The k3d cluster is named after it: a new cluster is created next to the old one | Say so before Apply; the old one stays until the person removes it |
13
+ | A UI still takes the old admin password | Some apps keep the first admin password in their database or read the Secret only on first boot | After a password change, log in to each UI and report which did not take |
14
+ | A stateful component cannot read its own data after a rebuild | A key created once (vault / encryption key) was created again | Treat such Secrets as state: never recreate them; missing while the data exists: stop and ask for the old key |
15
+ | Services refuse every token after the identity provider is configured | They read its discovery document / key set at start-up, before it was activated | Start or restart token-verifying services only after the identity step has passed |
16
+ | Pods `ErrImagePull` "no match for platform" for a locally imported image | Image built for another architecture | `k3d_images.py --cluster <name> <image>`; rebuild or re-import for the nodes' platform |
17
+ | macOS refuses a TLS server certificate | Valid more than 825 days, or the leaf outlives its CA | Keep both at 365 days or less |
@@ -0,0 +1,39 @@
1
+ # Bootstrapping a local k3d + Cilium cluster
2
+
3
+ For a stack whose anchor repository has no bootstrap yet. The templates are in `bootstrap/`; copy them
4
+ into the anchor repository, fill the placeholders, and point the profile's first component at the
5
+ result. These are starting points, not tested against every k3s / Cilium version: pin both versions and
6
+ keep what works in the anchor repository.
7
+
8
+ ## Steps (the bootstrap component's `run`)
9
+
10
+ 1. `k3d cluster list` — the cluster exists: heal it (`scripts/cilium_heal.py --cluster <name>`) and stop
11
+ here if it ends healthy. It does not: create it.
12
+ 2. `k3d cluster create --config k3d-cluster.yaml` (flannel, kube-proxy, network policy, Traefik and
13
+ ServiceLB off; host 80/443 → NodePorts 30080/30443).
14
+ 3. Mount what Cilium needs in every node container — they are lost at every restart:
15
+ `scripts/cilium_heal.py --cluster <name>` does it (bpffs, cgroup2), or by hand per node
16
+ `docker exec <node> sh -c 'mount bpffs /sys/fs/bpf -t bpf && mount --make-shared /sys/fs/bpf'`.
17
+ 4. `helm install cilium cilium/cilium --version <pinned> -n kube-system -f cilium-values.yaml
18
+ --kube-context k3d-<name> --wait --timeout 10m`.
19
+ 5. Nodes become Ready only once Cilium runs: `kubectl get nodes` all Ready;
20
+ `kubectl -n kube-system get pods -l k8s-app=cilium` Running;
21
+ `kubectl -n kube-system rollout status deploy/clustermesh-apiserver --timeout=180s`.
22
+ 6. TLS Secrets for the Ingresses: `<base_domain>-tls` from the local CA's leaf in every namespace that
23
+ serves an Ingress (`kubectl create secret tls ... --dry-run=client -o yaml | kubectl apply -f -`;
24
+ an existing one is replaced only after asking).
25
+
26
+ ## Profile entries
27
+
28
+ ```json
29
+ "cluster": {"kind": "k3d", "name_key": "apps_namespace"},
30
+ "components": [{"id": "cluster", "repo": "<anchor>", "run": "cd <anchor>/k8s && ./bootstrap.sh",
31
+ "long": true, "health": ["kubectl get nodes", "kubectl -n kube-system get pods -l k8s-app=cilium"]}]
32
+ ```
33
+
34
+ Without `cluster.heal`, the skill uses `scripts/cilium_heal.py --cluster <name>` after a reboot.
35
+
36
+ ## Health after any reboot
37
+
38
+ `scripts/cilium_heal.py --cluster <name> --check` (read-only) — per node container IP, Node IP,
39
+ CiliumNode IP, bpffs. `STOPPED`, `NO BPFFS` or `STALE`: run it without `--check`.
@@ -0,0 +1,44 @@
1
+ # Stack profile — `ops-env.profile.json`
2
+
3
+ One JSON file at the root of the stack's anchor repository (the one that bootstraps the cluster).
4
+ Every script of this skill reads it; nothing about a particular stack is hard-coded in the skill.
5
+ Start from `profile.example.json` and check it with `scripts/stack_plan.py --check`.
6
+
7
+ Lookup: `--profile FILE`, else `$SDTK_ENV_PROFILE`, else the nearest directory at or above the current
8
+ one that holds `ops-env.profile.json` or holds a repository that does. Workspace (the directory with
9
+ all the repositories side by side): `--root DIR`, else `$SDTK_ENV_ROOT`, else the anchor repository's
10
+ parent.
11
+
12
+ ## Keys
13
+
14
+ | Key | Used by | Meaning |
15
+ |---|---|---|
16
+ | `name` | all | Short stack name; hosts-file block, CA file name in the trust store |
17
+ | `tools` | preflight | CLI tools that must be on PATH |
18
+ | `python_modules` | preflight | `{"module": "pip package"}` the stack's own scripts need (the skill's scripts need none) |
19
+ | `registry` | preflight, registry_secret | `host`, `token_env` (name of the env variable, never the token), `kind` (`github-classic-pat` checks owner and scope through the GitHub API), `scope`, `pull_secret`, optional `username` |
20
+ | `repos[]` | ensure_repos, stack_plan | `dir` (folder in the workspace), `url` (SSH), `https` |
21
+ | `configs` | shared_config, hosts, plan | `{"name": "repo/path/config.yaml"}` — the files whose top-level `key: value` lines carry the shared values |
22
+ | `primary_config` | all | The config that owns the cluster-wide values (base domain, namespaces); `{key}` placeholders are filled from it |
23
+ | `base_domain_key` | shared_config, hosts | Default `base_domain`. Every other `*_domain` must be one label under it |
24
+ | `core_keys` | skill step 0.4 | The values asked first, in one question (e.g. namespace, base domain, database name) |
25
+ | `shared_keys` | shared_config | Keys every config that has them must agree on |
26
+ | `aliases[]` | shared_config | `{config, key, file_key}`: in that config the shared `key` is stored as `file_key` (`null`: not stored there, the name means something else) |
27
+ | `indented_followers[]` | shared_config | `{config, line_key, follows}`: indented `line_key:` lines in that config that hold the value of `follows` and move with it |
28
+ | `validators` | shared_config | `{key: regex}` beyond the defaults (`*_namespace`, `*_name`: DNS label; `*_domain`: FQDN; `ssl_country`: 2 letters) |
29
+ | `admin.users[]` / `admin.passwords[]` | admin_creds | `{file, key}`. Users in tracked configs; passwords in gitignored secrets files |
30
+ | `admin.k8s_secrets[]` | admin_creds | `{name, user_field, password_field}` Secrets made from the shared login (`--k8s-secrets NAMESPACE`) |
31
+ | `admin.user_rx` / `password_rx` | admin_creds | Override the default rules |
32
+ | `hosts` | hosts_entry | `configs` to collect `*_domain` names from, `ip` (default 127.0.0.1), `extra` names |
33
+ | `ca` | trust_ca, skill | `dir` (with `{key}` placeholders), `ca`, `leaf`, `site_key`; optional `cluster_issuer` (cert-manager ClusterIssuer loaded from this CA) and `issuer_after` (component that installs cert-manager) |
34
+ | `cluster` | skill | `kind` (`k3d`), `name_key` (config key naming the cluster), optional `heal` (script that repairs node networking after a reboot) |
35
+ | `components[]` | stack_plan, skill | In install order: `id`, `repo`, one of `skill` (the repository's own install skill) / `run` (command from the workspace) / `steps` (free text), `configs`, `after`, `gate`, `long` (run in the background with a log), `needs_registry_secret`, `health[]` (commands, `{key}` placeholders), `notes[]` (stack rules handed to that component's run, e.g. a value that must stay off) |
36
+ | `ingress` | skill | `dir` of the rendered Ingresses, `render` command |
37
+
38
+ ## Conventions the scripts rely on
39
+
40
+ - Config files are flat at the top: `key: "value" # explanation`. The scripts change only the value on
41
+ that line and read it back; they never rewrite a file with a YAML dumper (comments survive).
42
+ - Passwords never sit in a tracked file. Each component keeps them in a gitignored `secrets.yaml`
43
+ that its own launcher merges over `config.yaml`.
44
+ - A comment line on its own above a group of keys is a section title (`explain_config.py` shows it).
@@ -0,0 +1,37 @@
1
+ # Cilium values for a local k3d cluster (template). Replace <cluster> and <cluster-id>.
2
+ # helm repo add cilium https://helm.cilium.io && helm repo update
3
+ # helm install cilium cilium/cilium --version <version> -n kube-system -f cilium-values.yaml \
4
+ # --kube-context k3d-<cluster> --wait --timeout 10m
5
+ # Pin the chart version in your bootstrap and keep this file the whole user-supplied config: before a
6
+ # `helm upgrade`, `helm -n kube-system get values cilium` must hold nothing this file lacks.
7
+ cluster:
8
+ name: <cluster>
9
+ id: <cluster-id> # 1-255, unique among clusters you may mesh; peers also need another pod CIDR
10
+ k8sServiceHost: k3d-<cluster>-server-0
11
+ k8sServicePort: 6443
12
+ kubeProxyReplacement: true
13
+ ipam:
14
+ mode: kubernetes
15
+ operator:
16
+ replicas: 1
17
+ ingressController:
18
+ enabled: true
19
+ default: true
20
+ loadbalancerMode: shared
21
+ service:
22
+ type: NodePort
23
+ insecureNodePort: 30080
24
+ secureNodePort: 30443
25
+ hubble:
26
+ relay:
27
+ enabled: true
28
+ ui:
29
+ enabled: true
30
+ clustermesh:
31
+ useAPIServer: true
32
+ config:
33
+ enabled: true # without it the apiserver waits in Init for clustermesh-remote-users
34
+ apiserver:
35
+ service:
36
+ type: NodePort
37
+ nodePort: 32379
@@ -0,0 +1,37 @@
1
+ # k3d cluster for Cilium (template). Replace <cluster>; pin the k3s image you test with.
2
+ # k3d cluster create --config k3d-cluster.yaml
3
+ # Cilium replaces flannel, kube-proxy and the network policy controller; Traefik and ServiceLB are off
4
+ # because Cilium's ingress controller serves the Ingresses on NodePorts 30080 / 30443, mapped to the
5
+ # host's 80 / 443 below.
6
+ apiVersion: k3d.io/v1alpha5
7
+ kind: Simple
8
+ metadata:
9
+ name: <cluster>
10
+ servers: 1
11
+ agents: 2
12
+ image: rancher/k3s:v1.31.4-k3s1
13
+ ports:
14
+ - port: 80:30080
15
+ nodeFilters: [server:0]
16
+ - port: 443:30443
17
+ nodeFilters: [server:0]
18
+ options:
19
+ k3d:
20
+ wait: true
21
+ k3s:
22
+ extraArgs:
23
+ - arg: --flannel-backend=none
24
+ nodeFilters: [server:*]
25
+ - arg: --disable-network-policy
26
+ nodeFilters: [server:*]
27
+ - arg: --disable-kube-proxy
28
+ nodeFilters: [server:*]
29
+ - arg: --disable=traefik
30
+ nodeFilters: [server:*]
31
+ - arg: --disable=servicelb
32
+ nodeFilters: [server:*]
33
+ - arg: --cluster-cidr=10.42.0.0/16
34
+ nodeFilters: [server:*]
35
+ kubeconfig:
36
+ updateDefaultKubeconfig: true
37
+ switchCurrentContext: true
@@ -0,0 +1,80 @@
1
+ {
2
+ "name": "demo",
3
+ "description": "Fictional stack: k3d + Cilium cluster, object storage, PostgreSQL, a message broker, monitoring and the application charts.",
4
+ "tools": ["docker", "k3d", "kubectl", "helm", "openssl", "git", "curl"],
5
+ "python_modules": {"yaml": "pyyaml", "jinja2": "jinja2"},
6
+ "registry": {
7
+ "host": "ghcr.io",
8
+ "token_env": "REGISTRY_TOKEN",
9
+ "kind": "github-classic-pat",
10
+ "scope": "read:packages",
11
+ "pull_secret": "registry-pull"
12
+ },
13
+ "repos": [
14
+ {"dir": "demo-infra", "url": "git@github.com:example-org/demo-infra.git", "https": "https://github.com/example-org/demo-infra.git"},
15
+ {"dir": "demo-storage", "url": "git@github.com:example-org/demo-storage.git", "https": "https://github.com/example-org/demo-storage.git"},
16
+ {"dir": "demo-db", "url": "git@github.com:example-org/demo-db.git", "https": "https://github.com/example-org/demo-db.git"},
17
+ {"dir": "demo-mq", "url": "git@github.com:example-org/demo-mq.git", "https": "https://github.com/example-org/demo-mq.git"},
18
+ {"dir": "demo-monitoring", "url": "git@github.com:example-org/demo-monitoring.git", "https": "https://github.com/example-org/demo-monitoring.git"},
19
+ {"dir": "demo-charts", "url": "git@github.com:example-org/demo-charts.git", "https": "https://github.com/example-org/demo-charts.git"}
20
+ ],
21
+ "configs": {
22
+ "infra": "demo-infra/k8s/config.yaml",
23
+ "storage": "demo-storage/config.yaml",
24
+ "db": "demo-db/config.yaml",
25
+ "mq": "demo-mq/config.yaml",
26
+ "monitoring": "demo-monitoring/config.yaml"
27
+ },
28
+ "primary_config": "infra",
29
+ "base_domain_key": "base_domain",
30
+ "core_keys": ["apps_namespace", "base_domain", "db_name"],
31
+ "shared_keys": ["apps_namespace", "base_domain", "site_domain", "ingress_class", "db_name",
32
+ "ssl_country", "ssl_state", "ssl_city", "ssl_organization", "ssl_organization_unit"],
33
+ "aliases": [
34
+ {"config": "monitoring", "key": "apps_namespace", "file_key": null},
35
+ {"config": "monitoring", "key": "monitoring_namespace", "file_key": "apps_namespace"}
36
+ ],
37
+ "indented_followers": [
38
+ {"config": "monitoring", "line_key": "namespace", "follows": "apps_namespace"}
39
+ ],
40
+ "admin": {
41
+ "users": [
42
+ {"file": "demo-storage/config.yaml", "key": "storage_admin_user"},
43
+ {"file": "demo-db/config.yaml", "key": "db_admin_user"},
44
+ {"file": "demo-mq/config.yaml", "key": "mq_default_user"},
45
+ {"file": "demo-monitoring/config.yaml", "key": "grafana_admin_user"}
46
+ ],
47
+ "passwords": [
48
+ {"file": "demo-storage/secrets.yaml", "key": "storage_admin_password"},
49
+ {"file": "demo-db/secrets.yaml", "key": "db_admin_password"},
50
+ {"file": "demo-mq/secrets.yaml", "key": "mq_default_password"},
51
+ {"file": "demo-monitoring/secrets.yaml", "key": "grafana_admin_password"}
52
+ ],
53
+ "k8s_secrets": [
54
+ {"name": "demo-app-admin", "user_field": "username", "password_field": "password"}
55
+ ]
56
+ },
57
+ "hosts": {"configs": ["infra", "storage", "monitoring"], "ip": "127.0.0.1"},
58
+ "ca": {"dir": "demo-infra/k8s/certs/{base_domain}", "ca": "ca.crt", "leaf": "tls.crt", "site_key": "site_domain",
59
+ "cluster_issuer": "demo-ca", "issuer_after": "storage"},
60
+ "cluster": {"kind": "k3d", "name_key": "apps_namespace", "heal": "demo-infra/k8s/cilium-heal.sh"},
61
+ "components": [
62
+ {"id": "cluster", "repo": "demo-infra", "run": "cd demo-infra/k8s && ./launch.py -d", "configs": ["infra"],
63
+ "gate": "the confirmed Apply summary", "long": true,
64
+ "health": ["kubectl get nodes", "kubectl -n kube-system get pods -l k8s-app=cilium"]},
65
+ {"id": "storage", "repo": "demo-storage", "skill": "install-demo-storage", "configs": ["storage"], "after": ["cluster"],
66
+ "gate": "its own deploy go-ahead", "long": true,
67
+ "health": ["kubectl -n {apps_namespace} get pods -l app=object-store"]},
68
+ {"id": "db", "repo": "demo-db", "skill": "install-demo-db", "configs": ["db"], "after": ["storage"],
69
+ "gate": "its own deploy go-ahead", "long": true,
70
+ "health": ["kubectl -n {apps_namespace} get postgrescluster {db_name}"]},
71
+ {"id": "mq", "repo": "demo-mq", "skill": "install-demo-mq", "configs": ["mq"], "after": ["storage"],
72
+ "health": ["kubectl -n {apps_namespace} get rabbitmqcluster"]},
73
+ {"id": "monitoring", "repo": "demo-monitoring", "skill": "install-demo-monitoring", "configs": ["monitoring"], "after": ["cluster"],
74
+ "health": ["kubectl -n {monitoring_namespace} get pods"]},
75
+ {"id": "apps", "repo": "demo-charts", "run": "cd demo-charts && ./deploy-charts.sh", "after": ["db", "mq"],
76
+ "needs_registry_secret": true,
77
+ "health": ["helm -n {apps_namespace} list", "kubectl -n {apps_namespace} get pods"]}
78
+ ],
79
+ "ingress": {"dir": "demo-infra/k8s/ingress/{base_domain}", "render": "cd demo-infra/k8s && ./launch.py -ro"}
80
+ }
@@ -0,0 +1,212 @@
1
+ #!/usr/bin/env python3
2
+ """admin_creds.py - one admin user and one admin password for every component of the stack that has
3
+ a login (the profile's `admin.users` / `admin.passwords`), and the Kubernetes Secrets made from them
4
+ (`admin.k8s_secrets`). Never prints a password, except --reveal.
5
+
6
+ admin_creds.py --show # users per key; passwords only as set / EMPTY
7
+ admin_creds.py --user NAME # dry run: diff of the user lines
8
+ admin_creds.py --generate # dry run: a new random password, masked
9
+ admin_creds.py --user NAME --generate --apply # write, then read back
10
+ admin_creds.py --password-stdin [--apply] <<'EOF' # the person's own password, from stdin
11
+ <password>
12
+ EOF
13
+ admin_creds.py --k8s-secrets NAMESPACE # create / update admin.k8s_secrets (current context)
14
+ admin_creds.py --reveal # print the shared user and password (final summary only)
15
+
16
+ Users stay in the tracked config files; passwords go to gitignored secrets files (created with mode
17
+ 600 when missing). The password is kept, generated here (secrets.token_urlsafe), or read from stdin
18
+ -- never from the command line -- and written straight into the files. --show warns when git
19
+ tracks a password file: a `git diff` there prints the password.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import argparse
25
+ import base64
26
+ import difflib
27
+ import json
28
+ import re
29
+ import secrets
30
+ import subprocess
31
+ import sys
32
+ from pathlib import Path
33
+
34
+ from envprofile import Stack, add_common_args, fail, load_flat, set_line
35
+
36
+ USER_RX = r"^[a-z][a-z0-9_-]{2,31}$"
37
+ # goes into YAML and shell-rendered files: no space, quote, backtick, backslash or dollar
38
+ PASSWORD_RX = r'^[^\s"\'`\\$]{12,64}$'
39
+
40
+
41
+ class Admin:
42
+ def __init__(self, stack: Stack):
43
+ self.stack = stack
44
+ conf = stack.get("admin") or {}
45
+ self.users = [(u["file"], u["key"]) for u in conf.get("users") or []]
46
+ self.passwords = [(p["file"], p["key"]) for p in conf.get("passwords") or []]
47
+ self.k8s_secrets = conf.get("k8s_secrets") or []
48
+ self.user_rx = conf.get("user_rx") or USER_RX
49
+ self.password_rx = conf.get("password_rx") or PASSWORD_RX
50
+ if not self.users and not self.passwords:
51
+ raise SystemExit("error: the profile has no admin.users / admin.passwords")
52
+
53
+ def value(self, rel: str, key: str):
54
+ return load_flat(self.stack.path(rel)).get(key)
55
+
56
+ def shared(self) -> tuple[str, str] | None:
57
+ users = {self.value(rel, key) for rel, key in self.users}
58
+ passwords = {self.value(rel, key) for rel, key in self.passwords}
59
+ if len(users) != 1 or len(passwords) != 1 or None in users | passwords:
60
+ return None
61
+ return users.pop(), passwords.pop()
62
+
63
+ def tracked(self) -> list[str]:
64
+ out = []
65
+ for rel in sorted({rel for rel, _ in self.passwords}):
66
+ path = self.stack.path(rel)
67
+ res = subprocess.run(["git", "-C", str(path.parent), "ls-files", "--error-unmatch", path.name],
68
+ capture_output=True, check=False)
69
+ if res.returncode == 0:
70
+ out.append(rel)
71
+ return out
72
+
73
+ def warn_tracked(self) -> None:
74
+ files = self.tracked()
75
+ if files:
76
+ print(f"\ntracked by git, password in plain text: {', '.join(files)}\n"
77
+ " never git diff / git show / git log -p them, never stage or commit them")
78
+
79
+
80
+ def show(ad: Admin) -> int:
81
+ print(f"{'file':40} {'key':28} value")
82
+ for rel, key in ad.users:
83
+ path = ad.stack.path(rel)
84
+ value = load_flat(path).get(key, "(missing)") if path.is_file() else "(no file)"
85
+ print(f"{rel:40} {key:28} {value}")
86
+ values = []
87
+ for rel, key in ad.passwords:
88
+ path = ad.stack.path(rel)
89
+ val = load_flat(path).get(key) if path.is_file() else None
90
+ values.append(val)
91
+ print(f"{rel:40} {key:28} {'(no file)' if not path.is_file() else ('set' if val else 'EMPTY')}")
92
+ users = {str(ad.value(rel, key)) for rel, key in ad.users}
93
+ same_pw = len(set(values)) == 1 and values and values[0]
94
+ print(f"\nusers: {'all the same' if len(users) == 1 else 'DIFFER'}; "
95
+ f"passwords: {'all the same' if same_pw else 'DIFFER or EMPTY'}")
96
+ ad.warn_tracked()
97
+ return 0
98
+
99
+
100
+ def mask(lines: list[str], keys: set[str]) -> list[str]:
101
+ rx = re.compile(rf'^([-+ ]?(?:{"|".join(map(re.escape, keys))}):[ \t]*)("(?:[^"\\\n]|\\.)*"|\'[^\'\n]*\'|[^\n]*?)([ \t]*(?:(?<=[ \t])#.*)?)$')
102
+ return [rx.sub(r'\1"********"\3', line.rstrip("\n")) + "\n" for line in lines]
103
+
104
+
105
+ def change(ad: Admin, user: str | None, generate: bool, apply: bool, given: str | None) -> int:
106
+ if user is not None and not re.match(ad.user_rx, user):
107
+ return fail(f"error: user {user!r} does not match {ad.user_rx}")
108
+ if given is not None and not re.match(ad.password_rx, given):
109
+ return fail("error: the password must be 12-64 characters, with no space and none of \" ' ` \\ $")
110
+ password = secrets.token_urlsafe(18) if generate else given
111
+ edits: dict[str, list[tuple[str, str]]] = {}
112
+ if user is not None:
113
+ for rel, key in ad.users:
114
+ edits.setdefault(rel, []).append((key, user))
115
+ if password is not None:
116
+ for rel, key in ad.passwords:
117
+ edits.setdefault(rel, []).append((key, password))
118
+ if not edits:
119
+ return fail("error: pass --user NAME and/or --generate / --password-stdin")
120
+ pw_keys = {key for _, key in ad.passwords}
121
+ pw_files = {rel for rel, _ in ad.passwords}
122
+ changed = False
123
+ for rel, pairs in edits.items():
124
+ path = ad.stack.path(rel)
125
+ if not path.is_file() and rel not in pw_files:
126
+ return fail(f"error: {path} not found")
127
+ old = path.read_text(encoding="utf-8") if path.is_file() else ""
128
+ new = old
129
+ for key, value in pairs:
130
+ new = set_line(new, key, value, append=rel in pw_files)
131
+ if new == old:
132
+ continue
133
+ changed = True
134
+ sys.stdout.writelines(mask(list(difflib.unified_diff(old.splitlines(True), new.splitlines(True), rel, rel, n=0)), pw_keys))
135
+ if apply:
136
+ path.parent.mkdir(parents=True, exist_ok=True)
137
+ path.write_text(new, encoding="utf-8")
138
+ if rel in pw_files:
139
+ path.chmod(0o600)
140
+ back = load_flat(path)
141
+ for key, value in pairs:
142
+ if str(back.get(key)) != value:
143
+ return fail(f"error: {rel}: {key} does not read back as written")
144
+ if not changed:
145
+ print("nothing to change")
146
+ elif not apply:
147
+ print("\n(dry run; a generated password is discarded -- add --apply to write a new one)")
148
+ else:
149
+ print("\nwritten; passwords are in the files above, never printed")
150
+ ad.warn_tracked()
151
+ return 0
152
+
153
+
154
+ def k8s_secrets(ad: Admin, namespace: str) -> int:
155
+ """Create or update every admin.k8s_secrets entry in NAMESPACE (current kube context), from the
156
+ user and password the files share. Piped to kubectl, never shown."""
157
+ if not ad.k8s_secrets:
158
+ return fail("error: the profile lists no admin.k8s_secrets")
159
+ pair = ad.shared()
160
+ if not pair:
161
+ return fail("error: users or passwords differ or are empty; run --show, then set them first")
162
+ b64 = lambda s: base64.b64encode(s.encode()).decode()
163
+ rc = 0
164
+ for spec in ad.k8s_secrets:
165
+ secret = {"apiVersion": "v1", "kind": "Secret", "type": "Opaque",
166
+ "metadata": {"name": spec["name"], "namespace": namespace},
167
+ "data": {spec.get("user_field", "username"): b64(pair[0]),
168
+ spec.get("password_field", "password"): b64(pair[1])}}
169
+ run = subprocess.run(["kubectl", "apply", "--server-side", "--force-conflicts", "-f", "-"],
170
+ input=json.dumps(secret), text=True, capture_output=True, check=False)
171
+ if run.returncode:
172
+ rc = 1
173
+ sys.stderr.write(run.stderr)
174
+ else:
175
+ print(f"{spec['name']} in {namespace}: the shared admin user and password")
176
+ return rc
177
+
178
+
179
+ def reveal(ad: Admin) -> int:
180
+ pair = ad.shared()
181
+ if not pair:
182
+ return fail("error: users or passwords differ or are empty; run --show")
183
+ print(f"admin user: {pair[0]}\nadmin password: {pair[1]}")
184
+ return 0
185
+
186
+
187
+ def main() -> int:
188
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
189
+ add_common_args(parser)
190
+ parser.add_argument("--show", action="store_true")
191
+ parser.add_argument("--reveal", action="store_true", help="print the shared user and password (final summary only)")
192
+ parser.add_argument("--user", metavar="NAME")
193
+ pw = parser.add_mutually_exclusive_group()
194
+ pw.add_argument("--generate", action="store_true", help="one new random password for every key")
195
+ pw.add_argument("--password-stdin", action="store_true", help="read the password from stdin (first line)")
196
+ parser.add_argument("--apply", action="store_true")
197
+ parser.add_argument("--k8s-secrets", metavar="NAMESPACE", help="create / update admin.k8s_secrets in NAMESPACE")
198
+ args = parser.parse_args()
199
+ ad = Admin(Stack(args.profile, args.root))
200
+ print(f"workspace: {ad.stack.root}")
201
+ if args.reveal:
202
+ return reveal(ad)
203
+ if args.show:
204
+ return show(ad)
205
+ if args.k8s_secrets:
206
+ return k8s_secrets(ad, args.k8s_secrets)
207
+ given = sys.stdin.readline().rstrip("\r\n") if args.password_stdin else None
208
+ return change(ad, args.user, args.generate, args.apply, given)
209
+
210
+
211
+ if __name__ == "__main__":
212
+ sys.exit(main())