Skip to content

README.md

Latest commit

 

History

History
177 lines (131 loc) · 6.17 KB

README.md

File metadata and controls

177 lines (131 loc) · 6.17 KB
Raw

Configuration Files

This directory contains Kubernetes manifests and configuration files for the Stellar-K8s operator.

Directory Structure

config/
├── crd/              # Custom Resource Definitions (generated from src/crd/)
│   ├── stellarnode-crd.yaml
│   ├── stellarautoscaler-crd.yaml
│   ├── stellardr-crd.yaml
│   ├── stellarfederation-crd.yaml
│   ├── stellargitopsconfig-crd.yaml
│   ├── stellarobservability-crd.yaml
│   ├── stellarsecuritypolicy-crd.yaml
│   ├── stellarupgrade-crd.yaml
│   ├── stellarbenchmark-crd.yaml
│   ├── stellaraiops-crd.yaml
│   ├── stellarbenchmarkreport-crd.yaml
├── samples/          # Example resources for testing and reference
├── manifests/        # OLM ClusterServiceVersion bases and Gatekeeper policies
│   ├── bases/        # CSV base for operator-sdk bundle generation
│   └── gatekeeper/   # OPA Gatekeeper constraint templates and policies
├── dev/              # Development configuration (NOT for production)
│   └── kubeconfig-dev.yaml
├── operator-config.yaml   # Default operator ConfigMap — single source of truth for runtime defaults
└── custom-metrics-apiservice.yaml  # APIService for the custom metrics adapter

Configuration Defaults

config/operator-config.yaml is the single source of truth for operator runtime defaults. It is mounted as a ConfigMap at /etc/stellar-operator/config.yaml inside the operator pod.

The Helm chart (charts/stellar-operator/values.yaml) surfaces the same defaults as Helm values so they can be overridden at deploy time. The values file delegates to this file — do not define a default in both places without cross-referencing them.

Default Hierarchy

When a value is set in multiple places, the following precedence applies (highest wins):

Environment variable
  └── Helm values override (--set or values.yaml override file)
        └── charts/stellar-operator/values.yaml defaults
              └── config/operator-config.yaml (ConfigMap)
                    └── Rust struct Default impl (compile-time fallback)

Key Defaults at a Glance

Setting Default Location
Reconcile requeue interval 60 s reconciler.requeueInterval
Error backoff base 15 s reconciler.errorBackoffBase
Maximum backoff 300 s reconciler.maxBackoff
Backoff jitter enabled reconciler.enableJitter
Disk expansion threshold 80 % diskScaling.expansionThreshold
Disk expansion increment 50 % diskScaling.expansionIncrement
Minimum expansion interval 3600 s diskScaling.minExpansionInterval
Anomaly detection interval 30 s anomalyDetection.intervalSeconds
Validator CPU request 500m defaultResources.validator.requests.cpu
Validator memory limit 4Gi defaultResources.validator.limits.memory
Horizon CPU request 250m defaultResources.horizon.requests.cpu
Soroban RPC memory limit 8Gi defaultResources.sorobanRpc.limits.memory

To change a default for all deployments, update config/operator-config.yaml. To override for a specific Helm release, add the key to your values-override.yaml file.

Regenerating CRDs

CRD YAML files under config/crd/ are generated from the Rust type definitions in src/crd/. Do not hand-edit the generated CRD files. Modify the Rust types and then regenerate.

# Regenerate all CRDs from Rust type definitions
make crd-gen

After regenerating, commit both the source change and the updated CRD file in the same PR.

Tracing a Deployed Manifest Back to Its Source

Deployed CRD in cluster
  └── config/crd/stellar{feature}-crd.yaml     (generated YAML)
        └── src/crd/stellar_{feature}.rs        (Rust type + schemars annotations)
              └── #[derive(CustomResource, JsonSchema)]

To inspect the generated schema for a specific CRD:

kubectl get crd stellarnodes.stellar.org -o yaml
# Compare with: config/crd/stellarnode-crd.yaml

Regenerating the OLM Bundle

The bundle/ directory contains the Operator Lifecycle Manager (OLM) bundle, generated by operator-sdk. The bundle is derived from config/manifests/bases/ and the current CRDs.

# Requires operator-sdk >= 1.28
make bundle VERSION=0.1.0

# Validate the generated bundle
operator-sdk bundle validate ./bundle

bundle/manifests/stellar-operator.clusterserviceversion.yaml is fully generated and is gitignored — regenerate it locally with make bundle before running operator-sdk bundle validate or make bundle-build. Only bundle/metadata/annotations.yaml (hand-written channel and package metadata) is committed.

Usage

Install CRDs

kubectl apply -f config/crd/

Benchmark workloads require the canonical benchmark CRDs (not bundled in the Helm chart):

kubectl apply -f config/crd/stellarbenchmark-crd.yaml
kubectl apply -f config/crd/stellarbenchmarkreport-crd.yaml

Apply Sample Resources

kubectl apply -f config/samples/

Apply the Operator ConfigMap

kubectl create namespace stellar-system
kubectl apply -f config/operator-config.yaml -n stellar-system

Enable the Custom Metrics API

Required for the Horizon HPA to read stellar_horizon_tps and stellar_horizon_queue_length:

kubectl apply -f config/custom-metrics-apiservice.yaml

Development

# Use the development kubeconfig
export KUBECONFIG=config/dev/kubeconfig-dev.yaml

Important Notes

  • CRD files: Generated — do not hand-edit. Run make crd-gen after changing Rust types.
  • operator-config.yaml: The canonical source for runtime defaults. Helm values mirror these; update both consistently.
  • Sample files: Example configurations for testing and reference. Use them to verify CRD installs correctly.
  • Dev files: Local development configurations only. Never commit secrets here; add them to .gitignore if needed.
  • Gatekeeper policies (config/manifests/gatekeeper/): OPA policy library. See docs/gatekeeper-policies.md for usage.