K8s Gitops

Kubernetes GitOps

GitOps workflows using Flux and ArgoCD with kubectl-mcp-server tools.

When to Apply

Use this skill when:

• User mentions: "Flux", "ArgoCD", "GitOps", "sync", "reconcile"
• Operations: checking sync status, triggering reconciliation, drift detection
• Keywords: "out of sync", "deploy from git", "continuous delivery"

Priority Rules

Quick Reference

Flux CD

Check Flux Status

flux_kustomizations_list_tool(namespace="flux-system")
flux_helmreleases_list_tool(namespace)
flux_sources_list_tool(namespace="flux-system")

Reconcile Resources

flux_reconcile_tool(
    kind="kustomization",
    name="my-app",
    namespace="flux-system"
)

flux_reconcile_tool(
    kind="helmrelease",
    name="my-chart",
    namespace="default"
)

Suspend/Resume

flux_suspend_tool(kind="kustomization", name="my-app", namespace="flux-system")

flux_resume_tool(kind="kustomization", name="my-app", namespace="flux-system")

See FLUX.md for detailed Flux workflows.

ArgoCD

List Applications

argocd_apps_list_tool(namespace="argocd")

Get App Status

argocd_app_get_tool(name="my-app", namespace="argocd")

Sync Application

argocd_sync_tool(name="my-app", namespace="argocd")

Refresh App

argocd_refresh_tool(name="my-app", namespace="argocd")

See ARGOCD.md for detailed ArgoCD workflows.

GitOps Troubleshooting

Flux Not Syncing

ArgoCD Out of Sync

Environment Promotion

With Flux Kustomizations

flux_reconcile_tool(kind="kustomization", name="staging", namespace="flux-system")

flux_reconcile_tool(kind="kustomization", name="production", namespace="flux-system")

With ArgoCD

argocd_sync_tool(name="app-staging", namespace="argocd")

argocd_app_get_tool(name="app-staging", namespace="argocd")

argocd_sync_tool(name="app-production", namespace="argocd")

Multi-Cluster GitOps

Manage GitOps across clusters:

flux_kustomizations_list_tool(namespace="flux-system", context="cluster-1")
flux_kustomizations_list_tool(namespace="flux-system", context="cluster-2")

flux_reconcile_tool(
    kind="kustomization",
    name="apps",
    namespace="flux-system",
    context="production-cluster"
)

Drift Detection

Compare live state with desired:

argocd_app_get_tool(name="my-app", namespace="argocd")

flux_kustomizations_list_tool(namespace="flux-system")

Prerequisites

• Flux: Required for Flux tools

  flux install

• ArgoCD: Required for ArgoCD tools

  kubectl create namespace argocd
  kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Related Skills

• k8s-deploy - Standard deployments
• k8s-helm - Helm chart management

ArgoCD Deep Dive

Detailed workflows for GitOps with ArgoCD.

ArgoCD Resources

Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/my-app
    targetRevision: HEAD
    path: deploy/production
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

ApplicationSet

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-app
  namespace: argocd
spec:
  generators:
  - list:
      elements:
      - cluster: production
        url: https://prod.k8s.local
      - cluster: staging
        url: https://staging.k8s.local
  template:
    metadata:
      name: 'my-app-{{cluster}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/my-app
        path: 'deploy/{{cluster}}'
      destination:
        server: '{{url}}'
        namespace: my-app

MCP Server Tools

# List all applications
argocd_apps_list_tool(namespace="argocd")

# Get application details
argocd_app_get_tool(name="my-app", namespace="argocd")

# Sync application
argocd_sync_tool(name="my-app", namespace="argocd")

# Refresh application (fetch latest from git)
argocd_refresh_tool(name="my-app", namespace="argocd")

Application States

Health States

Common Workflows

Check Application Status

1. argocd_apps_list_tool(namespace="argocd")
2. argocd_app_get_tool(name="my-app", namespace="argocd")

Force Sync

