[GM-835] Update documentation for environment variables (#878)

* Update references of `ENGINE_API_KEY` in .mdx

* Update ENGINE_API_KEY references in .md

* Fix extra whitespace

* Further update production.md to remove config

* Apply suggestions from code review

Co-authored-by: Adam Zionts <adam@meteor.com>

docs/source/devtools/editor-plugins.md

@@ -50,7 +50,7 @@ To authenticate with Graph Manager to pull down the schema, create a file next t
 After the key is found, add the following line to the `.env` file:
 
 ```bash
-ENGINE_API_KEY=<enter copied key here>
+APOLLO_KEY=<enter copied key here>
 ```
 
 After this is done, VS Code can be reloaded and the Apollo integration will connect to Graph Manager to provide autocomplete, validation, and more.

docs/source/tutorial/client.mdx

@@ -31,18 +31,19 @@ Now, our dependencies are installed. Here are the packages we will be using to b
 While Apollo VSCode is not required to successfully complete the tutorial, setting it up unlocks a lot of helpful features such as autocomplete for operations, jump to fragment definitions, and more.
 
 First, make a copy of the `.env.example` file located in `client/` and call it `.env`. Add your Graph Manager API key that you already created in step #4 to the file:
+> Note: You may need to upgrade your plugin version, which relies on the former `ENGINE_API_KEY` environment variable
 
 ```bash:title=.env
-ENGINE_API_KEY=service:<your-service-name>:<hash-from-apollo-engine>
+APOLLO_KEY=service:<your-service-name>:<hash-from-apollo-engine>
 ```
 
 The entry should basically look something like this:
 
 ```bash:title=.env
-ENGINE_API_KEY=service:my-service-439:E4VSTiXeFWaSSBgFWXOiSA
+APOLLO_KEY=service:my-service-439:E4VSTiXeFWaSSBgFWXOiSA
 ```
 
-Our key is now stored under the environment variable `ENGINE_API_KEY`. Apollo VSCode uses this API key to pull down your schema from the registry.
+Our key is now stored under the environment variable `APOLLO_KEY`. Apollo VSCode uses this API key to pull down your schema from the registry.
 
 Next, create an Apollo config file called `apollo.config.js`. This config file is how you configure both the Apollo VSCode extension and CLI. Paste the snippet below into the file:
 

docs/source/tutorial/production.md

@@ -31,24 +31,14 @@ The entry should basically look like this:
 APOLLO_KEY=user:xz.5r134305-88p1-4840-12c1-88rc0xcxe179:E4VSTiXeFWaSSBgFWXOiSA
 ```
 
-Our key is now stored under the environment variable `APOLLO_KEY`. We now have to create a file called `apollo.config.js`. Apollo projects are configured using an `apollo.config.js` file at the root of your project. Many Apollo tools leverage your Apollo config, reducing the net amount of configuration you need to do in your project in the end.
-
-Create `apollo.config.js` with the following configuration:
-
-```js{3}
-module.exports = {
-  service: {
-    name: 'my-graph-name' // the name of your graph in Apollo Graph Manager
-  }
-};
-```
+Our key is now stored under the environment variable `APOLLO_KEY`.
 
 ### Check and publish with the Apollo CLI
 
-It's time to publish our schema to Graph Manager! First, start your server in one terminal window by running `npm start`. In another terminal window, run:
+It's time to publish our schema to Graph Manager! First, start your server in one terminal window by running `npm start`. In another terminal window, run the following command, substituting the name of your graph where indicated:
 
 ```bash
-npx apollo service:push --endpoint=http://localhost:4000
+npx apollo service:push --endpoint=http://localhost:4000 --graph=name-of-graph
 ```
 
 > npx is a tool bundled with npm for easily running packages that are not installed globally.
@@ -58,7 +48,7 @@ This command publishes your schema to the Apollo registry. Once your schema is u
 For subsequent publishes, we may first want to check for any breaking changes in our new schema against the old version. In a terminal window, run:
 
 ```bash
-npx apollo service:check --endpoint=http://localhost:4000
+npx apollo service:check --endpoint=http://localhost:4000 --graph=my-graph
 ```
 
 ### What are the benefits of Graph Manager?

graph-manager-docs/source/getting-started.mdx

@@ -47,13 +47,13 @@ In Graph Manager, each **graph** corresponds to the entirety of a GraphQL schema
 
 3. Add the `.env` file to your project's `.gitignore` file.
 
-4. Obtain a personal API key from Graph Manager and set it as the value of `ENGINE_API_KEY` in your `.env` file:
+4. Obtain a personal API key from Graph Manager and set it as the value of `APOLLO_KEY` (previously `ENGINE_API_KEY`) in your `.env` file:
 
     <ObtainPersonalApiKey />
 
     ```python:title=.env
     # Don't worry, the author invalidated this API key before sharing it 😉
-    ENGINE_API_KEY=user:gh.StephenBarlow:Rc6D_7mLxY74okHRCL2HMg
+    APOLLO_KEY=user:gh.StephenBarlow:Rc6D_7mLxY74okHRCL2HMg
     ```
 
 4. Add an `apollo.config.js` file to your project's root directory if there isn't one yet. Unlike `.env`, you _do_ add this file to version control.

graph-manager-docs/source/github-integration.md

@@ -41,7 +41,7 @@ jobs:
       # commands against it
       - run: sleep 5
 
-      # This will authenticate using the `ENGINE_API_KEY` environment
+      # This will authenticate using the `APOLLO_KEY` environment
       # variable. If the GraphQL server is available elsewhere than
       # http://localhost:4000/graphql, set it with `--endpoint=<URL>`.
       - run: apollo service:check

graph-manager-docs/source/managed-federation/advanced-topics.mdx

@@ -198,7 +198,7 @@ With this atomic strategy, the query planner resolves all outstanding requests t
 
 Like any distributed architecture, you should make sure that your federated graph has proper observability, monitoring, and automation to ensure reliability and performance of both your gateway and the federated services underneath it. Serving your GraphQL API from a distributed architecture has many benefits, like productivity, isolation, and being able to match the right services with the right runtimes. Operating a distributed system also has more complexity and points of failure than operating a monolith, and with that complexity comes a need to heighten observability into the state of your system and control over its coordination.
 
-Apollo Server has support for reporting federated [tracing](/performance/) information from the gateway. In order to support the gateway with detailed timing and error information, federated services expose their own tracing information per-fetch in their extensions, which are consumed by the gateway and merged together in order to be emitted to the Apollo metrics ingress. To enable this functionality, make sure the `ENGINE_API_KEY` is set in the environment for your gateway server and ensure that all federated services and the gateway are running `apollo-server` version `2.7.0` or greater. Also, ensure that federated services do not have the `ENGINE_API_KEY` environment variable set.
+Apollo Server has support for reporting federated [tracing](/performance/) information from the gateway. In order to support the gateway with detailed timing and error information, federated services expose their own tracing information per-fetch in their extensions, which are consumed by the gateway and merged together in order to be emitted to the Apollo metrics ingress. To enable this functionality, make sure the `APOLLO_KEY` is set in the environment for your gateway server and ensure that all federated services and the gateway are running `apollo-server` version `2.7.0` or greater. Also, ensure that federated services do not have the `APOLLO_KEY` environment variable (`ENGINE_API_KEY` in `apollo-server` versions pre 2.13.0) set.
 
 Traces will be reported in the shape of the query plan, with each unique fetch to a federated service reporting timing and error data.
 

graph-manager-docs/source/managed-federation/setup.mdx

@@ -98,7 +98,7 @@ const gateway = new ApolloGateway();
 
 Like your implementing services, your gateway uses an API key to identify itself to Graph Manager. Obtain a **graph API key** from your graph's Settings page in the [Graph Manager UI](https://engine.apollographql.com/).
 
-Provide your API key to your gateway by setting it as the value of the `ENGINE_API_KEY` environment variable in your gateway's environment. Apollo Server will automatically read this environment variable on startup.
+Provide your API key to your gateway by setting it as the value of the `APOLLO_KEY` environment variable (`ENGINE_API_KEY` in `apollo-server` pre-2.13.0) in your gateway's environment. Apollo Server will automatically read this environment variable on startup.
 
 Note that if you specify the API key in a `.env` file, the gateway does _not_ automatically read this file. Use a library such as [`dotenv`](https://www.npmjs.com/package/dotenv).
 

graph-manager-docs/source/operation-registry.mdx

@@ -64,11 +64,11 @@ npm install apollo --save-dev
 
 First, make sure Apollo Server is running and that introspection is enabled (it is often disabled in production).
 
-Next, using the following command as a reference, replace the `<ENGINE_API_KEY>` with the Apollo Graph Manager API key from the appropriate service and specify the correct server endpoint with the `--endpoint` flag:
+Next, using the following command as a reference, replace the `<APOLLO_KEY>` with the Apollo Graph Manager API key from the appropriate service and specify the correct server endpoint with the `--endpoint` flag:
 
 ```
 npx apollo service:push               \
-    --key <ENGINE_API_KEY>            \
+    --key <APOLLO_KEY>            \
     --endpoint https://server/graphql
 ```
 
@@ -101,7 +101,7 @@ To register operations, use the following command as a reference, taking care to
 
 ```
 npx apollo client:push \
-    --key <ENGINE_API_KEY> \
+    --key <APOLLO_KEY> \
     --clientName <CLIENT_IDENTIFIER> \
     --clientVersion <CLIENT_VERSION> \
     --includes="src/**/*.{ts,js,graphql}"
@@ -232,18 +232,18 @@ const server = new ApolloServer({
 
 If the server was already configured to use Apollo Graph Manager, no additional changes are necessary, but it's important to make sure that the server is configured to use the same service as the operations were registered with in step 3.
 
-If the server was not previously configured with Apollo Graph Manager, be sure to start the server with the `ENGINE_API_KEY` variable set to the appropriate API key. For example:
+If the server was not previously configured with Apollo Graph Manager, be sure to start the server with the `APOLLO_KEY` variable set to the appropriate API key. For example:
 
 ```
-ENGINE_API_KEY=<ENGINE_API_KEY> npm start
+APOLLO_KEY=<APOLLO_KEY> npm start
 ```
 
 Alternatively, the API key can be specified with the `engine` parameter on the Apollo Server constructor options:
 
 ```js
 const server = new ApolloServer({
   // ...
-  engine: '<ENGINE_API_KEY>', // highlight-line
+  engine: '<APOLLO_KEY>', // highlight-line
   // ...
 });
 ```
@@ -290,7 +290,7 @@ const server = new ApolloServer({
   typeDefs,
   resolvers,
   subscriptions: false,
-  engine: '<ENGINE_API_KEY>',
+  engine: '<APOLLO_KEY>',
   plugins: [
     require('apollo-server-plugin-operation-registry')({
       // De-structure the object to get the HTTP `headers` and the GraphQL

graph-manager-docs/source/schema-registry.mdx

@@ -105,15 +105,15 @@ If you omit the `--variant` flag, the `apollo service:push` command always pushe
 
 ### Associating metrics with a variant
 
-You can configure Apollo Server to associate the metrics it sends to Graph Manager with a particular variant. To do so, set the `ENGINE_SCHEMA_TAG` environment variable to the appropriate variant before initializing Apollo Server.
+You can configure Apollo Server to associate the metrics it sends to Graph Manager with a particular variant. To do so, set the `APOLLO_GRAPH_VARIANT` environment variable (`ENGINE_SCHEMA_TAG` in `apollo-server` pre-2.13.0) to the appropriate variant before initializing Apollo Server.
 
 Alternatively, you can include the `graphVariant` (`schemaTag` in `apollo-server` pre-2.13.0) option in your call to the `ApolloServer` constructor, like so:
 
 ```js
 const server = new ApolloServer({
   ...
   engine: {
-    apiKey: "<ENGINE_API_KEY>",
+    apiKey: "<APOLLO_KEY>",
     graphVariant: "beta" // highlight-line
   }
 });

graph-manager-docs/source/schema-validation.mdx

@@ -112,7 +112,7 @@ jobs:
       # commands against it.
       - run: sleep 5
 
-      # This command authenticates using the `ENGINE_API_KEY` environment
+      # This command authenticates using the `APOLLO_KEY` environment
       # variable. Specify your GraphQL endpoint's URL in your Apollo config.
       - run: npx apollo service:check --variant=staging
 ```

graph-manager-docs/source/setup-analytics.mdx

@@ -23,7 +23,7 @@ Apollo Server has built-in support for pushing traces to Graph Manager. To set i
 
 <ObtainGraphApiKey />
 
-After you obtain a graph API key, assign it to the `ENGINE_API_KEY` environment variable in your production server's environment.
+After you obtain a graph API key, assign it to the `APOLLO_KEY` environment variable (`ENGINE_API_KEY` in `apollo-server` pre-2.13.0) in your production server's environment.
 
 >Consult your production environment's documentation to learn how to set its environment variables.