GitOps with ArgoCD

Overview

ArgoCD enables GitOps-based continuous delivery for MCP Server, automatically syncing Kubernetes resources from Git to multiple GKE clusters. Changes in Git trigger automated deployments with rollback capabilities.

Multi-Cluster

Manage dev, staging, prod from one ArgoCD instance

Auto-Sync

Git commits trigger automated deployments

Image Updater

Auto-update images from Artifact Registry

Workload Identity

Keyless authentication with GCP

GitOps Benefits

Single Source of Truth

Git is the authoritative source for all deployments.

No manual kubectl apply
Full audit trail (Git history)
Easy rollback (git revert)

Automated Deployment

ArgoCD watches Git and auto-syncs to clusters.

Merge PR → Automatic deployment
Reduced manual errors
Consistent across environments

Multi-Cluster Management

One ArgoCD instance manages all clusters.

Dev, staging, prod from single UI
ApplicationSets for environment parity
Centralized observability

Image Automation

ArgoCD Image Updater detects new images.

Monitors Artifact Registry
Creates PRs with new image tags
Semantic versioning support

Architecture

Flow:

Developer pushes code → GitHub
CI/CD builds image → Artifact Registry
ArgoCD Image Updater detects new image
Creates PR with updated image tag
After PR merge, ArgoCD syncs to cluster

Quick Setup (15 minutes)

Run Setup Script

./deployments/argocd/setup-argocd-gcp.sh YOUR_PROJECT_ID

What it does:

Installs ArgoCD in argocd namespace
Installs ArgoCD Image Updater
Configures Workload Identity
Sets up GCP service account with registry access

Get ArgoCD Admin Password

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d

Copy the password for login.

Access ArgoCD UI

Port Forward (Quick)
Ingress (Production)

kubectl port-forward svc/argocd-server -n argocd 8080:443

Open: https://localhost:8080Login:

Username: admin
Password: (from Step 2)

argocd-ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server
  namespace: argocd
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/ssl-passthrough: "true"
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - argocd.example.com
    secretName: argocd-tls
  rules:
  - host: argocd.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: argocd-server
            port:
              number: 443

kubectl apply -f argocd-ingress.yaml

Add GKE Clusters

Using argocd CLI
Using Secrets (Declarative)

# Get cluster contexts
gcloud container clusters get-credentials mcp-dev-gke \
  --region us-central1 --project YOUR_PROJECT_ID
gcloud container clusters get-credentials mcp-preview-gke \
  --region us-central1 --project YOUR_PROJECT_ID
gcloud container clusters get-credentials production-mcp-server-langgraph-gke \
  --region us-central1 --project YOUR_PROJECT_ID

# Install argocd CLI
brew install argocd  # macOS
# or: curl -sSL -o argocd https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64

# Login
argocd login localhost:8080 --username admin --password PASSWORD

# Add clusters
argocd cluster add gke_YOUR_PROJECT_ID_us-central1_mcp-dev-gke --name gcp-dev
argocd cluster add gke_YOUR_PROJECT_ID_us-central1_mcp-preview-gke --name gcp-staging
argocd cluster add gke_YOUR_PROJECT_ID_us-central1_production-mcp-server-langgraph-gke --name gcp-production

# Generate cluster secret YAML
kubectl config view --minify --flatten \
  --context=gke_YOUR_PROJECT_ID_us-central1_production-mcp-server-langgraph-gke > prod-cluster.yaml

# Apply to ArgoCD namespace
kubectl apply -f deployments/argocd/gcp-multi-cluster-setup.yaml

Update the cluster endpoints and CA certs in the YAML first.

Deploy ApplicationSet

# Edit cluster endpoints in the file
vim deployments/argocd/gcp-multi-cluster-setup.yaml

# Apply ApplicationSet
kubectl apply -f deployments/argocd/gcp-multi-cluster-setup.yaml

Creates 3 Applications (dev, staging, prod) from one definition.

Verify Sync

# List applications
argocd app list

# Check sync status
argocd app get mcp-server-gcp-production

