Refresh operating guidance and standardize new workplan naming
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a0e77d-47a4-7771-8e34-7339c7fac0e4
This commit is contained in:
parent
36303d25a3
commit
63e3bb6f7d
7 changed files with 360 additions and 139 deletions
119
sso-mfa/k8s/FOUNDATIONS-HISTORICAL.md
Normal file
119
sso-mfa/k8s/FOUNDATIONS-HISTORICAL.md
Normal file
|
|
@ -0,0 +1,119 @@
|
|||
# Historical T02 — Kubernetes foundations
|
||||
|
||||
Exercise status: unknown for the procedures in this runbook; no per-procedure successful-run receipt with operator attribution was established in the 2026-09-05 review. See [procedure inventory](../../docs/attended-procedure-inventory.md).
|
||||
|
||||
Archived procedure from Phase 1 of NK-WP-0001: namespaces, NetworkPolicies,
|
||||
cert-manager, StorageClass. These commands describe the original bootstrap,
|
||||
not maintenance of the current Railiance cluster. The ThreePhoenix/KeePassXC
|
||||
prerequisites and network table below are historical assumptions, not current
|
||||
operating claims. See [current operations](README.md) for owner routing.
|
||||
|
||||
Use this only as a starting point for a separately reviewed isolated lab
|
||||
exercise. It is not a production apply, repair or recovery recipe.
|
||||
|
||||
## SSO stack overview
|
||||
|
||||
The `sso` namespace hosts three components:
|
||||
- **KeyCape** (`kc.coulomb.social`) — OIDC orchestration layer, stateless
|
||||
- **Authelia** (`auth.coulomb.social`) — password authentication frontend
|
||||
- **LLDAP** (`lldap.coulomb.social`) — lightweight LDAP directory (admin UI restricted)
|
||||
|
||||
The `mfa` namespace hosts:
|
||||
- **privacyIDEA** (`pink.coulomb.social`) — MFA engine, called by KeyCape
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- K3s cluster running (ThreePhoenix HA or single-node dev)
|
||||
- T01 Phase 0a complete (KeePassXC vault populated, ops bundle exported)
|
||||
- `kubectl` configured with cluster access
|
||||
|
||||
## Apply order
|
||||
|
||||
```bash
|
||||
# 1. Install cert-manager (if not already on cluster)
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
helm repo update
|
||||
helm install cert-manager jetstack/cert-manager \
|
||||
--namespace cert-manager --create-namespace \
|
||||
--set crds.enabled=true
|
||||
|
||||
# Wait for cert-manager to be ready
|
||||
kubectl rollout status deployment/cert-manager -n cert-manager
|
||||
|
||||
# 2. Create namespaces
|
||||
kubectl apply -f namespaces/namespaces.yaml
|
||||
|
||||
# 3. Apply NetworkPolicies
|
||||
kubectl apply -f network-policies/netpol-sso.yaml
|
||||
kubectl apply -f network-policies/netpol-mfa.yaml
|
||||
kubectl apply -f network-policies/netpol-databases.yaml
|
||||
|
||||
# 4. Create ClusterIssuers
|
||||
# Edit issuers.yaml first: replace ACME_EMAIL with your address
|
||||
kubectl apply -f cert-manager/issuers.yaml
|
||||
|
||||
# 5. Verify cert-manager with test certificate
|
||||
kubectl apply -f cert-manager/test-certificate.yaml
|
||||
kubectl wait --for=condition=Ready certificate/selfsigned-test \
|
||||
-n cert-manager-test --timeout=60s
|
||||
kubectl delete namespace cert-manager-test
|
||||
|
||||
# 6. Verify StorageClass
|
||||
kubectl apply -f storage/verify-pvc.yaml
|
||||
kubectl wait --for=condition=Ready pod/storage-test \
|
||||
-n storage-test --timeout=60s
|
||||
kubectl logs -n storage-test storage-test
|
||||
kubectl delete namespace storage-test
|
||||
|
||||
# 7. Run the full verification script
|
||||
chmod +x verify-t02.sh
|
||||
./verify-t02.sh
|
||||
```
|
||||
|
||||
## NetworkPolicy design
|
||||
|
||||
All three namespaces follow a default-deny-all posture. Only the minimal
|
||||
required paths are opened:
|
||||
|
||||
| Source | Destination | Port | Purpose |
|
||||
|--------|-------------|------|---------|
|
||||
| Traefik (kube-system) | KeyCape (sso) | 8080 | OIDC endpoints — public |
|
||||
| Traefik (kube-system) | Authelia (sso) | 9091 | Login portal — public |
|
||||
| Traefik (kube-system) | LLDAP (sso) | 17170 | Admin web UI — IP-restricted |
|
||||
| Traefik (kube-system) | privacyIDEA (mfa) | 8080 | MFA portal — public |
|
||||
| KeyCape (sso) | Authelia (sso) | 9091 | OIDC token exchange |
|
||||
| KeyCape (sso) | LLDAP (sso) | 3890 | User attribute lookup |
|
||||
| KeyCape (sso) | privacyIDEA (mfa) | 8080 | MFA challenge + validation |
|
||||
| Authelia (sso) | LLDAP (sso) | 3890 | Credential validation |
|
||||
| privacyIDEA (mfa) | PostgreSQL (databases) | 5432 | DB |
|
||||
| CNPG operator (cnpg-system) | PostgreSQL (databases) | 5432/9187 | Operator + metrics |
|
||||
| All pods | kube-dns (kube-system) | 53 | DNS resolution |
|
||||
| CNPG pods | K8s API | 6443 | Status updates |
|
||||
|
||||
## Verifying denied paths (manual)
|
||||
|
||||
After applying NetworkPolicies, confirm that illegal paths are blocked:
|
||||
|
||||
```bash
|
||||
# Test: KeyCape → privacyIDEA (should be ALLOWED)
|
||||
kubectl run test-allowed -n sso --rm -it --image=busybox --restart=Never \
|
||||
-- nc -zv privacyidea.mfa.svc.cluster.local 8080
|
||||
|
||||
# Test: Authelia → privacyIDEA (should be DENIED — only KeyCape calls privacyIDEA)
|
||||
kubectl run test-denied -n sso --rm -it --image=busybox --restart=Never \
|
||||
-l app.kubernetes.io/name=authelia \
|
||||
-- nc -zv -w3 privacyidea.mfa.svc.cluster.local 8080
|
||||
|
||||
# Test: databases → sso (should be DENIED — DB pods must not initiate connections)
|
||||
kubectl run test-denied2 -n databases --rm -it --image=busybox --restart=Never \
|
||||
-- nc -zw3 keycape.sso.svc.cluster.local 8080
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- `net-kingdom/component` labels on namespaces are used by NetworkPolicy
|
||||
`namespaceSelector` rules. Do not remove them.
|
||||
- `cnpg.io/cluster: net-kingdom-pg` in `netpol-databases.yaml` must match
|
||||
the name of the CloudNativePG `Cluster` CR you create in T03.
|
||||
- The `letsencrypt-prod` ClusterIssuer requires public DNS and port 80 open
|
||||
to Let's Encrypt servers. Update `ACME_EMAIL` before applying.
|
||||
|
|
@ -1,112 +1,71 @@
|
|||
# T02 — K8s Foundations
|
||||
# NetKingdom Kubernetes integration guidance
|
||||
|
||||
Exercise status: unknown for the procedures in this runbook; no per-procedure successful-run receipt with operator attribution was established in the 2026-09-05 review. See [procedure inventory](../../docs/attended-procedure-inventory.md).
|
||||
This directory holds bootstrap tooling, integration references and migration
|
||||
history. Current managed deployment belongs to the service/package owners
|
||||
under [ADR-0015](../../docs/adr/ADR-0015-netkingdom-railiance-workload-packaging-and-relational-platform.md).
|
||||
The [original foundation procedure](FOUNDATIONS-HISTORICAL.md) is retained as
|
||||
historical material, including its old prerequisites and apply commands.
|
||||
|
||||
Phase 1 of NK-WP-0001: namespaces, NetworkPolicies, cert-manager, StorageClass.
|
||||
## Operating baseline
|
||||
|
||||
## SSO stack overview
|
||||
The [September 28 review](../../history/2026-09-28-open-workplan-infrastructure-review.md)
|
||||
observed one Ready Railiance01 node at `92.205.62.239`, healthy lightweight
|
||||
identity components and single-instance CNPG databases. This is a dated
|
||||
inventory, not an HA, recovery or user-login acceptance claim.
|
||||
|
||||
The `sso` namespace hosts three components:
|
||||
- **KeyCape** (`kc.coulomb.social`) — OIDC orchestration layer, stateless
|
||||
- **Authelia** (`auth.coulomb.social`) — password authentication frontend
|
||||
- **LLDAP** (`lldap.coulomb.social`) — lightweight LDAP directory (admin UI restricted)
|
||||
| Surface | Current role and owner |
|
||||
| --- | --- |
|
||||
| KeyCape / Authelia / LLDAP (`sso`) and privacyIDEA (`mfa`) | Lightweight identity composition; issuer implementation in `key-cape`, integration contracts here |
|
||||
| User Engine | [rapp-user-engine](../../../rapp-user-engine/README.md) owns managed manifests, rollout and rollback |
|
||||
| Tenant Engine | [rapp-tenant-engine](../../../rapp-tenant-engine/README.md) owns managed runtime and database-consumption configuration |
|
||||
| flex-auth consumer services | [Owner values and chart pointers](tenant-engine/README.md); caller authentication is enforced by the owner declarations |
|
||||
| OpenBao and database custody | `railiance-platform`, with managed packages and consumer declarations in their owning repositories |
|
||||
| Kubernetes and host substrate | [railiance-cluster operator runbook](../../../railiance-cluster/docs/operator-runbook.md) and `railiance-infra` |
|
||||
|
||||
The `mfa` namespace hosts:
|
||||
- **privacyIDEA** (`pink.coulomb.social`) — MFA engine, called by KeyCape
|
||||
OpenBao's public browser endpoint `bao.coulomb.social` is retired. Operators
|
||||
use the named `openbao-ui-railiance01` tunnel at `http://127.0.0.1:18200`;
|
||||
workloads use the internal Service. Follow the platform's
|
||||
[operator-only cutover record](../../../railiance-platform/workplans/RPF-WP-0025-openbao-operator-only-access.md)
|
||||
and credential routing in [AGENTS.md](../../AGENTS.md). Route access before
|
||||
requesting credentials; never copy tokens or Secret values into evidence.
|
||||
|
||||
## Prerequisites
|
||||
## Read-only orientation
|
||||
|
||||
- K3s cluster running (ThreePhoenix HA or single-node dev)
|
||||
- T01 Phase 0a complete (KeePassXC vault populated, ops bundle exported)
|
||||
- `kubectl` configured with cluster access
|
||||
|
||||
## Apply order
|
||||
Check the context before interpreting these results. All commands below read
|
||||
resource metadata and readiness; none applies manifests or initiates login.
|
||||
|
||||
```bash
|
||||
# 1. Install cert-manager (if not already on cluster)
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
helm repo update
|
||||
helm install cert-manager jetstack/cert-manager \
|
||||
--namespace cert-manager --create-namespace \
|
||||
--set crds.enabled=true
|
||||
|
||||
# Wait for cert-manager to be ready
|
||||
kubectl rollout status deployment/cert-manager -n cert-manager
|
||||
|
||||
# 2. Create namespaces
|
||||
kubectl apply -f namespaces/namespaces.yaml
|
||||
|
||||
# 3. Apply NetworkPolicies
|
||||
kubectl apply -f network-policies/netpol-sso.yaml
|
||||
kubectl apply -f network-policies/netpol-mfa.yaml
|
||||
kubectl apply -f network-policies/netpol-databases.yaml
|
||||
|
||||
# 4. Create ClusterIssuers
|
||||
# Edit issuers.yaml first: replace ACME_EMAIL with your address
|
||||
kubectl apply -f cert-manager/issuers.yaml
|
||||
|
||||
# 5. Verify cert-manager with test certificate
|
||||
kubectl apply -f cert-manager/test-certificate.yaml
|
||||
kubectl wait --for=condition=Ready certificate/selfsigned-test \
|
||||
-n cert-manager-test --timeout=60s
|
||||
kubectl delete namespace cert-manager-test
|
||||
|
||||
# 6. Verify StorageClass
|
||||
kubectl apply -f storage/verify-pvc.yaml
|
||||
kubectl wait --for=condition=Ready pod/storage-test \
|
||||
-n storage-test --timeout=60s
|
||||
kubectl logs -n storage-test storage-test
|
||||
kubectl delete namespace storage-test
|
||||
|
||||
# 7. Run the full verification script
|
||||
chmod +x verify-t02.sh
|
||||
./verify-t02.sh
|
||||
kubectl config current-context
|
||||
kubectl get nodes -o wide
|
||||
kubectl -n sso get deployments
|
||||
kubectl -n mfa get deployments
|
||||
kubectl -n user-engine get deployments
|
||||
kubectl -n tenant-engine get deployments
|
||||
kubectl -n flex-auth get deployments
|
||||
kubectl -n openbao get statefulsets,deployments,services,ingresses
|
||||
kubectl get clusters.postgresql.cnpg.io -A
|
||||
```
|
||||
|
||||
## NetworkPolicy design
|
||||
Ready replicas do not prove negative authorization, actual-user MFA, successful
|
||||
backup restoration or independent failure domains. Use the relevant owner's
|
||||
verification and recovery procedure for those claims.
|
||||
|
||||
All three namespaces follow a default-deny-all posture. Only the minimal
|
||||
required paths are opened:
|
||||
## Deployment and recovery
|
||||
|
||||
| Source | Destination | Port | Purpose |
|
||||
|--------|-------------|------|---------|
|
||||
| Traefik (kube-system) | KeyCape (sso) | 8080 | OIDC endpoints — public |
|
||||
| Traefik (kube-system) | Authelia (sso) | 9091 | Login portal — public |
|
||||
| Traefik (kube-system) | LLDAP (sso) | 17170 | Admin web UI — IP-restricted |
|
||||
| Traefik (kube-system) | privacyIDEA (mfa) | 8080 | MFA portal — public |
|
||||
| KeyCape (sso) | Authelia (sso) | 9091 | OIDC token exchange |
|
||||
| KeyCape (sso) | LLDAP (sso) | 3890 | User attribute lookup |
|
||||
| KeyCape (sso) | privacyIDEA (mfa) | 8080 | MFA challenge + validation |
|
||||
| Authelia (sso) | LLDAP (sso) | 3890 | Credential validation |
|
||||
| privacyIDEA (mfa) | PostgreSQL (databases) | 5432 | DB |
|
||||
| CNPG operator (cnpg-system) | PostgreSQL (databases) | 5432/9187 | Operator + metrics |
|
||||
| All pods | kube-dns (kube-system) | 53 | DNS resolution |
|
||||
| CNPG pods | K8s API | 6443 | Status updates |
|
||||
Start with the owning package's current declaration, immutable image and
|
||||
reviewed rollout/rollback procedure. Do not recursively apply this tree.
|
||||
`tenant-engine/runtime.yaml` remains **REFERENCE ONLY — DO NOT APPLY** while
|
||||
its owner decides the disposition of the five retained historical objects.
|
||||
Its obsolete flex-auth objects have been replaced with owner pointers.
|
||||
|
||||
## Verifying denied paths (manual)
|
||||
The scripts and manifests elsewhere in this directory have individual scopes;
|
||||
their presence here does not make them current production repair commands.
|
||||
The [attended procedure inventory](../../docs/attended-procedure-inventory.md)
|
||||
records their exercise limits. Use the [custody model](../../docs/openbao-unseal-custody-models.md)
|
||||
and current owner runbooks to prepare recovery. A database-only drill does not
|
||||
prove restoration of LLDAP, Authelia, privacyIDEA and its matching encryption
|
||||
material, or all identity database state.
|
||||
|
||||
After applying NetworkPolicies, confirm that illegal paths are blocked:
|
||||
|
||||
```bash
|
||||
# Test: KeyCape → privacyIDEA (should be ALLOWED)
|
||||
kubectl run test-allowed -n sso --rm -it --image=busybox --restart=Never \
|
||||
-- nc -zv privacyidea.mfa.svc.cluster.local 8080
|
||||
|
||||
# Test: Authelia → privacyIDEA (should be DENIED — only KeyCape calls privacyIDEA)
|
||||
kubectl run test-denied -n sso --rm -it --image=busybox --restart=Never \
|
||||
-l app.kubernetes.io/name=authelia \
|
||||
-- nc -zv -w3 privacyidea.mfa.svc.cluster.local 8080
|
||||
|
||||
# Test: databases → sso (should be DENIED — DB pods must not initiate connections)
|
||||
kubectl run test-denied2 -n databases --rm -it --image=busybox --restart=Never \
|
||||
-- nc -zw3 keycape.sso.svc.cluster.local 8080
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- `net-kingdom/component` labels on namespaces are used by NetworkPolicy
|
||||
`namespaceSelector` rules. Do not remove them.
|
||||
- `cnpg.io/cluster: net-kingdom-pg` in `netpol-databases.yaml` must match
|
||||
the name of the CloudNativePG `Cluster` CR you create in T03.
|
||||
- The `letsencrypt-prod` ClusterIssuer requires public DNS and port 80 open
|
||||
to Let's Encrypt servers. Update `ACME_EMAIL` before applying.
|
||||
CoulombCore identity cutover is complete; final retained-resource deletion
|
||||
remains gated by [NK-WP-0022](../../workplans/NK-WP-0022-railiance01-identity-cutover-and-coulombcore-retirement.md).
|
||||
Expiration of the retention minimum does not authorize deletion.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue