Skip to content

Commit fb9bff2

Browse files
OtowoSamuelOtowoSamuel
authored
Merge pull request #955 from trinnode/feat/cleanup-docs-tests-feature-flags
Cleanup: docs regeneration guide, credentials centralization, e2e smoke tests, feature flag reduction
2 parents ce51f99 + 2e2a042 commit fb9bff2

12 files changed

Lines changed: 777 additions & 23 deletions

‎Cargo.toml‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -167,19 +167,18 @@ serde = { version = "1", features = ["derive"] }
167167

168168
[features]
169169
default = ["rest-api", "metrics", "admission-webhook", "k8s-v1-30"]
170-
rest-api = ["axum", "tower", "tower-http"]
170+
rest-api = ["dep:axum", "dep:tower", "dep:tower-http"]
171171
metrics = ["prometheus-client", "once_cell"]
172172
kafka = ["dep:rdkafka", "dep:sasl2-sys"]
173173
nats = ["dep:async-nats"]
174174
admission-webhook = [
175175
"wasmtime",
176176
"wasmtime-wasi",
177177
"tokio-rustls",
178-
"axum",
179-
"tower",
180-
"tower-http",
178+
"dep:axum",
179+
"dep:tower",
180+
"dep:tower-http",
181181
]
182-
axum = ["dep:axum"]
183182
# Expose reconciler for state-machine fuzzing (reconcile_no_panic, event sequences)
184183
reconciler-fuzz = []
185184

‎DEVELOPMENT.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -767,15 +767,18 @@ Run `make health` first — it executes format, lint, tests, and docs checks in
767767

768768
## Regenerating Manifests
769769

770-
Several files in this repo are generated from a source of truth. Always regenerate them after changing the source.
770+
Several files in this repo are generated from a source of truth. Always regenerate them after changing the source. See the [Regeneration Guide](docs/development/regeneration-guide.md) for detailed instructions.
771771

772772
| Generated file | Source of truth | Regeneration command |
773773
|---|---|---|
774774
| `docs/api-reference.md` | CRD types in `src/crd/` | `make generate-api-docs` |
775775
| `config/crd/*.yaml` | CRD structs in `src/crd/` | `make crd-gen` |
776776
| `bundle/manifests/*.yaml` | `config/manifests/bases/` + operator metadata | `make bundle` (requires operator-sdk) |
777+
| `charts/stellar-operator/templates/*.yaml` | Hand-written (see [guide](docs/development/regeneration-guide.md)) | `helm template` for validation |
777778
| Shell completions | CLI definitions in `src/cli.rs` | `make completions` |
778779

780+
For detailed instructions on each regeneration step, see the [Regeneration Guide](docs/development/regeneration-guide.md).
781+
779782
After running any of the above, commit the updated generated file alongside the source change in the same PR.
780783

781784
---

‎docs/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,11 +61,13 @@ Production-grade Stellar infrastructure on Kubernetes. This directory contains a
6161

6262
## Security
6363

64-
- [mTLS Guide](mtls-guide.md)
64+
- [Credentials and Secrets (Central Reference)](security/credentials-and-secrets.md)
65+
- [Secret Management Guide](secret-management-guide.md)
6566
- [Secret Rotation](secret-rotation.md)
6667
- [Secret Management (KMS)](secret-management-kms.md)
6768
- [Vault Tutorial](vault-stellar-tutorial.md)
6869
- [Production Security Hardening](production-security-hardening.md)
70+
- [mTLS Guide](mtls-guide.md)
6971
- [Gatekeeper Policies](gatekeeper-policies.md)
7072
- [Pod Security Standards](security/pss.md)
7173
- [Image Pinning](image-pinning.md)

