Update docs for graph artifacts (#8288)

Author: davidstaheli

apollo-router/src/executable.rs

@@ -221,7 +221,7 @@ pub struct Opt {
     // Should be a Vec<Url> when https://github.com/clap-rs/clap/discussions/3796 is solved
     apollo_uplink_endpoints: Option<String>,
 
-    /// An OCI reference to an image that contains the supergraph schema for the router.
+    /// An OCI reference to a graph artifact that contains the supergraph schema for the router to run.
     #[clap(long, env = "APOLLO_GRAPH_ARTIFACT_REFERENCE", action = ArgAction::Append)]
     graph_artifact_reference: Option<String>,
 

docs/source/routing/configuration/cli.mdx

@@ -184,11 +184,12 @@ For default behavior and possible values, see [Apollo Uplink](/federation/manage
 </td>
 <td>
 
-An OCI reference to an image that contains the supergraph schema for the router.<br/>
+An OCI reference to a graph artifact that contains the supergraph schema for the router to run.<br/><br/>
 
-When this option is set, the router will fetch the schema from the specified OCI image instead of using Apollo Uplink. Note that Apollo Uplink will still be used for entitlements and persisted queries.<br/>
+When you set this option, the router uses the schema from the specified graph artifact instead of Apollo Uplink.
+The router still fetches entitlements and persisted queries from Uplink.<br/><br/>
 
-⚠️ **This option does not support hot reloading schemas.**
+⚠️ **This option is in preview and doesn't support hot-reloading of schemas.**
 
 </td>
 </tr>

docs/source/routing/self-hosted/containerization/docker-router-only.mdx

@@ -24,7 +24,7 @@ The exact image version to use depends on which release you wish to use. In the
 
 ## Basic example running router in Docker
 
-To run the router, your Docker container must have the [`APOLLO_GRAPH_REF`](/router/configuration/overview#apollo_graph_ref) and [`APOLLO_KEY`](/router/configuration/overview#apollo_key) environment variables set to your graph ref and API key, respectively.
+To run the router, set the [`APOLLO_GRAPH_REF`](/graphos/routing/configuration/envvars#apollo_graph_ref) and [`APOLLO_KEY`](/graphos/routing/configuration/envvars#apollo_key) environment variables in your Docker container to your graph ref and API key.
 
 Below is a basic example of running a router image with Docker, either with `docker run` or `docker compose`. It downloads your supergraph schema from Apollo and uses a default configuration that listens for connections on port `4000`.
 
@@ -53,7 +53,7 @@ services:
 
 Whether you use `docker run` or `docker compose`, make sure to replace `<router-image-version>` with whichever version you want to use, and `<your-graph-ref>` and `<your-graph-api-key>` with your graph reference and API key, respectively.
 
-For more complex configurations, such as overriding subgraph URLs or propagating headers, see [Router Configuration](/router/configuration/overview/).
+For more complex configurations, such as overriding subgraph URLs or propagating headers, see [Router Configuration](/graphos/routing/configuration/overview/).
 
 ## Override the configuration
 
@@ -148,19 +148,24 @@ docker run -p 4000:4000 \
 
 In this example, we have to mount the local definition of the supergraph into our image, _and_ specify the location of the file. It doesn't have to be mounted in the `/dist/schema` directory, but it's a reasonable location to use. We must specify the configuration file location as well, since overriding the default params will override our default config file location. In this case, since we don't want to change our router configuration but want to make sure it's used, we just specify the default location of the default configuration.
 
-### Using an OCI image reference
+### Using a graph artifact reference
 
-You can use the `--graph-artifact-reference` option to fetch the supergraph schema from an OCI image:
+⚠️ This option is in preview and doesn't support hot-reloading of schemas.
+
+Set the `APOLLO_GRAPH_ARTIFACT_REFERENCE` environment variable to use the supergraph schema from a graph artifact:
 
 ```bash
 docker run -p 4000:4000 \
   --env APOLLO_KEY="<your-graph-api-key>" \
-  --env APOLLO_GRAPH_ARTIFACT_REFERENCE="<your-oci-reference>" \
+  --env APOLLO_GRAPH_ARTIFACT_REFERENCE="<your-graph-artifact-reference>" \
   --rm \
   ghcr.io/apollographql/router:<router-image-version>
 ```
 
-When using this option, the router will fetch the schema from the specified OCI image instead of using Apollo Uplink.
+When you set this option, the router uses the schema from the specified graph artifact instead of Apollo Uplink.
+The router still fetches entitlements and persisted queries from Uplink.
+
+For more information on graph artifacts, see the [Router CLI Configuration Reference](/graphos/routing/configuration/cli#--graph-artifact-reference).
 
 ## Building your own container
 

docs/source/routing/self-hosted/containerization/docker.mdx

@@ -20,7 +20,7 @@ The exact image version to use depends on which release you wish to use. In the
 
 ## Quick start
 
-To run the router, your Docker container must have the [`APOLLO_GRAPH_REF`](/router/configuration/overview#apollo_graph_ref) and [`APOLLO_KEY`](/router/configuration/overview#apollo_key) environment variables set to your graph ref and API key, respectively.
+To run the router, set the [`APOLLO_GRAPH_REF`](/graphos/routing/configuration/envvars#apollo_graph_ref) and [`APOLLO_KEY`](/graphos/routing/configuration/envvars#apollo_key) environment variables in your Docker container to your graph ref and API key.
 
 Below is a basic example of running an Apollo Runtime image with Docker. It downloads your supergraph schema from Apollo and uses a default configuration that listens for connections on port `4000`.
 
@@ -94,21 +94,25 @@ Both local and container paths must be specified as absolute paths.
 If you don't want to automatically update your supergraph via [Apollo Uplink](/federation/managed-federation/uplink/), or you don't have connectivity to access Apollo Uplink from your environment, you have two options:
 
 1. Using a local supergraph file, as documented in the [Configuring using local files](#configuring-using-local-files) section.
-1. Using an [OCI image reference](#using-an-oci-image-reference)
+1. Using a [graph artifact reference](#using-a-graph-artifact-reference)
 
-### Using an OCI image reference
+### Using a graph artifact reference
 
-You can use the `APOLLO_GRAPH_ARTIFACT_REFERENCE` environment variable to fetch the supergraph schema from an OCI image:
+⚠️ This option is in preview and doesn't support hot-reloading of schemas.
+
+Set the `APOLLO_GRAPH_ARTIFACT_REFERENCE` environment variable to use the supergraph schema from a graph artifact:
 
 ```bash
 docker run -p 4000:4000 \
   --env APOLLO_KEY="<your-graph-api-key>" \
-  --env APOLLO_GRAPH_ARTIFACT_REFERENCE="<your-oci-reference>" \
+  --env APOLLO_GRAPH_ARTIFACT_REFERENCE="<your-graph-artifact-reference>" \
   --rm \
   ghcr.io/apollographql/apollo-runtime:<runtime-image-version>
 ```
 
-When using this option, the router will fetch the schema from the specified OCI image instead of using Apollo Uplink. Additional information on graph artifacts is available in the [router CLI options documentation](/docs/graphos/routing/configuration/cli#command-line-options).
+When you set this option, the router uses the schema from the specified graph artifact instead of Apollo Uplink.
+The router still fetches entitlements and persisted queries from Uplink.
+For more information on graph artifacts, see the [Router CLI Configuration Reference](/graphos/routing/configuration/cli#--graph-artifact-reference).
 
 ## Running a specific Router and MCP version
 
@@ -118,7 +122,7 @@ To learn more, see the [tagging documentation](https://github.com/apollographql/
 
 ## Additional router configuration information
 
-For more complex configurations, such as overriding subgraph URLs or propagating headers, see [Router Configuration](/router/configuration/overview/).
+For more complex configurations, such as overriding subgraph URLs or propagating headers, see [Router Configuration](/graphos/routing/configuration/overview/).
 
 ## Router-only Docker container