k8s-gitops

Original source / Raw SKILL.md

---
name: k8s-gitops
description: Manage GitOps workflows with Flux and ArgoCD. Use for sync status, reconciliation, app management, source management, and GitOps troubleshooting.
license: Apache-2.0
metadata:
  author: rohitg00
  version: "1.0.0"
  tools: 7
  category: 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

| Priority | Rule | Impact | Tools |
|----------|------|--------|-------|
| 1 | Check source readiness before troubleshooting | CRITICAL | `flux_sources_list_tool` |
| 2 | Verify sync status before deployments | HIGH | `argocd_app_get_tool` |
| 3 | Reconcile after git changes | MEDIUM | `flux_reconcile_tool` |
| 4 | Suspend before manual changes | LOW | `flux_suspend_tool` |

## Quick Reference

| Task | Tool | Example |
|------|------|---------|
| List Flux kustomizations | `flux_kustomizations_list_tool` | `flux_kustomizations_list_tool(namespace)` |
| Reconcile Flux | `flux_reconcile_tool` | `flux_reconcile_tool(kind, name, namespace)` |
| List ArgoCD apps | `argocd_apps_list_tool` | `argocd_apps_list_tool(namespace)` |
| Sync ArgoCD | `argocd_sync_tool` | `argocd_sync_tool(name, namespace)` |

## Flux CD

### Check Flux Status

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

### Reconcile Resources

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

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

### Suspend/Resume

```python
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](FLUX.md) for detailed Flux workflows.

## ArgoCD

### List Applications

```python
argocd_apps_list_tool(namespace="argocd")
```

### Get App Status

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

### Sync Application

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

### Refresh App

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

See [ARGOCD.md](ARGOCD.md) for detailed ArgoCD workflows.

## GitOps Troubleshooting

### Flux Not Syncing

| Symptom | Check | Resolution |
|---------|-------|------------|
| Source not ready | `flux_sources_list_tool()` | Check git credentials |
| Kustomization failed | `flux_kustomizations_list_tool()` | Check manifest errors |
| HelmRelease failed | `flux_helmreleases_list_tool()` | Check values, chart version |

### ArgoCD Out of Sync

| Symptom | Check | Resolution |
|---------|-------|------------|
| OutOfSync | `argocd_app_get_tool()` | Manual sync or check auto-sync |
| Degraded | Check health status | Fix unhealthy resources |
| Unknown | Refresh app | `argocd_refresh_tool()` |

## Environment Promotion

### With Flux Kustomizations

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

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

### With ArgoCD

```python
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:

```python
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:

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

flux_kustomizations_list_tool(namespace="flux-system")
```

## Prerequisites

- **Flux**: Required for Flux tools
  ```bash
  flux install
  ```
- **ArgoCD**: Required for ArgoCD tools
  ```bash
  kubectl create namespace argocd
  kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
  ```

## Related Skills

- [k8s-deploy](../k8s-deploy/SKILL.md) - Standard deployments
- [k8s-helm](../k8s-helm/SKILL.md) - Helm chart management


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### FLUX.md

```markdown
# Flux CD Deep Dive

Detailed workflows for GitOps with Flux.

## Flux Resources

### GitRepository Source

```yaml
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

```yaml
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

```yaml
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

```python
# 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
```

```

### ARGOCD.md

```markdown
# ArgoCD Deep Dive

Detailed workflows for GitOps with ArgoCD.

## ArgoCD Resources

### Application

```yaml
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

```yaml
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

```python
# 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

| State | Meaning | Action |
|-------|---------|--------|
| Synced | Matches desired state | None |
| OutOfSync | Differs from git | Sync |
| Unknown | Cannot determine | Refresh |
| Missing | Resource deleted | Sync |

## Health States

| State | Meaning | Action |
|-------|---------|--------|
| Healthy | All resources ready | None |
| Progressing | Resources updating | Wait |
| Degraded | Resources failing | Debug |
| Suspended | Manually paused | Resume |
| Missing | App doesn't exist | Create |

## 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:

```yaml
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

