DevFW-CICD/website-and-documentation
23
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(orchestration);: WiP -IPCEICIS-6734
Some checks failed
Hugo Site Tests / test (push) Failing after 1s
Details
ci / build (push) Successful in 55s
Details

Browse source
This commit is contained in:
Stephan Lo 2025-11-24 00:54:31 +01:00
parent f452a5e663
commit ac1a2965f2
3 changed files with 1438 additions and 135 deletions
Download patch file Download diff file Expand all files Collapse all files

252
content/en/docs/components/orchestration/_index.md
View file

@ -1,28 +1,246 @@
---
title: "Orchestratiion"
title: "Orchestration"
linkTitle: "Orchestration"
weight: 10
description: >
Platform and infrastructure orchestration components.
Orchestration in the context of Platform Engineering - coordinating infrastructure, platform, and application delivery.
---
{{% alert title="Draft" color="warning" %}}
**Editorial Status**: This page is currently being developed.
## Overview
* **Jira Ticket**: [TICKET-6734](https://jira.telekom-mms.com/browse/IPCEICIS-6734)
* **Assignee**: Stephan
* **Status**: Draft
* **Last Updated**: YYYY-MM-DD
* **TODO**:
* [ ] Add detailed component description
* [ ] Include usage examples and code samples
* [ ] Add architecture diagrams
* [ ] Review and finalize content
{{% /alert %}}
Orchestration in the context of Platform Engineering refers to the coordinated automation and management of infrastructure, platform, and application components throughout their entire lifecycle. It is a fundamental concept that bridges the gap between declarative specifications (what should be deployed) and actual execution (how it is deployed).
The Orchestration manages platform and infrastructure provisioning, providing the foundation for the EDP deployment model.
## The Role of Orchestration in Platform Engineering
Platform Engineering has emerged as a discipline to improve developer experience and reduce cognitive load on development teams ([CNCF Platforms White Paper](https://tag-app-delivery.cncf.io/whitepapers/platforms/)). Orchestration is the central mechanism that enables this vision:
1. **Automation of Complex Workflows**: Orchestration coordinates multiple steps and dependencies automatically
2. **Consistency and Reproducibility**: Guaranteed, repeatable deployments across different environments
3. **Self-Service Capabilities**: Developers can independently orchestrate resources and deployments
4. **Governance and Compliance**: Centralized control over policies and best practices
### What Does Orchestration Do?
Orchestration systems perform the following tasks:
- **Workflow Coordination**: Coordination of complex, multi-step deployment processes
- **Dependency Management**: Resolution and management of dependencies between components
- **State Management**: Continuous monitoring and reconciliation between desired and actual state
- **Resource Provisioning**: Automatic provisioning of infrastructure and services
- **Configuration Management**: Management of configurations across different environments
- **Health Monitoring**: Monitoring the health of deployed resources
## Three Layers of Orchestration
In modern Platform Engineering, we distinguish three fundamental layers of orchestration:
### [Infrastructure Orchestration](infrastructure/)
Infrastructure Orchestration deals with the lowest level - the physical and virtual infrastructure layer. This includes:
- Provisioning of compute, network, and storage resources
- Cloud resource management (VMs, networking, storage)
- Infrastructure-as-Code deployment (Terraform, etc.)
- Bare metal and hypervisor management
**Target Audience**: Infrastructure Engineers, Cloud Architects
**Note**: Detailed documentation for Infrastructure Orchestration is maintained separately.
More details: [Infrastructure Orchestration →](infrastructure/)
### [Platform Orchestration](platform/)
Platform Orchestration focuses on deploying and managing the platform itself - the services and tools that development teams use. This includes:
- Installation and configuration of Kubernetes clusters
- Deployment of platform services (GitOps tools, Observability, Security)
- Management of platform components via Stacks
- Multi-cluster orchestration
**Target Audience**: Platform Engineering Teams, SRE Teams
**In IPCEI-CIS**: Platform orchestration is realized using the CNOE stack concept with ArgoCD and Forgejo.
More details: [Platform Orchestration →](platform/)
### [Application Orchestration](application/)
Application Orchestration concentrates on the deployment and lifecycle management of applications running on the platform. This includes:
- Deployment of microservices and containerized applications
- CI/CD pipeline orchestration
- Configuration management and secrets handling
- Application health monitoring and auto-scaling
**Target Audience**: Application Developers, DevOps Engineers
**In IPCEI-CIS**: Application orchestration uses Forgejo pipelines for CI/CD and ArgoCD for GitOps-based deployment.
More details: [Application Orchestration →](application/)
## GitOps as Orchestration Paradigm
A central approach in modern platform orchestration solutions is **GitOps**. GitOps uses Git repositories as the single source of truth for declarative infrastructure and applications:
- **Declarative Approach**: The desired state is defined in Git
- **Automatic Synchronization**: Controllers monitor Git and reconcile the live state
- **Audit Trail**: All changes are traceable in Git history
- **Rollback Capability**: Easy rollback through Git revert
### Continuous Reconciliation
An important concept is **continuous reconciliation**:
1. The orchestrator monitors both the source (Git) and the target (e.g., Kubernetes cluster)
2. Deviations trigger automatic corrective actions
3. Health checks validate that the desired state has been achieved
4. Drift detection warns of unexpected changes
## Orchestration Tools in IPCEI-CIS
Within the IPCEI-CIS platform, we utilize the [CNOE (Cloud Native Operational Excellence)](https://cnoe.io/) stack concept with the following orchestration components:
### ArgoCD
- **Continuous Delivery** for Kubernetes based on GitOps
- Synchronizes Kubernetes manifests from Git repositories
- Supports Helm Charts, Kustomize, Jsonnet, and plain YAML
- Multi-cluster deployment capabilities
- Application Sets for parameterized deployments
**Role in IPCEI-CIS**: ArgoCD is the central component for GitOps-based deployment management. After the initial bootstrapping phase, ArgoCD takes over the technical coordination of all components.
### Forgejo
- **Git Repository Management** and source control
- **CI/CD Pipelines** via Forgejo Actions (GitHub Actions compatible)
- **Developer Portal Capabilities** (initially planned, project discontinued)
- Package registry and artifact management
- Integration with ArgoCD for GitOps workflows
**Role in IPCEI-CIS**: Forgejo serves as the Git repository host and CI/CD engine. It was initially planned as a developer portal (similar to Backstage's role in other stacks) but this aspect was not fully realized before project completion.
**Note on Backstage**: In typical CNOE implementations, Backstage serves as the developer portal providing golden paths through software templates. IPCEI-CIS initially planned to use Forgejo for this purpose but the project concluded before full implementation.
### Terraform
- **Infrastructure-as-Code** provisioning
- Multi-cloud resource management
- State management for infrastructure
- Integration with Forgejo pipelines for automated deployment
**Role in IPCEI-CIS**: Terraform handles infrastructure provisioning at the infrastructure orchestration layer, integrated into automated workflows via Forgejo pipelines.
### CNOE Stacks Concept
- **Modular Platform Components** bundled as stacks
- Reusable, composable platform building blocks
- Version-controlled stack definitions
- GitOps-based stack deployment via ArgoCD
**Role in IPCEI-CIS**: The stacks concept from CNOE provides the structural foundation for platform orchestration, enabling modular deployment and management of platform components.
## The Orchestration Workflow
A typical orchestration workflow in the IPCEI-CIS platform:
```text
┌─────────────┐ ┌───────────┐ ┌───────────┐ ┌────────────┐
│ Developer │────▶│ Forgejo │────▶│ Git │────▶│ ArgoCD │
│ │ │ Pipelines│ │Repository │ │ │
└─────────────┘ └───────────┘ └───────────┘ └─────┬──────┘
│
▼
┌───────────────────────────────────────────────┐
│ │
│ Kubernetes Cluster(s) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Apps │ │Services │ │Resources │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
└───────────────────────────────────────────────┘
▲
│
┌────┴─────┐
│Terraform │
│ │
└──────────┘
```
**Workflow Steps**:
1. **Definition**: Developer defines application/infrastructure as code
2. **Commit**: Changes are committed to Forgejo Git repository
3. **CI Pipeline**: Forgejo Actions build, test, and package the application
4. **Sync**: ArgoCD detects changes and triggers deployment
5. **Provision**: Terraform orchestrates required cloud resources (if needed)
6. **Deploy**: Application is deployed to Kubernetes
7. **Monitor**: Continuous monitoring and health checks
8. **Reconcile**: Automatic correction on drift detection
## Benefits of Coordinated Orchestration
The integration of infrastructure, platform, and application orchestration provides crucial advantages:
- **Reduced Complexity**: Developers don't need to know all infrastructure details
- **Faster Time-to-Market**: Automated workflows accelerate deployments
- **Consistency**: Standardized patterns across all teams
- **Governance**: Central policies are automatically enforced
- **Scalability**: Platform teams can support many application teams
- **Self-Service**: Developers can provision services independently
- **Audit and Compliance**: Complete traceability through Git history
## Best Practices
Successful orchestration follows proven principles ([Platform Engineering Principles](https://platformengineering.org/blog/what-is-platform-engineering)):
1. **Platform as a Product**: Treat the platform as a product with focus on user experience
2. **Self-Service First**: Enable developers to use services autonomously
3. **Documentation**: Comprehensive documentation of golden paths
4. **Feedback Loops**: Continuous improvement through user feedback
5. **Thin Platform Layer**: Use managed services where possible instead of building everything
6. **Progressive Disclosure**: Offer different abstraction levels
7. **Focus on Common Problems**: Solve recurring problems centrally
8. **Treat Glue as Valuable**: Integration of different tools is valuable
9. **Clear Mission**: Define clear goals and responsibilities
## Avoiding Anti-Patterns
Common mistakes in platform orchestration ([How to fail at Platform Engineering](https://www.cncf.io/blog/2024/03/08/how-to-fail-at-platform-engineering/)):
- **Product Misfit**: Building platform without involving developers
- **Overly Complex Design**: Too many features and unnecessary complexity
- **Swiss Knife Syndrome**: Trying to solve all problems with one tool
- **Insufficient Documentation**: Missing or outdated documentation
- **Siloed Development**: Platform and development teams working in isolation
- **Stagnant Platform**: Platform not continuously evolved
## Sub-Components
* **Infrastructure Provisioning**: Low-level infrastructure deployment (infra-deploy, infra-catalogue)
* **Platform Provisioning**: Platform-level component deployment via Stacks
The orchestration component includes the following sub-areas:
- **[Infrastructure Orchestration](infrastructure/)**: Low-level infrastructure deployment and provisioning
- **[Platform Orchestration](platform/)**: Platform-level component deployment via Stacks
- **[Application Orchestration](application/)**: Application-level deployment and CI/CD
- **[Stacks](stacks/)**: Reusable component bundles and compositions
## Further Resources
### Fundamentals
- [CNCF Platforms White Paper](https://tag-app-delivery.cncf.io/whitepapers/platforms/) - Comprehensive paper on Platform Engineering
- [Platform Engineering Definition](https://platformengineering.org/blog/what-is-platform-engineering) - What is Platform Engineering?
- [Team Topologies](https://teamtopologies.com/) - Organizational structures for modern teams
### GitOps
- [GitOps Principles](https://opengitops.dev/) - Official GitOps principles
- [ArgoCD Documentation](https://argo-cd.readthedocs.io/) - ArgoCD documentation
### Tools
- [CNOE.io](https://cnoe.io/) - Cloud Native Operational Excellence Framework
- [Forgejo](https://forgejo.org/) - Self-hosted Git service with CI/CD
- [Terraform](https://www.terraform.io/) - Infrastructure as Code tool

828
content/en/docs/components/orchestration/application.md
View file

@ -3,126 +3,830 @@ title: "Application Orchestration"
linkTitle: "Application Orchestration"
weight: 30
description: >
Application-level component provisioning via Stacks
Application deployment via CI/CD pipelines and GitOps - Orchestrating application deployments
---
{{% alert title="Draft" color="warning" %}}
**Editorial Status**: This page is currently being developed.
* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
* **Assignee**: [Name or Team]
* **Status**: Draft
* **Last Updated**: YYYY-MM-DD
* **TODO**:
* [ ] Add detailed component description
* [ ] Include usage examples and code samples
* [ ] Add architecture diagrams
* [ ] Review and finalize content
{{% /alert %}}
## Overview
[Detailed description of the component - what it is, what it does, and why it exists]
Application Orchestration deals with the automation of application deployment and lifecycle management. It encompasses the entire workflow from source code to running application in production.
In the context of IPCEI-CIS, Application Orchestration includes:
- **CI/CD Pipelines**: Automated build, test, and deployment pipelines
- **GitOps Deployment**: Declarative application deployment via ArgoCD
- **Progressive Delivery**: Canary deployments, blue-green deployments
- **Application Configuration**: Environment-specific configuration management
- **Golden Paths**: Standardized deployment templates and workflows
### Target Audience
Application Orchestration is primarily for:
- **Application Developers**: Teams developing and deploying applications
- **DevOps Teams**: Teams responsible for deployment automation
- **Product Teams**: Teams responsible for application lifecycle
## Key Features
* [Feature 1]
* [Feature 2]
* [Feature 3]
### Automated CI/CD Pipelines
Forgejo Actions provides GitHub Actions-compatible CI/CD:
- **Build Automation**: Automatic building of container images
- **Test Automation**: Automated unit, integration, and E2E tests
- **Security Scanning**: Vulnerability scanning of dependencies and images
- **Artifact Publishing**: Publishing to container registries
- **Deployment Triggering**: Automatic deployment after successful build
### GitOps-based Deployment
ArgoCD enables declarative application deployment:
- **Declarative Configuration**: Applications defined as Kubernetes manifests
- **Automated Sync**: Automatic synchronization between Git and cluster
- **Rollback Capability**: Easy rollback to previous versions
- **Multi-Environment**: Consistent deployment across Dev/Test/Prod
- **Health Monitoring**: Continuous monitoring of application health
### Progressive Delivery
Support for advanced deployment strategies:
- **Canary Deployments**: Gradual rollout to subset of users
- **Blue-Green Deployments**: Zero-downtime deployments with instant rollback
- **A/B Testing**: Traffic splitting for feature testing
- **Feature Flags**: Dynamic feature enablement without deployment
### Configuration Management
Flexible configuration for different environments:
- **Environment Variables**: Configuration via environment variables
- **ConfigMaps**: Kubernetes-native configuration
- **Secrets Management**: Secure handling of sensitive data
- **External Secrets**: Integration with external secret stores (Vault, etc.)
## Purpose in EDP
[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
Application Orchestration is the core of developer experience in IPCEI-CIS Edge Developer Platform.
### Developer Self-Service
Developers can deploy applications independently:
- **Self-Service Deployment**: No dependency on operations team
- **Standardized Workflows**: Clear, documented deployment processes
- **Fast Feedback**: Quick feedback through automated pipelines
- **Environment Parity**: Consistent behavior across all environments
### Quality and Security
Automated checks ensure quality and security:
- **Automated Testing**: All changes are automatically tested
- **Security Scans**: Vulnerability scanning of dependencies and images
- **Policy Enforcement**: Automated policy checks (OPA, Kyverno)
- **Compliance**: Auditability of all deployments
### Efficiency and Productivity
Automation increases team efficiency:
- **Faster Time-to-Market**: Faster deployment of new features
- **Reduced Manual Work**: Automation of repetitive tasks
- **Fewer Errors**: Fewer manual mistakes through automation
- **Better Collaboration**: Clear interfaces between Dev and Ops
## Repository
**Code**: [Link to source code repository]
**Forgejo**: [forgejo.org](https://forgejo.org/)
**Documentation**: [Link to component-specific documentation]
**Forgejo Actions**: [Forgejo Actions Documentation](https://forgejo.org/docs/latest/user/actions/)
**ArgoCD**: [argoproj.github.io/cd](https://argoproj.github.io/cd/)
## Getting Started
### Prerequisites
* [Prerequisite 1]
* [Prerequisite 2]
- **Forgejo Account**: Access to Forgejo instance
- **Kubernetes Cluster**: Target cluster for deployments
- **ArgoCD Access**: Access to ArgoCD instance
- **Git**: For repository management
### Quick Start
### Quick Start: Application Deployment
[Step-by-step guide to get started with this component]
1. **Create Application Repository**
1. [Step 1]
2. [Step 2]
3. [Step 3]
```bash
# Create new repository in Forgejo
git init my-application
cd my-application
### Verification
# Add application code and Dockerfile
cat > Dockerfile <<EOF
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]
EOF
```
[How to verify the component is working correctly]
2. **Add CI/CD Pipeline**
Create `.forgejo/workflows/build.yaml`:
```yaml
name: Build and Push
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
- name: Login to Registry
uses: docker/login-action@v2
with:
registry: registry.example.com
username: ${{ secrets.REGISTRY_USER }}
password: ${{ secrets.REGISTRY_PASSWORD }}
- name: Build and push
uses: docker/build-push-action@v4
with:
context: .
push: ${{ github.event_name == 'push' }}
tags: registry.example.com/my-app:${{ github.sha }}
```
3. **Create Kubernetes Manifests**
Create `k8s/deployment.yaml`:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-application
spec:
replicas: 3
selector:
matchLabels:
app: my-application
template:
metadata:
labels:
app: my-application
spec:
containers:
- name: app
image: registry.example.com/my-app:latest
ports:
- containerPort: 3000
env:
- name: NODE_ENV
value: "production"
---
apiVersion: v1
kind: Service
metadata:
name: my-application
spec:
selector:
app: my-application
ports:
- port: 80
targetPort: 3000
```
4. **Configure ArgoCD Application**
```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-application
namespace: argocd
spec:
project: default
source:
repoURL: https://forgejo.example.com/myteam/my-application
targetRevision: main
path: k8s
destination:
server: https://kubernetes.default.svc
namespace: production
syncPolicy:
automated:
prune: true
selfHeal: true
```
5. **Deploy**
```bash
# Commit and push
git add .
git commit -m "Add application and deployment configuration"
git push origin main
# ArgoCD will automatically deploy the application
argocd app sync my-application --watch
```
## Usage Examples
### [Use Case 1]
### Use Case 1: Multi-Environment Deployment
[Example with code/commands showing common use case]
Deploy application to multiple environments:
```bash
# Example commands
**Repository Structure:**
```text
my-application/
├── .forgejo/
│ └── workflows/
│ └── build.yaml
├── base/
│ ├── deployment.yaml
│ ├── service.yaml
│ └── kustomization.yaml
├── overlays/
│ ├── dev/
│ │ ├── kustomization.yaml
│ │ └── patches.yaml
│ ├── staging/
│ │ ├── kustomization.yaml
│ │ └── patches.yaml
│ └── production/
│ ├── kustomization.yaml
│ └── patches.yaml
```
### [Use Case 2]
**Kustomize Base** (`base/kustomization.yaml`):
[Another common scenario]
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployment.yaml
- service.yaml
commonLabels:
app: my-application
```
**Environment Overlay** (`overlays/production/kustomization.yaml`):
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
bases:
- ../../base
namespace: production
replicas:
- name: my-application
count: 5
images:
- name: my-app
newTag: v1.2.3
patches:
- patches.yaml
```
**ArgoCD Applications for each environment:**
```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-application-prod
namespace: argocd
spec:
project: default
source:
repoURL: https://forgejo.example.com/myteam/my-application
targetRevision: main
path: overlays/production
destination:
server: https://kubernetes.default.svc
namespace: production
syncPolicy:
automated:
prune: true
selfHeal: true
```
### Use Case 2: Canary Deployment
Progressive rollout with canary strategy:
**Argo Rollouts Canary:**
```yaml
apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
name: my-application
spec:
replicas: 10
strategy:
canary:
steps:
- setWeight: 10
- pause: {duration: 5m}
- setWeight: 30
- pause: {duration: 5m}
- setWeight: 60
- pause: {duration: 5m}
- setWeight: 100
selector:
matchLabels:
app: my-application
template:
metadata:
labels:
app: my-application
spec:
containers:
- name: app
image: registry.example.com/my-app:v2.0.0
```
### Use Case 3: Feature Flags
Dynamic feature control without deployment:
**Application Code with Feature Flag:**
```javascript
const Unleash = require('unleash-client');
const unleash = new Unleash({
url: 'http://unleash.platform/api/',
appName: 'my-application',
customHeaders: {
Authorization: process.env.UNLEASH_API_TOKEN
}
});
// Use feature flag
if (unleash.isEnabled('new-checkout-flow')) {
// New checkout implementation
renderNewCheckout();
} else {
// Old checkout implementation
renderOldCheckout();
}
```
## Integration Points
* **[Component A]**: [How it integrates]
* **[Component B]**: [How it integrates]
* **[Component C]**: [How it integrates]
### Forgejo Integration
Forgejo serves as central source code management and CI/CD platform:
- **Source Control**: Git repositories for application code
- **CI/CD Pipelines**: Forgejo Actions for automated builds and tests
- **Container Registry**: Built-in container registry for images
- **Webhook Integration**: Triggers for external systems
- **Pull Request Workflows**: Code review and approval processes
### ArgoCD Integration
ArgoCD handles declarative application deployment:
- **GitOps Sync**: Continuous synchronization with Git state
- **Health Monitoring**: Application health status monitoring
- **Rollback Support**: Easy rollback to previous versions
- **Multi-Cluster**: Deployment to multiple clusters
- **UI and CLI**: Web interface and command-line access
### Observability Integration
Integration with monitoring and logging:
- **Metrics**: Prometheus metrics from applications
- **Logs**: Centralized log collection via Loki/ELK
- **Tracing**: Distributed tracing with Jaeger/Tempo
- **Alerting**: Alert rules for application issues
## Architecture
[Optional: Add architectural diagrams and descriptions]
### Application Deployment Flow
### Component Architecture (C4)
```text
┌──────────────┐
│ Developer │
└──────┬───────┘
│ git push
▼
┌─────────────────────────────────────────┐
│ Forgejo │
│ │
│ ┌────────────────────────────────┐ │
│ │ Git Repository │ │
│ │ - Application Code │ │
│ │ - Kubernetes Manifests │ │
│ │ - Pipeline Configuration │ │
│ └─────────┬──────────────────────┘ │
│ │ │
│ │ triggers │
│ ▼ │
│ ┌────────────────────────────────┐ │
│ │ Forgejo Actions (CI/CD) │ │
│ │ - Build Container Image │ │
│ │ - Run Tests │ │
│ │ - Security Scans │ │
│ │ - Push to Registry │ │
│ └─────────┬──────────────────────┘ │
└────────────┼────────────────────────────┘
│
│ image pushed
▼
┌─────────────────────────────────────────┐
│ Container Registry │
└─────────────────────────────────────────┘
│
│ watches manifests
▼
┌─────────────────────────────────────────┐
│ ArgoCD │
│ │
│ - Monitors Git Repository │
│ - Detects Changes │
│ - Syncs to Kubernetes │
│ - Reports Health Status │
└─────────────┬───────────────────────────┘
│
│ deploys
▼
┌─────────────────────────────────────────┐
│ Kubernetes Cluster │
│ │
│ ┌────────────────────────────────┐ │
│ │ Running Application │ │
│ │ - Pods │ │
│ │ - Services │ │
│ │ - Ingress │ │
│ └────────────────────────────────┘ │
└─────────────────────────────────────────┘
```
[Add C4 Container or Component diagrams showing the internal structure]
### CI/CD Pipeline Architecture
### Sequence Diagrams
Typical Forgejo Actions pipeline stages:
[Add sequence diagrams showing key interaction flows with other components]
### Deployment Architecture
[Add infrastructure and deployment diagrams showing how the component is deployed]
1. **Checkout**: Clone source code
2. **Build**: Compile application and dependencies
3. **Test**: Run unit and integration tests
4. **Security Scan**: Scan dependencies and code for vulnerabilities
5. **Build Image**: Create container image
6. **Push Image**: Push to container registry
7. **Update Manifests**: Update Kubernetes manifests with new image tag
8. **Notify**: Send notifications on success/failure
## Configuration
[Key configuration options and how to set them]
### Forgejo Actions Configuration
Example for Node.js application:
```yaml
name: CI/CD Pipeline
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main ]
env:
REGISTRY: registry.example.com
IMAGE_NAME: ${{ github.repository }}
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
- name: Run linter
run: npm run lint
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run Trivy vulnerability scanner
uses: aquasecurity/trivy-action@master
with:
scan-type: 'fs'
scan-ref: '.'
format: 'sarif'
output: 'trivy-results.sarif'
build-and-push:
needs: [test, security]
runs-on: ubuntu-latest
if: github.event_name == 'push'
steps:
- uses: actions/checkout@v3
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
- name: Login to Registry
uses: docker/login-action@v2
with:
registry: ${{ env.REGISTRY }}
username: ${{ secrets.REGISTRY_USER }}
password: ${{ secrets.REGISTRY_PASSWORD }}
- name: Extract metadata
id: meta
uses: docker/metadata-action@v4
with:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
tags: |
type=ref,event=branch
type=sha,prefix={{branch}}-
- name: Build and push
uses: docker/build-push-action@v4
with:
context: .
push: true
tags: ${{ steps.meta.outputs.tags }}
cache-from: type=gha
cache-to: type=gha,mode=max
```
### ArgoCD Application Configuration
Complete configuration example:
```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-application
namespace: argocd
finalizers:
- resources-finalizer.argocd.argoproj.io
spec:
project: default
source:
repoURL: https://forgejo.example.com/myteam/my-application
targetRevision: main
path: k8s/overlays/production
# Kustomize options
kustomize:
version: v5.0.0
images:
- my-app=registry.example.com/my-app:v1.2.3
destination:
server: https://kubernetes.default.svc
namespace: production
# Sync policy
syncPolicy:
automated:
prune: true # Delete resources not in Git
selfHeal: true # Override manual changes
allowEmpty: false # Don't delete everything on empty repo
syncOptions:
- CreateNamespace=true
- PruneLast=true
- RespectIgnoreDifferences=true
retry:
limit: 5
backoff:
duration: 5s
factor: 2
maxDuration: 3m
# Ignore differences (avoid sync loops)
ignoreDifferences:
- group: apps
kind: Deployment
jsonPointers:
- /spec/replicas # Ignore if HPA manages replicas
```
## Troubleshooting
### [Common Issue 1]
### Pipeline Fails
**Problem**: [Description]
**Problem**: Forgejo Actions pipeline fails
**Solution**: [How to fix]
**Solution**:
### [Common Issue 2]
```bash
# 1. Check pipeline logs in Forgejo UI
# Navigate to: Repository → Actions → Select failed run
**Problem**: [Description]
# 2. Check runner status
# In Forgejo: Site Admin → Actions → Runners
**Solution**: [How to fix]
# 3. Check runner logs
kubectl logs -n forgejo-runner deployment/act-runner
# 4. Test pipeline locally with act
act -l # List available jobs
act -j build # Run specific job
```
### ArgoCD Application OutOfSync
**Problem**: Application shows "OutOfSync" status
**Solution**:
```bash
# 1. Check differences
argocd app diff my-application
# 2. View sync status details
argocd app get my-application
# 3. Manual sync
argocd app sync my-application
# 4. Hard refresh (ignore cache)
argocd app sync my-application --force
# 5. Check for ignored differences
argocd app get my-application --show-operation
```
### Application Deployment Fails
**Problem**: Application pod crashes after deployment
**Solution**:
```bash
# 1. Check pod status
kubectl get pods -n production
# 2. View pod logs
kubectl logs -n production deployment/my-application
# 3. Describe pod for events
kubectl describe pod -n production <pod-name>
# 4. Check resource limits
kubectl top pod -n production
# 5. Rollback via ArgoCD
argocd app rollback my-application
```
### Image Pull Errors
**Problem**: Kubernetes cannot pull container image
**Solution**:
```bash
# 1. Verify image exists
docker pull registry.example.com/my-app:v1.2.3
# 2. Check image pull secret
kubectl get secret -n production regcred
# 3. Create image pull secret if missing
kubectl create secret docker-registry regcred \
--docker-server=registry.example.com \
--docker-username=user \
--docker-password=password \
-n production
# 4. Reference secret in deployment
kubectl patch deployment my-application -n production \
-p '{"spec":{"template":{"spec":{"imagePullSecrets":[{"name":"regcred"}]}}}}'
```
## Best Practices
### Golden Path Templates
Provide standardized templates for common use cases:
1. **Web Application Template**: Node.js, Python, Go web services
2. **API Service Template**: RESTful API with OpenAPI
3. **Batch Job Template**: Kubernetes CronJob configurations
4. **Microservice Template**: Service mesh integration
Example repository template structure:
```text
application-template/
├── .forgejo/
│ └── workflows/
│ ├── build.yaml
│ ├── test.yaml
│ └── deploy.yaml
├── k8s/
│ ├── base/
│ └── overlays/
├── src/
│ └── ...
├── Dockerfile
├── README.md
└── .gitignore
```
### Deployment Checklist
Before deploying to production:
- ✅ All tests passing
- ✅ Security scans completed
- ✅ Resource limits defined
- ✅ Health checks configured
- ✅ Monitoring and alerts set up
- ✅ Backup strategy defined
- ✅ Rollback plan documented
- ✅ Team notified about deployment
### Configuration Management
- Use ConfigMaps for non-sensitive configuration
- Use Secrets for sensitive data
- Use External Secrets Operator for vault integration
- Never commit secrets to Git
- Use environment-specific overlays (Kustomize)
- Document all configuration options
## Status
**Maturity**: [Production / Beta / Experimental]
**Maturity**: Production
**Stability**: Stable
**Support**: Internal Platform Team
## Additional Resources
* [Link to external documentation]
* [Link to community resources]
* [Link to related components]
### Forgejo
## Documentation Notes
- [Forgejo Documentation](https://forgejo.org/docs/latest/)
- [Forgejo Actions Guide](https://forgejo.org/docs/latest/user/actions/)
- [Forgejo API Reference](https://forgejo.org/docs/latest/api/)
[Instructions for team members filling in this documentation - remove this section once complete]
### ArgoCD
- [ArgoCD Documentation](https://argo-cd.readthedocs.io/)
- [ArgoCD Best Practices](https://argo-cd.readthedocs.io/en/stable/user-guide/best_practices/)
- [ArgoCD Sync Waves](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/)
### GitOps
- [GitOps Principles](https://opengitops.dev/)
- [GitOps Patterns](https://www.gitops.tech/)
- [Kubernetes Deployment Strategies](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy)
### CI/CD
- [GitHub Actions Documentation](https://docs.github.com/en/actions) (Forgejo Actions compatible)
- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)
- [Container Security Best Practices](https://kubernetes.io/docs/concepts/security/pod-security-standards/)

493
content/en/docs/components/orchestration/platform.md
View file

@ -3,126 +3,507 @@ title: "Platform Orchestration"
linkTitle: "Platform Orchestration"
weight: 20
description: >
Platform-level component provisioning via Stacks
Platform-level component provisioning via Stacks - Orchestrating the platform infrastructure itself
---
{{% alert title="Draft" color="warning" %}}
**Editorial Status**: This page is currently being developed.
* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
* **Assignee**: [Name or Team]
* **Status**: Draft
* **Last Updated**: YYYY-MM-DD
* **TODO**:
* [ ] Add detailed component description
* [ ] Include usage examples and code samples
* [ ] Add architecture diagrams
* [ ] Review and finalize content
{{% /alert %}}
## Overview
[Detailed description of the component - what it is, what it does, and why it exists]
Platform Orchestration refers to the automation and management of the platform infrastructure itself. This includes the provisioning, configuration, and lifecycle management of all components that make up the Internal Developer Platform (IDP).
In the context of IPCEI-CIS, Platform Orchestration means:
- **Platform Bootstrap**: Initial setup of Kubernetes clusters and core services
- **Platform Services Management**: Deployment and management of ArgoCD, Forgejo, Keycloak, etc.
- **Infrastructure-as-Code**: Declarative management using Terraform and GitOps
- **Multi-Cluster Orchestration**: Coordination across different Kubernetes clusters
- **Platform Stacks**: Reusable bundles of platform components (CNOE concept)
### Target Audience
Platform Orchestration is primarily aimed at:
- **Platform Engineering Teams**: Teams that build and operate the IDP
- **Infrastructure Architects**: Those responsible for the platform architecture
- **SRE Teams**: Teams responsible for reliability and operations
## Key Features
* [Feature 1]
* [Feature 2]
* [Feature 3]
### Declarative Platform Definition
The entire platform is defined declaratively as code:
- **GitOps-First**: Everything is versioned in Git and traceable
- **Reproducibility**: The platform can be rebuilt at any time
- **Environment Parity**: Consistency between Dev, Test, and Production
- **Auditability**: Complete history of all changes
### Self-Bootstrapping
The platform can bootstrap itself:
1. **Initial Bootstrap**: Minimal tool (like `idpbuilder`) starts the platform
2. **Self-Management**: After bootstrap, ArgoCD takes over management
3. **Continuous Reconciliation**: Platform is continuously reconciled with Git state
4. **Self-Healing**: Automatic recovery on deviations
### Stack-based Composition
Platform components are organized as reusable stacks (CNOE concept):
- **Modularity**: Components can be updated individually
- **Reusability**: Stacks can be used across different environments
- **Composability**: Compose complex platforms from simple building blocks
- **Versioning**: Stacks can be versioned and tested
**In IPCEI-CIS**: The stacks concept from CNOE is the core organizational principle for platform components.
### Multi-Cluster Support
Platform Orchestration supports different cluster topologies:
- **Control Plane + Worker Clusters**: Centralized control, distributed workloads
- **Hub-and-Spoke**: One management cluster manages multiple target clusters
- **Federation**: Coordination across multiple independent clusters
## Purpose in EDP
[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
Platform Orchestration is the foundation of the IPCEI-CIS Edge Developer Platform. It enables:
### Foundation for Developer Self-Service
Platform Orchestration ensures all services are available that developers need for self-service:
- **GitOps Engine** (ArgoCD) for continuous deployment
- **Source Control** (Forgejo) for code and configuration management
- **Identity Management** (Keycloak) for authentication and authorization
- **Observability** (Grafana, Prometheus) for monitoring and logging
- **CI/CD** (Forgejo Actions/Pipelines) for automated build and test
### Consistency Across Environments
Through declarative definition, consistency is guaranteed:
- Development, test, and production environments are identically configured
- No "configuration drift" between environments
- Predictable behavior across all stages
### Platform as Code
The platform itself is treated like software:
- **Version Control**: All changes are versioned in Git
- **Code Review**: Platform changes go through review processes
- **Testing**: Platform configurations can be tested
- **Rollback**: Easy rollback on problems
### Reduced Operational Overhead
Automation reduces manual effort:
- No manual installation steps
- Automatic updates and patching
- Self-healing on failures
- Standardized deployment processes
## Repository
**Code**: [Link to source code repository]
**CNOE Reference Implementation**: [cnoe-io/stacks](https://github.com/cnoe-io/stacks)
**Documentation**: [Link to component-specific documentation]
**CNOE idpbuilder**: [cnoe-io/idpbuilder](https://github.com/cnoe-io/idpbuilder)
**Documentation**: [CNOE.io Documentation](https://cnoe.io/docs/)
## Getting Started
### Prerequisites
* [Prerequisite 1]
* [Prerequisite 2]
- **Docker**: For local Kubernetes clusters (Kind)
- **kubectl**: Kubernetes CLI tool
- **Git**: For repository management
- **idpbuilder**: CNOE bootstrap tool
### Quick Start
[Step-by-step guide to get started with this component]
Platform Orchestration with CNOE Reference Implementation:
1. [Step 1]
2. [Step 2]
3. [Step 3]
```bash
# 1. Install idpbuilder
curl -fsSL https://cnoe.io/install.sh | bash
# 2. Bootstrap platform
idpbuilder create \
--use-path-routing \
--package-dir https://github.com/cnoe-io/stacks//ref-implementation
# 3. Wait for platform ready (ca. 10 minutes)
kubectl get applications -A
```
### Verification
[How to verify the component is working correctly]
Verify the platform is running correctly:
```bash
# Get platform secrets (credentials)
idpbuilder get secrets
# Check all ArgoCD applications
kubectl get applications -n argocd
# Expected: All applications "Synced" and "Healthy"
```
Access URLs (with path-routing):
- **ArgoCD**: `https://cnoe.localtest.me:8443/argocd`
- **Forgejo**: `https://cnoe.localtest.me:8443/gitea`
- **Keycloak**: `https://cnoe.localtest.me:8443/keycloak`
## Usage Examples
### [Use Case 1]
### Use Case 1: Platform Bootstrap
[Example with code/commands showing common use case]
Initial bootstrapping of a new platform instance:
```bash
# Example commands
idpbuilder create \
--use-path-routing \
--package-dir https://github.com/cnoe-io/stacks//ref-implementation \
--log-level debug
# Workflow:
# 1. Creates Kind cluster
# 2. Installs ingress-nginx
# 3. Clones and installs ArgoCD
# 4. Installs Forgejo
# 5. Waits for core services
# 6. Creates technical users
# 7. Configures Git repositories
# 8. Installs remaining stacks via ArgoCD
```
### [Use Case 2]
After approximately 10 minutes, the platform is fully deployed.
[Another common scenario]
### Use Case 2: Adding New Platform Components
Add new platform components via ArgoCD:
```bash
# Create ArgoCD Application for new component
cat <<EOF | kubectl apply -f -
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: external-secrets
namespace: argocd
spec:
project: default
source:
repoURL: https://charts.external-secrets.io
targetRevision: 0.9.9
chart: external-secrets
destination:
server: https://kubernetes.default.svc
namespace: external-secrets-system
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
EOF
```
### Use Case 3: Platform Updates
Update platform components:
```bash
# 1. Update via Git (GitOps)
cd your-platform-config-repo
git pull
# 2. Update stack version
vim argocd/applications/component.yaml
# Change targetRevision to new version
# 3. Commit and push
git add .
git commit -m "Update component to v1.2.3"
git push
# 4. ArgoCD will automatically sync
# 5. Monitor the update
argocd app sync component --watch
```
## Integration Points
* **[Component A]**: [How it integrates]
* **[Component B]**: [How it integrates]
* **[Component C]**: [How it integrates]
### ArgoCD Integration
- **Bootstrap**: ArgoCD is initially installed via idpbuilder
- **Self-Management**: After bootstrap, ArgoCD manages itself via Application CRD
- **Platform Coordination**: ArgoCD orchestrates all other platform components
- **Health Monitoring**: ArgoCD monitors health status of all platform services
### Forgejo Integration
- **Source of Truth**: Git repositories contain all platform definitions
- **GitOps Workflow**: Changes in Git trigger platform updates
- **Backup**: Git serves as backup of platform configuration
- **Audit Trail**: Git history documents all platform changes
- **CI/CD**: Forgejo Actions can automate platform operations
### Terraform Integration
- **Infrastructure Provisioning**: Terraform provisions cloud resources for platform
- **State Management**: Terraform state tracks infrastructure
- **Integration**: Terraform can be triggered via Forgejo pipelines
- **Multi-Cloud**: Support for multiple cloud providers
## Architecture
[Optional: Add architectural diagrams and descriptions]
### Platform Orchestration Flow
### Component Architecture (C4)
```text
┌─────────────────┐
│ idpbuilder │ Bootstrap Tool
│ (Initial Run) │
└────────┬────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Kubernetes Cluster │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ ArgoCD │────────▶│ Forgejo │ │
│ │ (GitOps) │ │ (Git Repo) │ │
│ └──────┬───────┘ └──────────────┘ │
│ │ │
│ │ Monitors & Syncs │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ Platform Stacks │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ │ │
│ │ │Forgejo │ │Keycloak │ │ │
│ │ └──────────┘ └──────────┘ │ │
│ │ ┌──────────┐ ┌──────────┐ │ │
│ │ │Observ- │ │Ingress │ │ │
│ │ │ability │ │ │ │ │
│ │ └──────────┘ └──────────┘ │ │
│ └──────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
```
[Add C4 Container or Component diagrams showing the internal structure]
### Platform Bootstrap Sequence
### Sequence Diagrams
The idpbuilder executes the following workflow:
[Add sequence diagrams showing key interaction flows with other components]
1. Create Kind Kubernetes cluster
2. Install ingress-nginx controller
3. Install ArgoCD
4. Install Forgejo Git server
5. Wait for services to be ready
6. Create technical users in Forgejo
7. Create repository for platform state in Forgejo
8. Push platform stacks to Forgejo
9. Create ArgoCD Applications for all stacks
10. ArgoCD takes over continuous synchronization
### Deployment Architecture
[Add infrastructure and deployment diagrams showing how the component is deployed]
The platform is deployed in different namespaces:
- `argocd`: ArgoCD and its components
- `gitea`: Forgejo Git server
- `keycloak`: Identity and access management
- `observability`: Prometheus, Grafana, etc.
- `ingress-nginx`: Ingress controller
## Configuration
[Key configuration options and how to set them]
### idpbuilder Configuration
Key configuration options for idpbuilder:
```bash
# Path-based routing (recommended for local development)
idpbuilder create --use-path-routing
# Custom package directory
idpbuilder create --package-dir /path/to/custom/packages
# Custom Kind cluster config
idpbuilder create --kind-config custom-kind.yaml
# Enable debug logging
idpbuilder create --log-level debug
```
### ArgoCD Configuration
Important ArgoCD configurations for platform orchestration:
```yaml
# argocd-cm ConfigMap
data:
# Enable automatic sync
application.instanceLabelKey: argocd.argoproj.io/instance
# Repository credentials
repositories: |
- url: https://github.com/cnoe-io/stacks
name: cnoe-stacks
type: git
# Resource exclusions
resource.exclusions: |
- apiGroups:
- cilium.io
kinds:
- CiliumIdentity
```
### Platform Stack Configuration
Configuration of platform stacks via Kustomize:
```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: platform-system
resources:
- argocd-app.yaml
- forgejo-app.yaml
- keycloak-app.yaml
patches:
- target:
kind: Application
patch: |-
- op: add
path: /spec/syncPolicy
value:
automated:
prune: true
selfHeal: true
```
## Troubleshooting
### [Common Issue 1]
### Platform not reachable
**Problem**: [Description]
**Problem**: After `idpbuilder create`, platform services are not reachable
**Solution**: [How to fix]
**Solution**:
### [Common Issue 2]
```bash
# 1. Check if all pods are running
kubectl get pods -A
**Problem**: [Description]
# 2. Check ArgoCD application status
kubectl get applications -n argocd
**Solution**: [How to fix]
# 3. Check ingress
kubectl get ingress -A
# 4. Verify DNS resolution
nslookup cnoe.localtest.me
# 5. Check idpbuilder logs
idpbuilder get logs
```
### ArgoCD Applications not synchronized
**Problem**: ArgoCD Applications show status "OutOfSync"
**Solution**:
```bash
# 1. Check application details
argocd app get <app-name>
# 2. View sync status
argocd app sync <app-name> --dry-run
# 3. Force sync
argocd app sync <app-name> --force
# 4. Check for errors in ArgoCD logs
kubectl logs -n argocd deployment/argocd-application-controller
```
### Git Repository Connection Issues
**Problem**: ArgoCD cannot access Git repository
**Solution**:
```bash
# 1. Verify repository configuration
argocd repo list
# 2. Test connection
argocd repo get https://your-git-repo
# 3. Check credentials
kubectl get secret -n argocd
# 4. Re-add repository with correct credentials
argocd repo add https://your-git-repo \
--username <user> \
--password <token>
```
## Platform Orchestration Best Practices
Based on experience and [CNCF Guidelines](https://tag-app-delivery.cncf.io/whitepapers/platforms/):
1. **Start Simple**: Begin with the CNOE reference stack, extend gradually
2. **Automate Everything**: Manual platform changes are anti-pattern
3. **Monitor Continuously**: Use observability tools for platform health
4. **Document Well**: Platform documentation is essential for adoption
5. **Version Everything**: All platform components should be versioned
6. **Test Changes**: Platform updates should be tested in non-prod
7. **Plan for Disaster**: Backup and disaster recovery strategies are important
8. **Use Stacks**: Organize platform components as reusable stacks
## Status
**Maturity**: [Production / Beta / Experimental]
**Maturity**: Production (for CNOE Reference Implementation)
**Stability**: Stable
**Support**: Community Support via CNOE Community
## Additional Resources
* [Link to external documentation]
* [Link to community resources]
* [Link to related components]
### CNOE Resources
## Documentation Notes
- [CNOE Official Website](https://cnoe.io/)
- [CNOE GitHub Organization](https://github.com/cnoe-io)
- [CNOE Reference Implementation](https://github.com/cnoe-io/stacks)
- [CNOE Community Slack](https://cloud-native.slack.com/archives/C05TN9WFN5S)
[Instructions for team members filling in this documentation - remove this section once complete]
### Platform Engineering
- [CNCF Platforms White Paper](https://tag-app-delivery.cncf.io/whitepapers/platforms/)
- [Platform Engineering Maturity Model](https://tag-app-delivery.cncf.io/whitepapers/platform-eng-maturity-model/)
- [Team Topologies](https://teamtopologies.com/) - Organizational patterns
### GitOps
- [GitOps Working Group](https://opengitops.dev/)
- [ArgoCD Best Practices](https://argo-cd.readthedocs.io/en/stable/user-guide/best_practices/)
- [GitOps Principles](https://opengitops.dev/)
### CNOE Stacks
- [Understanding CNOE Stacks](https://cnoe.io/docs/reference-implementation/stacks/)
- [Creating Custom Stacks](https://cnoe.io/docs/reference-implementation/customization/)