# View in UI
# https://localhost:8080

All apps should show Synced and Healthy

ApplicationSet for Multi-Environment

Configuration

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: mcp-server-gcp-environments
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - cluster: gcp-dev
            url: https://GCP_DEV_ENDPOINT
            namespace: mcp-dev
            overlay: dev-gke
            replicas: "1"

          - cluster: gcp-staging
            url: https://GCP_STAGING_ENDPOINT
            namespace: staging-mcp-server-langgraph
            overlay: preview-gke
            replicas: "2"

          - cluster: gcp-production
            url: https://GCP_PROD_ENDPOINT
            namespace: production-mcp-server-langgraph
            overlay: production-gke
            replicas: "3"

  template:
    metadata:
      name: 'mcp-server-{{cluster}}'
    spec:
      source:
        repoURL: https://github.com/vishnu2kmohan/mcp-server-langgraph
        targetRevision: main
        path: 'deployments/overlays/{{overlay}}'

      destination:
        server: '{{url}}'
        namespace: '{{namespace}}'

      syncPolicy:
        automated:
          prune: true      # Delete resources removed from Git
          selfHeal: true   # Revert manual changes

        retry:
          limit: 5
          backoff:
            duration: 5s
            maxDuration: 3m

# ArgoCD generates 3 Applications:

1. mcp-server-gcp-dev
   - Cluster: gcp-dev
   - Path: deployments/overlays/dev-gke
   - Namespace: mcp-dev

2. mcp-server-gcp-staging
   - Cluster: gcp-staging
   - Path: deployments/overlays/preview-gke
   - Namespace: mcp-staging

3. mcp-server-gcp-production
   - Cluster: gcp-production
   - Path: deployments/overlays/production-gke
   - Namespace: mcp-production

Sync Policies

Automated (Recommended)
Manual
Hybrid

syncPolicy:
  automated:
    prune: true      # Auto-delete removed resources
    selfHeal: true   # Revert manual kubectl changes

Behavior:

Git commit → Automatic deployment
Manual changes reverted within 3 minutes
Resources removed from Git are deleted

Best for: Staging, production (strict GitOps)

syncPolicy:
  automated: null  # No automation

Behavior:

Git changes detected but not auto-applied
Click “Sync” in UI to deploy
Allows manual intervention

Best for: Development, testing

syncPolicy:
  automated:
    prune: false     # Don't auto-delete
    selfHeal: true   # But revert manual changes

Behavior:

Auto-sync new changes
Don’t delete resources
Revert manual edits

Best for: Migration period

ArgoCD Image Updater

Purpose

Automatically update container image tags when new versions are pushed to Artifact Registry.

Configuration

Configure Registry Access

argocd-image-updater-config.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-image-updater-config
  namespace: argocd
data:
  registries.conf: |
    registries:
    - name: gcp-artifact-registry
      api_url: https://us-central1-docker.pkg.dev
      prefix: us-central1-docker.pkg.dev
      credentials: ext:/scripts/gcp-credentials.sh
      default: true

Workload Identity handles authentication automatically.

Annotate Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: mcp-server-production-gke
  namespace: argocd
  annotations:
    # Image to watch
    argocd-image-updater.argoproj.io/image-list: |
      mcp-server=us-central1-docker.pkg.dev/PROJECT_ID/mcp-production/mcp-server-langgraph

    # Update strategy: semver (respect semantic versioning)
    argocd-image-updater.argoproj.io/mcp-server.update-strategy: semver

    # Only allow stable versions (v1.2.3, not v1.2.3-beta)
    argocd-image-updater.argoproj.io/mcp-server.allow-tags: regexp:^v?[0-9]+\.[0-9]+\.[0-9]+$

    # Write changes back to Git
    argocd-image-updater.argoproj.io/write-back-method: git
    argocd-image-updater.argoproj.io/write-back-target: kustomization

Update Strategy Options

Semver (Recommended)
Latest
Digest

