GitOps Deployment Guide (ArgoCD & FluxCD)

Mockarty supports declarative GitOps deployment via Helm charts and the Kubernetes Operator CRD.

ArgoCD

Prerequisites

• ArgoCD installed in your cluster
• Helm chart repository accessible (OCI registry or Git)
• kubectl access to the target namespace

Option 1: Helm Chart via ArgoCD Application

Create an ArgoCD Application manifest:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: mockarty
  namespace: argocd
spec:
  project: default
  source:
    # Option A: Git repository
    repoURL: https://github.com/mockarty/mockarty.git
    targetRevision: main
    path: deploy/helm/mockarty
    helm:
      valueFiles:
        - values.yaml
        # Use values.minimal.yaml for single-node or values.cluster.yaml for HA
      parameters:
        - name: admin.replicaCount
          value: "2"
        - name: admin.env.CLUSTER_MODE
          value: "true"
        - name: resolver.enabled
          value: "true"
        - name: runner.enabled
          value: "true"
  destination:
    server: https://kubernetes.default.svc
    namespace: mockarty
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true

Apply it:

kubectl apply -f mockarty-argocd-app.yaml

Option 2: CRD-based Operator via ArgoCD

If you use the Mockarty Operator, deploy the CRD and operator first, then manage MockartyCluster resources declaratively:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: mockarty-operator
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/mockarty/mockarty.git
    targetRevision: main
    path: deploy/operator
    directory:
      recurse: false
      include: "bundle.yaml"
  destination:
    server: https://kubernetes.default.svc
    namespace: mockarty-system
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
---
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: mockarty-cluster
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/your-org/gitops-configs.git
    targetRevision: main
    path: clusters/production/mockarty
  destination:
    server: https://kubernetes.default.svc
    namespace: mockarty
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Your GitOps repo would contain a MockartyCluster manifest:

# clusters/production/mockarty/cluster.yaml
apiVersion: mockarty.io/v1alpha1
kind: MockartyCluster
metadata:
  name: production
  namespace: mockarty
spec:
  adminNode:
    replicas: 2
    image: mockarty/mockarty:1.0.0
  resolver:
    enabled: true
    replicas: 2
  runner:
    enabled: true
    replicas: 3
  postgresql:
    host: postgres.database.svc
    port: 5432
    credentialsSecretRef:
      name: mockarty-db-credentials

ArgoCD Sync Waves

For proper ordering, use sync-wave annotations:

# Wave 0: Namespace + Secrets
apiVersion: v1
kind: Namespace
metadata:
  name: mockarty
  annotations:
    argocd.argoproj.io/sync-wave: "0"
---
# Wave 1: Database (if managed)
# Wave 2: Mockarty Helm release
# Wave 3: Token bootstrap job

Health Checks

ArgoCD automatically monitors Deployment health. Mockarty exposes three distinct endpoints — wire Kubernetes probes to the specific endpoints, not to plain /health:

• /health/live — liveness probe (HTTP 200 as long as the process is running). Safe for livenessProbe.
• /health/ready — readiness probe. Checks database and (if configured) Redis connectivity. Use for readinessProbe. Only registered when DB or Redis is wired — otherwise fall back to /health/live.
• /health — comprehensive health report with per-component statuses (DB, Redis, schedulers, etc.). Intended for operators and dashboards, not probes — it can return non-200 even when the pod should keep serving traffic.

Custom health check in ArgoCD:

resource.customizations.health.mockarty.io_MockartyCluster: |
  hs = {}
  if obj.status ~= nil then
    if obj.status.phase == "Ready" then
      hs.status = "Healthy"
      hs.message = "Cluster is running"
    elseif obj.status.phase == "Deploying" then
      hs.status = "Progressing"
      hs.message = "Cluster is deploying"
    else
      hs.status = "Degraded"
      hs.message = obj.status.phase
    end
  end
  return hs

FluxCD

