-
Notifications
You must be signed in to change notification settings - Fork 92
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* docs(introspection): add docs for introspection command * add blank core doc * add subgraph introspection docs * add supergraph command docs * WIP on Rover doc improvements * Edits to release PR * Fix broken links * CI/CD tweaks and feedback fixes Co-authored-by: Stephen Barlow <[email protected]> Co-authored-by: Avery Harnish <[email protected]>
- Loading branch information
3 people
authored
Mar 30, 2021
1 parent
e714bb6
commit 8e65d8c
Showing
9 changed files
with
209 additions
and
128 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| --- | ||
| title: 'Configuring Rover' | ||
| sidebar_title: 'Configuring' | ||
| sidebar_title: 'Configure' | ||
| --- | ||
|
|
||
| ## Authenticating with Apollo Studio | ||
|
|
@@ -84,36 +84,44 @@ You can override the location of this configuration file by setting the `APOLLO_ | |
| APOLLO_CONFIG_HOME=./myspecialconfig/ | ||
| ``` | ||
|
|
||
| ## All supported environment variables | ||
| ## Git context | ||
|
|
||
| You can configure Rover's behavior by setting the environment variables listed below. | ||
| Rover sends non-confidential information about your Git environment to Apollo Studio when you run a `check` or `publish` command. This information is displayed in relevant views of the Studio UI, making it easier to track down where schema changes were proposed or published: | ||
|
|
||
| If present, an environment variable's value takes precedence over all other methods of configuring the associated behavior. | ||
| <img src="./assets/checks-git-info.png" alt="Checks info in Apollo Studio" class="screenshot" width="400"> | ||
|
|
||
| | Name | Value | | ||
| |-----------------------------|----------------| | ||
| | `APOLLO_HOME` | The path to the parent directory of Rover's binary. The default value is your operating system's default home directory. Rover will install itself in a folder called `.rover` inside the directory specified. | | ||
| | `APOLLO_CONFIG_HOME` | The path where Rover's configuration is stored. The default value is your operating system's default configuration directory. | | ||
| | `APOLLO_KEY` | The API key that Rover should use to authenticate with Apollo Studio. | | ||
| | `APOLLO_TELEMETRY_DISABLED` | Set to `1` if you don't want Rover to collect anonymous usage data. | | ||
| | `APOLLO_VCS_REMOTE_URL` | The location of your project's repository. More info [here](#git-context) | | ||
| | `APOLLO_VCS_BRANCH` | The name of the version controlled branch. More info [here](#git-context) | | ||
| | `APOLLO_VCS_COMMIT` | The long identifier (sha in git) of the commit. More info [here](#git-context) | | ||
| | `APOLLO_VCS_AUTHOR` | The name and email of a commit's author (ex. "Jane Doe \<[email protected]\>"). More info [here](#git-context) | | ||
| This Git information includes: | ||
|
|
||
| * The remote URL of your Git repository (stripped of any usernames/passwords) | ||
| * The current commit's SHA | ||
| * The committer of the current SHA | ||
| * The current branch name | ||
|
|
||
| To see these values, run any `check` or `publish` command with the `--log trace` option. | ||
|
|
||
| ## Advanced | ||
| ### Overriding | ||
|
|
||
| ### Git Context | ||
| None of this information should be sensitive, but if you want to override these values, you can set the `APOLLO_VCS_REMOTE_URL`, `APOLLO_VCS_BRANCH`, `APOLLO_VCS_COMMIT`, and `APOLLO_VCS_AUTHOR` [environment variables](#supported-environment-variables). | ||
|
|
||
| Apollo uses information about your git environment when running `check` and `publish` commands This context is used to impprove the experience in Apollo Studio. This includes the remote url of your git repository (stripped of any usernames/passwords), commit sha, commiter, and branch name. | ||
| ### Non-Git version control | ||
|
|
||
| This information powers the ability to be able to link to a specific commit from the checks or history tabs in Apollo Studio, making it easier to track down where schema changes were proposed or published. | ||
| If you use a version control system besides Git, you can use the environment variables described in [Git context](#git-context) to set similar information relevant to your VCS tool, | ||
|
|
||
| <img src="./assets/checks-git-info.png" alt="Checks info in Apollo Studio" width="400"> | ||
| Currently, only Git is fully supported by Apollo Studio. | ||
|
|
||
| To see these values, just run any `check` or `publish` command with the `--log trace` option. | ||
| ## Supported environment variables | ||
|
|
||
| None of this information should be sensitive, but if you would rather overwrite these values, you may use the `APOLLO_VCS_REMOTE_URL`, `APOLLO_VCS_BRANCH`, `APOLLO_VCS_COMMIT`, and `APOLLO_VCS_AUTHOR` environment variables documented [here](./configuring#all-supported-environment-variables). | ||
| You can configure Rover's behavior by setting the environment variables listed below. | ||
|
|
||
| If present, an environment variable's value takes precedence over all other methods of configuring the associated behavior. | ||
|
|
||
| **Non-git users** may also use these vaiables to set similar information relevant to your VCS tool, but only git is fully supported by Apollo Studio. | ||
| | Name | Value | | ||
| |-----------------------------|----------------| | ||
| | `APOLLO_HOME` | The path to the parent directory of Rover's binary. The default value is your operating system's default home directory. Rover will install itself in a folder called `.rover` inside the directory specified. | | ||
| | `APOLLO_CONFIG_HOME` | The path where Rover's configuration is stored. The default value is your operating system's default configuration directory. | | ||
| | `APOLLO_KEY` | The API key that Rover should use to authenticate with Apollo Studio. | | ||
| | `APOLLO_TELEMETRY_DISABLED` | Set to `1` if you don't want Rover to collect anonymous usage data. | | ||
| | `APOLLO_VCS_REMOTE_URL` | The URL of your project's remote repository. See [Git context](#git-context). | | ||
| | `APOLLO_VCS_BRANCH` | The name of the version-controlled branch. See [Git context](#git-context). | | ||
| | `APOLLO_VCS_COMMIT` | The long identifier (SHA in Git) of the commit. See [Git context](#git-context). | | ||
| | `APOLLO_VCS_AUTHOR` | The name and email of a commit's author (e.g., `Jane Doe <[email protected]>`). See [Git context](#git-context). | | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,75 +1,77 @@ | ||
| --- | ||
| title: 'Essential concepts' | ||
| sidebar_title: 'Essential concepts' | ||
| description: 'Things you should understand to get the most out of Rover' | ||
| title: 'Rover conventions' | ||
| sidebar_title: 'Conventions' | ||
| --- | ||
|
|
||
| ## Graph vs Subgraph | ||
| These are conventions for all Rover commands. | ||
|
|
||
| Rover uses the terms `graph` to refer to traditional, monolithic graphs, and `subgraph` to refer to each "subgraph" that is a part of a larger [federated graph](https://www.apollographql.com/docs/federation/). Generally, when working with federated graphs, you will be running operations based on a single _subgraph_ (and thus using the `subgraph` command), rather than on the whole composed graph. | ||
| ## Terminology | ||
|
|
||
| ### Graph Refs | ||
| ### Graph / Subgraph / Supergraph | ||
|
|
||
| Rover uses a format known as a graph ref to refer to a graph id/variant combination. This format defines a graph ref as `graph_id@variant_name`. All Rover commands that interact with the Apollo graph registry require a graph ref as their first positional argument. If using the default variant, `current`, you don't need to provide the variant in the graph ref, although it is recommended for clarity. | ||
| Rover provides commands for interacting with federated [`subgraph`s](./subgraphs/) and [`supergraph`s](./supergraphs/), along with commands for interacting with a monolithic (non-federated) [`graph`](./graphs/). | ||
|
|
||
| ## Using stdout | ||
| A **supergraph** is the composition of multiple **subgraphs** in a [federated architecture](https://www.apollographql.com/docs/federation/): | ||
|
|
||
| `stdout` is a stream that processes can write to. For Rover, `stdout` is usually | ||
| the result of a command, whether that be SDL output, checks errors, or | ||
| composition errors. | ||
| ```mermaid | ||
| graph BT; | ||
| gateway(["Supergraph (A + B + C)"]); | ||
| serviceA[Subgraph A]; | ||
| serviceB[Subgraph B]; | ||
| serviceC[Subgraph C]; | ||
| gateway --- serviceA & serviceB & serviceC; | ||
| ``` | ||
|
|
||
| When working on a federated graph, you'll run _most_ Rover commands on a particular subgraph (using a `subgraph` command), rather than on the whole composed supergraph. The `supergraph` commands are useful when working with [supergraph schemas](./supergraphs). | ||
|
|
||
| ### Graph refs | ||
|
|
||
| Rover uses **graph refs** to refer to a particular variant of a particular graph in [Apollo Studio](https://www.apollographql.com/docs/studio/org/graphs/). A graph ref is a string with the following format: | ||
|
|
||
| ``` | ||
| graph_id@variant_name | ||
| ``` | ||
|
|
||
| **For example:** `docs-example-graph@staging` | ||
|
|
||
| All Rover commands that interact with the Apollo graph registry require a graph ref as their first positional argument. If you're using the default variant (`current`), you don't need to include the `@variant_name` portion of the graph ref (although it's recommended for clarity). | ||
|
|
||
| ## I/O | ||
|
|
||
| Rover was designed to allow the output to `stdout` to be as flexible as | ||
| possible. This means that any command that prints to `stdout` should only print | ||
| things in a format that could be usable elsewhere (like other CLI tools). Rover | ||
| is intentional about printing logs to `stderr` instead of `stdout`, to make sure | ||
| logs never show up in places they're not expected. | ||
| ### Using `stdout` | ||
|
|
||
| To redirect stdout to somwhere other than your terminal, you can use either the | ||
| pipe `|` or output redirect `>` operators. | ||
| Rover commands print to `stdout` in a predictable, portable format. This enables output to be used elsewhere (such as in another CLI, or as input to another Rover command). To help maintain this predictability, Rover prints logs to `stderr` instead of `stdout`. | ||
|
|
||
| The pipe operator is used to pass the `stdout` of one command to the `stdin` | ||
| (the standard input stream) of another process. | ||
| To redirect Rover's output to a location other than your terminal, you can use the pipe `|` or output redirect `>` operators. | ||
|
|
||
| <!-- TODO: remove this first comment line after introspection lands --> | ||
| #### Pipe `|` | ||
|
|
||
| Use the pipe operator to pass the `stdout` of one command directly to the `stdin` of another, like so: | ||
|
|
||
| ```bash | ||
| # Note: this `graph introspect` command does not exist yet | ||
| rover graph introspect http://localhost:4000 | pbcopy | ||
| ``` | ||
|
|
||
| The above example shows the output of the `introspect` command being piped to | ||
| `pbcopy`, a common tool in Mac OS which copies values to the clipboard. Rover | ||
| also can use values from `stdin`, which is explained [below](#using-stdin). | ||
| In this example, the output of the `introspect` command is piped to `pbcopy`, a MacOS command that copies a value to the clipboard. Certain Rover commands also accept values from `stdin`, as explained in [Using `stdin`](#using-stdin). | ||
|
|
||
| In addition to the pipe, the output redirect operator is especially useful for | ||
| handling `stdout`. | ||
| #### Output redirect `>` | ||
|
|
||
| ```bash | ||
| Use the output redirect operator to write the `stdout` of a command to a file, like so: | ||
|
|
||
| ``` | ||
| rover graph fetch my-graph@prod > schema.graphql | ||
| ``` | ||
|
|
||
| The output redirect operator, as shown in this example is useful for pushing | ||
| the output from `stdout` to a file (here that's `schema.graphql`). If this file | ||
| already exists, it will be overwritten. If it doesn't, it will be created. | ||
|
|
||
| ## Using stdin | ||
| In this example, the schema returned by `graph fetch` is written to the file `schema.graphql`. If this file already exists, it's overwritten. Otherwise, it's created. | ||
|
|
||
| To be as flexible as possible, Rover allows for certain input values to be | ||
| provided from `stdin`. This means that Rover can accept the output from another | ||
| command as input. | ||
| ### Using `stdin` | ||
|
|
||
| Rover follows fairly common conventions for using `stdin`. Wherever Rover allows | ||
| `stdin` to be used, you can pass `-` to signify that you'd like to use `stdin` | ||
| rather than a file path. | ||
| Rover commands that take a file path as an option can instead accept input from `stdin`. To do so, pass `-` as the argument for the file path: | ||
|
|
||
| Right now, the only place `stdin` is fully supported is the `--schema` flag used | ||
| in many of the `graph` and `subgraph` commands. Using `stdin` for schema inputs | ||
| can be convenient when using Rover (or other command line tools) to generate | ||
| SDL. | ||
| ``` | ||
| rover graph introspect http://localhost:4000 | rover graph check my-graph --schema - | ||
| ``` | ||
|
|
||
| <!-- TODO: remove this first comment line after introspection lands --> | ||
| In this example, the schema returned by `graph introspect` is then passed as the `--schema` option to `graph check`. | ||
|
|
||
| ```bash | ||
| # Note: this `graph introspect` command does not exist yet | ||
| rover graph introspect http://localhost:4000 | rover graph check my-graph --schema - | ||
| ``` | ||
| > Currently, `--schema` is the only Rover option that accepts a file path. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.