argocd-image-updater.argoproj.io/mcp-server.update-strategy: semver
argocd-image-updater.argoproj.io/mcp-server.allow-tags: regexp:^v?[0-9]+\.[0-9]+\.[0-9]+$

Behavior: Upgrades to latest stable semver tag (v1.2.3 → v1.2.4)Skips: Pre-releases (v1.2.3-beta, v1.2.3-rc1)

argocd-image-updater.argoproj.io/mcp-server.update-strategy: latest

Behavior: Always use latest image (by timestamp)Risk: May deploy unstable builds

argocd-image-updater.argoproj.io/mcp-server.update-strategy: digest

Behavior: Pin to specific image SHA256 digestBest for: Maximum reproducibility

Workflow

Deployment Patterns

Progressive Delivery

1. Deploy to Dev (Automatic)

git push origin main

ArgoCD auto-syncs to dev cluster within 3 minutes.

2. Promote to Staging (Manual Sync)

# Option 1: argocd CLI
argocd app sync mcp-server-gcp-staging

# Option 2: UI
# Click "Sync" in ArgoCD UI for staging app

Validates in production-like environment.

3. Promote to Production (Approval Required)

Via GitHub Actions
Via ArgoCD Sync Waves

.github/workflows/promote-to-prod.yaml

name: Promote to Production
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to promote'
        required: true

jobs:
  promote:
    runs-on: ubuntu-latest
    environment: production  # Requires approval
    steps:
      - uses: actions/checkout@v4

      - name: Update production overlay
        run: |
          cd deployments/overlays/production-gke
          kustomize edit set image \
            mcp-server=us-central1-docker.pkg.dev/PROJECT_ID/mcp-production/mcp-server-langgraph:${{ github.event.inputs.version }}

      - name: Commit and push
        run: |
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git commit -am "Promote v${{ github.event.inputs.version }} to production"
          git push

Requires manual approval in GitHub.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "10"  # Deploy after wave 0-9

Controls deployment order across applications.

Canary Deployment

Use Flagger with ArgoCD for automated canary analysis:

apiVersion: flagger.app/v1beta1
kind: Canary
metadata:
  name: mcp-server-canary
  namespace: production-mcp-server-langgraph
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: production-mcp-server-langgraph
  progressDeadlineSeconds: 600
  service:
    port: 8000
  analysis:
    interval: 1m
    threshold: 5
    maxWeight: 50
    stepWeight: 10
    metrics:
    - name: request-success-rate
      thresholdRange:
        min: 99
      interval: 1m
    - name: request-duration
      thresholdRange:
        max: 500
      interval: 1m

Flow:

ArgoCD syncs new version
Flagger creates canary deployment (10% traffic)
Monitors metrics for 1 minute
If healthy, increases to 20%, 30%, … 100%
If unhealthy, auto-rollback

Monitoring & Troubleshooting

Application Health

Via CLI
Via UI

# List all apps
argocd app list

# Get detailed status
argocd app get mcp-server-gcp-production

# View sync history
argocd app history mcp-server-gcp-production

# View logs
argocd app logs mcp-server-gcp-production

Common Issues

Application stuck in 'Progressing'

Symptom: Application shows “Progressing” for >10 minutesCauses:

Deployment rollout waiting for pods
Resource quota exceeded
Image pull errors

Solution:

# Check pod status
kubectl get pods -n production-mcp-server-langgraph

# View pod events
kubectl describe pod POD_NAME -n production-mcp-server-langgraph

# Check ArgoCD sync logs
argocd app logs mcp-server-gcp-production

Out of Sync despite automated sync

Symptom: App shows “OutOfSync” with automated sync enabledCauses:

Manual kubectl changes (selfHeal disabled)
Ignored differences (e.g., replicas managed by HPA)
Sync failed due to error

Solution:

# Force sync
argocd app sync mcp-server-gcp-production --force

# View diff
argocd app diff mcp-server-gcp-production

# Ignore specific fields
argocd app set mcp-server-gcp-production \
  --ignore-difference group=apps,kind=Deployment,jsonPointers=/spec/replicas

