Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: Spaceport docs formatting and editorial #495

Merged
merged 1 commit into from
Feb 17, 2022
Merged

docs: Spaceport docs formatting and editorial #495

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
40 changes: 26 additions & 14 deletions docs/source/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -273,33 +273,45 @@ graph:
key: service:<redacted>
```

You must configure the graph section. If you specify a graph section, then both the reference and the key must be specified. The reference must refer to a valid graph/version combination against which statistics are reported. The Key must be a valid API key which can be used for reporting statistics.
To enable usage reporting, configure the `graph` section. Within the `graph` section, both the `reference` and the `key` must be specified. The `reference` must refer to a valid graph/variant combination against which statistics are reported. The `key` must be a valid, [Contributor API key](https://www.apollographql.com/docs/studio/org/members/#organization-wide-member-roles) which can be used for reporting statistics.
For more details on this process, refer to the [usage reporting documentation](https://www.apollographql.com/docs/studio/metrics/usage-reporting/)
The key fulfills the same function as the APOLLO_KEY environment variable.
The reference fulfills the same function as the APOLLO_GRAPH_REF environment variable.
NB: These environment variables are *not* currently recognised by the router. This is being tracked by [issue](https://github.com/apollographql/router/issues/425)
The `key` value fulfills the same function as the `APOLLO_KEY` environment variable in Apollo Server, Apollo Gateway and the Rover CLI.
Similarly, the `reference` fulfills the same function as the `APOLLO_GRAPH_REF` environment variable.

### Spaceport Configuration
> **Note:** These environment variables are *not* currently recognised by the router. This is being tracked by [issue #425](https://github.com/apollographql/router/issues/425). Please follow and enage on that issue if you're interested in this functionality!

The spaceport can either be run as an internal, router specific component or as an external resource shared by multiple routers.
### Spaceport configuration

Spaceport can either be run as an internal, router-specific component or as an external resource shared by multiple routers.

```yaml:title=configuration.yaml
# Spaceport configuration. These values are the default values if not specified
spaceport:
# Should we spawn a Spaceport or talk to an existing external Spaceport?
# By default, Apollo Router will run an internal collector. It can be
# configured to not do this by setting this to `true`. When `true`, no
# agent will spawn and we will attempt to communicate to `collector` below.
external: false
# What's the address of the Spaceport?

# This can be left unconfigured when `external` is `false`. When `true`,
# this should be the location of a spaceport that is running external from
# the Router.
collector: https://127.0.0.1:50051
# Where should we listen IF we have spawned an internal Spaceport?

# For an internal spaceport instance (when `external` is `false`), what
# interface and port should we listen on.
listener: 0.0.0.0:50051
```

#### Internal Spaceport
#### Internal spaceport

This is the default appropriate for most cirumstances, including many production deployments. This is the default collector mode and requires no additional configuration, so long as the `graph` configuration is set with a `reference` and `key`.

In this mode it is possible to further configure the address at which the internal spaceport is listening via the `listener` property. Configuring a `listener` should only be necessary if there is a clash on the default port that Router chooses (e.g., if running multiple routers or other applications using the same port on the same host), of if it's desirable to change the bind address.

This is the default and is most appropriate for evaluations, demos, development support and generally getting started. This requires no configuration by default and will be automatically started if the graph configuration is present.
In this mode it is possible to further configure the address at which the internal spaceport is listening and the address of the spaceport to use. This should only be necessary if there is a clash on the default port, for instance if running multiple routers on the same system or clashing with another application.
#### External spaceport

#### External Spaceport
Running an external spaceport _is not necessary in most circumstances_. It may be desireable in certain production environments where configuration of sensitive key data or allocation of reporting resources needs to be operated centrally. Under heavier workloads, it can also be beneficial to externalize the trace processing to reduce the amount of work that individiual Router instances take on. The `listener` parameter is ignored for an external spaceport.

In this case, external is true, the router will not start an internal spaceport task but will attempt to connect to an external process at the specified listener address. This mode of operation is intended for production environments where, for example, configuration of sensitive key data or allocation of reporting resources, can be centralised and tightly controlled. The listener parameter is ignored for an external spaceport. The collector parameter specifies the address of the shared spaceport.
To enable the external spaceport, another Router can be run to act as the collector with the exclusive role of processing Studio data. To configure this, the "collector" should have `external` set to `false` and an appropriate `listener` address and port combination. Routers exporting Studio data should have `external` set to `true`, `listener` unspecified, and their `collector` property configured to point to the collector Router.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hadn't really thought about the notion of running a spaceport in a separate router, although of course that is possible.

We do have a separate binary spaceport which has a minimalist CLI and is intended to be run when a standalone collector is required. The thinking here isn't fully baked, because we don't even include spaceport (the binary) in our releases yet...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, that's a really good callout and good to capture here; I considered that briefly when writing this and went with what I suggested mostly for packaging and convenience purposes in the near-term.

I think we can pull this back out again in the future, and this PR + this conversation acts as a good artifact for now!


If you're looking for help with this feature, please [open a Discussion](https://github.com/apollographql/router/discussions).