The `stacks` and `stacks-instances` repositories form the core of a GitOps-based system for provisioning Edge Developer Platforms (EDP). They implement a template-instance pattern that enables the deployment of reusable platform components across different environments. The concept of "stacks" originates from the CNOE.io project (Cloud Native Operational Excellence), which can be traced through the evolutionary development from `edpbuilder` (derived from CNOE.io's `EDPbuilder`) to `infra-deploy`.
This declarative Stacks provisioning architecture is characterized by the following central properties:
### Complete Code Declaration
**Platform as Code**: All Kubernetes resources, Helm charts, and application manifests are declaratively versioned as YAML files. The entire platform topology is traceable in Git.
**Configuration as Code**: Environment-specific configurations are generated through template hydration, not manually edited. Gomplate transforms generic templates into concrete configurations.
### GitOps-Native Architecture
**Single Source of Truth**: Git is the sole source of truth for the desired state of all infrastructure and platform components.
**Declarative State Management**: ArgoCD continuously synchronizes the actual state with the desired state defined in Git. Deviations are automatically corrected.
**Audit Trail**: Every change to infrastructure or platform is documented through Git commits, with author, timestamp, and change description.
**Pull-based Deployment**: ArgoCD pulls changes from Git, rather than external systems requiring push access to the cluster. This significantly increases security.
### Template-Instance Separation
**DRY Principle (Don't Repeat Yourself)**: Common platform components are defined once as templates and reused for all environments.
**Environment Promotion**: New environments can be quickly created through template hydration. Consistency across environments is guaranteed.
**Centralized Maintainability**: Updates to stack definitions can be made centrally in the `stacks` repository and then selectively rolled out to instances.
**Customization Points**: Despite reuse, environment-specific customizations remain possible through values files and manifest overlays.
### Modular Composition
**Stack-based Architecture**: Platform capabilities are organized into independent, reusable stacks (core, otc, forgejo, observability).
**Selective Deployment**: Through the `STACKS` environment variable, only required components can be deployed selectively.
**Mix-and-Match**: Different stack combinations yield different platform profiles (Development, Production, Observability clusters).
**Pluggable Components**: New stacks can be added without modifying existing ones.
### Environment Agnosticism
**Cloud Provider Abstraction**: Templates are formulated generically. Provider-specific details are introduced through hydration.
**Multi-Cloud Ready**: The architecture supports various cloud providers (currently OTC, historically KIND, extensible to AWS/Azure/GCP).
**Environment Variables as Interface**: All environment-specific aspects are controlled through clearly defined environment variables.
**Portable Definitions**: Stack definitions can be ported between environments and even cloud providers.
### Self-Healing and Drift Detection
**Automated Reconciliation**: ArgoCD detects deviations from the desired state and corrects them automatically.
**Continuous Monitoring**: Permanent monitoring of cluster state compared to Git definition.
**Declarative State Recovery**: After failures or manual changes, the declared state is automatically restored.
**Sync Policies**: Configurable sync strategies (automated, manual, with pruning) per application.
### Secrets Management
**Secrets Outside Git**: Sensitive data is not stored in Git but generated at runtime or injected from secret stores.
**Generated Credentials**: Passwords, tokens, and secrets are generated during deployment and directly created as Kubernetes Secrets.
**Sealed Secrets Ready**: The architecture is compatible with Sealed Secrets or External Secrets Operators for encrypted secret storage in Git.
**Credential Rotation**: Secrets can be regenerated through re-deployment.
### Observability and Auditability
**Declarative Monitoring**: Observability stacks are part of the Platform-as-Code definition.
**Deployment History**: Complete history of all deployments and changes through Git log.
**ArgoCD UI**: Graphical representation of sync status and application topology.
**Infrastructure Events**: Terraform state changes and Terragrunt outputs document infrastructure changes.
### Idempotence and Reproducibility
**Idempotent Operations**: Repeated execution of the same declaration leads to the same result without side effects.
**Deterministic Builds**: Same input parameters (Git commit + environment variables) produce identical environments.
**Disaster Recovery**: Complete environments can be rebuilt from code without restoring backups.
**Testing in Production-Like Environments**: Development and staging environments are code-identical to production, only with different parameter values.
The `stacks` repository contains reusable template definitions for platform components. It serves as a central library of building blocks from which Edge Developer Platforms can be composed.
**edfbuilder.yaml**: The central bootstrap definition. This is an ArgoCD Application that references the `registry` directory and serves as the entry point for the entire platform provisioning.
**registry/**: Contains ArgoCD ApplicationSets that function as a meta-layer. Each file defines a category of stacks (e.g., core, forgejo, observability) and references the corresponding subdirectory in `stacks/`.
These placeholders are replaced with environment-specific values during the deployment phase.
## The stacks-instances Repository
### Purpose and Structure
The `stacks-instances` repository contains the materialized, environment-specific configurations. While `stacks` provides the blueprints, `stacks-instances` contains the actual deployment definitions for concrete environments.
```
stacks-instances/
└── otc/
├── osctest.t09.de/
│ ├── edfbuilder.yaml
│ ├── registry/
│ └── stacks/
├── backup-test-manu.t09.de/
│ ├── edfbuilder.yaml
│ ├── registry/
│ └── stacks/
└── ...
```
### Organizational Principle
The structure follows the schema `{cloud-provider}/{domain}/`:
- **cloud-provider**: Identifies the cloud environment (e.g., `otc` for Open Telekom Cloud)
- **domain**: The fully qualified domain name of the environment (e.g., `osctest.t09.de`)
Each environment replicates the structure of `stacks/template`, but with resolved template variables and environment-specific customizations.
### Usage by ArgoCD
ArgoCD synchronizes directly from this repository. Applications reference paths such as:
This enables true GitOps: every change to the configurations is traceable through Git commits and automatically synchronized by ArgoCD in the target environment.
The `infra-deploy` repository is the orchestration layer that coordinates both infrastructure and platform provisioning. It represents the evolution of `edpbuilder`, which was originally derived from the CNOE.io project's `EDPbuilder`.
### Two-Phase Provisioning
**Phase 1: Infrastructure Provisioning**
Uses Terragrunt Stacks (experimental feature) to provision cloud resources:
```
infra-deploy/
├── root.hcl
├── non-prod/
│ ├── tenant.hcl
│ ├── dns_zone/
│ │ ├── terragrunt.hcl
│ │ ├── terragrunt.stack.hcl
│ │ └── terragrunt.values.hcl
│ └── testing/
├── prod/
└── templates/
└── forgejo/
├── terragrunt.hcl
└── terragrunt.stack.hcl
```
Terragrunt Stacks provision:
- VPC and network segments
- Kubernetes clusters (CCE on OTC)
- Managed databases (RDS PostgreSQL)
- Load balancers and DNS entries
- Security groups and other cloud resources
**Phase 2: Platform Provisioning**
The script `scripts/edp-install.sh` executes the following steps:
**plan.yaml**: Terraform/Terragrunt plan preview without execution
**destroy.yaml**: Controlled teardown of environments
## Deployment Workflow
The complete provisioning process proceeds as follows:
1.**Initiation**: GitHub Actions workflow is triggered (manually or automatically)
2.**Environment Preparation**:
```bash
export CLUSTER_ENVIRONMENT=qa-stage
cd scripts
./new-otc-env.sh # Creates Terragrunt configuration if new
```
3.**Infrastructure Provisioning**:
```bash
./ensure-cluster.sh otc
# Internally executes:
# - ./ensure-otc-cluster.sh
# - terragrunt stack run apply
```
4.**Platform Provisioning**:
```bash
./edp-install.sh
# Executes:
# - Checkout of stacks
# - Gomplate hydration
# - Checkout/update of stacks-instances
# - Secrets generation
# - ArgoCD installation
# - Bootstrap of stacks
```
5.**ArgoCD Synchronization**: ArgoCD continuously reads from `stacks-instances` and synchronizes the desired state
## The CNOE.io Stacks Concept
The term "stacks" originates from the Cloud Native Operational Excellence (CNOE.io) project. The core idea is the composition of platform capabilities from modular, reusable building blocks.
### Principles
**Modularity**: Each stack is a self-contained unit with clear dependencies
**Composability**: Stacks can be freely combined to create different platform profiles
**Declarativeness**: All configurations are declarative and GitOps-capable
**Environment-agnostic**: Templates are generic; environment specifics are introduced through hydration
### Stack Selection and Combinations
The environment variable `STACKS` controls which components are deployed:
The platform deployment is the second part of the EDP installtaion. First there is the infrastructure setup, which ends with a created kubernetes cluster. Then the platform provisioning by the defined stacks is done. Both is runnable by the `deploy`pipelien in `infra-deploy`:
The green pipeline looks liek this:
### Local setup with 'kind'
It's also possible to just run the second part, the stcks provisionning. Then you need to have a kubernetes cluster already running, which is e.g. feasable by a local kind-cluster.
So imagine, you want to to the stacks 'core,observability' on your local machine. Then you can run the local entzr
