Onboarding — Deployment to Rollout
Migrate an existing application running as a standard Kubernetes Deployment to Argo Rollouts for progressive delivery. This guide covers the complete flow from validation through verification, including optional analysis, traffic routing, and Argo CD integration.
Prerequisites
| Component | Status |
|---|---|
| Kubernetes cluster | Accessible via kubectl |
| Argo Rollouts | Installed (kubectl get rollouts -A) |
| Argo Rollout MCP Server | Running (Docker recommended) |
| Existing Deployment | Exists in a known namespace |
| Prometheus | For analysis (optional) |
| Traefik / Ingress | For canary traffic routing (optional) |
Application Requirements
Before onboarding, the existing application must have:
| Requirement | Details | Validated By |
|---|---|---|
| Container Image | Pushed to a registry | Manual |
| Kubernetes Deployment | Standard Deployment YAML | validate_deployment_ready |
| Health Probes | Readiness and liveness probes | validate_deployment_ready |
| Resource Requests | CPU/memory requests and limits | validate_deployment_ready |
| Replicas ≥ 2 | Minimum 2 replicas for HA | validate_deployment_ready |
| Service selectors | No pod-template-hash in selectors | validate_deployment_ready |
Environment Setup
Verify Deployment and Services
kubectl get deployment hello-world -n default
kubectl get svc -n default | grep hello-world
Verify Prometheus (if using analysis)
kubectl get svc -n monitoring prometheus-server
Set the Prometheus URL when starting the MCP server:
export PROMETHEUS_URL="http://prometheus-server.monitoring.svc.cluster.local:80"
Start MCP Server (Docker — recommended)
docker run --rm -it \
-p 8768:8768 \
-v ~/.kube:/app/.kube:ro \
-e K8S_KUBECONFIG=/app/.kube/config \
-e PROMETHEUS_URL="http://prometheus-server.monitoring.svc.cluster.local:80" \
talkopsai/argo-rollout-mcp-server:latest
If Prometheus is in a different namespace or URL, adjust PROMETHEUS_URL. For host networking, use --network host or the appropriate host URL.
Complete Workflow Overview
Zero manual kubectl steps. Every resource — Services, Rollout, AnalysisTemplate — is applied directly to the cluster by the tools.
Step 1: Validate Readiness
Goal: Confirm the Deployment is structurally sound and doesn't have issues that would cause the migration to fail.
Prompt:
"Check if my hello-world deployment in the default namespace is ready to migrate to Argo Rollouts."
What this checks:
| Check | Severity | Impact |
|---|---|---|
Missing spec.selector | Blocking | Must fix before proceeding |
Missing spec.template | Blocking | Must fix before proceeding |
| No containers defined | Blocking | Must fix before proceeding |
replicas < 2 | Warning | Informational |
| Missing resource limits | Warning | Informational |
| No readiness probe | Warning | Informational |
Service selector uses pod-template-hash | Blocking | Remove for Rollout compatibility |
| No Service found | Warning | Tool will create required Services |
Decision Gate: ready: true → proceed. Fix blocking issues before continuing.
Step 2: Convert and Apply Rollout
Goal: Convert the existing Deployment to an Argo Rollout — preserving all resource limits, probes, env vars — and apply it to the cluster along with prerequisite Services.
Canary Strategy
Prompt:
"Convert the hello-world deployment in default to a canary Argo Rollout and apply it to the cluster."
Blue-Green Strategy
Prompt:
"Convert the hello-world deployment in default to a blue-green Argo Rollout and apply it."
What Gets Preserved
spec.template(pod template with all containers, env vars, volumes)spec.selector(pod label selectors)spec.replicasmetadata(name, namespace, labels, annotations)
Review Mode (no apply)
"Convert hello-world to a canary rollout — give me the YAML for review first, don't apply yet."
Step 3: Link Traffic Routing (Optional, Canary Only)
Goal: If using external traffic routing (Traefik, Istio, Gateway API), link the Rollout to your weighted traffic service. The traffic service must be created separately via your ingress controller or CI/CD.
TraefikService:
"Link the hello-world rollout in default to TraefikService hello-world-route-wrr."
Gateway API (HTTPRoute):
Use argo_update_rollout with update_type='traffic_routing' and gateway_api_config={"httpRoute": "api-http-route", "namespace": "default"}.
Blue-green does not use traffic routing — it flips the activeService selector on promotion. Rolling uses standard K8s mechanics.
Step 4: Set Up Analysis (Optional)
Goal: Configure Prometheus-based health checks so Argo Rollouts can auto-abort on failures. Skip this step if you don't have Prometheus.
Default Metrics
Prompt:
"Set up automated Prometheus analysis for the hello-world rollout in default."
Default metrics use http_requests_total and http_request_duration_seconds_bucket with a job label. If your Prometheus scrape config does not expose these (e.g. Traefik-only), use custom metrics below.
Traefik Custom Metrics
Traefik uses different metric names. Use custom metrics when configuring analysis for Traefik-backed apps:
| Metric | Traefik Name | Purpose |
|---|---|---|
| Request count | traefik_service_requests_total | Error rate |
| Latency | traefik_service_request_duration_seconds_bucket | P99, P95 |
Traefik service name format: hello-world-stable-default@kubernetescrd, hello-world-canary-default@kubernetescrd. Use regex: service=~"hello-world.*".
Error rate (successCondition: < 5%):
sum(rate(traefik_service_requests_total{service=~"hello-world.*", code=~"5.."}[5m]))
/ sum(rate(traefik_service_requests_total{service=~"hello-world.*"}[5m]))
P99 latency (successCondition: < 2 seconds):
histogram_quantile(0.99,
sum(rate(traefik_service_request_duration_seconds_bucket{service=~"hello-world.*"}[5m])) by (le)
)
Prompt for custom Traefik metrics:
"Configure analysis for hello-world rollout in default using custom Traefik metrics: error rate from traefik_service_requests_total, latency from traefik_service_request_duration_seconds_bucket, service label matching hello-world."
Or call argo_configure_analysis_template with the metrics parameter — see Tools for the full JSON structure.
Step 5: Verify
Goal: Confirm rollout is healthy before any traffic changes.
Prompt:
"Show me the status of the hello-world rollout in default namespace."
Expected: phase="Healthy", readyReplicas matches desired replicas.
Resource: argorollout://rollouts/default/hello-world/detail
Onboarding Scenarios
Choose the scenario that matches your setup:
Scenario A: Canary (no analysis)
| Step | Action | Prompt |
|---|---|---|
| 1 | Validate | "Check if hello-world deployment in default is ready to migrate to Argo Rollouts." |
| 2 | Convert | "Convert hello-world to a canary Argo Rollout and apply it to the cluster." |
| 3 | Verify | "Show me the status of the hello-world rollout in default namespace." |
Skip: Analysis, traffic routing.
Scenario B: Canary with Analysis (default metrics)
| Step | Action | Prompt |
|---|---|---|
| 1 | Validate | "Check if hello-world deployment in default is ready to migrate to Argo Rollouts." |
| 2 | Convert | "Convert hello-world to a canary Argo Rollout and apply it to the cluster." |
| 3 | Configure analysis | "Set up automated Prometheus analysis for the hello-world rollout in default." |
| 4 | Verify | "Show me the status of the hello-world rollout in default namespace." |
Scenario C: Canary with Analysis (Traefik metrics)
| Step | Action | Prompt |
|---|---|---|
| 1 | Validate | "Check if hello-world deployment in default is ready to migrate to Argo Rollouts." |
| 2 | Convert | "Convert hello-world to a canary Argo Rollout and apply it to the cluster." |
| 3 | Configure analysis (custom) | Use argo_configure_analysis_template with metrics = Traefik JSON (error-rate, latency-p99, latency-p95). |
| 4 | Verify | "Show me the status of the hello-world rollout in default namespace." |
Scenario D: Blue-Green (no analysis)
| Step | Action | Prompt |
|---|---|---|
| 1 | Validate | "Check if hello-world deployment in default is ready to migrate to Argo Rollouts." |
| 2 | Convert | "Convert hello-world to a blue-green Argo Rollout and apply it to the cluster." |
| 3 | Verify | "Show me the status of the hello-world rollout in default namespace." |
Scenario E: Blue-Green with Analysis
| Step | Action | Prompt |
|---|---|---|
| 1 | Validate | "Check if hello-world deployment in default is ready to migrate to Argo Rollouts." |
| 2 | Convert | "Convert hello-world to a blue-green Argo Rollout and apply it to the cluster." |
| 3 | Configure analysis | "Set up automated Prometheus analysis for the hello-world rollout in default." |
| 4 | Verify | "Show me the status of the hello-world rollout in default namespace." |
Scenario F: Rolling Update (Single-Step Canary)
convert_deployment_to_rollout supports canary and blue-green only. For a rolling-update–style experience (no staged traffic):
- Convert to canary with steps
[{"setWeight": 100}](single step = full cutover). - Or convert to canary, then update strategy:
argo_update_rollout(update_type='strategy', canary_steps=[{"setWeight": 100}]).
| Step | Action | Prompt / Tool |
|---|---|---|
| 1 | Validate | "Check if hello-world deployment in default is ready to migrate to Argo Rollouts." |
| 2 | Convert | "Convert hello-world to a canary Argo Rollout and apply it." |
| 3 | Update strategy (optional) | argo_update_rollout(update_type='strategy', canary_steps=[{"setWeight": 100}]) |
| 4 | Verify | "Show me the status of the hello-world rollout in default namespace." |
Post-Onboarding: Deploy New Image
After onboarding with analysis:
| Step | Action | Prompt |
|---|---|---|
| 1 | Deploy new image | "Deploy hello-world:v2 to the hello-world rollout in default." |
| 2 | Promote (if paused) | "Promote the hello-world rollout in default to the next step." |
| 3 | Monitor | "Show me the status of the hello-world rollout in default namespace." |
| 4 | Full promotion | "Fully promote the hello-world rollout in default." |
Argo CD Integration
If Your Deployment is Argo CD–Managed
- Before onboarding: Argo CD syncs the Deployment. MCP tools create the Rollout and Services.
- Update Argo CD Application: Point the Application to the Rollout manifest (or Helm chart that renders the Rollout) instead of the Deployment.
- ignoreDifferences: Generate and add to your Argo CD Application spec to avoid OutOfSync from Rollout status and TraefikService weights.
Prompt:
"Generate ArgoCD ignoreDifferences for hello-world in default, including rollout status, analysis runs, and Traefik service."
workloadRef Mode
For workloadRef (Rollout references existing Deployment):
"Generate ArgoCD ignoreDifferences for hello-world in default, including deployment replicas for workloadRef, rollout status, and analysis runs."
Use include_deployment_replicas=True and deployment_name="hello-world" so Argo CD does not revert the Rollout's scale-down of the Deployment.
Natural Language Prompts Reference
Onboarding
"Check if my hello-world deployment in the default namespace is ready to migrate to Argo Rollouts."
"Convert the hello-world deployment in default to a canary Argo Rollout and apply it to the cluster."
"Convert the hello-world deployment in default to a blue-green Argo Rollout and apply it."
"Set up automated Prometheus analysis for the hello-world rollout in default."
"Link the hello-world rollout in default to TraefikService hello-world-route-wrr."
Verification
"Show me the status of the hello-world rollout in default namespace."
"List all rollouts in the default namespace."
"Show me the cluster health summary."
Quick Reference: Tool → Prompt Mapping
| Tool | Example Prompt |
|---|---|
validate_deployment_ready | "Check if hello-world deployment in default is ready to migrate to Argo Rollouts." |
convert_deployment_to_rollout | "Convert hello-world to a canary Argo Rollout and apply it." |
argo_configure_analysis_template | "Set up Prometheus analysis for hello-world rollout in default." |
argo_update_rollout (image) | "Deploy hello-world:v2 to the hello-world rollout in default." |
argo_manage_rollout_lifecycle (promote) | "Promote the hello-world rollout in default." |
argo_manage_rollout_lifecycle (abort) | "Abort the hello-world rollout in default." |
argo_delete_rollout | "Delete the hello-world rollout from default." |
argorollout://rollouts/default/hello-world/detail | "Show me the status of the hello-world rollout in default." |
Troubleshooting
| Issue | Check |
|---|---|
| Analysis always "Inconclusive" | Verify successCondition (not successCriteria) in AnalysisTemplate. Run kubectl get analysistemplate -n default -o yaml. |
| Prometheus queries return no data | Confirm Traefik metrics are scraped. Run queries in Prometheus UI. Adjust service regex in custom metrics. |
| Rollout stuck in Progressing | Check argorollout://rollouts/default/hello-world/detail. Promote manually or abort. |
| Argo CD OutOfSync | Add generate_argocd_ignore_differences output to Application spec. |
| trafficRouting not in spec after patch | Blue-green does not support trafficRouting — only canary. For Argo CD/Helm: add trafficRouting to Helm chart/Argo CD source, or use include_rollout_traffic_routing=True in ignoreDifferences. |
| "Pod does not have a named port 'http'" | argo_update_rollout(update_type='image') preserves the full container spec (ports, probes) and only updates the image. |
Next Steps
- Deployment Strategies — Rolling, Canary, Blue-Green
- ArgoCD GitOps — ignoreDifferences reference
- Emergency Abort — Rollback workflow
- Tools — Full tool reference
- Examples — Quick reference and prompts