| Option | Purpose |
|--------|---------|
| Prune | Delete resources removed from git |
| SelfHeal | Auto-fix manual changes |
| CreateNamespace | Create target namespace |
| ApplyOutOfSyncOnly | Only sync changed resources |
| SkipDryRunOnMissingResource | Skip validation |

```

### ../k8s-deploy/SKILL.md

```markdown
---
name: k8s-deploy
description: Deploy and manage Kubernetes workloads with progressive delivery. Use for deployments, rollouts, blue-green, canary releases, scaling, and release management.
license: Apache-2.0
metadata:
  author: rohitg00
  version: "1.0.0"
  tools: 20
  category: workloads
---

# Kubernetes Deployment Workflows

Comprehensive deployment strategies using kubectl-mcp-server tools, including Argo Rollouts and Flagger for progressive delivery.

## When to Apply

Use this skill when:
- User mentions: "deploy", "release", "rollout", "scale", "update", "upgrade"
- Operations: creating deployments, updating images, scaling replicas
- Strategies: canary, blue-green, rolling update, recreate
- Keywords: "new version", "push to production", "traffic shifting"

## Priority Rules

| Priority | Rule | Impact | Tools |
|----------|------|--------|-------|
| 1 | Preview with template before apply | CRITICAL | `template_helm_chart` |
| 2 | Check existing state first | CRITICAL | `get_pods`, `list_helm_releases` |
| 3 | Use progressive delivery for prod | HIGH | `rollout_*` tools |
| 4 | Verify health after deployment | HIGH | `get_pod_metrics`, `get_endpoints` |
| 5 | Keep rollback revision noted | MEDIUM | `get_helm_history` |
| 6 | Scale incrementally | LOW | `scale_deployment` |

## Quick Reference

| Task | Tool | Example |
|------|------|---------|
| Deploy from manifest | `kubectl_apply` | `apply_manifest(yaml, namespace)` |
| Deploy with Helm | `install_helm_chart` | `install_helm_chart(name, chart, namespace)` |
| Update image | `set_deployment_image` | `set_deployment_image(name, ns, container, image)` |
| Scale replicas | `scale_deployment` | `scale_deployment(name, ns, replicas=5)` |
| Rollback | `rollback_deployment` | `rollback_deployment(name, ns, revision=0)` |
| Canary promote | `rollout_promote_tool` | `rollout_promote_tool(name, ns)` |

## Standard Deployments

### Deploy from Manifest

```python
kubectl_apply(manifest_yaml, namespace)
```

### Deploy with Helm

```python
install_helm_chart(
    name="my-app",
    chart="bitnami/nginx",
    namespace="production",
    values={"replicaCount": 3}
)
```

### Scale Deployment

```python
scale_deployment(name, namespace, replicas=5)
```

### Rolling Update

```python
set_deployment_image(name, namespace, container="app", image="myapp:v2")

rollout_status(name, namespace, resource_type="deployment")
```

## Progressive Delivery

### Argo Rollouts (Recommended)

For canary and blue-green deployments with analysis.

**List Rollouts**
```python
rollouts_list_tool(namespace)
```

**Canary Promotion**
```python
rollout_status_tool(name, namespace)

rollout_promote_tool(name, namespace)
```

**Abort Bad Release**
```python
rollout_abort_tool(name, namespace)
```

**Retry Failed Rollout**
```python
rollout_retry_tool(name, namespace)
```

See [ROLLOUTS.md](ROLLOUTS.md) for detailed Argo Rollouts workflows.

### Flagger Canary

For service mesh-integrated canary releases:

```python
flagger_canaries_list_tool(namespace)
flagger_canary_get_tool(name, namespace)
```

## Deployment Strategies

| Strategy | Use Case | Tools |
|----------|----------|-------|
| Rolling | Standard updates | `set_deployment_image`, `rollout_status` |
| Recreate | Stateful apps | Set strategy in manifest |
| Canary | Risk mitigation | `rollout_*` tools |
| Blue-Green | Zero downtime | `rollout_*` with blue-green |

See [references/STRATEGIES.md](references/STRATEGIES.md) for detailed strategy comparisons.

