Multi-Stage Environments
Summary
Keymate supports multi-stage environment management, allowing you to run separate development, staging, and production instances with isolated configuration. You promote changes through stages in a controlled workflow, ensuring that you validate production deployments before they reach end users. This model works with both Helm-based and GitOps-based deployment paths.
Why It Exists
Deploying changes directly to production without intermediate validation stages creates unacceptable risk for enterprise IAM platforms. A misconfigured authorization policy or a broken identity provider update can lock users out of critical systems. Multi-stage environments provide the safety net: test in dev, validate in staging, deploy to production with confidence.
Where It Fits in Keymate
Multi-Stage Environments is a deployment model that applies on top of the base deployment path (Kubernetes Native or GitOps with ArgoCD). The practical setup is covered in Multi-Environment Management.
Boundaries
This page covers:
- Why multi-stage environments matter for Keymate
- The recommended stage structure and purpose of each stage
- How environment isolation works
- How promotion workflows move changes between stages
This page does not cover:
- Step-by-step environment setup (see Multi-Environment Management)
- Configuration override model (see Customization Overview)
How It Works
Recommended Stage Structure
| Stage | Purpose | Who uses it |
|---|---|---|
| Development | Rapid iteration, feature testing, debugging | Developers, platform engineers |
| Staging | Pre-production validation, integration testing, release candidates | QA, platform engineers, product |
| Production | Live environment serving end users | End users, operators |
Environment Isolation
Each stage runs independently. Changes in one stage do not affect other stages.
| Isolation aspect | How it works |
|---|---|
| Configuration | Each stage has its own configuration overrides (see Customization Overview) |
| Data | Each stage has its own databases and data stores — no shared state between stages |
| Networking | Each stage operates on its own domain and network configuration |
| Scaling | Each stage has independent resource allocation and replica counts |
Promotion Workflow
Changes move through stages in order: development → staging → production.
For GitOps deployments: Promotion is a Git operation — pull request from the dev configuration to staging, then from staging to production. ArgoCD applies changes automatically after merge.
For Helm deployments: Promotion is an explicit helm upgrade using the next stage's values file after validation in the current stage.
Example Scenario
Scenario
Acme Corp needs to update the authorization policy structure for their Keymate deployment. The change must be tested before reaching production users.
Input
- Actor: Platform Engineer
- Change: Updated authorization policy configuration
- Stages: dev, staging, production
Expected Outcome
- The engineering team applies the change to dev and validates it
- After dev validation, the team promotes the change to staging where QA tests it
- After staging approval, the team promotes the change to production with no disruption to end users
- Each stage remains independent throughout the process
Common Misunderstandings
- "I can promote only configuration changes." Both configuration changes and component version upgrades follow the same promotion workflow.
- "Staging must match production exactly." Keep staging structurally similar to production, but feel free to differ in scale (fewer replicas, smaller resource limits). The goal is to validate behavior, not replicate exact capacity.
- "Multi-stage is only for GitOps." Multi-stage environments work with both Helm and GitOps deployment paths.
Design Notes
- The number of stages is flexible. Some organizations add QA, performance testing, or canary stages between staging and production.
- Each stage can serve multiple Tenants. Tenant isolation operates within each stage independently.
- The promotion workflow is the primary quality gate. Treat it as a pipeline with validation at each step, not as a manual copy operation.