Safe Deployments

Safe deployments enable progressive, canary‑based rollouts with controlled traffic shifting, metrics‑driven analysis, and automatic promotion or rollback to reduce risk during router, schema, and configuration changes. You declaratively define rollout steps, weights, timing, and pause points in your Supergraph configuration and the Apollo GraphOS Operator creates and manages the necessary Argo Rollouts resources to execute these transitions and resume safely after failures.

Prerequisites

You need:

• A Kubernetes cluster with permissions to install resources

• kubectl configured to access your cluster

• The Apollo GraphOS Operator v1.1.0 or greater installed in your cluster (see Install Operator)

For Helm installation, you also need Helm installed.

Install Argo Rollouts

Before you can use safe deployments, you need to install Argo Rollouts in your cluster. You can install Argo Rollouts using different methods. The most common methods are kubectl or Helm.

Install with kubectl

Create the Argo Rollouts namespace

kubectl create namespace argo-rollouts --dry-run=client -o yaml | kubectl apply -f -

Install Argo Rollouts

Install Argo Rollouts v1.7.2:

kubectl apply -n argo-rollouts -f https://github.com/argoproj/argo-rollouts/releases/download/v1.7.2/install.yaml

Install with Helm

Add the Argo Helm repository

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update

Install Argo Rollouts

Install Argo Rollouts using Helm:

helm install argo-rollouts argo/argo-rollouts --namespace argo-rollouts --create-namespace --version 1.7.2

Verify installation

After installing using either method, verify the installation by waiting for the Argo Rollouts deployment to be ready:

kubectl rollout -n argo-rollouts status deployment argo-rollouts --timeout=90s

You should now have Argo Rollouts installed and ready to use.

Configure safe deployments

To enable safe deployments for a Supergraph, configure the deploymentStrategy field in your Supergraph spec. The operator supports canary deployments with Argo Rollouts.

If you have an existing Supergraph using a standard Kubernetes Deployment, you can migrate to a Rollout strategy with zero downtime. See the migration guide for details.

Basic configuration

Here's a complete example that configures a canary deployment with steps:

1apiVersion: apollographql.com/v1alpha2
2kind: Supergraph
3metadata:
4  name: my-supergraph
5spec:
6  replicas: 2  # Number of replicas for the Supergraph
7  podTemplate:
8    routerVersion: 2.7.0  # GraphOS Router version
9  deploymentStrategy:
10    rollout:  # Use Argo Rollouts for safe deployments
11      steps:
12        - setWeight: 30  # Shift 30% of traffic to new version
13        - pause:
14            duration: 2m  # Wait 2 minutes before next step
15        - setWeight: 50  # Shift 50% of traffic to new version
16        - pause:
17            duration: 2m  # Wait 2 minutes before next step
18        - setWeight: 80  # Shift 80% of traffic to new version
19        - pause:
20            duration: 2m  # Wait 2 minutes before final step
21        - setWeight: 100  # Shift all traffic to new version
22  routerConfig:
23    homepage:
24      enabled: false
25    sandbox:
26      enabled: true
27    supergraph:
28      introspection: true
29  schema:
30    studio:
31      graphRef: my-graph@my-variant  # GraphOS graph variant reference

Understand Rollout Steps

Steps define the canary deployment progression. Use the following patterns as starting points for common use cases. For additional options and advanced configurations, see the Argo Rollouts canary documentation.

Common step types include:

• setWeight: Sets the percentage of traffic to send to the new version (0-100)

• pause: Pauses the rollout for a specified duration or until manually resumed

• pause: {}: Pauses indefinitely until manually resumed

Recommended canary step patterns

Gradual traffic increase

Gradually increase traffic over time:

1deploymentStrategy:
2  rollout:
3    steps:
4      - setWeight: 10
5      - pause:
6          duration: 5m
7      - setWeight: 25
8      - pause:
9          duration: 5m
10      - setWeight: 50
11      - pause:
12          duration: 5m
13      - setWeight: 100

Manual approval points

Add manual approval steps for critical deployments:

1deploymentStrategy:
2  rollout:
3    steps:
4      - setWeight: 20
5      - pause: {}  # Wait for manual approval
6      - setWeight: 50
7      - pause: {}  # Wait for manual approval
8      - setWeight: 100

To resume a paused rollout, use the Argo Rollouts kubectl plugin:

kubectl argo rollouts promote <rollout-name>

Understand Rollout states

When using safe deployments, the Supergraph status includes detailed rollout information. Understanding the states helps you monitor your deployments.

Rollout phases

The rollout goes through several phases, which map to Supergraph conditions:

Check the Rollout status

The Supergraph status includes rollout details:

1status:
2  rollout:
3    currentStep: 2
4    totalSteps: 5
5    trafficPercentage: 50
6    phase: Progressing

• currentStep: Current step index (0-based) in the rollout

• totalSteps: Total number of steps configured

• trafficPercentage: Current traffic percentage for the canary (0-100)

• phase: Current rollout phase

Monitor Rollouts

When you check the Supergraph status, you see Rollout information in the status.rollout section. Here's an example of what to look for:

1status:
2  rollout:
3    currentStep: 2        # Current step in the rollout (0-based)
4    totalSteps: 5         # Total number of steps configured
5    trafficPercentage: 50 # Percentage of traffic on the canary
6    phase: Progressing    # Current rollout phase

Key fields to monitor:

• rollout.phase: Shows the current phase (e.g., Progressing, PausedForStep, Completed, Failed)

• rollout.currentStep and rollout.totalSteps: Indicates progress through the rollout steps

• rollout.trafficPercentage: Shows how much traffic is currently on the canary version

Check the rollout status:

kubectl get supergraph my-supergraph -o yaml

View rollout details:

kubectl get rollout my-supergraph -o yaml

Explore next steps

Now that you have safe deployments configured, you can:

• Learn about advanced topics including custom analysis, networking integration, and migration

• Monitor your rollouts using the status information

• Configure automated analysis for your deployments