Skip to content

Commit

Permalink
docs: add links to solutions repositories (#6329)
Browse files Browse the repository at this point in the history
Co-authored-by: Edward Huang <edward.huang@apollographql.com>
  • Loading branch information
Meschreiber and shorgi authored Nov 25, 2024
1 parent dc77a66 commit 6566ef4
Show file tree
Hide file tree
Showing 11 changed files with 73 additions and 15 deletions.
6 changes: 6 additions & 0 deletions docs/source/reference/migration/from-gateway.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -142,3 +142,9 @@ Refer the full list of [router error codes](/router/errors) for any changes to y
## Reporting migration issues

If you encounter a migration issue that isn't resolved by this article, please search for existing [GitHub discussions](https://github.com/apollographql/router/discussions/) and start a new discussion if you don't find what you're looking for.

## Additional resources

You can use the Apollo Solutions [router proxy migration strategy repository](https://github.com/apollosolutions/router-node-proxy) to run both `@apollo/gateway` and Apollo Router and conditionally proxy traffic to the router for a gradual release.

<SolutionsNote />
10 changes: 5 additions & 5 deletions docs/source/routing/about-router.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,13 +26,13 @@ Whenever your router receives an incoming GraphQL operation, it needs to figure
<img src='../images/get-started/qp.svg' class="dark:hidden"/>
<img src='../images/get-started/qp-dark.svg' class="hidden dark:block"/>

A query plan is a blueprint for dividing a single incoming operation into one or more operations that are each resolvable by a single subgraph. Some of these operations depend on the results of other operations, so the query plan also defines any required ordering for their execution. The router's query planner determines the optimal set of subgraph queries for each client operation, then it merges the subgraph responses into a single response for the client.
A query plan is a blueprint for dividing a single incoming operation into one or more operations that are each resolvable by a single subgraph. Some of these operations depend on the results of other operations, so the query plan also defines any required ordering for their execution. The router's query planner determines the optimal set of subgraph queries for each client operation, then it merges the subgraph responses into a single response for the client.

<Tip>
You can use the following tools for inspecting query plans:
- Use the [Explorer IDE](/graphos/platform/explorer/) to view dynamically calculated example query plans for your operations in its right-hand panel.
- Use the [Apollo Solutions command line utility](https://github.com/apollosolutions/generate-query-plan) for generating a query plan locally.

Use the [Explorer IDE](/graphos/platform/explorer/) to view dynamically calculated example query plans for your operations in its right-hand panel.

</Tip>
<SolutionsNote />

### Entry point to federated GraphQL API

Expand Down
11 changes: 11 additions & 0 deletions docs/source/routing/customization/coprocessor.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -1257,3 +1257,14 @@ When your coprocessor receives this request from the router, it should add claim
}
}
```

## Additional resources

- See the Apollo Solutions ["Hello World" coprocessor](https://github.com/apollosolutions/example-coprocessor-helloworld) for an example of a coprocessor that simply logs the router's payload.
- See the following Apollo Solutions authorization and authentication examples:
- [External authentication coprocessor example](https://github.com/apollosolutions/example-coprocessor-external-auth)
- [Custom auth coprocessor example](https://github.com/apollosolutions/example-coprocessor-custom-auth-directive)
- [`@policy` coprocessor example](https://github.com/apollosolutions/example-coprocessor-auth-policy)
- Use the Apollo Solutions [router extensibility load testing repository](https://github.com/apollosolutions/router-extensibility-load-testing) to load test coprocessors.

<SolutionsNote />
7 changes: 7 additions & 0 deletions docs/source/routing/customization/rhai.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -546,3 +546,10 @@ Syntax highlighting can make it easier to spot errors in a script. We recommend
### Logging

For tracking down runtime errors, insert [logging](/graphos/reference/router/rhai#logging) statements to narrow down the issue.

## Additional resources

You can use the Apollo Solutions [router extensibility load testing repository](https://github.com/apollosolutions/router-extensibility-load-testing) to load test Rhai scripts as well as router configurations.
The Apollo Solutions [Rhai test repository](https://github.com/apollosolutions/rhai-test) is an experimental CLI tool for running unit tests against your router Rhai scripts.

<SolutionsNote />
8 changes: 2 additions & 6 deletions docs/source/routing/observability/client-id-enforcement.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -61,13 +61,9 @@ fn process_request(request) {
}
```

<Tip>

If you're an enterprise customer looking for more material on this topic, try the [Enterprise best practices: Router extensibility](https://www.apollographql.com/tutorials/router-extensibility) course on Odyssey.
See a runnable example Rhai script in the [Apollo Solutions repository](https://github.com/apollosolutions/example-rhai-client-id-validation).

Not an enterprise customer? [Learn about GraphOS for Enterprise.](https://www.apollographql.com/pricing)

</Tip>
<SolutionsNote />

## Enforcing in Apollo Server

Expand Down
5 changes: 3 additions & 2 deletions docs/source/routing/observability/federated-trace-data.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,15 +26,16 @@ In summary, subgraphs report timing and error information to the router, and the

### In your subgraphs

For a subgraph to include trace data in its responses to your router, it must use a subgraph-compatible library that supports the trace format.
For a subgraph to include trace data in its responses to your router, it must use a [subgraph-compatible library](/graphos/reference/federation/compatible-subgraphs) that supports the trace format.

To check whether your subgraph library supports federated tracing, see the `FEDERATED TRACING` entry for the library on [this page](/federation/building-supergraphs/supported-subgraphs/).
To check whether your subgraph library supports federated tracing, see the `FEDERATED TRACING` entry for the library on [this page](/graphos/reference/federation/compatible-subgraphs).

If your library does support federated tracing, see its documentation to learn how to enable the feature.

<Note>

If your subgraph uses Apollo Server with `@apollo/subgraph`, federated tracing is enabled by default. You can customize this behavior with Apollo Server's [inline trace plugin](/apollo-server/api/plugin/inline-trace).
If your subgraph uses the Ariadne Python library, this [demo repository](https://github.com/apollosolutions/ariadne-federated-traces) shows how to add support for federated tracing.

</Note>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -83,3 +83,10 @@ With the exception of [heartbeats](#heartbeats), every response part body includ
```

Both types of `errors` follow the [GraphQL error format](http://spec.graphql.org/draft/#sec-Errors.Error-Result-Format), but top-level `errors` never include `locations` or `path`.

## Additional resources

Check out the [federated subscriptions course](https://www.apollographql.com/tutorials/federated-subscriptions-typescript) to explore an end-to-end implementation with Apollo Router, Apollo Server, and Typescript.
You can also see the Apollo Solutions [federated subscriptions repository](https://github.com/apollosolutions/router-extensibility-load-testing) for an example of federated subscriptions via an HTTP Multipart based subscription with the router in HTTP callback mode.

<SolutionsNote />
12 changes: 10 additions & 2 deletions docs/source/routing/security/authorization.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -964,6 +964,14 @@ authorization:
dry_run: true # default: false
```

## Related topics
## Additional resources

* [Authenticating requests with the GraphOS Router](/technotes/TN0004-router-authentication/)
Refer to the guide on [authenticating requests with the GraphOS Router](/graphos/routing/security/router-authentication) for an overview of authorization and authentication techniques.

- See the Apollo Solutions [auth coprocessor example](https://github.com/apollosolutions/example-coprocessor-custom-auth-directive) for how to set up a JavaScript coprocessor that applies custom auth checks.
- See the Apollo Solutions [`@policy` coprocessor example](https://github.com/apollosolutions/example-coprocessor-auth-policy) for how to set up a JavaScript coprocessor that evaluates policy-based authorization
- See the following Apollo Solutions repositories for examples of how to use JWT authentication with the `@requiresScopes` directive:
- [Standard JWT authentication and authorization](https://github.com/apollosolutions/example-jwtauthentication)
- [Non-standard authorization](https://github.com/apollosolutions/example-rhai-normalizejwtscopes) with Rhai scripts

<SolutionsNote />
6 changes: 6 additions & 0 deletions docs/source/routing/security/jwt.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -761,3 +761,9 @@ apollo_authentication_failure_count{kind="JWT",service_name="apollo-router"} 1
# TYPE apollo_authentication_success_count counter
apollo_authentication_success_count{kind="JWT",service_name="apollo-router"} 11
```

## Additional resources

You can use the Apollo Solutions [router JWKS generator](https://github.com/apollosolutions/router-jwks-generator) to create a router configuration file for use with the authentication plugin.

<SolutionsNote />
12 changes: 12 additions & 0 deletions docs/source/routing/security/router-authentication.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,12 @@ Cons:
- It supports only JWT-based authentication with keys from a JWKS endpoint.
### Additional resources
You can use the Apollo Solutions [router JWKS generator](https://github.com/apollosolutions/router-jwks-generator) to create a router configuration file for use with the authentication plugin.
<SolutionsNote />
## Use a coprocessor
If you have a custom authentication strategy, you can use a [coprocessor](/graphos/routing/customization/coprocessor) to implement it.
Expand Down Expand Up @@ -204,6 +210,12 @@ Cons:

- The initial lift of implementing a coprocessor is non-trivial, but once it's in place you can leverage it for any number of router customizations.

### Additional resources

See the Apollo Solutions [coprocessor example](https://github.com/apollosolutions/example-coprocessor-external-auth) for a runnable example including configuration YAML.

<SolutionsNote />

## Combining authentication strategies

You can combine the strategies to handle a number of authentication requirements and practice "defense-in-depth":
Expand Down
4 changes: 4 additions & 0 deletions docs/source/routing/self-hosted/containerization/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,7 @@ The default behavior of a router image is suitable for a basic deployment or dev
For examples of customizing and deploying router images in specific environments, see the guides for:
* [Deploying in Kubernetes](/router/containerization/kubernetes/).
* [Running in Docker](/router/containerization/docker/)

See the Apollo Solutions [example Cloud Foundry deployment](https://github.com/apollosolutions/example-pcf-deployment) for a minimal router configuration and Cloud Foundry manifest file.

<SolutionsNote />

0 comments on commit 6566ef4

Please sign in to comment.