From 6566ef40ac7e9f5dc52e478c0a0640ef77c0c781 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Mon, 25 Nov 2024 09:41:48 -0700 Subject: [PATCH] docs: add links to solutions repositories (#6329) Co-authored-by: Edward Huang --- docs/source/reference/migration/from-gateway.mdx | 6 ++++++ docs/source/routing/about-router.mdx | 10 +++++----- docs/source/routing/customization/coprocessor.mdx | 11 +++++++++++ docs/source/routing/customization/rhai.mdx | 7 +++++++ .../routing/observability/client-id-enforcement.mdx | 8 ++------ .../routing/observability/federated-trace-data.mdx | 5 +++-- .../operations/subscriptions/multipart-protocol.mdx | 7 +++++++ docs/source/routing/security/authorization.mdx | 12 ++++++++++-- docs/source/routing/security/jwt.mdx | 6 ++++++ .../routing/security/router-authentication.mdx | 12 ++++++++++++ .../routing/self-hosted/containerization/index.mdx | 4 ++++ 11 files changed, 73 insertions(+), 15 deletions(-) diff --git a/docs/source/reference/migration/from-gateway.mdx b/docs/source/reference/migration/from-gateway.mdx index e1fa6222a3..72de828208 100644 --- a/docs/source/reference/migration/from-gateway.mdx +++ b/docs/source/reference/migration/from-gateway.mdx @@ -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. + + diff --git a/docs/source/routing/about-router.mdx b/docs/source/routing/about-router.mdx index 6f9d428256..47c71d0de6 100644 --- a/docs/source/routing/about-router.mdx +++ b/docs/source/routing/about-router.mdx @@ -26,13 +26,13 @@ Whenever your router receives an incoming GraphQL operation, it needs to figure -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. - +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. - - + ### Entry point to federated GraphQL API diff --git a/docs/source/routing/customization/coprocessor.mdx b/docs/source/routing/customization/coprocessor.mdx index fd3aa8438b..9d9f74ad14 100644 --- a/docs/source/routing/customization/coprocessor.mdx +++ b/docs/source/routing/customization/coprocessor.mdx @@ -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. + + \ No newline at end of file diff --git a/docs/source/routing/customization/rhai.mdx b/docs/source/routing/customization/rhai.mdx index 0716e19639..c8511bf983 100644 --- a/docs/source/routing/customization/rhai.mdx +++ b/docs/source/routing/customization/rhai.mdx @@ -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. + + diff --git a/docs/source/routing/observability/client-id-enforcement.mdx b/docs/source/routing/observability/client-id-enforcement.mdx index da882d2ba7..76e2766606 100644 --- a/docs/source/routing/observability/client-id-enforcement.mdx +++ b/docs/source/routing/observability/client-id-enforcement.mdx @@ -61,13 +61,9 @@ fn process_request(request) { } ``` - - -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) - - + ## Enforcing in Apollo Server diff --git a/docs/source/routing/observability/federated-trace-data.mdx b/docs/source/routing/observability/federated-trace-data.mdx index c5d434c938..3aa5f1da67 100644 --- a/docs/source/routing/observability/federated-trace-data.mdx +++ b/docs/source/routing/observability/federated-trace-data.mdx @@ -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. 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. diff --git a/docs/source/routing/operations/subscriptions/multipart-protocol.mdx b/docs/source/routing/operations/subscriptions/multipart-protocol.mdx index 53f51ec5a2..9cae39c397 100644 --- a/docs/source/routing/operations/subscriptions/multipart-protocol.mdx +++ b/docs/source/routing/operations/subscriptions/multipart-protocol.mdx @@ -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. + + diff --git a/docs/source/routing/security/authorization.mdx b/docs/source/routing/security/authorization.mdx index d59e07090f..f0a07eab2a 100644 --- a/docs/source/routing/security/authorization.mdx +++ b/docs/source/routing/security/authorization.mdx @@ -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 + + diff --git a/docs/source/routing/security/jwt.mdx b/docs/source/routing/security/jwt.mdx index 4083721245..ece4d02c77 100644 --- a/docs/source/routing/security/jwt.mdx +++ b/docs/source/routing/security/jwt.mdx @@ -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. + + \ No newline at end of file diff --git a/docs/source/routing/security/router-authentication.mdx b/docs/source/routing/security/router-authentication.mdx index cdcc22ef4e..832acf4dee 100644 --- a/docs/source/routing/security/router-authentication.mdx +++ b/docs/source/routing/security/router-authentication.mdx @@ -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. + + + ## Use a coprocessor If you have a custom authentication strategy, you can use a [coprocessor](/graphos/routing/customization/coprocessor) to implement it. @@ -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. + + + ## Combining authentication strategies You can combine the strategies to handle a number of authentication requirements and practice "defense-in-depth": diff --git a/docs/source/routing/self-hosted/containerization/index.mdx b/docs/source/routing/self-hosted/containerization/index.mdx index 0b9a452de0..2134e6a6b8 100644 --- a/docs/source/routing/self-hosted/containerization/index.mdx +++ b/docs/source/routing/self-hosted/containerization/index.mdx @@ -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. + + \ No newline at end of file