Rolling back schema changes

When rolling back a deployment, you must ensure the supergraph schema and router version are compatible with the deployed subgraphs and subgraph schemas in the target environment so all possible GraphQL operations can be successfully executed.

Best practices for rollback

• Validate schema compatibility. Any rollback must ensure the router's supergraph schema is compatible with the underlying subgraphs deployed in the target environment.

• Manage schema delivery with GraphOS. GraphOS's standard CI/CD schema delivery pipeline is the best choice for most environments seeking continuous deployment and empowerment of subgraph teams to ship both independently and with the safety of GraphOS checks to prevent breaking changes. For details, see the change management article.

• Use embedded supergraph schema for immutable infrastructure environments. In environments with existing blue-green or canary deployments that rely on an immutable infrastructure approach—where no in-place updates, patches, or configuration changes can be made on production workloads—the router image can use an embedded supergraph schema. The supergraph schema is set for the router with the --supergraph flag for a specific GraphOS launchID that's generated by publishing the subgraph schemas for the specific subgraph image versions used in a blue-green or canary deployment. In this way, a blue-green or canary deployment can be made immutable as a whole, so rolling back to a previous deployment ensures the router's supergraph schema is compatible with the underlying subgraphs deployed in the target environment.

• Don't only roll back supergraph schema. In general, Apollo doesn't recommend rolling back only the supergraph schema on the router in isolation. Subgraph compatibility must also be taken into account. Subsequent publishing of subgraphs generates a new supergraph schema that may lose rolled back changes, so in general it's better to fix the problem at the source of truth in the subgraph repository.

Rolling back schema changes

There are several ways to roll back a deployment, depending on the deployment strategy and the nature of the changes that need to be rolled back. Apollo typically recommends one of three approaches:

• Rolling forward to revert

• Rolling back the entire deployment

• Rolling back the supergraph schema only

Roll forward to revert

Rollbacks are typically implemented by rolling forward to a new version that reverts the changes in the subgraph code repository, then performing the full release process (publishing the subgraph schema and rolling out the new code together) as outlined in the schema change management best practices. This ensures the supergraph schema exposed by the router matches the underlying subgraphs.

Rolling forward to revert is often the safest approach when using the standard schema delivery pipeline, where Apollo Uplink provides the supergraph schema to the router for continuous deployment of new launches.

Roll back entire deployment

For blue-green deployment scenarios, where the router and subgraphs in a deployment have versioned Docker container images, you may be able to roll back the entire deployment (assuming no underlying database schema changes). Doing so ensures that the supergraph schema embedded in the router image is compatible with underlying subgraphs in the target environment. This kind of rollback is typically what happens when a blue-green deployment is aborted if post-promotion analysis fails.

For more information on blue-green deployments, see the exampleblue-green deployment workflow.

Roll back supergraph schema only

In rare circumstances where a backward compatible subgraph schema-only change is made (for example, setting progressive @override percentage), it may be possible to only rollback the supergraph schema by fixing the router fleet to the supergraph schema for a specific launchID using the --supergraph flag.

This approach is only suitable for short-term fixes for a limited set of schema-only changes. It requires the router to be fixed to a specific supergraph launchID, as republishing the underlying subgraphs will result in a new supergraph schema being generated.

Given the issues with this approach, it's often best to implement rollbacks by rolling forward to a new version.