From 4564323ec6e99917c6ecea959c23837180abbf7a Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Fri, 22 Nov 2024 12:29:07 -0700 Subject: [PATCH 1/6] Add Ariadne federated trace library --- docs/source/routing/observability/federated-trace-data.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) 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. From 6f07d22b8968729baa34cb1acb26ba60d46add3e Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Fri, 22 Nov 2024 12:36:29 -0700 Subject: [PATCH 2/6] Add proxy migration strategy repo link --- docs/source/reference/migration/from-gateway.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/source/reference/migration/from-gateway.mdx b/docs/source/reference/migration/from-gateway.mdx index e1fa6222a3..13cda183e5 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-extensibility-load-testing) to run both `@apollo/gateway` and Apollo Router and conditionally proxy traffic to the router for a gradual release. + + From 55f5f6e92553bd46c95b965af08b6ef20fb65c38 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Fri, 22 Nov 2024 12:42:22 -0700 Subject: [PATCH 3/6] Add JWSK generator repo link --- docs/source/routing/security/jwt.mdx | 6 ++++++ docs/source/routing/security/router-authentication.mdx | 4 ++++ 2 files changed, 10 insertions(+) diff --git a/docs/source/routing/security/jwt.mdx b/docs/source/routing/security/jwt.mdx index 4083721245..abb2a43256 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 to 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..cdbfe8871a 100644 --- a/docs/source/routing/security/router-authentication.mdx +++ b/docs/source/routing/security/router-authentication.mdx @@ -142,6 +142,10 @@ Cons: - It supports only JWT-based authentication with keys from a JWKS endpoint. +You can use the Apollo Solutions [router JWKS generator](https://github.com/apollosolutions/router-jwks-generator) to create a router configuration file to 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. From 9ae40210e23ef3961ed445e99507cfeb570d7f79 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Fri, 22 Nov 2024 13:27:02 -0700 Subject: [PATCH 4/6] Add example repos --- docs/source/routing/customization/coprocessor.mdx | 6 ++++++ docs/source/routing/customization/rhai.mdx | 6 ++++++ .../routing/observability/client-id-enforcement.mdx | 8 ++------ docs/source/routing/security/jwt.mdx | 2 +- docs/source/routing/security/router-authentication.mdx | 10 +++++++++- 5 files changed, 24 insertions(+), 8 deletions(-) diff --git a/docs/source/routing/customization/coprocessor.mdx b/docs/source/routing/customization/coprocessor.mdx index fd3aa8438b..3e26e01e95 100644 --- a/docs/source/routing/customization/coprocessor.mdx +++ b/docs/source/routing/customization/coprocessor.mdx @@ -1257,3 +1257,9 @@ When your coprocessor receives this request from the router, it should add claim } } ``` + +## Additional resources + +You can use the Apollo Solutions [router extensibility load testing repository](https://github.com/apollosolutions/router-extensibility-load-testing) to load test coprocessors as well as router configurations. + + \ No newline at end of file diff --git a/docs/source/routing/customization/rhai.mdx b/docs/source/routing/customization/rhai.mdx index 0716e19639..f087c38dd5 100644 --- a/docs/source/routing/customization/rhai.mdx +++ b/docs/source/routing/customization/rhai.mdx @@ -546,3 +546,9 @@ 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. + + 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/security/jwt.mdx b/docs/source/routing/security/jwt.mdx index abb2a43256..ece4d02c77 100644 --- a/docs/source/routing/security/jwt.mdx +++ b/docs/source/routing/security/jwt.mdx @@ -764,6 +764,6 @@ 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 to use with the authentication plugin. +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 cdbfe8871a..832acf4dee 100644 --- a/docs/source/routing/security/router-authentication.mdx +++ b/docs/source/routing/security/router-authentication.mdx @@ -142,7 +142,9 @@ Cons: - It supports only JWT-based authentication with keys from a JWKS endpoint. -You can use the Apollo Solutions [router JWKS generator](https://github.com/apollosolutions/router-jwks-generator) to create a router configuration file to use with the authentication plugin. +### 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. @@ -208,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": From 1b7e485dd6be7e60c2eae4458ee1c9bfc2ba57ac Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Fri, 22 Nov 2024 14:42:25 -0700 Subject: [PATCH 5/6] Add more examples --- docs/source/routing/about-router.mdx | 10 +++++----- docs/source/routing/customization/coprocessor.mdx | 7 ++++++- docs/source/routing/customization/rhai.mdx | 1 + .../operations/subscriptions/multipart-protocol.mdx | 7 +++++++ docs/source/routing/security/authorization.mdx | 12 ++++++++++-- .../routing/self-hosted/containerization/index.mdx | 4 ++++ 6 files changed, 33 insertions(+), 8 deletions(-) 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 3e26e01e95..9d9f74ad14 100644 --- a/docs/source/routing/customization/coprocessor.mdx +++ b/docs/source/routing/customization/coprocessor.mdx @@ -1260,6 +1260,11 @@ When your coprocessor receives this request from the router, it should add claim ## Additional resources -You can use the Apollo Solutions [router extensibility load testing repository](https://github.com/apollosolutions/router-extensibility-load-testing) to load test coprocessors as well as router configurations. +- 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 f087c38dd5..c8511bf983 100644 --- a/docs/source/routing/customization/rhai.mdx +++ b/docs/source/routing/customization/rhai.mdx @@ -550,5 +550,6 @@ For tracking down runtime errors, insert [logging](/graphos/reference/router/rha ## 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/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/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 From ad82eb370f2595cdcdd75fed513fa08cede6be39 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Mon, 25 Nov 2024 09:12:10 -0700 Subject: [PATCH 6/6] Update docs/source/reference/migration/from-gateway.mdx Co-authored-by: Edward Huang --- docs/source/reference/migration/from-gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/reference/migration/from-gateway.mdx b/docs/source/reference/migration/from-gateway.mdx index 13cda183e5..72de828208 100644 --- a/docs/source/reference/migration/from-gateway.mdx +++ b/docs/source/reference/migration/from-gateway.mdx @@ -145,6 +145,6 @@ If you encounter a migration issue that isn't resolved by this article, please s ## Additional resources -You can use the Apollo Solutions [router proxy migration strategy repository](https://github.com/apollosolutions/router-extensibility-load-testing) to run both `@apollo/gateway` and Apollo Router and conditionally proxy traffic to the router for a gradual release. +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.