Prerequisites

• Flux v2 installed (flux bootstrap)
• Git repository for cluster state
• Sealed Secrets or SOPS for secret management

Option 1: Helm Release

Create Flux resources in your GitOps repository:

# infrastructure/mockarty/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: mockarty
---
# infrastructure/mockarty/source.yaml
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: mockarty
  namespace: flux-system
spec:
  interval: 5m
  url: https://github.com/mockarty/mockarty.git
  ref:
    branch: main
---
# infrastructure/mockarty/release.yaml
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: mockarty
  namespace: mockarty
spec:
  interval: 10m
  chart:
    spec:
      chart: deploy/helm/mockarty
      sourceRef:
        kind: GitRepository
        name: mockarty
        namespace: flux-system
  values:
    admin:
      replicaCount: 2
      env:
        CLUSTER_MODE: "true"
    resolver:
      enabled: true
      replicaCount: 2
    runner:
      enabled: true
      replicaCount: 2
    postgresql:
      enabled: true
      auth:
        password: "${DB_PASSWORD}"
  valuesFrom:
    - kind: Secret
      name: mockarty-helm-values
      optional: true

Option 2: CRD-based Operator

# infrastructure/mockarty-operator/kustomization.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: mockarty-operator
  namespace: flux-system
spec:
  interval: 10m
  path: ./deploy/operator
  prune: true
  sourceRef:
    kind: GitRepository
    name: mockarty
  healthChecks:
    - apiVersion: apps/v1
      kind: Deployment
      name: mockarty-operator
      namespace: mockarty-system
---
# clusters/production/mockarty-cluster.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: mockarty-cluster
  namespace: flux-system
spec:
  dependsOn:
    - name: mockarty-operator
  interval: 10m
  path: ./clusters/production/mockarty
  prune: true
  sourceRef:
    kind: GitRepository
    name: fleet-config

Secrets Management with SOPS

Encrypt database credentials:

sops --encrypt --age age1... secrets.yaml > secrets.enc.yaml

# secrets.enc.yaml (before encryption)
apiVersion: v1
kind: Secret
metadata:
  name: mockarty-db-credentials
  namespace: mockarty
type: Opaque
stringData:
  DB_DSN: "postgres://mockarty:password@postgres:5432/mockarty?sslmode=disable"
  FIRST_ADMIN_PASSWORD: "your-admin-password"

Configure Flux decryption:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: mockarty
spec:
  decryption:
    provider: sops
    secretRef:
      name: sops-age

Notifications

Set up Flux notifications for deployment events:

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
metadata:
  name: mockarty-alerts
  namespace: flux-system
spec:
  providerRef:
    name: slack
  eventSeverity: error
  eventSources:
    - kind: HelmRelease
      name: mockarty
      namespace: mockarty

Upgrade Strategy

Both ArgoCD and FluxCD support controlled rollouts:

1. Update image tag in your GitOps repo (e.g., mockarty/mockarty:1.1.0)
2. Commit and push — GitOps controller detects the change
3. Rolling update — Kubernetes performs zero-downtime rolling deployment
4. Health checks — Controller verifies pods are healthy before proceeding
5. Automatic rollback — If health checks fail, the previous version is restored

Version Pinning

Always pin specific versions in production:

# Good: pinned version
image: mockarty/mockarty:1.2.3

# Bad: floating tag
image: mockarty/mockarty:latest

Recommended Directory Structure

gitops-repo/
  infrastructure/
    mockarty/
      namespace.yaml
      source.yaml           # GitRepository / HelmRepository
      release.yaml           # HelmRelease / ArgoCD Application
      secrets.enc.yaml       # Encrypted secrets (SOPS)
  clusters/
    production/
      mockarty/
        cluster.yaml         # MockartyCluster CR (if using operator)
        kustomization.yaml
    staging/
      mockarty/
        cluster.yaml
        kustomization.yaml