argocd_refresh_tool(name="my-app", namespace="argocd")  # Refresh first
argocd_sync_tool(name="my-app", namespace="argocd")     # Then sync

Sync with Prune

When resources are deleted from git:

argocd_sync_tool(name="my-app", namespace="argocd", prune=True)

Multi-Cluster Deployment

ArgoCD can manage multiple clusters:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-prod
spec:
  destination:
    server: https://prod-cluster.k8s.local  # External cluster
    namespace: production

Troubleshooting

OutOfSync

argocd_app_get_tool(name, namespace)
# Check diff between desired and live state
# May need manual sync or auto-sync enabled

Sync Failed

argocd_app_get_tool(name, namespace)
get_events(namespace=target_namespace)
# Check:
# - RBAC permissions
# - Resource conflicts
# - Namespace exists

Degraded Health

argocd_app_get_tool(name, namespace)
get_pods(namespace=target_namespace)
describe_pod(name, target_namespace)

Sync Options

Flux CD Deep Dive

Detailed workflows for GitOps with Flux.

Flux Resources

GitRepository Source

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/org/my-app
  ref:
    branch: main
  secretRef:
    name: git-credentials

Kustomization

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 5m
  path: ./deploy/production
  prune: true
  sourceRef:
    kind: GitRepository
    name: my-app
  healthChecks:
  - apiVersion: apps/v1
    kind: Deployment
    name: my-app
    namespace: production

HelmRelease

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: my-app
  namespace: production
spec:
  interval: 5m
  chart:
    spec:
      chart: my-app
      version: "1.2.x"
      sourceRef:
        kind: HelmRepository
        name: my-charts
        namespace: flux-system
  values:
    replicas: 3

MCP Server Tools

# List sources (GitRepository, HelmRepository, etc.)
flux_sources_list_tool(namespace="flux-system")

# List Kustomizations
flux_kustomizations_list_tool(namespace="flux-system")

# List HelmReleases
flux_helmreleases_list_tool(namespace="production")

# Force reconciliation
flux_reconcile_tool(
    kind="kustomization",
    name="my-app",
    namespace="flux-system"
)

# Suspend reconciliation
flux_suspend_tool(
    kind="kustomization",
    name="my-app",
    namespace="flux-system"
)

# Resume reconciliation
flux_resume_tool(
    kind="kustomization",
    name="my-app",
    namespace="flux-system"
)

Common Workflows

Check Sync Status

1. flux_sources_list_tool(namespace="flux-system")  # Source ready?
2. flux_kustomizations_list_tool(namespace="flux-system")  # Applied?
3. flux_helmreleases_list_tool(namespace="production")  # Helm ready?

Force Sync

flux_reconcile_tool(kind="gitrepository", name="my-app", namespace="flux-system")
flux_reconcile_tool(kind="kustomization", name="my-app", namespace="flux-system")

Pause for Maintenance

flux_suspend_tool(kind="kustomization", name="production", namespace="flux-system")
# Do maintenance
flux_resume_tool(kind="kustomization", name="production", namespace="flux-system")

Troubleshooting

Source Not Ready

flux_sources_list_tool(namespace="flux-system")
# Check:
# - Git URL correct
# - Secret exists and has valid credentials
# - Network access to git server

Kustomization Failed

flux_kustomizations_list_tool(namespace="flux-system")
get_events(namespace="flux-system")
# Check:
# - Path exists in repo
# - Kustomization.yaml valid
# - Target namespace exists

HelmRelease Failed

flux_helmreleases_list_tool(namespace)
get_events(namespace)
# Check:
# - Chart exists in repo
# - Version exists
# - Values are valid

Multi-Environment Setup

flux-system/
├── sources/
│   └── git-repository.yaml
├── clusters/
│   ├── production/
│   │   └── kustomization.yaml
│   └── staging/
│       └── kustomization.yaml
└── apps/
    ├── base/
    │   ├── deployment.yaml
    │   └── kustomization.yaml
    ├── production/
    │   └── kustomization.yaml
    └── staging/
        └── kustomization.yaml