Status
Proposed
Context
The UI currently loads runtime configuration during pod startup using an initContainer that retrieves a JSON file from AWS SSM Parameter Store.
Flow:
Pod start → initContainer → SSM → write file → UI container
This works for small scale but introduces external dependencies during startup and increases rollout latency.
As the platform grows, this creates reliability and scalability risks.
The system runs on Amazon EKS and uses IRSA for IAM access.
Problem
The current approach has the following issues:
- Cold start latency for every pod
- Slower rollouts and scale-out events
- Potential SSM throttling
- Startup depends on external control plane
- Extra operational complexity (aws-cli, scripts, retries)
Kubernetes best practice:
Pods should not depend on external services during startup.
Decision
Adopt the Secrets Store CSI Driver with AWS provider to mount configuration directly from SSM into the pod filesystem.
Components:
- Secrets Store CSI Driver
- AWS SSM Parameter Store
- IRSA
- SecretProviderClass
New flow:
Pod start → CSI mounts file → UI starts instantly
No initContainers.
Rationale
Benefits:
- Zero startup latency
- No external dependency during startup
- Native Kubernetes integration
- Fewer moving parts
- Better reliability
- Enterprise standard pattern
- Cleaner manifests
Alternatives Considered
InitContainer
Rejected — startup blocking, throttling risk
Sidecar cache
Acceptable — but adds extra container complexity
S3 mount/EFS
Rejected — overkill and not designed for config
CSI Driver (selected)
Chosen — cleanest and most scalable
Consequences
Positive
- Faster rollouts
- Faster autoscaling
- More resilient
- Simpler code
- Better operational posture
Negative
- Additional cluster add-on (CSI)
- Slight setup complexity
Implementation Plan
- Install CSI driver
- Install AWS provider
- Create IRSA role
- Store config in SSM
- Mount via SecretProviderClass
- Remove initContainer
Review Date
Re-evaluate if configuration size grows beyond SSM limits or large files are required.
Status
Proposed
Context
The UI currently loads runtime configuration during pod startup using an initContainer that retrieves a JSON file from AWS SSM Parameter Store.
Flow:
Pod start → initContainer → SSM → write file → UI container
This works for small scale but introduces external dependencies during startup and increases rollout latency.
As the platform grows, this creates reliability and scalability risks.
The system runs on Amazon EKS and uses IRSA for IAM access.
Problem
The current approach has the following issues:
Kubernetes best practice:
Pods should not depend on external services during startup.
Decision
Adopt the Secrets Store CSI Driver with AWS provider to mount configuration directly from SSM into the pod filesystem.
Components:
New flow:
Pod start → CSI mounts file → UI starts instantly
No initContainers.
Rationale
Benefits:
Alternatives Considered
InitContainer
Rejected — startup blocking, throttling risk
Sidecar cache
Acceptable — but adds extra container complexity
S3 mount/EFS
Rejected — overkill and not designed for config
CSI Driver (selected)
Chosen — cleanest and most scalable
Consequences
Positive
Negative
Implementation Plan
Review Date
Re-evaluate if configuration size grows beyond SSM limits or large files are required.