Skip to main content

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​

ComponentStatus
Kubernetes clusterAccessible via kubectl
Argo RolloutsInstalled (kubectl get rollouts -A)
Argo Rollout MCP ServerRunning (Docker recommended)
Existing DeploymentExists in a known namespace
PrometheusFor analysis (optional)
Traefik / IngressFor canary traffic routing (optional)

Application Requirements​

Before onboarding, the existing application must have:

RequirementDetailsValidated By
Container ImagePushed to a registryManual
Kubernetes DeploymentStandard Deployment YAMLvalidate_deployment_ready
Health ProbesReadiness and liveness probesvalidate_deployment_ready
Resource RequestsCPU/memory requests and limitsvalidate_deployment_ready
Replicas ≥ 2Minimum 2 replicas for HAvalidate_deployment_ready
Service selectorsNo pod-template-hash in selectorsvalidate_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
tip

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:

CheckSeverityImpact
Missing spec.selectorBlockingMust fix before proceeding
Missing spec.templateBlockingMust fix before proceeding
No containers definedBlockingMust fix before proceeding
replicas < 2WarningInformational
Missing resource limitsWarningInformational
No readiness probeWarningInformational
Service selector uses pod-template-hashBlockingRemove for Rollout compatibility
No Service foundWarningTool 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.replicas
  • metadata (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."

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"}.

note

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:

MetricTraefik NamePurpose
Request counttraefik_service_requests_totalError rate
Latencytraefik_service_request_duration_seconds_bucketP99, 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)​

StepActionPrompt
1Validate"Check if hello-world deployment in default is ready to migrate to Argo Rollouts."
2Convert"Convert hello-world to a canary Argo Rollout and apply it to the cluster."
3Verify"Show me the status of the hello-world rollout in default namespace."

Skip: Analysis, traffic routing.

Scenario B: Canary with Analysis (default metrics)​

StepActionPrompt
1Validate"Check if hello-world deployment in default is ready to migrate to Argo Rollouts."
2Convert"Convert hello-world to a canary Argo Rollout and apply it to the cluster."
3Configure analysis"Set up automated Prometheus analysis for the hello-world rollout in default."
4Verify"Show me the status of the hello-world rollout in default namespace."

Scenario C: Canary with Analysis (Traefik metrics)​

StepActionPrompt
1Validate"Check if hello-world deployment in default is ready to migrate to Argo Rollouts."
2Convert"Convert hello-world to a canary Argo Rollout and apply it to the cluster."
3Configure analysis (custom)Use argo_configure_analysis_template with metrics = Traefik JSON (error-rate, latency-p99, latency-p95).
4Verify"Show me the status of the hello-world rollout in default namespace."

Scenario D: Blue-Green (no analysis)​

StepActionPrompt
1Validate"Check if hello-world deployment in default is ready to migrate to Argo Rollouts."
2Convert"Convert hello-world to a blue-green Argo Rollout and apply it to the cluster."
3Verify"Show me the status of the hello-world rollout in default namespace."

Scenario E: Blue-Green with Analysis​

StepActionPrompt
1Validate"Check if hello-world deployment in default is ready to migrate to Argo Rollouts."
2Convert"Convert hello-world to a blue-green Argo Rollout and apply it to the cluster."
3Configure analysis"Set up automated Prometheus analysis for the hello-world rollout in default."
4Verify"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):

  1. Convert to canary with steps [{"setWeight": 100}] (single step = full cutover).
  2. Or convert to canary, then update strategy: argo_update_rollout(update_type='strategy', canary_steps=[{"setWeight": 100}]).
StepActionPrompt / Tool
1Validate"Check if hello-world deployment in default is ready to migrate to Argo Rollouts."
2Convert"Convert hello-world to a canary Argo Rollout and apply it."
3Update strategy (optional)argo_update_rollout(update_type='strategy', canary_steps=[{"setWeight": 100}])
4Verify"Show me the status of the hello-world rollout in default namespace."

Post-Onboarding: Deploy New Image​

After onboarding with analysis:

StepActionPrompt
1Deploy new image"Deploy hello-world:v2 to the hello-world rollout in default."
2Promote (if paused)"Promote the hello-world rollout in default to the next step."
3Monitor"Show me the status of the hello-world rollout in default namespace."
4Full promotion"Fully promote the hello-world rollout in default."

Argo CD Integration​

If Your Deployment is Argo CD–Managed​

  1. Before onboarding: Argo CD syncs the Deployment. MCP tools create the Rollout and Services.
  2. Update Argo CD Application: Point the Application to the Rollout manifest (or Helm chart that renders the Rollout) instead of the Deployment.
  3. 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​

ToolExample 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​

IssueCheck
Analysis always "Inconclusive"Verify successCondition (not successCriteria) in AnalysisTemplate. Run kubectl get analysistemplate -n default -o yaml.
Prometheus queries return no dataConfirm Traefik metrics are scraped. Run queries in Prometheus UI. Adjust service regex in custom metrics.
Rollout stuck in ProgressingCheck argorollout://rollouts/default/hello-world/detail. Promote manually or abort.
Argo CD OutOfSyncAdd generate_argocd_ignore_differences output to Application spec.
trafficRouting not in spec after patchBlue-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​