README.md

GitOps Platform

Centralized platform repository for managing ArgoCD ApplicationSets, Kargo progressive delivery, and shared GitOps resources for all services in the organization.

Repository Purpose

This repository contains:

• ✅ ArgoCD ApplicationSets for all services
• ✅ Kargo projects and stages for progressive delivery
• ✅ Shared plugins (Backstage integration, etc.)
• ✅ Platform-wide GitOps policies and documentation

This repository does NOT contain:

• ❌ Helm charts (see service-specific chart repositories)
• ❌ Environment-specific values (see service-specific config repositories)
• ❌ Application code

Directory Structure

gitops-platform/
├── argocd/
│   ├── applicationsets/
│   │   ├── paved-road-service/       # ApplicationSets for paved-road-service
│   │   ├── payment-service/          # ApplicationSets for payment-service
│   │   └── user-service/             # ApplicationSets for user-service
│   └── plugins/
│       └── backstage/                # Backstage integration plugin
├── kargo/
│   └── projects/
│       ├── paved-road-service/       # Kargo project for paved-road-service
│       │   ├── project.yaml          # Promotion policies
│       │   ├── warehouse.yaml        # Image registry subscription
│       │   └── stages/               # 11 deployment stages
│       ├── payment-service/          # Kargo project for payment-service
│       └── user-service/             # Kargo project for user-service
└── docs/
    ├── ONBOARDING.md                 # How to add new service
    └── BACKSTAGE-INTEGRATION.md      # Backstage setup guide

Services Managed

Currently managing GitOps for:

• paved-road-service - Reference implementation with 11 deployment flavors

Adding a New Service

To onboard a new service to the platform:

1. Create ApplicationSet

mkdir -p argocd/applicationsets/my-service

Create argocd/applicationsets/my-service/applicationset.yaml:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-service
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - env: dev
            flavor: dev
            namespace: my-service-dev
  template:
    metadata:
      name: 'my-service-{{flavor}}'
    spec:
      project: default
      sources:
        - repoURL: oci://registry.cloudwalkersinc.com/helm-charts
          chart: my-service
          targetRevision: 0.1.0
          helm:
            valueFiles:
              - $values/environments/{{env}}/{{flavor}}.yaml
        - repoURL: https://github.com/cloudwalkersinc/my-service-config.git
          targetRevision: main
          ref: values
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{namespace}}'

2. Create Kargo Project

mkdir -p kargo/projects/my-service/stages

Create kargo/projects/my-service/project.yaml:

apiVersion: kargo.akuity.io/v1alpha1
kind: Project
metadata:
  name: my-service
spec:
  promotionPolicies:
    - stage: dev
      autoPromotionEnabled: true

Create kargo/projects/my-service/warehouse.yaml:

apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  name: my-service
  namespace: kargo-project-my-service
spec:
  subscriptions:
    - image:
        repoURL: cloudwalkersinc/my-service
        semverConstraint: ^1.0.0

Create stages in kargo/projects/my-service/stages/dev.yaml:

apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: dev
  namespace: kargo-project-my-service
spec:
  subscriptions:
    warehouse: my-service
  promotionMechanisms:
    gitRepoUpdates:
      - repoURL: https://github.com/cloudwalkersinc/my-service-config.git
        writeBranch: main
        helm:
          images:
            - image: cloudwalkersinc/my-service
              valuesFilePath: environments/dev/dev.yaml
              key: image.tag
    argoCDAppUpdates:
      - appName: my-service-dev
        appNamespace: argocd

3. Deploy to Cluster

# Deploy ApplicationSet
kubectl apply -f argocd/applicationsets/my-service/applicationset.yaml

# Deploy Kargo resources
kubectl apply -f kargo/projects/my-service/project.yaml
kubectl apply -f kargo/projects/my-service/warehouse.yaml
kubectl apply -f kargo/projects/my-service/stages/

Deployment

Prerequisites

• ArgoCD installed in cluster (namespace: argocd)
• Kargo installed in cluster
• Helm charts published to OCI registry or accessible Git repository
• Service config repositories created

Deploy Platform Resources

# Deploy all ApplicationSets
kubectl apply -R -f argocd/applicationsets/

# Deploy all Kargo projects
kubectl apply -R -f kargo/projects/

# Deploy Backstage plugin (if using)
kubectl apply -f argocd/plugins/backstage/plugin-configmap.yaml

Verify Deployment

# Check ApplicationSets
kubectl get applicationset -n argocd

# Check Applications
kubectl get applications -n argocd

# Check Kargo projects
kubectl get projects -A

# Check Kargo stages
kubectl get stages -A

Backstage Integration

For dynamic, metadata-driven deployments using Backstage:

1. Configure Backstage API credentials
2. Deploy plugin ConfigMap
3. Patch argocd-repo-server
4. Use applicationset-backstage.yaml instead of static ApplicationSet

See docs/BACKSTAGE-INTEGRATION.md for complete setup.

Multi-Source ApplicationSet Pattern

All ApplicationSets use the multi-source pattern:

sources:
  # Chart from OCI registry or Git
  - repoURL: oci://registry.cloudwalkersinc.com/helm-charts
    chart: my-service
    targetRevision: 0.1.0
    helm:
      valueFiles:
        - $values/environments/prod/prod.yaml
  
  # Values from config repository
  - repoURL: https://github.com/cloudwalkersinc/my-service-config.git
    targetRevision: main
    ref: values

Repository Access

Required Permissions

ArgoCD Service Account:

• Read access to this repository
• Read access to chart repositories (OCI or Git)
• Read access to config repositories

Kargo Bot:

• Read/Write access to config repositories (to update image tags)

Maintenance

Updating Chart Versions

When a new chart version is released:

1. Update targetRevision in ApplicationSet
2. Commit and push
3. ArgoCD auto-syncs and deploys new chart version

Updating Promotion Policies

Edit Kargo project.yaml to change auto-promotion rules:

promotionPolicies:
  - stage: dev
    autoPromotionEnabled: true  # Auto-promote to dev
  - stage: prod
    autoPromotionEnabled: false # Manual approval for prod

Related Repositories

• Helm Chart: https://github.com/cloudwalkersinc/helm-charts-paved-road
• Config Repository: https://github.com/cloudwalkersinc/paved-road-service-config
• Chart Registry: oci://registry.cloudwalkersinc.com/helm-charts

Support

For platform issues:

• Check ArgoCD ApplicationSet controller logs
• Check Kargo logs
• Review service-specific ApplicationSet configuration
• Verify chart and config repository accessibility