## Rollback Operations

### Native Kubernetes

```python
rollback_deployment(name, namespace, revision=0)

rollback_deployment(name, namespace, revision=2)
```

### Helm Rollback

```python
rollback_helm_release(name, namespace, revision=1)
```

### Argo Rollouts Rollback

```python
rollout_abort_tool(name, namespace)
```

## Health Verification

After deployment, verify health:

```python
get_pods(namespace, label_selector="app=myapp")

get_pod_metrics(name, namespace)

get_endpoints(namespace)
```

## Multi-Cluster Deployments

Deploy to specific clusters using context:

```python
install_helm_chart(
    name="app",
    chart="./charts/app",
    namespace="prod",
    context="production-us-east"
)

install_helm_chart(
    name="app",
    chart="./charts/app",
    namespace="prod",
    context="production-eu-west"
)
```

## Example Manifests

See [examples/](examples/) for ready-to-use deployment manifests:
- [examples/canary-rollout.yaml](examples/canary-rollout.yaml) - Argo Rollouts canary
- [examples/blue-green.yaml](examples/blue-green.yaml) - Blue-green deployment
- [examples/hpa-deployment.yaml](examples/hpa-deployment.yaml) - Deployment with HPA

## Prerequisites

- **Argo Rollouts**: Required for `rollout_*` tools
  ```bash
  kubectl create namespace argo-rollouts
  kubectl apply -n argo-rollouts -f https://github.com/argoproj/argo-rollouts/releases/latest/download/install.yaml
  ```
- **Flagger**: Required for `flagger_*` tools
  ```bash
  kubectl apply -k github.com/fluxcd/flagger/kustomize/kubernetes
  ```

## Related Skills

- [k8s-gitops](../k8s-gitops/SKILL.md) - GitOps deployments with Flux/ArgoCD
- [k8s-autoscaling](../k8s-autoscaling/SKILL.md) - Auto-scale deployments
- [k8s-rollouts](../k8s-rollouts/SKILL.md) - Advanced progressive delivery
- [k8s-helm](../k8s-helm/SKILL.md) - Helm chart operations

```

### ../k8s-helm/SKILL.md

```markdown
---
name: k8s-helm
description: Manage Helm charts, releases, and repositories. Use for Helm installations, upgrades, rollbacks, chart development, and release management.
license: Apache-2.0
metadata:
  author: rohitg00
  version: "1.0.0"
  tools: 16
  category: workloads
---

# Helm Chart Management

Comprehensive Helm v3 operations using kubectl-mcp-server's 16 Helm tools.

## When to Apply

Use this skill when:
- User mentions: "helm", "chart", "release", "values", "repository"
- Operations: installing charts, upgrading releases, rollbacks
- Keywords: "package", "template", "lint", "repo add"

## Priority Rules

| Priority | Rule | Impact | Tools |
|----------|------|--------|-------|
| 1 | Template before install (dry run) | CRITICAL | `template_helm_chart` |
| 2 | Check existing releases first | CRITICAL | `list_helm_releases` |
| 3 | Lint charts before packaging | HIGH | `lint_helm_chart` |
| 4 | Note revision before upgrade | HIGH | `get_helm_history` |
| 5 | Verify values after upgrade | MEDIUM | `get_helm_values` |
| 6 | Update repos before search | LOW | `update_helm_repos` |

## Quick Reference

| Task | Tool | Example |
|------|------|---------|
| Install chart | `install_helm_chart` | `install_helm_chart(name, chart, namespace)` |
| Upgrade release | `upgrade_helm_release` | `upgrade_helm_release(name, chart, namespace, values)` |
| Rollback | `rollback_helm_release` | `rollback_helm_release(name, namespace, revision)` |
| List releases | `list_helm_releases` | `list_helm_releases(namespace)` |
| Get values | `get_helm_values` | `get_helm_values(name, namespace)` |
| Template (dry run) | `template_helm_chart` | `template_helm_chart(name, chart, namespace)` |

## Install Chart

