OCI Registry

Open Container Initiative (OCI) support

Graph artifacts use the Open Container Initiative (OCI) image format, and the GraphOS registry is an OCI-compliant artifact registry. That means you can use standard OCI tools to pull graph artifacts from the GraphOS registry and inspect their contents.

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 references

To programmatically retrieve a graph artifact reference, query the GraphOS Platform API. Apollo allows certain characters in the graph ID and variant name that the OCI Distribution Spec doesn't, so Apollo removes these characters and appends a hash to preserve uniqueness.

Run the following Platform API query to retrieve the OCI-compatible repository and tag mapping:

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

Alternatively, calculate the tag mapping manually by stripping any non-alphanumeric characters (besides dot, underscore, and dash) and then calculating the SHA256 checksum. For example, the variant name current maps to:

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

Query the Platform API to retrieve the unique digest fingerprint of the latest build:

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

The returned uri is a combination of the hashed graph ID and variant, and you can use that uri to directly launch a router using that supergraph.

Pull graph artifacts

You can use any OCI-compliant tool to pull graph artifacts from the GraphOS registry.

In most cases, Apollo Router can fetch the artifact directly when you configure APOLLO_KEY and APOLLO_GRAPH_ARTIFACT_REFERENCE. Pull the graph artifact manually when you need a local copy for inspection, debugging, or custom workflows.

Authenticate with the GraphOS registry

Graph artifacts are stored in an OCI-compliant registry at artifact.api.apollographql.com. Tools like ORAS and the Docker CLI use your local Docker credential store (for example, ~/.docker/config.json and any configured credential helpers) to authenticate. Before you can pull an artifact, sign in to the registry with a graph API key.

To authenticate with the GraphOS registry using ORAS:

1oras login artifact.api.apollographql.com
2# When prompted, enter any non-empty username.
3# Use your Graph API key as the password.

To authenticate with the GraphOS registry using Docker:

1export APOLLO_KEY="service:YOUR_GRAPH_API_KEY"
2echo "$APOLLO_KEY" | docker login artifact.api.apollographql.com --username token --password-stdin

After signing in, your credentials are saved to the Docker authentication configuration, which ORAS and Docker both use when pulling artifacts.

To pull a graph artifact using ORAS:

1oras pull artifact.api.apollographql.com/<your-graph-id>@sha256:<your-artifact-sha-digest>

To pull a graph artifact using Docker:

1docker pull artifact.api.apollographql.com/<your-graph-id>@sha256:<your-artifact-sha-digest>

Inspect graph artifacts

Use any OCI-compliant tool to inspect graph artifacts from the GraphOS registry. For example, after installing the ORAS CLI, inspect a graph artifact using the following command, substituting your own graph ID and artifact SHA digest:

1oras manifest fetch artifact.api.apollographql.com/<your-graph-id>@sha256:<your-artifact-sha-digest>

You can also use the Docker CLI to inspect graph artifacts from the GraphOS registry:

1docker manifest inspect artifact.api.apollographql.com/<your-graph-id>@sha256:<your-artifact-sha-digest>

Local OCI registry

Configure your own OCI-compatible artifact registry to mirror graph artifacts from Apollo. By setting up a remote repository, you can proxy and cache Apollo artifacts through your own registry infrastructure. That is useful for air-gapped or restricted network environments.

Running a local OCI registry provides multiple benefits:

• Remove dependence on Apollo for deployments: Deploy without requiring connectivity to Apollo's registry.

• Enhance security and compliance: Keep artifacts within your own infrastructure.

• Reduce network latency: Serve artifacts from a registry closer to your routers.

• Maintain complete control: Full ownership over artifact storage and lifecycle.

Prerequisites

• An Apollo account with a valid graph API key

• Administrative access to your artifact registry (for example, JFrog Artifactory)

• The ORAS CLI (optional, used for testing)

• Your current Apollo artifact reference (for example, artifact.api.apollographql.com/your-graph-id:tag)

General configuration

Configure your OCI-compatible registry with the following parameters:

Set up JFrog Artifactory

Configure JFrog Artifactory as your OCI artifact mirror:

1. Go to Administration > Repositories, then select Create a Repository > Remote.

   

2. Select OCI as the package type.

   

3. Enter a repository key (for example, apollo-artifacts) and configure these settings:

   • URL: https://artifact.api.apollographql.com/

   • User Name: apollo

   • Password / Access Token: Your Apollo graph API key

   

4. Configure these advanced settings to ensure proper artifact retrieval:

   • Clear the Block Mismatching MIME Types checkbox

   • Select Bypass HEAD Requests

   • Select Disable URL Normalization

   

Configure the router

After you've configured your remote repository, update the APOLLO_GRAPH_ARTIFACT_REFERENCE environment variable to point to your local registry. Replace the Apollo artifact URL with your registry URL and repository, but keep the graph identifier and tag.

1# Original reference:
2APOLLO_GRAPH_ARTIFACT_REFERENCE="artifact.api.apollographql.com/your-graph-id:your-tag"
3
4# Updated reference pointing to your local registry:
5APOLLO_GRAPH_ARTIFACT_REFERENCE="your-registry.com/remote-repository/your-graph-id:your-tag"

Verify the configuration

To confirm the configuration has been set up correctly, sign in to your registry using the ORAS client and pull an artifact:

1# Log in to your registry
2oras login your-artifactory-instance.jfrog.io
3
4# Pull an artifact from your mirrored repository
5oras pull your-artifactory-instance.jfrog.io/apollo-artifacts/your-graph-id:your-tag

A successful pull confirms that your remote repository is correctly configured and can fetch artifacts from Apollo GraphQL.

Cache settings

When you use a mirrored repository, adjust your cache settings to reduce the delay between a new artifact version becoming available in Apollo and its availability in your local registry. Shorter cache TTL values ensure more timely updates but might increase upstream traffic.

Self-hosted OCI artifacts

A supergraph schema can be composed locally with Rover and pushed to an OCI registry (for example, a private registry or AWS ECR). The Apollo Router can then run using that artifact. The following requirements apply when you use self-hosted OCI artifacts.

Schema layer media type

The Apollo Router expects the schema layer to use the media type application/apollo.schema. When you push with ORAS, specify that media type explicitly using the ORAS file syntax local_file_path:media_type:

1oras push your-registry.com/supergraph-schema:latest \
2  path/to/supergraph-schema.graphql:application/apollo.schema

Use a digest reference

APOLLO_GRAPH_ARTIFACT_REFERENCE must be a digest reference (@sha256:...), not a tag. Tag references such as your-registry.com/supergraph-schema:latest do not work. After pushing, resolve the digest and use the full reference as the environment variable:

1oras discover your-registry.com/supergraph-schema:latest
2# Output: your-registry.com/supergraph-schema@sha256:e5c8efeb176643feba5ff32cbb8e8d15ffc6323dadaa748b902fa68890792607

Set APOLLO_GRAPH_ARTIFACT_REFERENCE to that full registry/repo@sha256:digest string.

Set APOLLO_KEY

When the schema source is an OCI artifact, APOLLO_KEY must be set (any valid graph API key). Apollo Router does not use the OCI reference without it.

Run Apollo Router

Set APOLLO_GRAPH_REF, APOLLO_KEY, and APOLLO_GRAPH_ARTIFACT_REFERENCE (using the digest from oras discover), then start Apollo Router:

1APOLLO_GRAPH_REF="your_graph_id@variant_name" \
2APOLLO_KEY="your_apollo_key" \
3APOLLO_GRAPH_ARTIFACT_REFERENCE="your-registry.com/your-repo@sha256:digest" \
4./router