‎docs/development/regeneration-guide.md‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# Regenerating Charts and Bundle Manifests
2+
3+
Several files in this repository are **generated** and must never be hand-edited. This guide documents how to regenerate Helm charts and OLM bundle manifests from their sources of truth.
4+
5+
## Overview
6+
7+
| Generated artifact | Source of truth | Command |
8+
|---|---|---|
9+
| Helm chart templates (`charts/stellar-operator/templates/`) | `src/` Rust types + `config/` manifests | `helm template` or `make crd-gen` |
10+
| CRD YAML (`config/crd/*.yaml`) | `src/crd/` Rust structs | `make crd-gen` |
11+
| OLM bundle (`bundle/manifests/`, `bundle/metadata/`) | `config/manifests/bases/` | `make bundle` |
12+
| API reference docs (`docs/api-reference.md`) | `src/crd/` + `scripts/generate-api-docs.py` | `make generate-api-docs` |
13+
14+
## Prerequisites
15+
16+
| Tool | Version | Required for |
17+
|---|---|---|
18+
| [operator-sdk](https://sdk.operatorframework.io/docs/installation/) | >= 1.42.0 | Bundle generation |
19+
| [kustomize](https://kustomize.io/) | >= 5.x | Bundle generation |
20+
| [helm](https://helm.sh/) | >= 3.x | Chart rendering |
21+
| Python 3 | >= 3.12 | API docs generation |
22+
23+
```bash
24+
# Verify installed tools
25+
operator-sdk version
26+
kustomize version
27+
helm version
28+
python3 --version
29+
```
30+
31+
---
32+
33+
## Regenerating CRD Manifests
34+
35+
The StellarNode CRD and all other CRDs are generated from Rust types in `src/crd/`.
36+
37+
```bash
38+
make crd-gen
39+
```
40+
41+
This runs the `crdgen` binary which reads the `#[derive(JsonSchema)]` annotated structs and outputs updated CRD YAML files to `config/crd/`.
42+
43+
> **Note:** After modifying any `src/crd/*.rs` file, always run `make crd-gen` and commit the updated CRD alongside your Rust changes. The CI pipeline will fail if CRDs are stale.
44+
45+
---
46+
47+
## Regenerating the OLM Bundle
48+
49+
The Operator Lifecycle Manager (OLM) bundle is generated from the Kustomize bases in `config/manifests/`.
50+
51+
### Step-by-step
52+
53+
```bash
54+
# 1. Generate OLM manifests from Helm chart + bases
55+
make bundle
56+
57+
# 2. Validate the generated bundle
58+
operator-sdk bundle validate ./bundle
59+
60+
# 3. (Optional) Build the bundle container image
61+
make bundle-build
62+
```
63+
64+
The `make bundle` target performs these steps internally:
65+
66+
1. Renders the Helm chart to raw manifests: `helm template stellar-operator charts/stellar-operator`
67+
2. Generates Kustomize manifests: `operator-sdk generate kustomize manifests -q`
68+
3. Produces the OLM bundle: `kustomize build config/manifests | operator-sdk generate bundle -q --overwrite --version $(VERSION)`
69+
4. Validates the bundle structure with `operator-sdk bundle validate`
70+
71+
### Bundle structure
72+
73+
```
74+
bundle/
75+
├── manifests/
76+
│ └── stellar-operator.clusterserviceversion.yaml # ClusterServiceVersion
77+
└── metadata/
78+
└── annotations.yaml # Bundle annotations
79+
```
80+
81+
### Customizing bundle metadata
82+
83+
Edit these files directly (they are **not** auto-generated):
84+
85+
| File | Purpose |
86+
|---|---|
87+
| `bundle/metadata/annotations.yaml` | Channel, package name, mediatype |
88+
| `config/manifests/bases/stellar-operator.clusterserviceversion.yaml` | CSV base (descriptor, icon, maintainer) |
89+
90+
After editing, run `make bundle` to regenerate the full CSV.
91+
92+
---
93+
94+
## Regenerating the Helm Chart
95+
96+
The Helm chart in `charts/stellar-operator/` is **hand-written** for the most part, but some components are derived from code:
97+
98+
### Chart templates that are hand-written
99+
100+
| Template | Description |
101+
|---|---|
102+
| `deployment.yaml` | Operator Deployment spec |
103+
| `rbac.yaml` | ClusterRole, ClusterRoleBinding, Role, RoleBinding |
104+
| `service.yaml` | Service definition |
105+
| `serviceaccount.yaml` | ServiceAccount |
106+
| `secret.yaml` | Kubernetes Secret |
107+
| `externalsecret.yaml` | External Secrets Operator integration |
108+
| `configmap.yaml` | Operator ConfigMap |
109+
| `webhook.yaml` | Admission webhook configuration |
110+
| `pdb.yaml` | PodDisruptionBudget |
111+
| `hpa-*.yaml` | Horizontal Pod Autoscalers |
112+
| `otel-collector.yaml` | OpenTelemetry sidecar |
113+
| `scp-kafka-sidecar.yaml` | SCP Kafka sidecar |
114+
| `byzantine-watcher.yaml` | Byzantine monitoring |
115+
| `fork-detector.yaml` | Fork detection |
116+
| `network-isolation.yaml` | Network policies |
117+
118+
### Testing chart changes
119+
120+
After modifying any template or `values.yaml`:
121+
122+
```bash
123+
# Lint the chart
124+
make helm-lint
125+
126+
# Validate against JSON schema
127+
helm lint charts/stellar-operator --strict
128+
129+
# Render and inspect output
130+
helm template stellar-operator charts/stellar-operator > /tmp/rendered.yaml
131+
132+
# Run Helm unit tests
133+
helm unittest charts/stellar-operator --strict --color
134+
```
135+
136+
### Updating Chart.yaml
137+
138+
| Field | Source | When to update |
139+
|---|---|---|
140+
| `version` | Manual | On each release / breaking chart change |
141+
| `appVersion` | Manual | When the operator image version changes |
142+
| `dependencies` | Manual | When adding new chart dependencies |
143+
144+
---
145+
146+
## Regenerating API Reference Docs
147+
148+
```bash
149+
make generate-api-docs
150+
```
151+
152+
This regenerates `docs/api-reference.md` from the CRD schema. The CI job `api-docs` in `.github/workflows/ci.yml` will fail if this file is stale.
153+
154+
---
155+
156+
## Testing Generated Assets in CI
157+
158+
The CI pipeline automatically validates generated files:
159+
160+
1. **CRD freshness** — the `api-docs` job regenerates `docs/api-reference.md` and fails if `git diff` shows changes
161+
2. **Helm chart correctness** — `helm-lint` and `helm-test` jobs validate chart syntax and run unit tests
162+
3. **Bundle validity** — `make bundle` validates with `operator-sdk bundle validate`
163+
164+
When making PR changes, always run:
165+
166+
```bash
167+
make crd-gen # Regenerate CRDs if Rust types changed
168+
make bundle # Regenerate OLM bundle if bases changed
169+
make generate-api-docs # Regenerate API docs if CRD schema changed
170+
make helm-lint # Validate Helm chart
171+
```
172+
173+
Commit all regenerated files in the same PR as the source change.
174+
175+
---
176+
177+
## Troubleshooting
178+
179+
### `operator-sdk` not found
180+
181+
```bash
182+
# Install operator-sdk (Linux / macOS / WSL2)
183+
export ARCH=$(case $(uname -m) in x86_64) echo -n amd64 ;; aarch64) echo -n arm64 ;; esac)
184+
export OS=$(uname | awk '{print tolower($0)}')
185+
export OPERATOR_SDK_DL_URL=https://github.com/operator-framework/operator-sdk/releases/download/v1.42.0
186+
curl -LO ${OPERATOR_SDK_DL_URL}/operator-sdk_${OS}_${ARCH}
187+
chmod +x operator-sdk_${OS}_${ARCH} && sudo mv operator-sdk_${OS}_${ARCH} /usr/local/bin/operator-sdk
188+
```
189+
190+
### `kustomize` not found
191+
192+
```bash
193+
# Install kustomize
194+
curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
195+
sudo mv kustomize /usr/local/bin/
196+
```
197+
198+
### Bundle validation fails
199+
200+
```bash
201+
# Check the specific validation errors
202+
operator-sdk bundle validate ./bundle --verbose
203+
204+
# Common fixes:
205+
# - Ensure CRD YAML files exist in bundle/manifests/
206+
# - Verify CSV metadata (displayName, description, installModes)
207+
# - Check that all referenced images are valid
208+
```
209+
210+
### Helm unit tests fail
211+
212+
```bash
213+
# Install helm-unittest plugin
214+
helm plugin install https://github.com/helm-unittest/helm-unittest.git
215+
216+
# Run with verbose output
217+
helm unittest charts/stellar-operator --strict --color -v
218+
```

‎docs/secret-management-guide.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Secret Management Guide
22

3+
> **See also:** [Credentials & Secrets (Central Reference)](security/credentials-and-secrets.md) for a complete index of all secret-related documentation.
4+
35
Declarative secret management via the `StellarSecret` CRD with dynamic credentials,
46
automatic rotation, KMS encryption, and multi-backend support.
57

‎docs/secret-management-kms.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Advanced Secret Management with External KMS
22

3+
> **See also:** [Credentials & Secrets (Central Reference)](security/credentials-and-secrets.md) for a complete index of all secret-related documentation.
4+
35
Declarative secret management via the `SecretPolicy` CRD with AWS KMS, Azure Key Vault,
46
GCP Cloud KMS integrations, automatic rotation, and cross-cluster sync.
57

‎docs/secret-rotation.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Automated Secret Rotation for Database Credentials
22

3+
> **See also:** [Credentials & Secrets (Central Reference)](security/credentials-and-secrets.md) for a complete index of all secret-related documentation.
4+
35
## Overview
46

57
Stellar-K8s provides automated rotation of PostgreSQL database passwords for Stellar Core and Horizon nodes, ensuring zero-downtime credential updates and enhanced security posture.

‎docs/security/credentials-and-secrets.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Credentials and Secrets Management
2+
3+
Central reference for all credential and secret management documentation in Stellar-K8s.
4+
5+
## Overview
6+
7+
Stellar-K8s supports multiple strategies for managing sensitive credentials, from basic Kubernetes Secrets to external KMS providers with automatic rotation. The right choice depends on your security requirements, compliance needs, and operational maturity.
8+
9+
## Quick Reference
10+
11+
| Topic | Doc | Use case |
12+
|---|---|---|
13+
| Basic secret management | [Secret Management Guide](../secret-management-guide.md) | Getting started with `StellarSecret` CRD |
14+
| KMS integration | [Advanced Secret Management with KMS](../secret-management-kms.md) | AWS KMS, Azure Key Vault, GCP Cloud KMS |
15+
| Automated rotation | [Secret Rotation](../secret-rotation.md) | Zero-downtime database credential rotation |
16+
| HashiCorp Vault | [Vault + Stellar Tutorial](../vault-stellar-tutorial.md) | Production Vault Agent Injector pattern |
17+
| Production hardening | [Security Hardening Guide](../production-security-hardening.md) | Full security posture for production |
18+
| External Secrets Operator | [ExternalSecret chart template](../../charts/stellar-operator/templates/externalsecret.yaml) | ESO integration via Helm |
19+
20+
## Secret Types
21+
22+
| Secret | Storage | Rotation | Source |
23+
|---|---|---|---|
24+
| Validator seed (`STELLAR_SEED`) | Kubernetes Secret / Vault | Manual or `vaultRef` | Wallet / Stellar Core |
25+
| Database credentials (Horizon / Core) | Kubernetes Secret | Automatic (cron-based) | Generated / Provided |
26+
| mTLS certificates | Kubernetes Secret (operator-managed) | Automatic renewal | Operator CA |
27+
| Webhook HMAC key | Kubernetes Secret | Manual | Deployer |
28+
| API tokens / OIDC secrets | Kubernetes Secret / ExternalSecret | Manual or ESO | Identity provider |
29+
| S3 / cloud credentials | Kubernetes Secret / IRSA | Cloud IAM rotation | Cloud provider |
30+
31+
## Architecture Overview
32+
33+
```
34+
┌──────────────────────────────────┐
35+
│ Credential Sources │
36+
├──────────────────────────────────┤
37+
│ Kubernetes Secrets (static) │
38+
│ External Secrets (ESO) │
39+
│ Vault Agent (injector) │
40+
│ KMS backends (AWS/Azure/GCP) │
41+
└──────────┬───────────────────────┘
42+
│
43+
┌──────────▼───────────────────────┐
44+
│ Consumption Methods │
45+
├──────────────────────────────────┤
46+
│ Environment variables │
47+
│ Volume mounts (files) │
48+
│ Sidecar injection │
49+
│ Direct API (Vault Agent) │
50+
└──────────┬───────────────────────┘
51+
│
52+
┌──────────▼───────────────────────┐
53+
│ Lifecycle Management │
54+
├──────────────────────────────────┤
55+
│ Automatic rotation (cron) │
56+
│ Zero-downtime updates │
57+
│ Version rollback │
58+
│ Immutable audit trail │
59+
└──────────────────────────────────┘
60+
```
61+
62+
## Security Principles
63+
64+
1. **Secrets are never logged** — The operator redacts secret values from all log output
65+
2. **Least privilege** — Each component accesses only the secrets it needs
66+
3. **Encryption at rest** — Kubernetes Secrets are encrypted at the etcd level (recommended)
67+
4. **Encryption in transit** — All secret delivery uses TLS
68+
5. **Rotation** — Automated rotation limits the blast radius of credential leaks
69+
6. **Audit** — All secret access and rotation events are logged immutably
70+
71+
## Compliance Mapping
72+
73+
| Standard | Requirement | How Stellar-K8s addresses it |
74+
|---|---|---|
75+
| SOC 2 | Access control, credential management | RBAC + audit logging + rotation |
76+
| PCI DSS 8.2.4 | Change passwords every 90 days | Configurable cron-based rotation |
77+
| HIPAA §164.312 | Technical safeguards for access control | mTLS + KMS encryption + audit |
78+
| ISO 27001 A.9.4.3 | Password management system | Automated rotation + vault integration |
79+
80+
## Related Documentation
81+
82+
- [Production Security Hardening](../production-security-hardening.md)
83+
- [mTLS Guide](../mtls-guide.md)
84+
- [Pod Security Standards](pss.md)
85+
- [Gatekeeper Policies](../gatekeeper-policies.md)
86+
- [Image Pinning](../image-pinning.md)

‎docs/vault-stellar-tutorial.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Production-oriented HashiCorp Vault + Stellar validators
22

3+
> **See also:** [Credentials & Secrets (Central Reference)](security/credentials-and-secrets.md) for a complete index of all secret-related documentation.
4+
35
This tutorial matches the native **`vaultRef`** seed source on `StellarNode` (see [`src/crd/seed_secret.rs`](../src/crd/seed_secret.rs)) and the Vault Agent Injector sidecar pattern.
46

57
## 1. Install Vault with injector

0 commit comments

Comments
 (0)