Learn Multigress - Configuration Management & GitOps

#Introduction

Changing a gateway with a careless kubectl apply is a recipe for disaster: no history, no review, and hard to roll back. Episode 11 introduces configuration management and GitOps for Multigress configuration — storing all manifests in Git, validating every change, and applying safe rollout patterns.

The GitOps principle is simple: Git is the source of truth, and an agent like Argo CD or Flux syncs what's in Git to the cluster. Changes start as pull requests, not as kubectl commands.

#Storing Multigress Manifests in Git

#A Recommended Repo Structure

Separate configuration by environment and by function. Example structure:

config/
  base/
    gateway.yaml
    gatewayclass.yaml
  overlays/
    staging/
      kustomization.yaml
      httproute-tenant-a.yaml
    prod/
      kustomization.yaml
      httproute-tenant-a.yaml
      securitypolicy.yaml

The base directory holds the manifests shared by all environments, while overlays adds environment-specific differences. This uses the Kustomize pattern common in the GitOps ecosystem.

#Applying with Argo CD

Argo CD will sync the application to the cluster:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: multigress-config
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/multigress-gitops
    targetRevision: HEAD
    path: config/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: multigress-system
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

The kubectl get app multigress-config -n argocd command shows the sync status. With selfHeal: true, any manual change in the cluster will be reverted to the Git state — that's what brings configuration back under control.

#Validating Configuration Changes and Rollout Patterns

#Validation Before Merge

Never let a broken manifest reach the cluster. Validation is done in layers in the CI pipeline (details in episode 19):

kubectl apply --dry-run=client -f config/overlays/prod -k

The kubectl apply --dry-run=client -k config/overlays/prod command checks syntax without changing the cluster. For schema validation against CRDs, you can use a tool like kubeconform:

kubeconform -strict -summary -c \
  config/overlays/prod/httroute-tenant-a.yaml

This validation catches field typos before the manifest gets through Argo CD.

#Previewing Changes

Before syncing, see the difference between Git and the cluster:

argocd app diff multigress-config

The argocd app diff multigress-config command shows exactly what will change. Combine it with the canary pattern from episode 9 for changes bigger than just a route.

#Rollout Patterns for Configuration

Gateway configuration changes also need a rollout pattern:

• Small changes like weights: direct, can be patched.
• Listener or TLS changes: apply in a maintenance window, monitor the error rate.
• Architectural changes like namespace moves: use the blue-green route pattern.

Each pattern is documented in a runbook — a topic we'll refine in episode 21.

#Managing Overlays Between Environments

#Environment Differences in Overlays

The staging and prod environments differ in several ways: hostname, rate limit, and replica count. Overlays centralize those differences:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
  - httproute-tenant-a.yaml
patches:
  - target:
      kind: HTTPRoute
      name: tenant-a-route
    patch: |-
      - op: replace
        path: /spec/hostnames
        value:
          - staging.example.com

The staging overlay replaces the hostname with staging.example.com. The base manifests stay free of environment differences — any change is made in just one place.

#Ensuring Consistency

Check that all environments still render without errors:

kubectl kustomize config/overlays/staging > /dev/null
kubectl kustomize config/overlays/prod > /dev/null

The two commands above ensure the staging and prod overlays are valid. The kubectl kustomize config/overlays/prod command produces the final manifest to be applied — that's what Argo CD actually syncs.

#Closing

Episode 11 put Multigress configuration where it belongs: in Git. You know how to organize base and overlays, validate changes before syncing, and apply safe rollout patterns for each type of change.

The key takeaways:

• Git is the source of truth; Argo CD or Flux syncs to the cluster.
• Separate base and overlays per environment.
• Layered validation: dry-run, kubeconform, then the Argo CD diff.
• Big changes use a rollout pattern, not a direct apply.
• Limit direct write access to gateway resources with RBAC.

In the next episode 12 we'll discuss security policies & access control — gating access with AuthorizationPolicy, JWT authentication and external auth integration, and securing routes with mutual TLS and certificate validation. Your GitOps configuration is the right place to add this security layer.