Skip to main content

Developer Golden Path

Purpose: For application developers, shows the recommended workflow for repo structure, CI/CD integration, and environment promotion.

Task Summary​

This guide describes the recommended end-to-end workflow for application teams deploying on openCenter. It covers repository setup, local validation, CI pipeline integration, and promoting changes through dev → staging → production.

Prerequisites​

  • An openCenter cluster with FluxCD bootstrapped
  • kubectl and kustomize CLI installed
  • A Git repository with the Kustomize overlay structure (see Application Patterns)
  • Platform team has onboarded your application (GitRepository + Kustomization created)

Steps​

1. Structure Your Repository​

Use the multi-environment overlay pattern:

my-app/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── httproute.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    ├── staging/
    │   └── kustomization.yaml
    └── production/
        └── kustomization.yaml

The base/ directory contains shared manifests. Each overlay customizes replicas, image tags, resource limits, and environment-specific configuration.

2. Validate Locally Before Pushing​

Run kustomize build to catch errors before they reach the cluster:

# Validate the dev overlay
kustomize build overlays/dev | kubectl apply --dry-run=client -f -

# Validate the production overlay
kustomize build overlays/production | kubectl apply --dry-run=client -f -

This catches missing fields, invalid YAML, and schema violations without touching the cluster.

3. Integrate with CI​

Add a CI step that validates manifests and builds the container image on every push:

# .github/workflows/ci.yaml (simplified)
name: CI
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate Kustomize overlays
        run: |
          for overlay in overlays/*/; do
            echo "Validating $overlay"
            kustomize build "$overlay" | kubectl apply --dry-run=client -f -
          done
  build:
    runs-on: ubuntu-latest
    needs: validate
    steps:
      - uses: actions/checkout@v4
      - name: Build and push image
        run: |
          docker build -t harbor.opencenter.example.com/customer-apps/my-app:${GITHUB_SHA::7} .
          docker push harbor.opencenter.example.com/customer-apps/my-app:${GITHUB_SHA::7}

4. Deploy to Dev​

Update the dev overlay with the new image tag:

# overlays/dev/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
images:
  - name: my-app
    newName: harbor.opencenter.example.com/customer-apps/my-app
    newTag: "abc1234"

Push to the main branch. FluxCD detects the change within 5 minutes and deploys to the dev cluster.

5. Promote to Staging​

After validating in dev, update the staging overlay:

# overlays/staging/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
images:
  - name: my-app
    newName: harbor.opencenter.example.com/customer-apps/my-app
    newTag: "abc1234"
patches:
  - target:
      kind: Deployment
      name: my-app
    patch: |
      - op: replace
        path: /spec/replicas
        value: 3

Commit to a release/staging branch or tag. The staging cluster's FluxCD Kustomization watches this ref.

6. Promote to Production​

After staging validation, update the production overlay with the same image tag and production-specific settings (higher replicas, stricter resource limits). Use a Git tag or release/production branch.

Verification​

At each stage, confirm the deployment:

# Check pod status
kubectl get pods -n my-app -l app=my-app

# Check FluxCD reconciliation
flux get kustomizations -n flux-system | grep my-app

# Check HTTPRoute is attached to the Gateway
kubectl get httproute -n my-app

Troubleshooting​

SymptomCauseFix
FluxCD shows "kustomize build failed"Invalid YAML or missing resourceRun kustomize build locally to reproduce
Pods stuck in ImagePullBackOffImage not in Harbor or wrong tagVerify image exists: skopeo inspect docker://harbor.../my-app:<tag>
HTTPRoute not routing trafficWrong parentRefs or hostnameCheck Gateway listeners match your hostname

Further Reading​