```python
install_helm_chart(
    name="my-release",
    chart="bitnami/nginx",
    namespace="web",
    values={"replicaCount": 3, "service.type": "LoadBalancer"}
)
```

## Upgrade Release

```python
upgrade_helm_release(
    name="my-release",
    chart="bitnami/nginx",
    namespace="web",
    values={"replicaCount": 5}
)
```

## Rollback Release

```python
rollback_helm_release(
    name="my-release",
    namespace="web",
    revision=1
)
```

## Uninstall Release

```python
uninstall_helm_chart(name="my-release", namespace="web")
```

## Release Management

### List Releases

```python
list_helm_releases(namespace="web")

list_helm_releases()
```

### Get Release Details

```python
get_helm_release(name="my-release", namespace="web")
```

### Release History

```python
get_helm_history(name="my-release", namespace="web")
```

### Get Release Values

```python
get_helm_values(name="my-release", namespace="web")
```

### Get Release Manifest

```python
get_helm_manifest(name="my-release", namespace="web")
```

## Repository Management

### Add Repository

```python
add_helm_repo(name="bitnami", url="https://charts.bitnami.com/bitnami")
```

### List Repositories

```python
list_helm_repos()
```

### Update Repositories

```python
update_helm_repos()
```

### Search Charts

```python
search_helm_charts(keyword="nginx")

search_helm_charts(keyword="postgres", repo="bitnami")
```

## Chart Development

### Template Chart (Dry Run)

```python
template_helm_chart(
    name="my-release",
    chart="./my-chart",
    namespace="test",
    values={"key": "value"}
)
```

### Lint Chart

```python
lint_helm_chart(chart="./my-chart")
```

### Package Chart

```python
package_helm_chart(chart="./my-chart", destination="./packages")
```

## Common Workflows

### New Application Deployment

```python
add_helm_repo(name="bitnami", url="...")

search_helm_charts(keyword="postgresql")

template_helm_chart(...)

install_helm_chart(...)

get_helm_release(...)
```

### Upgrade with Rollback Safety

```python
get_helm_history(name, namespace)

upgrade_helm_release(name, chart, namespace, values)

rollback_helm_release(name, namespace, revision)
```

### Multi-Environment Deployment

```python
install_helm_chart(
    name="app",
    chart="./charts/app",
    namespace="dev",
    values={"replicas": 1},
    context="development"
)

install_helm_chart(
    name="app",
    chart="./charts/app",
    namespace="staging",
    values={"replicas": 2},
    context="staging"
)

install_helm_chart(
    name="app",
    chart="./charts/app",
    namespace="prod",
    values={"replicas": 5},
    context="production"
)
```

## Chart Structure

See [references/CHART-STRUCTURE.md](references/CHART-STRUCTURE.md) for best practices on organizing Helm charts.

## Troubleshooting

See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues.

### Release Stuck in Pending

```python
get_helm_release(name, namespace)

get_pods(namespace, label_selector="app.kubernetes.io/instance=<release>")
```

### Failed Installation

```python
get_helm_history(name, namespace)

get_events(namespace)

uninstall_helm_chart(name, namespace)
```

### Values Not Applied

```python
get_helm_values(name, namespace)

template_helm_chart(...)

upgrade_helm_release(...)
```

## Scripts

See [scripts/lint-chart.sh](scripts/lint-chart.sh) for automated chart validation.

## Best Practices

1. **Always Template First**
   ```python
   template_helm_chart(name, chart, namespace, values)
   ```

2. **Use Semantic Versioning**
   ```python
   install_helm_chart(..., version="1.2.3")
   ```

3. **Store Values in Git**
   - `values-dev.yaml`
   - `values-staging.yaml`
   - `values-prod.yaml`

4. **Namespace Isolation**
   - One namespace per release
   - Easier cleanup and RBAC

## Prerequisites

- **Helm CLI**: Required for all Helm operations
  ```bash
  curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
  ```

## Related Skills

- [k8s-deploy](../k8s-deploy/SKILL.md) - Deployment strategies
- [k8s-gitops](../k8s-gitops/SKILL.md) - GitOps Helm releases

```