Schema from Graph Artifacts

Use OCI artifact references

When you push your schema to GraphOS, Apollo stores an immutable artifact containing your composed supergraph in an OCI-compliant registry. You can reference these artifacts using SHA256 digest references for deterministic deployments.

Overview

OCI (Open Container Initiative) artifact references provide immutable, versioned schema references that are ideal for production deployments. Each artifact is identified by a SHA256 digest, ensuring that the same reference always points to the exact same schema version.

By default, OCI artifacts are stored in Apollo's registry, which requires network connectivity. However, you can also run your own local OCI registry for complete independence from external services.

Find OCI artifact reference

To get the latest graph artifact for a supergraph, first map the graph identifiers to their OCI counterparts. Apollo allows characters in the graph id and variant name that are not allowed by the OCI Distribution Spec, so Apollo removes illegal characters and appends a hash to preserve uniqueness.

Apollo provides a Platform API query to retrieve the mapping:

GraphQL
1query GraphArtifactTagLocation($graphId: ID!, $variantName: String!) {
2  graphArtifactTagLocation(graphID: $graphId, variantName: $variantName) {
3    repository
4    tag
5  }
6}

Or calculate it by stripping any non-alphanumeric characters besides dot, underscore and dash and then calculate the sha256 checksum. For example, the variant name "current" maps to:

Bash
1$ echo -n current | sha256sum | cut -c 1-16
2current-97b0560280ed60a5

To retrieve the unique digest fingerprint of the latest build, query the Platform API:

GraphQL
1query GetGraphArtifact($graphId: ID!, $tag: String!) {
2  graphArtifactByTag(graphID: $graphId, tag: $tag) {
3    location {
4      digest
5      uri
6    }
7  }
8}

Note the URI; it is a combination of the hashed graph id and variant and can be used to directly launch a router using that supergraph.

Configuration

Command line

Bash
1router --graph-artifact-reference artifact.api.apollographql.com/my-graph-a50b9d546b298e5a@sha256:14409db3d8a8d74ff9e9a0b5712c0aa8d574bcacc3656e1bc0c55ecf97cd9264

Environment variables

Set the APOLLO_GRAPH_ARTIFACT_REFERENCE environment variable.

Bash
1APOLLO_GRAPH_ARTIFACT_REFERENCE="artifact.api.apollographql.com/my-graph-a50b9d546b298e5a@sha256:14409db3d8a8d74ff9e9a0b5712c0aa8d574bcacc3656e1bc0c55ecf97cd9264"
2router

Local OCI registry

For complete independence from external services, run your own local OCI registry to:

  • Remove dependence on Apollo for deployments

  • Enhance security and compliance

  • Reduce network latency

  • Maintain complete control over artifact storage

Best practices

Follow these guidelines to ensure reliability:

  • Use digest references for production: SHA256 digests ensure deterministic deployments.

  • Automate reference retrieval: Integrate API queries into your CI/CD pipeline.

  • Track deployment versions: Track metrics on the schema changes in each environment.

  • Use blue/green deployments: Use immutable deployments of references for zero-downtime updates and fast rollbacks.

  • Consider a local registry: Balance your uptime considerations with the complexity of managing graph artifacts yourself.

Related documentation

For more information, see the following resources:
Feedback

Edit on GitHub

Ask Community