Image Updater not detecting new images

Symptom: New images pushed to Artifact Registry, but no PR createdChecks:

# View Image Updater logs
kubectl logs -n argocd deployment/argocd-image-updater

# Check Workload Identity
kubectl describe sa argocd-image-updater -n argocd

# Verify GCP SA permissions
gcloud projects get-iam-policy PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:argocd-sa"

Common fix: Grant roles/artifactregistry.reader to GCP SA

Cluster not reachable

Symptom: ArgoCD can’t connect to GKE clusterSolution:

# Re-add cluster
argocd cluster add CONTEXT_NAME --name gcp-production

# Update cluster secret with new endpoint/cert
kubectl edit secret gcp-production-cluster -n argocd

Security Best Practices

Enable RBAC for ArgoCD users

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.csv: |
    # Developers: read-only access
    p, role:developers, applications, get, */*, allow
    p, role:developers, applications, sync, dev/*, allow
    g, engineering@example.com, role:developers

    # DevOps: full access to staging/prod
    p, role:devops, applications, *, */*, allow
    p, role:devops, clusters, *, *, allow
    g, devops@example.com, role:devops

Use Workload Identity (no service account keys)

Already configured by setup script.

Enable audit logging

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  audit.log.enabled: "true"
  audit.log.maxsize: "100"  # MB
  audit.log.maxage: "30"    # days

Restrict allowed Git repos

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  repositories: |
    - url: https://github.com/vishnu2kmohan/mcp-server-langgraph
      name: mcp-server-langgraph
    # Deny all others

GKE Production

Production deployment with Kustomize overlays

Binary Authorization

Image signing for secure deployments

CI/CD Pipeline

GitHub Actions workflow with ArgoCD

Operations Runbooks

Incident response and troubleshooting

Next Steps

Install ArgoCD

./deployments/argocd/setup-argocd-gcp.sh PROJECT_ID

Add Clusters

argocd cluster add CONTEXT --name gcp-production

Deploy ApplicationSet

kubectl apply -f deployments/argocd/gcp-multi-cluster-setup.yaml

Configure Image Updater

Add annotations to Application for automatic image updates

Enable Monitoring

Operations Guide →

Getting Started

Deployment Options

LangGraph Platform

Kubernetes - GKE

Kubernetes - EKS & AKS

Kubernetes - Best Practices

Infrastructure as Code

Monitoring & Observability

Advanced Deployment

Configuration

Operations

Overview

Multi-Cluster

Auto-Sync

Image Updater

Workload Identity

GitOps Benefits

Architecture

Quick Setup (15 minutes)

ApplicationSet for Multi-Environment

Configuration

Sync Policies

ArgoCD Image Updater

Purpose

Configuration

Workflow

Deployment Patterns

Progressive Delivery

Canary Deployment

Monitoring & Troubleshooting

Application Health

Common Issues

Security Best Practices

GKE Production

Binary Authorization

CI/CD Pipeline

Operations Runbooks

Next Steps

​Overview

Multi-Cluster

Auto-Sync

Image Updater

Workload Identity

​GitOps Benefits

​Architecture

​Quick Setup (15 minutes)

​ApplicationSet for Multi-Environment

​Configuration

​Sync Policies

​ArgoCD Image Updater

​Purpose

​Configuration

​Workflow

​Deployment Patterns

​Progressive Delivery

​Canary Deployment

​Monitoring & Troubleshooting

​Application Health

​Common Issues

​Security Best Practices

​Related Documentation

GKE Production

Binary Authorization

CI/CD Pipeline

Operations Runbooks

​Next Steps

Overview

GitOps Benefits

Architecture

Quick Setup (15 minutes)

ApplicationSet for Multi-Environment

Configuration

Sync Policies

ArgoCD Image Updater

Purpose

Configuration

Workflow

Deployment Patterns

Progressive Delivery

Canary Deployment

Monitoring & Troubleshooting

Application Health

Common Issues

Security Best Practices

Related Documentation

Next Steps