Zero-Downtime Migration (Argo CD)
Migrate a Deployment managed by Argo CD to Argo Rollouts without downtime. Argo CD reverts cluster-direct changes, so scale-down of the Deployment must be done via Git commits. See workloadRef Migration for gradual migration details and ArgoCD GitOps for ignoreDifferences.
Prerequisites
| Component | Status |
|---|---|
| Argo CD | Installed and managing the Deployment |
| Argo Rollouts | Installed in cluster |
| Argo Rollout MCP Server | Running (Docker recommended) |
| Existing Deployment | Exists in target namespace, managed by Argo CD from Git |
Key Principle
Argo CD reverts cluster-direct changes. Scale-down of the Deployment must be done via Git commits (or
ignoreDifferencesforworkloadRef). Useargo_manage_legacy_deployment(action='generate_scale_down_manifest')for the GitOps path;argo_manage_legacy_deployment(action='scale_cluster'|'delete_cluster')only for non–Argo CD–managed workloads.
Environment Setup
Verify Argo CD and Deployment
argocd app get hello-world
kubectl get deployment hello-world -n default
Start MCP Server (Docker — recommended)
docker run --rm -it \
-p 8768:8768 \
-v ~/.kube:/app/.kube:ro \
-e K8S_KUBECONFIG=/app/.kube/config \
talkopsai/argo-rollout-mcp-server:latest
Validate Readiness Workflow
| Step | Action | Prompt / Tool |
|---|---|---|
| 1 | Validate | "Run validate_deployment_ready for hello-world in default before zero-downtime migration." |
| 2 | Or use tool | validate_deployment_ready(deployment_name="hello-world", namespace="default") |
| 3 | Fix issues | Address any blocking issues (selector, template, pod-template-hash in Service) |
Convert with workloadRef Workflow (Co-Existence)
| Step | Action | Prompt / Tool |
|---|---|---|
| 1 | Convert | "Convert the hello-world deployment in default to an Argo Rollout using workloadRef mode — keep the existing Deployment running, scale_down=never. Apply to cluster." |
| 2 | Or use tool | convert_deployment_to_rollout(deployment_name="hello-world", namespace="default", strategy="canary", migration_mode="workload_ref", scale_down="never", apply=True) |
| 3 | Verify | Rollout and Deployment run in parallel (co-existence) |
Generate ArgoCD ignoreDifferences Workflow
| Step | Action | Prompt / Tool |
|---|---|---|
| 1 | Generate | "Generate ArgoCD ignoreDifferences for hello-world in default with include_deployment_replicas so Argo CD won't revert the Rollout's scale-down of the Deployment." |
| 2 | Or use tool | generate_argocd_ignore_differences(include_deployment_replicas=True, deployment_name="hello-world") |
| 3 | Add to Application | Paste output into Application.spec.ignoreDifferences |
| 4 | Commit and sync | Commit to Git, Argo CD syncs |
Update scaleDown Workflow
| Step | Action | Prompt / Tool |
|---|---|---|
| 1 | Update | "Change the workloadRef scaleDown on hello-world rollout in default to progressively." |
| 2 | Or use tool | argo_update_rollout(update_type='workload_ref', name="hello-world", namespace="default", scale_down="progressively") |
Scale Down Deployment — GitOps Path (Argo CD–Managed)
| Step | Action | Prompt / Tool |
|---|---|---|
| 1 | Generate manifest | "Generate the Deployment scale-down YAML for hello-world in default — I'll commit it to Git for Argo CD to apply after the Rollout is stable." |
| 2 | Or use tool | argo_manage_legacy_deployment(action='generate_scale_down_manifest', name="hello-world", namespace="default") |
| 3 | Commit to Git | Add the returned Deployment YAML (with replicas: 0) to your repo |
| 4 | Sync | Argo CD applies the change; Deployment scales to 0 |
Scale Down Deployment — Non-GitOps Path
When Deployment is not managed by Argo CD:
| Step | Action | Prompt / Tool |
|---|---|---|
| 1 | Scale to 0 | Use tool: argo_manage_legacy_deployment(action='scale_cluster', name="hello-world", namespace="default", replicas=0) |
| 2 | Verify | kubectl get deployment hello-world -n default |
Delete Deployment (Non-GitOps Only)
| Step | Action | Prompt / Tool |
|---|---|---|
| 1 | Delete | Use tool: argo_manage_legacy_deployment(action='delete_cluster', name="hello-world", namespace="default") |
| 2 | Warning | Only when not managed by Argo CD. Argo CD will recreate if still in Git. |
Natural Language Prompts
Copy-paste these prompts into your MCP client (Cursor, Claude, etc.).
Validate
"Run validate_deployment_ready for hello-world in default before zero-downtime migration."
Convert (workloadRef)
"Convert the hello-world deployment in default to an Argo Rollout using workloadRef mode — keep the existing Deployment running, scale_down=never. Apply to cluster."
ignoreDifferences
"Generate ArgoCD ignoreDifferences for hello-world in default with include_deployment_replicas so Argo CD won't revert the Rollout's scale-down of the Deployment."
Scale-Down Manifest (GitOps)
"Generate the Deployment scale-down YAML for hello-world in default — I'll commit it to Git for Argo CD to apply after the Rollout is stable."
Full Sequence
"Run validate_deployment_ready for hello-world in default before zero-downtime migration."
"Generate ArgoCD ignoreDifferences for hello-world in default with include_deployment_replicas so Argo CD won't revert the Rollout's scale-down of the Deployment."
"Generate the Deployment scale-down YAML for hello-world in default — I'll commit it to Git for Argo CD to apply after the Rollout is stable."
Quick Reference: Tool → Migration Step
| Migration Step | Tool | Notes |
|---|---|---|
| 1. Validate readiness | validate_deployment_ready | Structural + Service selector (no pod-template-hash) |
| 2. Introduce Rollout (workloadRef) | convert_deployment_to_rollout(migration_mode="workload_ref", scale_down="never", apply=True) | Co-existence phase |
| 3. Argo CD ignoreDifferences | generate_argocd_ignore_differences(include_deployment_replicas=True, deployment_name="hello-world") | Prevents revert of scale-down |
| 4. Switch traffic | Traffic MCP server (out of scope) | Traefik, Istio, etc. |
| 5. Update scaleDown | argo_update_rollout(update_type='workload_ref', scale_down="progressively") | never → onsuccess or progressively |
| 6. Scale down Deployment | GitOps: argo_manage_legacy_deployment(action='generate_scale_down_manifest') → commit YAML. Non-GitOps: argo_manage_legacy_deployment(action='scale_cluster', replicas=0) | Argo CD reverts cluster-direct scale |
| 7. Delete Deployment (optional) | Non-GitOps: argo_manage_legacy_deployment(action='delete_cluster') | Only when not managed by Argo CD |
Troubleshooting
| Issue | Check |
|---|---|
| Argo CD reverts Deployment scale-down | Use Git path: generate_scale_down_manifest → commit YAML. Add include_deployment_replicas=True to ignoreDifferences. |
| Rollout and Deployment both running | Expected during co-existence. Update scale_down to onsuccess or progressively when ready. |
| Traffic not switching | Traffic switching is out of scope for this MCP server. Configure Traefik/Istio separately. |
| ignoreDifferences not applied | Ensure output is in Application.spec.ignoreDifferences. Sync the Application. |
| Deployment still in Git | Remove Deployment manifest from Git repo before or after scale-down, depending on your GitOps workflow. |
Next Steps
- workloadRef Migration — Gradual migration details
- ArgoCD GitOps — ignoreDifferences reference
- Tools — Full tool reference
- Examples — Quick reference and prompts