From 20aaf5a187855c062807d5335180ddfd1f74bc26 Mon Sep 17 00:00:00 2001 From: Lucas Leadbetter <5595530+lleadbet@users.noreply.github.com> Date: Wed, 14 May 2025 15:15:49 -0400 Subject: [PATCH 1/7] draft: changes to the kubernetes docs --- docs/shared/helm-show-router-output.mdx | 64 ++-- .../containerization/kubernetes.mdx | 301 ------------------ docs/source/routing/self-hosted/index.mdx | 38 +-- .../self-hosted/kubernetes/extensibility.mdx | 138 ++++++++ .../self-hosted/kubernetes/metrics.mdx | 46 +++ .../kubernetes/other-considerations.mdx | 54 ++++ .../self-hosted/kubernetes/quickstart.mdx | 131 ++++++++ 7 files changed, 432 insertions(+), 340 deletions(-) delete mode 100644 docs/source/routing/self-hosted/containerization/kubernetes.mdx create mode 100644 docs/source/routing/self-hosted/kubernetes/extensibility.mdx create mode 100644 docs/source/routing/self-hosted/kubernetes/metrics.mdx create mode 100644 docs/source/routing/self-hosted/kubernetes/other-considerations.mdx create mode 100644 docs/source/routing/self-hosted/kubernetes/quickstart.mdx diff --git a/docs/shared/helm-show-router-output.mdx b/docs/shared/helm-show-router-output.mdx index d0f7035d69..54b8217faf 100644 --- a/docs/shared/helm-show-router-output.mdx +++ b/docs/shared/helm-show-router-output.mdx @@ -1,35 +1,30 @@ ```yaml -Pulled: ghcr.io/apollographql/helm-charts/router:1.31.0 -Digest: sha256:26fbe98268456935cac5b51d44257bf96c02ee919fde8d47a06602ce2cda66a3 # Default values for router. # This is a YAML-formatted file. # Declare variables to be passed into your templates. replicaCount: 1 -# -- See https://www.apollographql.com/docs/router/configuration/overview/#yaml-config-file for yaml structure +# -- See https://www.apollographql.com/docs/graphos/reference/router/configuration#yaml-config-file for yaml structure router: configuration: - supergraph: # HTTP server - listen: 0.0.0.0:80 + supergraph: + listen: 0.0.0.0:4000 health_check: listen: 0.0.0.0:8088 - telemetry: - metrics: - prometheus: - enabled: false - listen: 0.0.0.0:9090 - path: "/metrics" args: - - --hot-reload + - --hot-reload managedFederation: # -- If using managed federation, the graph API key to identify router to Studio apiKey: - # -- If using managed federation, use an existing secret which stores the graph API key instead of creating a new one. + # -- If using managed federation, use existing Secret which stores the graph API key instead of creating a new one. # If set along `managedFederation.apiKey`, a secret with the graph API key will be created using this parameter as name existingSecret: + # -- If using managed federation, the name of the key within the existing Secret which stores the graph API key. + # If set along `managedFederation.apiKey`, a secret with the graph API key will be created using this parameter as key, defaults to using a key of `managedFederationApiKey` + existingSecretKeyRefKey: # -- If using managed federation, the variant of which graph to use graphRef: "" @@ -46,8 +41,8 @@ supergraphFile: # value: debug # extraEnvVars: [] -extraEnvVarsCM: '' -extraEnvVarsSecret: '' +extraEnvVarsCM: "" +extraEnvVarsSecret: "" # An array of extra VolumeMounts # Example: @@ -74,7 +69,7 @@ image: containerPorts: # -- If you override the port in `router.configuration.server.listen` then make sure to match the listen port here - http: 80 + http: 4000 # -- For exposing the metrics port when running a serviceMonitor for example metrics: 9090 # -- For exposing the health check endpoint @@ -127,10 +122,12 @@ serviceAccount: podAnnotations: {} -podSecurityContext: {} +podSecurityContext: + {} # fsGroup: 2000 -securityContext: {} +securityContext: + {} # capabilities: # drop: # - ALL @@ -142,6 +139,7 @@ service: type: ClusterIP port: 80 annotations: {} + targetport: http serviceMonitor: enabled: false @@ -166,7 +164,12 @@ ingress: virtualservice: enabled: false # namespace: "" - # gatewayName: "" + # gatewayName: "" # Deprecated in favor of gatewayNames + # gatewayNames: [] + # - "gateway-1" + # - "gateway-2" + # Hosts: "" # configurable but will default to '*' + # - somehost.domain.com # http: # main: # # set enabled to true to add @@ -194,7 +197,8 @@ serviceentry: # a list of external hosts you want to be able to make https calls to # - api.example.com -resources: {} +resources: + {} # We usually recommend not to specify default resources and to leave this as a conscious # choice for the user. This also increases chances charts run on environments with little # resources, such as Minikube. If you do want to specify resources, uncomment the following @@ -212,6 +216,20 @@ autoscaling: maxReplicas: 100 targetCPUUtilizationPercentage: 80 # targetMemoryUtilizationPercentage: 80 + # + # Specify container-specific HPA scaling targets + # Only available in 1.27+ (https://kubernetes.io/blog/2023/05/02/hpa-container-resource-metric/) + # containerBased: + # - name: + # type: cpu + # targetUtilizationPercentage: 75 + +# -- Sets the [rolling update strategy parameters](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-update-deployment). Can take absolute values or % values. +rollingUpdate: + {} +# Defaults if not set are: +# maxUnavailable: 25% +# maxSurge: 25% nodeSelector: {} @@ -235,4 +253,10 @@ probes: # -- Configure liveness probe liveness: initialDelaySeconds: 0 + +# -- Sets the [topology spread constraints](https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints/) for Deployment pods +topologySpreadConstraints: [] + +# -- Sets the restart policy of pods +restartPolicy: Always ``` diff --git a/docs/source/routing/self-hosted/containerization/kubernetes.mdx b/docs/source/routing/self-hosted/containerization/kubernetes.mdx deleted file mode 100644 index 6fe549132f..0000000000 --- a/docs/source/routing/self-hosted/containerization/kubernetes.mdx +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Deploy in Kubernetes -subtitle: Self-hosted deployment of the router in Kubernetes -description: Deploy the Apollo GraphOS Router or Apollo Router Core in Kubernetes using Helm charts. Customize configurations, enable metrics, and choose values for migration. ---- - -import ElasticNotice from '../../../../shared/elastic-notice.mdx'; -import HelmShowOutput from '../../../../shared/helm-show-router-output.mdx'; -import CoprocTypicalConfig from '../../../../shared/coproc-typical-config.mdx'; - -Learn how to deploy a self-hosted router (GraphOS Router or Apollo Router Core) in Kubernetes using Helm charts. - -```mermaid -flowchart LR; - clients(Clients); - subgraph "Kubernetes cluster"; - lb(["Load Balancer"]) - router_a(["Router"]); - coproc_a(["Coprocessor"]); - router_b(["Router"]); - coproc_b(["Coprocessor"]); - router_a <-.-> coproc_a; - router_b <-.-> coproc_b; - end; - clients -.->|Query| lb; - lb -.-> router_a & router_b; - class clients secondary; -``` - -The following guides provide the steps to: - -* Get a router Helm chart from the Apollo container repository. -* Deploy a router with a basic Helm chart. -* Configure chart values to export metrics, enable Rhai scripting, and deploy a coprocessor. -* Choose chart values that best suit migration from a gateway to the router. - - - -## About the router Helm chart - -[Helm](https://helm.sh) is a package manager for Kubernetes (k8s). Apollo provides an application Helm chart with each release of Apollo Router Core in GitHub. Since the router version 0.14.0, Apollo has released the router Helm chart as an [Open Container Initiative (OCI)](https://helm.sh/docs/topics/registries/) image in a GitHub container registry. - - - -The path to the OCI router chart is `oci://ghcr.io/apollographql/helm-charts/router`. - - - -You customize a deployed router with the same [command-line options and YAML configuration](/router/configuration/overview) but under different Helm CLI options and YAML keys. - -## Basic deployment - -Follow this guide to deploy the Router using Helm to install the basic chart provided with each router release. - -Each router chart has a `values.yaml` file with router and deployment settings. The released, unedited file has a few explicit settings, including: - -* Default container ports for the router's [HTTP server](/router/configuration/overview/#listen-address), [health check endpoint](/router/configuration/health-checks), and [metrics endpoint](/router/configuration/telemetry/exporters/metrics/overview). -* A command-line argument to enable [hot reloading of the router](/router/configuration/overview/#--hr----hot-reload). -* A single replica. - - - -The values of the Helm chart for Apollo Router Core v1.31.0 in the GitHub container repository, as output by the `helm show` command: - -```bash -helm show values oci://ghcr.io/apollographql/helm-charts/router -``` - - - - - -### Set up Helm - -1. Install [Helm](https://helm.sh/docs/intro/install/) **version 3.x**. The router's Helm chart requires Helm v3.x. - - - - Your Kubernetes version must be compatible with Helm v3. For details, see [Helm Version Support Policy](https://helm.sh/docs/topics/version_skew/#supported-version-skew). - - - - -1. Verify you can pull from the registry by showing the latest router chart values with the `helm show values` command: - - ```bash - helm show values oci://ghcr.io/apollographql/helm-charts/router - ``` - -### Set up cluster - -Install the tools and provision the infrastructure for your Kubernetes cluster. - -For an example, see the [Setup from Apollo's Reference Architecture](https://github.com/apollosolutions/reference-architecture/blob/main/docs/setup.md). It provides steps you can reference for gathering accounts and credentials for your cloud platform (GCP or AWS), provisioning resources, and deploying your subgraphs. - - - -To manage the system resources you need to deploy the router on Kubernetes: - -* Read [Managing router resources in Kubernetes](/technotes/TN0016-router-resource-management/). -* Use the [router resource estimator](/technotes/TN0045-router_resource_estimator/). - - - -### Set up graph - -Set up your self-hosted graph and get its [graph ref](/router/configuration/overview/#apollo_graph_ref) and [API key](/router/configuration/overview/#apollo_graph_ref). - -If you need a guide to set up your graph, you can follow [the self-hosted router quickstart](/graphos/quickstart/self-hosted) and complete [step 1 (Set up Apollo tools)](/graphos/quickstart/self-hosted/#1-set-up-apollo-tools), [step 4 (Obtain your subgraph schemas)](/graphos/quickstart/self-hosted/#4-obtain-your-subgraph-schemas), and [step 5 (Publish your subgraph schemas)](/graphos/quickstart/self-hosted/#5-publish-your-subgraph-schemas). - -### Deploy router - -To deploy the router, run the `helm install` command with an argument for the OCI image in the container repository, an argument for the `values.yaml` configuration file, and additional arguments to override specific configuration values. - -```bash -helm install --namespace --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml -``` -The necessary arguments for specific configuration values: - -* `--set managedFederation.graphRef=""`. The reference to your managed graph (`id@variant`), the same value as the [`APOLLO_GRAPH_REF` environment variable](/router/configuration/overview/#apollo_graph_ref). -* `--set managedFederation.apiKey=""`. The API key to your managed graph, the same value as the [`APOLLO_KEY` environment variable](/router/configuration/overview/#apollo_key). - -Some optional but recommended arguments: - -* `--namespace `. The namespace scope for this deployment. -* `--version `. The version of the router to deploy. If not specified by `helm install`, the latest version is installed. - -### Verify deployment - -Verify that your router is one of the deployed releases with the `helm list` command. - -If you deployed with the `--namespace ` option, you can list only the releases within your namespace: - -```bash -helm list --namespace -``` - -## Deploy with metrics endpoints - -The router supports [metrics endpoints for Prometheus and OpenTelemetry protocol (OTLP)](/router/configuration/telemetry/exporters/metrics/overview). A [basic deployment](#basic-deployment) doesn't enable metrics endpoints, because the router chart disables both Prometheus (explicitly) and OTLP (by omission). - -To enable metrics endpoints in your deployed router through a YAML configuration file: - -1. Create a YAML file, `my_values.yaml`, to contain additional values that override default values. -1. Edit `my_values.yaml` to enable metrics endpoints: - - ```yaml title="my_values.yaml" - router: - configuration: - telemetry: - metrics: - prometheus: - enabled: true - listen: 0.0.0.0:9090 - path: "/metrics" - otlp: - temporality: delta - endpoint: - ``` - - - - Although this example enables both Prometheus and OTLP, in practice it's common to enable only one endpoint. - - - - * `router.configuration.telemetry.metrics.prometheus` was already configured but disabled (`enabled: false`) by default. This configuration sets `enabled: true`. - * `router.configuration.telemetry.metrics.otlp` is enabled by inclusion. - * `router.configuration.telemetry.temporality` by default is `temporality: cumulative` and is a good choice for most metrics consumers. For DataDog, use `temporality: delta`. - -1. Deploy the router with the additional YAML configuration file. For example, starting with the `helm install` command from the basic deployment step, append `--values my_values.yaml`: - - ```bash - helm install --namespace --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --values my_values.yaml - ``` - -## Deploy with Rhai scripts - -The router supports [Rhai scripting](/graphos/routing/customization/rhai) to add custom functionality. - -Enabling Rhai scripts in your deployed router requires mounting an extra volume for your Rhai scripts and getting your scripts onto the volume. That can be done by following steps in [a separate example for creating a custom in-house router chart](https://github.com/apollographql/in-house-router-example). The example creates a new (in-house) chart that wraps (and depends on) the released router chart, and the new chart has templates that add the necessary configuration to allow Rhai scripts for a deployed router. - -## Deploy with a coprocessor - -The router supports [external coprocessing](/router/customizations/coprocessor) to run custom logic on requests throughout the [router's request-handling lifecycle](/graphos/routing/customization/rhai/#router-request-lifecycle). - -A deployed coprocessor has its own application image and container in the router pod. - -To configure a coprocessor and its container for your deployed router through a YAML configuration file: - -1. Create a YAML file, `my_values.yaml`, to contain additional values that override default values. -1. Edit `my_values.yaml` to configure a coprocessor for the router. For reference, follow the [typical](/router/customizations/coprocessor#typical-configuration) and [minimal](/router/customizations/coprocessor#minimal-configuration) configuration examples, and apply them to `router.configuration.coprocessor`. - - - - - - - -1. Edit `my_values.yaml` to add a container for the coprocessor. - - ```yaml title="my_values.yaml" - extraContainers: - - name: # name of deployed container - image: # name of application image - ports: - - containerPort: # must match port of router.configuration.coprocessor.url - env: [] # array of environment variables - ``` - -1. Deploy the router with the additional YAML configuration file. For example, starting with the `helm install` command from the basic deployment step, append `--values my_values.yaml`: - - ```bash - helm install --namespace --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --values my_values.yaml - ``` - -## Separate configurations per environment - -To support your different deployment configurations for different environments (development, staging, production, etc.), Apollo recommends separating your configuration values into separate files: - -- A **common** file, which contains values that apply across all environments. -- A unique **environment** file per environment, which includes and overrides the values from the common file while adding new environment-specific values. - -The `helm install` command applies each `--values ` option in the order you set them within the command. Therefore, a common file must be set before an environment file so that the environment file's values are applied last and override the common file's values. - -For example, this command deploys with a `common_values.yaml` file applied first and then a `prod_values.yaml` file: - -```bash -helm install --namespace --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --values common_values.yaml --values prod_values.yaml -``` - -## Deploying in Kubernetes with Istio - -[Istio](https://istio.io/) is a service mesh for Kubernetes which is often installed on a cluster for its traffic-shaping abilities. While we do not specifically recommend or support Istio, nor do we provide specific instructions for installing the Router in a cluster with Istio, there is a known consideration to make when configuring Istio. - -Consideration and additional configuration may be necessary as a consequence of how Istio does its sidecar injection. Without additional configuration, Istio may attempt to reconfigure the network interface at the same time the router is starting, which will result in a failure to start. - -This is not specifically a router issue and Istio has instructions on how to manage the matter in a general sense in their [own documentation](https://istio.io/latest/docs/ops/common-problems/injection/#pod-or-containers-start-with-network-issues-if-istio-proxy-is-not-ready). Their suggestion prevents the startup of all other containers in a pod until Istio itself is ready. We recommend this approach when using Istio. - -## Configure for migration from gateway - -When [migrating from `@apollo/gateway` to the router](/router/migrating-from-gateway), consider the following tips to maximize the compatibility of your router deployment. - -### Increase maximum request bytes - -By default the router sets its maximum supported request size at 2MB, while the gateway sets its maximum supported request size at 20MB. If your gateway accepts requests larger than 2MB, which it does by default, you can use the following configuration to ensure that the router is compatible with your gateway deployment. - - ```yaml title="values.yaml" - router: - configuration: - limits: - http_max_request_bytes: 20000000 #20MB - ``` - -### Increase request timeout - -The router's timeout is increased to accommodate subgraph operations with high latency. - - ```yaml title="values.yaml" - router: - configuration: - traffic_shaping: - router: - timeout: 6min - all: - timeout: 5min - ``` - -### Propagate subgraph errors - -The gateway propagates subgraph errors to clients, but the router doesn't by default, so it needs to be configured to propagate them. - - ```yaml title="values.yaml" - router: - configuration: - include_subgraph_errors: - all: true - ``` - -## Troubleshooting - -### Pods terminating due to memory pressure - -If your deployment of routers is terminating due to memory pressure, you can add router cache metrics to monitor and remediate your system: - -1. Add and track the following metrics to your monitoring system: - - * `apollo.router.cache.storage.estimated_size` - * `apollo.router.cache.size` - * ratio of `apollo.router.cache.hit.time.count` to `apollo.router.cache.miss.time.count` - -2. Observe and monitor the metrics: - - * Observe the `apollo.router.cache.storage.estimated_size` to see if it grows over time and correlates with pod memory usage. - * Observe the ratio of cache hits to misses to determine if the cache is being effective. - -3. Based on your observations, try some remediating adjustments: - - * Lower the cache size if the cache reaches near 100% hit-rate but the cache size is still growing. - * Increase the pod memory if the cache hit rate is low and the cache size is still growing. - * Lower the cache size if the latency of query planning cache misses is acceptable and memory availability is limited. diff --git a/docs/source/routing/self-hosted/index.mdx b/docs/source/routing/self-hosted/index.mdx index 3cdf684cf2..3edd4095de 100644 --- a/docs/source/routing/self-hosted/index.mdx +++ b/docs/source/routing/self-hosted/index.mdx @@ -1,6 +1,6 @@ --- -title: Deploying Self-Hosted Apollo Router -subtitle: How to deploy router for your own infrastructure +title: Self-Hosting the Apollo Router +subtitle: How to deploy router on your own infrastructure --- Apollo Router is a graph runtime that you can deploy in your own infrastructure. @@ -18,31 +18,31 @@ flowchart LR; class clients secondary; ``` -Each release of Apollo Router includes: +For each version of the Apollo Router, Apollo provides: -- A binary -- A container image -- A Helm chart +- [A Helm chart for Kubernetes](#kubernetes-using-helm) +- [A binary](#local-binary) +- [A Docker image](#container) -## Local binary +## Kubernetes Using Helm -Running Apollo Router directly from its binary speeds up local development, and it enables embedded use cases where containers are unavailable. +Helm is a package manager for Kubernetes. Apollo provides an application Helm chart with each release of Apollo Router in GitHub Container Registry. Since router v0.14.0, Apollo has released each router Helm chart as an Open Container Initiative (OCI) image in `oci://ghcr.io/apollographql/helm-charts/router`. -Follow the [quickstart](/graphos/routing/get-started) to run a router binary. +Follow the [Kubernetes quickstart](/graphos/routing/kubernetes/quickstart) to deploy the router with a Helm chart. -## Kubernetes via Helm +## Docker -Helm is a package manager for Kubernetes. Apollo provides an application Helm chart with each release of Apollo Router in GitHub Container Registry. Since router v0.14.0, Apollo has released each router Helm chart as an Open Container Initiative (OCI) image in `oci://ghcr.io/apollographql/helm-charts/router`. +Apollo provides Docker images with each release of Apollo Router. The images are available via GitHub, downloadable from the `ghcr.io/apollographql/router` and the [router repository](https://github.com/apollographql/router/pkgs/container/router). Both debug and production images are provided. -Follow the [Kubernetes deployment guide](/graphos/routing/self-hosted/containerization/kubernetes) to deploy the router with a Helm chart. +For more information on deploying using your container environment: -## Container +- [Docker](/graphos/routing/self-hosted/containerization/docker) +- [AWS using Elastic Container Service (ECS)](/graphos/routing/self-hosted/containerization/aws) +- [Azure using Azure Container App](/graphos/routing/self-hosted/containerization/azure) +- [GCP using Google Cloud Run](/graphos/routing/self-hosted/containerization/gcp) -For containerization without k8s or Helm, Apollo provides container images with each release of Apollo Router. The images are available in GitHub, downloadable from `ghcr.io/apollographql/router` and the [router repo](https://github.com/apollographql/router/pkgs/container/router). Both debug and production images are provided. +## Local binary -Follow the router deployment guide for your container environment: +Running the Apollo Router directly from its binary speeds up local development, and it enables embedded use cases where containers are unavailable. -- [AWS](/graphos/routing/self-hosted/containerization/aws) -- [Azure](/graphos/routing/self-hosted/containerization/azure) -- [GCP](/graphos/routing/self-hosted/containerization/gcp) -- [Docker](/graphos/routing/self-hosted/containerization/docker) +Follow the [quickstart](/graphos/routing/get-started) to run a router binary. diff --git a/docs/source/routing/self-hosted/kubernetes/extensibility.mdx b/docs/source/routing/self-hosted/kubernetes/extensibility.mdx new file mode 100644 index 0000000000..4dbc7a743e --- /dev/null +++ b/docs/source/routing/self-hosted/kubernetes/extensibility.mdx @@ -0,0 +1,138 @@ +--- +title: Using router extensibility features in Kubernetes +subtitle: Learn how to deploy a self-hosted router (GraphOS Router or Apollo Router Core) in Kubernetes with extensibility features +description: How to deploy the Apollo GraphOS Router or Apollo Router Core in Kubernetes with extensibility features. +--- + +import ElasticNotice from '../../../../shared/elastic-notice.mdx'; + + + +The router supports two extensibility options to customize the router's behavior. The extensibility features are: + +- [Rhai scripting](/graphos/routing/customization/rhai) +- [External coprocessors](/router/customizations/coprocessor) + +## Deploy with Rhai scripts + +The router supports [Rhai scripting](/graphos/routing/customization/rhai) to add custom functionality. + +Enabling Rhai scripts in your deployed router requires mounting an extra volume for your Rhai scripts and getting your scripts onto the volume. That can be done by following steps in [a separate example for creating a custom in-house router chart](https://github.com/apollographql/in-house-router-example). The example creates a new (in-house) chart that depends on the released router chart, and the new chart has templates that add the necessary configuration to allow Rhai scripts for a deployed router. + + + Ideally this would a separate example fully within the docs, however the `in-house-router-example` is public and the example is a good one so it isn't worth duplicating the effort as of now. + + +## Deploying with a coprocessor + +You have two options to consider when deploying a coprocessor. + +* [Deploy as a sidecar container](#deploy-as-a-sidecar-container) +* [Deploy as a separate Kubernetes `Deployment`](#deploying-using-a-separate-deployment) + +Consider the following when deciding which option to use: + +* The sidecar container option is the simplest and most common way to deploy a coprocessor. It allows you to run the coprocessor in the same pod as the router, which can simplify networking and configuration. +* The separate `Deployment` option allows you to run the coprocessor in a different pod, which can be useful if you want to scale the coprocessor independently of the router. + +### Deploy as a sidecar container + +The router supports [external coprocessing](/router/customizations/coprocessor) to run custom logic on requests throughout the [router's request-handling lifecycle](/graphos/routing/customization/rhai/#router-request-lifecycle). + +A deployed coprocessor can have its own application image and container in the router pod. + +To configure a coprocessor and its container for your deployed router through a YAML configuration file: + +1. Create a YAML file, `coprocessor_values.yaml`, to contain additional values that override default values. +1. Edit `coprocessor_values.yaml` to configure a coprocessor for the router. For reference, follow the [typical](/router/customizations/coprocessor#typical-configuration) and [minimal](/router/customizations/coprocessor#minimal-configuration) configuration examples, and apply them to `router.configuration.coprocessor`. + + + + + + + +1. Edit `coprocessor_values.yaml` to add a container for the coprocessor. + + ```yaml title="coprocessor_values.yaml" + extraContainers: + - name: # name of deployed container + image: # name of application image + ports: + - containerPort: # must match port of router.configuration.coprocessor.url + env: [] # array of environment variables + ``` + +1. Deploy the router with the additional YAML configuration file. For example, starting with the `helm install` command from the basic deployment step, append `--values coprocessor_values.yaml`: + + ```bash + helm install --namespace --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --values coprocessor_values.yaml + ``` + +### Deploying using a separate `Deployment` + +Deploying as a separate `Deployment` can take shape in two ways: + +* Using an entirely separate Helm chart. +* Using the router's Helm chart as a dependency and adding a new `Deployment` template + * This option is more complex but allows you to customize the router's Helm chart and add your own templates whilst keeping the coporcessor's deployment alongside the router's. + +#### Separate Helm chart + +In the case of using a separate Helm chart, a `coprocessor` chart would be deployed independently of the router. This chart would contain the configuration for the coprocessor's deployment. An example folder structure might look like: + +``` +charts/ +├── coprocessor/ +│ ├── Chart.yaml +│ ├── values.yaml +│ ├── templates/ +│ │ ├── deployment.yaml +│ │ ├── service.yaml +│ │ └── ... +│ └── ... +├── router/ +│ ├── values.yaml +│ └── ... +``` + + +The `router` chart would be the router's Helm chart, which you can deploy as described in the [Kubernetes deployment guide](/graphos/routing/kubernetes/quickstart). + +#### Using the router's Helm chart as a dependency + +In the case of using the router's Helm chart as a dependency, you can create a new template in the `templates` folder of the `router` Helm chart. This template would contain the configuration for the coprocessor's deployment. + +The `Chart.yaml` file for the router would include: + +```yaml +dependencies: + - name: router + version: 2.2.1 + repository: oci://ghcr.io/apollographql/helm-charts +``` + +An example folder structure might look like: + +``` +charts/ +├── router/ +│ ├── Chart.yaml +│ ├── values.yaml +│ ├── templates/ +│ │ ├── deployment.yaml +│ │ ├── service.yaml +│ │ └── ... +│ └── ... +``` + +In the above example, the `router` chart would be the router's Helm chart, which you can deploy as described in the [Kubernetes deployment guide](/graphos/routing/kubernetes/quickstart). The `templates` folder would contain the configuration for the coprocessor's deployment. Within the `values.yaml` you can then nest the necessary configuration under the `router` key, such as: + +```values.yaml +router: + configuration: + coprocessor: + url: http://: +``` + + diff --git a/docs/source/routing/self-hosted/kubernetes/metrics.mdx b/docs/source/routing/self-hosted/kubernetes/metrics.mdx new file mode 100644 index 0000000000..a9be29111d --- /dev/null +++ b/docs/source/routing/self-hosted/kubernetes/metrics.mdx @@ -0,0 +1,46 @@ +--- +title: Metrics endpoints +subtitle: Learn how to use a self-hosted router (GraphOS Router or Apollo Router Core) in Kubernetes with metrics endpoints +description: Use the Apollo GraphOS Router or Apollo Router Core in Kubernetes with metrics endpoints and considerations when doing so. +--- + +import ElasticNotice from '../../../../shared/elastic-notice.mdx'; + + + +The router supports [metrics endpoints for Prometheus and OpenTelemetry protocol (OTLP)](/router/configuration/telemetry/exporters/metrics/overview). The default deployment doesn't enable metrics endpoints because the router chart disables both Prometheus (explicitly) and OTLP (by omission). + +To enable metrics endpoints in your deployed router through a YAML configuration file: + +1. Create a YAML file, `my_values.yaml`, to contain additional values that override default values. +1. Edit `my_values.yaml` to enable metrics endpoints: + + ```yaml title="my_values.yaml" + router: + configuration: + telemetry: + metrics: + prometheus: + enabled: true + listen: 0.0.0.0:9090 + path: "/metrics" + otlp: + temporality: cumulative # default; if using DataDog, use temporality: delta + endpoint: + ``` + + + + Although this example enables both Prometheus and OTLP, in practice it's common to enable only one endpoint. + + + + * `router.configuration.telemetry.metrics.prometheus` was already configured but disabled (`enabled: false`) by default. This configuration sets `enabled: true`. + * `router.configuration.telemetry.metrics.otlp` is enabled by inclusion. + * `router.configuration.telemetry.temporality` by default is `temporality: cumulative` and is a good choice for most metrics consumers. For DataDog, use `temporality: delta`. + +1. Deploy the router with the additional YAML configuration file. For example, starting with the `helm install` command from the basic deployment step, append `--values my_values.yaml`: + + ```bash + helm install --namespace --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --values my_values.yaml + ``` diff --git a/docs/source/routing/self-hosted/kubernetes/other-considerations.mdx b/docs/source/routing/self-hosted/kubernetes/other-considerations.mdx new file mode 100644 index 0000000000..6304bd3e31 --- /dev/null +++ b/docs/source/routing/self-hosted/kubernetes/other-considerations.mdx @@ -0,0 +1,54 @@ +--- +title: Other considerations for hosting the router in Kubernetes +subtitle: Learn about other considerations for hosting the router in Kubernetes, including Istio and resources +description: Other considerations for hosting the router in Kubernetes. +--- + +import ElasticNotice from '../../../../shared/elastic-notice.mdx'; + + + +There are a few other considerations to keep in mind when hosting the router in Kubernetes. These include: + +* [Using Istio](#deploying-in-kubernetes-with-istio) +* [Troubleshooting a hosted router](#troubleshooting-a-hosted-router) + +## Deploying in Kubernetes with Istio + +[Istio](https://istio.io/) is a service mesh for Kubernetes which is often installed on a cluster for its traffic-shaping abilities. While Apollo dopes not specifically recommend or support Istio, nor does Apollo provide specific instructions for installing the Router in a cluster with Istio, there is a known consideration to make when configuring Istio. + +Consideration and additional configuration may be necessary as a consequence of how Istio does its sidecar injection. Without additional configuration, Istio may attempt to reconfigure the network interface at the same time the router is starting, which will result in a failure to start. + +This is not specifically a router issue and Istio has instructions on how to manage the matter in a general sense in their [own documentation](https://istio.io/latest/docs/ops/common-problems/injection/#pod-or-containers-start-with-network-issues-if-istio-proxy-is-not-ready). Their suggestion prevents the startup of all other containers in a pod until Istio itself is ready. Apollo recommends this approach when using Istio. + +## Troubleshooting a hosted router + + + +To manage the system resources you need to deploy the router on Kubernetes: + +* Read [Managing router resources in Kubernetes](/technotes/TN0016-router-resource-management/). +* Use the [router resource estimator](/technotes/TN0045-router_resource_estimator/). + + + +### Pods terminating due to memory pressure + +If your deployment of routers is terminating due to memory pressure, you can add router cache metrics to monitor and remediate your system: + +1. Add and track the following metrics to your monitoring system: + + * `apollo.router.cache.storage.estimated_size` + * `apollo.router.cache.size` + * ratio of `apollo.router.cache.hit.time.count` to `apollo.router.cache.miss.time.count` + +2. Observe and monitor the metrics: + + * Observe the `apollo.router.cache.storage.estimated_size` to see if it grows over time and correlates with pod memory usage. + * Observe the ratio of cache hits to misses to determine if the cache is being effective. + +3. Based on your observations, try some remediating adjustments: + + * Lower the cache size if the cache reaches near 100% hit-rate but the cache size is still growing. + * Increase the pod memory if the cache hit rate is low and the cache size is still growing. + * Lower the cache size if the latency of query planning cache misses is acceptable and memory availability is limited. diff --git a/docs/source/routing/self-hosted/kubernetes/quickstart.mdx b/docs/source/routing/self-hosted/kubernetes/quickstart.mdx new file mode 100644 index 0000000000..6794e1a561 --- /dev/null +++ b/docs/source/routing/self-hosted/kubernetes/quickstart.mdx @@ -0,0 +1,131 @@ +--- +title: Kubernetes quickstaart +subtitle: Learn how to deploy a self-hosted router (GraphOS Router or Apollo Router Core) in Kubernetes using Helm charts +description: Deploy the Apollo GraphOS Router or Apollo Router Core in Kubernetes using Helm charts. Customize configurations, enable metrics, and choose values for migration. +--- + +import ElasticNotice from '../../../../shared/elastic-notice.mdx'; +import HelmShowOutput from '../../../../shared/helm-show-router-output.mdx'; +import CoprocTypicalConfig from '../../../../shared/coproc-typical-config.mdx'; + +The following guide provide the steps to: + +* Get the router Helm chart from the Apollo container repository. +* Deploy a router with a basic Helm chart. +* Configure chart values to export metrics, enable Rhai scripting, and deploy a coprocessor. +* Choose chart values that best suit migration from a gateway to the router. + + + +## Prerequisites + + + +This guide assumes you are familiar with Kubernetes and Helm. If you are not familiar with either, you can find a [Kubernetes tutorial](https://kubernetes.io/docs/tutorials/) and a [Helm tutorial](https://helm.sh/docs/intro/quickstart/) to get started. + + + +* A GraphOS graph set up in your Apollo account. If you don't have a graph, you can create one in the [Apollo Studio](https://studio.apollographql.com/). +* [Helm](https://helm.sh/docs/intro/install/) **version 3.x or higher** installed on your local machine. +* A Kubernetes cluster with access to the internet. + +### GraphOS graph + +Set up your self-hosted graph and get its [graph ref](/router/configuration/overview/#apollo_graph_ref) and [API key](/router/configuration/overview/#apollo_graph_ref). + +If you need a guide to set up your graph, you can follow [the self-hosted router quickstart](/graphos/quickstart/self-hosted) and complete [step 1 (Set up Apollo tools)](/graphos/quickstart/self-hosted/#1-set-up-apollo-tools), [step 4 (Obtain your subgraph schemas)](/graphos/quickstart/self-hosted/#4-obtain-your-subgraph-schemas), and [step 5 (Publish your subgraph schemas)](/graphos/quickstart/self-hosted/#5-publish-your-subgraph-schemas). + +### Kubernetes cluster + +If you don't have a Kubernetes cluster, you can set one up using [kind](https://kind.sigs.k8s.io/) or [minikube](https://minikube.sigs.k8s.io/docs/) locally, or by referring to your cloud provider's documentation. + +## Quickstart + +To deploy the router, run the `helm install` command with an argument for the OCI image in the container repository. Optionally, you can add arguments for the `values.yaml` configuration file and/or additional arguments to override specific configuration values. + +```bash +helm install --namespace apollo-router --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router +``` + +The necessary arguments for specific configuration values: + +* `--set managedFederation.graphRef=""`. The reference to your managed graph (`id@variant`), the same value as the [`APOLLO_GRAPH_REF` environment variable](/router/configuration/overview/#apollo_graph_ref). +* `--set managedFederation.apiKey=""`. The API key to your managed graph, the same value as the [`APOLLO_KEY` environment variable](/router/configuration/overview/#apollo_key). + +Some optional but recommended arguments: + +* `--namespace `. The namespace scope for this deployment. +* `--version `. The version of the router to deploy. If not specified by `helm install`, the latest version is installed. + +### Verify deployment + +Verify that your router is one of the deployed releases with the `helm list` command. If you deployed with the `--namespace ` option, you can list only the releases within your namespace: + +```bash +helm list --namespace +``` +## Deployed architecture + +The default deployed architecture will be (when using a coprocessor): + +```mermaid +flowchart LR; + clients(Clients); + subgraph "Kubernetes cluster"; + lb(["Load Balancer"]) + router_a(["Router"]); + coproc_a(["Coprocessor"]); + router_b(["Router"]); + coproc_b(["Coprocessor"]); + router_a <-.-> coproc_a; + router_b <-.-> coproc_b; + end; + clients -.->|Query| lb; + lb -.-> router_a & router_b; + class clients secondary; +``` + +## Router Helm chart configuration + + Apollo provides an application Helm chart with each release of Apollo Router Core in GitHub. Since the router version v0.14.0, Apollo has released the router Helm chart as an [Open Container Initiative (OCI)](https://helm.sh/docs/topics/registries/) image in the GitHub container registry. + + + +The path to the OCI router chart is `oci://ghcr.io/apollographql/helm-charts/router` and tagged with the applicable router release version. For example, router version `v.2.2.1`'s Helm chart would be `oci://ghcr.io/apollographql/helm-charts/router:2.2.1`. + + + +You customize a deployed router with the same [command-line options and YAML configuration options](/router/configuration/overview) using different Helm CLI options and YAML keys through a [values file](https://helm.sh/docs/chart_template_guide/values_files/). + +Each router chart has a defult `values.yaml` file with router and deployment settings. The released, unedited file has a few explicit settings, including: + +* Default container ports for the router's [HTTP server](/router/configuration/overview/#listen-address), [health check endpoint](/router/configuration/health-checks), and [metrics endpoint](/router/configuration/telemetry/exporters/metrics/overview). +* A command-line argument to enable [hot reloading of the router](/router/configuration/overview/#--hr----hot-reload). +* A single replica. + + + +The values of the Helm chart for Apollo Router Core v2.2.1 in the GitHub container repository, as output by the `helm show` command: + +```bash +helm show values oci://ghcr.io/apollographql/helm-charts/router +``` + + + + + +## Separate configurations per environment + +To support your different deployment configurations for different environments (development, staging, production, etc.), Apollo recommends separating your configuration values into separate files: + +- A **common** file, which contains values that apply across all environments. +- A unique **environment** file per environment, which includes and overrides the values from the common file while adding new environment-specific values. + +The `helm install` command applies each `--values ` option in the order you set them within the command. Therefore, a common file must be set before an environment file so that the environment file's values are applied last and override the common file's values. + +For example, this command deploys with a `common_values.yaml` file applied first and then a `prod_values.yaml` file: + +```bash +helm install --namespace --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --values common_values.yaml --values prod_values.yaml +``` \ No newline at end of file From beade6d718af1365185c6bab53c558a42d84e778 Mon Sep 17 00:00:00 2001 From: Lucas Leadbetter <5595530+lleadbet@users.noreply.github.com> Date: Wed, 14 May 2025 15:44:16 -0400 Subject: [PATCH 2/7] add sidebar --- docs/source/_sidebar.yaml | 293 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 293 insertions(+) create mode 100644 docs/source/_sidebar.yaml diff --git a/docs/source/_sidebar.yaml b/docs/source/_sidebar.yaml new file mode 100644 index 0000000000..60385033cc --- /dev/null +++ b/docs/source/_sidebar.yaml @@ -0,0 +1,293 @@ +switcher: + heading: "Apollo Router" + versions: + - label: v2 + latest: true + href: ./ + - label: v1 + href: ./v1 +items: + - label: "Overview" + href: "." + - label: "Get Started" + href: "./get-started" + - label: "Request Lifecycle" + href: "./request-lifecycle" + - label: "Configuration" + children: + - label: "Overview" + href: "./configuration/overview" + - label: "Environment Variable Reference" + href: "./configuration/envvars" + - label: "CLI Reference" + href: "./configuration/cli" + - label: "YAML Reference" + href: "./configuration/yaml" + - label: "Features" + children: + - label: "Security" + children: + - label: "Overview" + href: "./security" + - label: "Persisted Queries" + href: "./security/persisted-queries" + - label: "Authorization" + href: "./security/authorization" + - label: "Authentication" + children: + - label: "JWT Authentication" + href: "./security/jwt" + - label: "Router Authentication" + href: "./security/router-authentication" + - label: "Subgraph Authentication" + href: "./security/subgraph-authentication" + - label: "CORS" + href: "./security/cors" + - label: "CSRF Prevention" + href: "./security/csrf" + - label: "TLS" + href: "./security/tls" + - label: "Request Limits" + href: "./security/request-limits" + - label: "Demand Control" + href: "./security/demand-control" + - label: "Observability" + children: + - label: "Overview" + href: "./observability" + - label: "Federated Trace Data" + href: "./observability/federated-trace-data" + - label: "Router Telemetry" + children: + - label: "Overview" + href: "./observability/telemetry" + - label: "Log Exporters" + children: + - label: "Overview" + href: "./observability/telemetry/log-exporters/overview" + - label: "Stdout" + href: "./observability/telemetry/log-exporters/stdout" + - label: "Metrics Exporters" + children: + - label: "Overview" + href: "./observability/telemetry/metrics-exporters/overview" + - label: "Datadog" + href: "./observability/telemetry/metrics-exporters/datadog" + - label: "Dynatrace" + href: "./observability/telemetry/metrics-exporters/dynatrace" + - label: "New Relic" + href: "./observability/telemetry/metrics-exporters/new-relic" + - label: "OTLP" + href: "./observability/telemetry/metrics-exporters/otlp" + - label: "Prometheus" + href: "./observability/telemetry/metrics-exporters/prometheus" + - label: "Trace Exporters" + children: + - label: "Overview" + href: "./observability/telemetry/trace-exporters/overview" + - label: "Datadog" + href: "./observability/telemetry/trace-exporters/datadog" + - label: "Dynatrace" + href: "./observability/telemetry/trace-exporters/dynatrace" + - label: "Jaeger" + href: "./observability/telemetry/trace-exporters/jaeger" + - label: "New Relic" + href: "./observability/telemetry/trace-exporters/new-relic" + - label: "OTLP" + href: "./observability/telemetry/trace-exporters/otlp" + - label: "Zipkin" + href: "./observability/telemetry/trace-exporters/zipkin" + - label: "Instrumentation" + children: + - label: "Instruments" + href: "./observability/telemetry/instrumentation/instruments" + - label: "Events" + href: "./observability/telemetry/instrumentation/events" + - label: "Conditions" + href: "./observability/telemetry/instrumentation/conditions" + - label: "Spans" + href: "./observability/telemetry/instrumentation/spans" + - label: "Selectors" + href: "./observability/telemetry/instrumentation/selectors" + - label: "Standard Attributes" + href: "./observability/telemetry/instrumentation/standard-attributes" + - label: "Standard Instruments" + href: "./observability/telemetry/instrumentation/standard-instruments" + - label: "Subgraph Observability" + children: + - label: "Subgraph Error Inclusion" + href: "./observability/subgraph-error-inclusion" + - label: "Debugging Subgraph Requests" + href: "./observability/debugging-subgraph-requests" + - label: "Client Observability" + children: + - label: "Debugging Client Requests" + href: "./observability/debugging-client-requests" + - label: "Client ID Enforcement" + href: "./observability/client-id-enforcement" + - label: "OpenTelemetry" + children: + - label: "Set up OTel" + href: "./observability/otel" + - label: "Connect OTel to Prometheus" + href: "./observability/otel-traces-to-prometheus" + - label: "Query Planning" + children: + - label: "Native Query Planner" + href: "./query-planning/native-query-planner" + - label: "Query Planning Best Practices" + href: "./query-planning/query-planning-best-practices" + - label: "Caching" + children: + - label: "In-Memory Caching" + href: "./performance/caching/in-memory" + - label: "Distributed Caching" + href: "./performance/caching/distributed" + - label: "Entity Caching" + href: "./performance/caching/entity" + - label: "Performance and Scaling" + children: + - label: "Overview" + href: "./performance" + - label: "Traffic Shaping" + href: "./performance/traffic-shaping" + - label: "Query Batching" + href: "./performance/query-batching" + - label: "Client Features" + children: + - label: "HTTP Header Propagation" + href: "./header-propagation" + - label: "@defer" + href: "./operations/defer" + - label: "GraphQL Subscriptions" + children: + - label: "Overview" + href: "./operations/subscriptions/overview" + - label: "Configuration" + href: "./operations/subscriptions/configuration" + - label: "Callback Protocol" + href: "./operations/subscriptions/callback-protocol" + - label: "Multipart Protocol" + href: "./operations/subscriptions/multipart-protocol" + - label: "Enable with API Gateway" + href: "./operations/subscriptions/api-gateway" + - label: "File Upload" + href: "./operations/file-upload" + - label: "Customization" + children: + - label: "Overview" + href: "./customization/overview" + - label: "Coprocessors" + children: + - label: "Coprocessor Configuration" + href: "./customization/coprocessor" + - label: "Coprocessor Reference" + href: "./customization/coprocessor/reference" + - label: "Rhai Scripts" + children: + - label: "Rhai Configuration" + href: "./customization/rhai" + - label: "Rhai API Reference" + href: "./customization/rhai/reference" + - label: "Custom Builds" + children: + - label: "Building a Binary" + href: "./customization/custom-binary" + - label: "Rust Plugins" + href: "./customization/native-plugins" + - label: "Deployment" + children: + - label: "Overview" + href: "./self-hosted" + - label: "Docker" + href: "./self-hosted/containerization/docker" + - label: "Kubernetes" + children: + - label: "Quickstart" + href: "./self-hosted/kubernetes/quickstart" + - label: "Deploying with extensibility" + href: "./self-hosted/kubernetes/extensibility" + - label: "Enabling metrics" + href: "./self-hosted/kubernetes/metrics" + - label: "Other consideration" + href: "./self-hosted/kubernetes/other-considerations" + - label: "AWS" + children: + - label: "AWS ECS" + href: "./self-hosted/containerization/aws" + - label: "Azure" + children: + - label: "Azure Container Apps" + href: "./self-hosted/containerization/azure" + - label: "GCP" + children: + - label: "Google Cloud Run" + href: "./self-hosted/containerization/gcp" + - label: "Apollo Cloud Routing" + children: + - label: "Overview" + href: "./cloud/" + - label: "Configuration" + href: "./cloud/configuration" + - label: "Secure Subgraphs" + href: "./cloud/secure-subgraphs" + - label: "Subscriptions" + href: "./cloud/subscriptions" + - label: "Serverless" + href: "./cloud/serverless" + - label: "Dedicated" + children: + - label: "Overview" + href: "./cloud/dedicated" + - label: "Quickstart" + href: "./cloud/dedicated-quickstart" + - label: "Custom Domains" + href: "./cloud/custom-domains" + - label: "Throughput Guide" + href: "./cloud/throughput-guide" + - label: "Migrate to Dedicated" + href: "./cloud/migrate-to-dedicated" + - label: "AWS Lattice" + children: + - label: "Lattice Configuration" + href: "./cloud/lattice-configuration" + - label: "Lattice Management" + href: "./cloud/lattice-management" + - label: "Lattice Troubleshooting" + href: "./cloud/lattice-troubleshooting" + - label: "Tools" + children: + - label: "Router Resource Estimator" + href: "./self-hosted/resource-estimator" + - label: "Health Checks" + href: "./self-hosted/health-checks" + - label: "Resource Management" + href: "./self-hosted/resource-management" + - label: "Releases" + children: + - label: "Changelogs" + href: "./changelog" + - label: "What's New in Router v2" + href: "./about-v2" + - label: "Upgrade from Router v1" + href: "./upgrade/from-router-v1" + - label: "Migrate from Gateway" + href: "./migration/from-gateway" + - label: "API Gateway Comparison" + href: "./router-api-gateway-comparison" + - label: "GraphOS Integration" + children: + - label: "GraphOS Plan License" + href: "./license" + - label: "GraphOS Plan Features" + href: "./graphos-features" + - label: "Apollo Uplink" + href: "./uplink" + - label: "Operation Metrics Reporting" + href: "./graphos-reporting" + - label: "Reference" + children: + - label: "Federation Version Support" + href: "./federation-version-support" + - label: "Errors" + href: "./errors" From 1685717ca53ef30b520fac160aa2e85c79fc576b Mon Sep 17 00:00:00 2001 From: Lucas Leadbetter <5595530+lleadbet@users.noreply.github.com> Date: Mon, 19 May 2025 14:44:28 -0400 Subject: [PATCH 3/7] Update docs/source/_sidebar.yaml Co-authored-by: Maria Elisabeth Schreiber --- docs/source/_sidebar.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/_sidebar.yaml b/docs/source/_sidebar.yaml index 60385033cc..daa36d4e06 100644 --- a/docs/source/_sidebar.yaml +++ b/docs/source/_sidebar.yaml @@ -204,13 +204,13 @@ items: - label: "Kubernetes" children: - label: "Quickstart" - href: "./self-hosted/kubernetes/quickstart" + href: "./self-hosted/containerization/kubernetes/quickstart" - label: "Deploying with extensibility" - href: "./self-hosted/kubernetes/extensibility" + href: "./self-hosted/containerization/kubernetes/extensibility" - label: "Enabling metrics" - href: "./self-hosted/kubernetes/metrics" + href: "./self-hosted/containerization/kubernetes/metrics" - label: "Other consideration" - href: "./self-hosted/kubernetes/other-considerations" + href: "./self-hosted/containerization/kubernetes/other-considerations" - label: "AWS" children: - label: "AWS ECS" From 231486bd7014ae04a0124e8602245c5586914819 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Mon, 19 May 2025 16:10:17 -0600 Subject: [PATCH 4/7] move k8s docs --- .../kubernetes/extensibility.mdx | 138 ++++++++++++++++++ .../containerization/kubernetes/metrics.mdx | 46 ++++++ .../kubernetes/other-considerations.mdx | 54 +++++++ .../kubernetes/quickstart.mdx | 131 +++++++++++++++++ 4 files changed, 369 insertions(+) create mode 100644 docs/source/routing/self-hosted/containerization/kubernetes/extensibility.mdx create mode 100644 docs/source/routing/self-hosted/containerization/kubernetes/metrics.mdx create mode 100644 docs/source/routing/self-hosted/containerization/kubernetes/other-considerations.mdx create mode 100644 docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx diff --git a/docs/source/routing/self-hosted/containerization/kubernetes/extensibility.mdx b/docs/source/routing/self-hosted/containerization/kubernetes/extensibility.mdx new file mode 100644 index 0000000000..4dbc7a743e --- /dev/null +++ b/docs/source/routing/self-hosted/containerization/kubernetes/extensibility.mdx @@ -0,0 +1,138 @@ +--- +title: Using router extensibility features in Kubernetes +subtitle: Learn how to deploy a self-hosted router (GraphOS Router or Apollo Router Core) in Kubernetes with extensibility features +description: How to deploy the Apollo GraphOS Router or Apollo Router Core in Kubernetes with extensibility features. +--- + +import ElasticNotice from '../../../../shared/elastic-notice.mdx'; + + + +The router supports two extensibility options to customize the router's behavior. The extensibility features are: + +- [Rhai scripting](/graphos/routing/customization/rhai) +- [External coprocessors](/router/customizations/coprocessor) + +## Deploy with Rhai scripts + +The router supports [Rhai scripting](/graphos/routing/customization/rhai) to add custom functionality. + +Enabling Rhai scripts in your deployed router requires mounting an extra volume for your Rhai scripts and getting your scripts onto the volume. That can be done by following steps in [a separate example for creating a custom in-house router chart](https://github.com/apollographql/in-house-router-example). The example creates a new (in-house) chart that depends on the released router chart, and the new chart has templates that add the necessary configuration to allow Rhai scripts for a deployed router. + + + Ideally this would a separate example fully within the docs, however the `in-house-router-example` is public and the example is a good one so it isn't worth duplicating the effort as of now. + + +## Deploying with a coprocessor + +You have two options to consider when deploying a coprocessor. + +* [Deploy as a sidecar container](#deploy-as-a-sidecar-container) +* [Deploy as a separate Kubernetes `Deployment`](#deploying-using-a-separate-deployment) + +Consider the following when deciding which option to use: + +* The sidecar container option is the simplest and most common way to deploy a coprocessor. It allows you to run the coprocessor in the same pod as the router, which can simplify networking and configuration. +* The separate `Deployment` option allows you to run the coprocessor in a different pod, which can be useful if you want to scale the coprocessor independently of the router. + +### Deploy as a sidecar container + +The router supports [external coprocessing](/router/customizations/coprocessor) to run custom logic on requests throughout the [router's request-handling lifecycle](/graphos/routing/customization/rhai/#router-request-lifecycle). + +A deployed coprocessor can have its own application image and container in the router pod. + +To configure a coprocessor and its container for your deployed router through a YAML configuration file: + +1. Create a YAML file, `coprocessor_values.yaml`, to contain additional values that override default values. +1. Edit `coprocessor_values.yaml` to configure a coprocessor for the router. For reference, follow the [typical](/router/customizations/coprocessor#typical-configuration) and [minimal](/router/customizations/coprocessor#minimal-configuration) configuration examples, and apply them to `router.configuration.coprocessor`. + + + + + + + +1. Edit `coprocessor_values.yaml` to add a container for the coprocessor. + + ```yaml title="coprocessor_values.yaml" + extraContainers: + - name: # name of deployed container + image: # name of application image + ports: + - containerPort: # must match port of router.configuration.coprocessor.url + env: [] # array of environment variables + ``` + +1. Deploy the router with the additional YAML configuration file. For example, starting with the `helm install` command from the basic deployment step, append `--values coprocessor_values.yaml`: + + ```bash + helm install --namespace --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --values coprocessor_values.yaml + ``` + +### Deploying using a separate `Deployment` + +Deploying as a separate `Deployment` can take shape in two ways: + +* Using an entirely separate Helm chart. +* Using the router's Helm chart as a dependency and adding a new `Deployment` template + * This option is more complex but allows you to customize the router's Helm chart and add your own templates whilst keeping the coporcessor's deployment alongside the router's. + +#### Separate Helm chart + +In the case of using a separate Helm chart, a `coprocessor` chart would be deployed independently of the router. This chart would contain the configuration for the coprocessor's deployment. An example folder structure might look like: + +``` +charts/ +├── coprocessor/ +│ ├── Chart.yaml +│ ├── values.yaml +│ ├── templates/ +│ │ ├── deployment.yaml +│ │ ├── service.yaml +│ │ └── ... +│ └── ... +├── router/ +│ ├── values.yaml +│ └── ... +``` + + +The `router` chart would be the router's Helm chart, which you can deploy as described in the [Kubernetes deployment guide](/graphos/routing/kubernetes/quickstart). + +#### Using the router's Helm chart as a dependency + +In the case of using the router's Helm chart as a dependency, you can create a new template in the `templates` folder of the `router` Helm chart. This template would contain the configuration for the coprocessor's deployment. + +The `Chart.yaml` file for the router would include: + +```yaml +dependencies: + - name: router + version: 2.2.1 + repository: oci://ghcr.io/apollographql/helm-charts +``` + +An example folder structure might look like: + +``` +charts/ +├── router/ +│ ├── Chart.yaml +│ ├── values.yaml +│ ├── templates/ +│ │ ├── deployment.yaml +│ │ ├── service.yaml +│ │ └── ... +│ └── ... +``` + +In the above example, the `router` chart would be the router's Helm chart, which you can deploy as described in the [Kubernetes deployment guide](/graphos/routing/kubernetes/quickstart). The `templates` folder would contain the configuration for the coprocessor's deployment. Within the `values.yaml` you can then nest the necessary configuration under the `router` key, such as: + +```values.yaml +router: + configuration: + coprocessor: + url: http://: +``` + + diff --git a/docs/source/routing/self-hosted/containerization/kubernetes/metrics.mdx b/docs/source/routing/self-hosted/containerization/kubernetes/metrics.mdx new file mode 100644 index 0000000000..a9be29111d --- /dev/null +++ b/docs/source/routing/self-hosted/containerization/kubernetes/metrics.mdx @@ -0,0 +1,46 @@ +--- +title: Metrics endpoints +subtitle: Learn how to use a self-hosted router (GraphOS Router or Apollo Router Core) in Kubernetes with metrics endpoints +description: Use the Apollo GraphOS Router or Apollo Router Core in Kubernetes with metrics endpoints and considerations when doing so. +--- + +import ElasticNotice from '../../../../shared/elastic-notice.mdx'; + + + +The router supports [metrics endpoints for Prometheus and OpenTelemetry protocol (OTLP)](/router/configuration/telemetry/exporters/metrics/overview). The default deployment doesn't enable metrics endpoints because the router chart disables both Prometheus (explicitly) and OTLP (by omission). + +To enable metrics endpoints in your deployed router through a YAML configuration file: + +1. Create a YAML file, `my_values.yaml`, to contain additional values that override default values. +1. Edit `my_values.yaml` to enable metrics endpoints: + + ```yaml title="my_values.yaml" + router: + configuration: + telemetry: + metrics: + prometheus: + enabled: true + listen: 0.0.0.0:9090 + path: "/metrics" + otlp: + temporality: cumulative # default; if using DataDog, use temporality: delta + endpoint: + ``` + + + + Although this example enables both Prometheus and OTLP, in practice it's common to enable only one endpoint. + + + + * `router.configuration.telemetry.metrics.prometheus` was already configured but disabled (`enabled: false`) by default. This configuration sets `enabled: true`. + * `router.configuration.telemetry.metrics.otlp` is enabled by inclusion. + * `router.configuration.telemetry.temporality` by default is `temporality: cumulative` and is a good choice for most metrics consumers. For DataDog, use `temporality: delta`. + +1. Deploy the router with the additional YAML configuration file. For example, starting with the `helm install` command from the basic deployment step, append `--values my_values.yaml`: + + ```bash + helm install --namespace --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --values my_values.yaml + ``` diff --git a/docs/source/routing/self-hosted/containerization/kubernetes/other-considerations.mdx b/docs/source/routing/self-hosted/containerization/kubernetes/other-considerations.mdx new file mode 100644 index 0000000000..6304bd3e31 --- /dev/null +++ b/docs/source/routing/self-hosted/containerization/kubernetes/other-considerations.mdx @@ -0,0 +1,54 @@ +--- +title: Other considerations for hosting the router in Kubernetes +subtitle: Learn about other considerations for hosting the router in Kubernetes, including Istio and resources +description: Other considerations for hosting the router in Kubernetes. +--- + +import ElasticNotice from '../../../../shared/elastic-notice.mdx'; + + + +There are a few other considerations to keep in mind when hosting the router in Kubernetes. These include: + +* [Using Istio](#deploying-in-kubernetes-with-istio) +* [Troubleshooting a hosted router](#troubleshooting-a-hosted-router) + +## Deploying in Kubernetes with Istio + +[Istio](https://istio.io/) is a service mesh for Kubernetes which is often installed on a cluster for its traffic-shaping abilities. While Apollo dopes not specifically recommend or support Istio, nor does Apollo provide specific instructions for installing the Router in a cluster with Istio, there is a known consideration to make when configuring Istio. + +Consideration and additional configuration may be necessary as a consequence of how Istio does its sidecar injection. Without additional configuration, Istio may attempt to reconfigure the network interface at the same time the router is starting, which will result in a failure to start. + +This is not specifically a router issue and Istio has instructions on how to manage the matter in a general sense in their [own documentation](https://istio.io/latest/docs/ops/common-problems/injection/#pod-or-containers-start-with-network-issues-if-istio-proxy-is-not-ready). Their suggestion prevents the startup of all other containers in a pod until Istio itself is ready. Apollo recommends this approach when using Istio. + +## Troubleshooting a hosted router + + + +To manage the system resources you need to deploy the router on Kubernetes: + +* Read [Managing router resources in Kubernetes](/technotes/TN0016-router-resource-management/). +* Use the [router resource estimator](/technotes/TN0045-router_resource_estimator/). + + + +### Pods terminating due to memory pressure + +If your deployment of routers is terminating due to memory pressure, you can add router cache metrics to monitor and remediate your system: + +1. Add and track the following metrics to your monitoring system: + + * `apollo.router.cache.storage.estimated_size` + * `apollo.router.cache.size` + * ratio of `apollo.router.cache.hit.time.count` to `apollo.router.cache.miss.time.count` + +2. Observe and monitor the metrics: + + * Observe the `apollo.router.cache.storage.estimated_size` to see if it grows over time and correlates with pod memory usage. + * Observe the ratio of cache hits to misses to determine if the cache is being effective. + +3. Based on your observations, try some remediating adjustments: + + * Lower the cache size if the cache reaches near 100% hit-rate but the cache size is still growing. + * Increase the pod memory if the cache hit rate is low and the cache size is still growing. + * Lower the cache size if the latency of query planning cache misses is acceptable and memory availability is limited. diff --git a/docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx b/docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx new file mode 100644 index 0000000000..6794e1a561 --- /dev/null +++ b/docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx @@ -0,0 +1,131 @@ +--- +title: Kubernetes quickstaart +subtitle: Learn how to deploy a self-hosted router (GraphOS Router or Apollo Router Core) in Kubernetes using Helm charts +description: Deploy the Apollo GraphOS Router or Apollo Router Core in Kubernetes using Helm charts. Customize configurations, enable metrics, and choose values for migration. +--- + +import ElasticNotice from '../../../../shared/elastic-notice.mdx'; +import HelmShowOutput from '../../../../shared/helm-show-router-output.mdx'; +import CoprocTypicalConfig from '../../../../shared/coproc-typical-config.mdx'; + +The following guide provide the steps to: + +* Get the router Helm chart from the Apollo container repository. +* Deploy a router with a basic Helm chart. +* Configure chart values to export metrics, enable Rhai scripting, and deploy a coprocessor. +* Choose chart values that best suit migration from a gateway to the router. + + + +## Prerequisites + + + +This guide assumes you are familiar with Kubernetes and Helm. If you are not familiar with either, you can find a [Kubernetes tutorial](https://kubernetes.io/docs/tutorials/) and a [Helm tutorial](https://helm.sh/docs/intro/quickstart/) to get started. + + + +* A GraphOS graph set up in your Apollo account. If you don't have a graph, you can create one in the [Apollo Studio](https://studio.apollographql.com/). +* [Helm](https://helm.sh/docs/intro/install/) **version 3.x or higher** installed on your local machine. +* A Kubernetes cluster with access to the internet. + +### GraphOS graph + +Set up your self-hosted graph and get its [graph ref](/router/configuration/overview/#apollo_graph_ref) and [API key](/router/configuration/overview/#apollo_graph_ref). + +If you need a guide to set up your graph, you can follow [the self-hosted router quickstart](/graphos/quickstart/self-hosted) and complete [step 1 (Set up Apollo tools)](/graphos/quickstart/self-hosted/#1-set-up-apollo-tools), [step 4 (Obtain your subgraph schemas)](/graphos/quickstart/self-hosted/#4-obtain-your-subgraph-schemas), and [step 5 (Publish your subgraph schemas)](/graphos/quickstart/self-hosted/#5-publish-your-subgraph-schemas). + +### Kubernetes cluster + +If you don't have a Kubernetes cluster, you can set one up using [kind](https://kind.sigs.k8s.io/) or [minikube](https://minikube.sigs.k8s.io/docs/) locally, or by referring to your cloud provider's documentation. + +## Quickstart + +To deploy the router, run the `helm install` command with an argument for the OCI image in the container repository. Optionally, you can add arguments for the `values.yaml` configuration file and/or additional arguments to override specific configuration values. + +```bash +helm install --namespace apollo-router --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router +``` + +The necessary arguments for specific configuration values: + +* `--set managedFederation.graphRef=""`. The reference to your managed graph (`id@variant`), the same value as the [`APOLLO_GRAPH_REF` environment variable](/router/configuration/overview/#apollo_graph_ref). +* `--set managedFederation.apiKey=""`. The API key to your managed graph, the same value as the [`APOLLO_KEY` environment variable](/router/configuration/overview/#apollo_key). + +Some optional but recommended arguments: + +* `--namespace `. The namespace scope for this deployment. +* `--version `. The version of the router to deploy. If not specified by `helm install`, the latest version is installed. + +### Verify deployment + +Verify that your router is one of the deployed releases with the `helm list` command. If you deployed with the `--namespace ` option, you can list only the releases within your namespace: + +```bash +helm list --namespace +``` +## Deployed architecture + +The default deployed architecture will be (when using a coprocessor): + +```mermaid +flowchart LR; + clients(Clients); + subgraph "Kubernetes cluster"; + lb(["Load Balancer"]) + router_a(["Router"]); + coproc_a(["Coprocessor"]); + router_b(["Router"]); + coproc_b(["Coprocessor"]); + router_a <-.-> coproc_a; + router_b <-.-> coproc_b; + end; + clients -.->|Query| lb; + lb -.-> router_a & router_b; + class clients secondary; +``` + +## Router Helm chart configuration + + Apollo provides an application Helm chart with each release of Apollo Router Core in GitHub. Since the router version v0.14.0, Apollo has released the router Helm chart as an [Open Container Initiative (OCI)](https://helm.sh/docs/topics/registries/) image in the GitHub container registry. + + + +The path to the OCI router chart is `oci://ghcr.io/apollographql/helm-charts/router` and tagged with the applicable router release version. For example, router version `v.2.2.1`'s Helm chart would be `oci://ghcr.io/apollographql/helm-charts/router:2.2.1`. + + + +You customize a deployed router with the same [command-line options and YAML configuration options](/router/configuration/overview) using different Helm CLI options and YAML keys through a [values file](https://helm.sh/docs/chart_template_guide/values_files/). + +Each router chart has a defult `values.yaml` file with router and deployment settings. The released, unedited file has a few explicit settings, including: + +* Default container ports for the router's [HTTP server](/router/configuration/overview/#listen-address), [health check endpoint](/router/configuration/health-checks), and [metrics endpoint](/router/configuration/telemetry/exporters/metrics/overview). +* A command-line argument to enable [hot reloading of the router](/router/configuration/overview/#--hr----hot-reload). +* A single replica. + + + +The values of the Helm chart for Apollo Router Core v2.2.1 in the GitHub container repository, as output by the `helm show` command: + +```bash +helm show values oci://ghcr.io/apollographql/helm-charts/router +``` + + + + + +## Separate configurations per environment + +To support your different deployment configurations for different environments (development, staging, production, etc.), Apollo recommends separating your configuration values into separate files: + +- A **common** file, which contains values that apply across all environments. +- A unique **environment** file per environment, which includes and overrides the values from the common file while adding new environment-specific values. + +The `helm install` command applies each `--values ` option in the order you set them within the command. Therefore, a common file must be set before an environment file so that the environment file's values are applied last and override the common file's values. + +For example, this command deploys with a `common_values.yaml` file applied first and then a `prod_values.yaml` file: + +```bash +helm install --namespace --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --values common_values.yaml --values prod_values.yaml +``` \ No newline at end of file From 37cbcf70ab6e2ca838035682286bf736cd20d423 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Mon, 19 May 2025 16:29:54 -0600 Subject: [PATCH 5/7] Delete duplicates --- .../self-hosted/kubernetes/extensibility.mdx | 138 ------------------ .../self-hosted/kubernetes/metrics.mdx | 46 ------ .../kubernetes/other-considerations.mdx | 54 ------- .../self-hosted/kubernetes/quickstart.mdx | 131 ----------------- 4 files changed, 369 deletions(-) delete mode 100644 docs/source/routing/self-hosted/kubernetes/extensibility.mdx delete mode 100644 docs/source/routing/self-hosted/kubernetes/metrics.mdx delete mode 100644 docs/source/routing/self-hosted/kubernetes/other-considerations.mdx delete mode 100644 docs/source/routing/self-hosted/kubernetes/quickstart.mdx diff --git a/docs/source/routing/self-hosted/kubernetes/extensibility.mdx b/docs/source/routing/self-hosted/kubernetes/extensibility.mdx deleted file mode 100644 index 4dbc7a743e..0000000000 --- a/docs/source/routing/self-hosted/kubernetes/extensibility.mdx +++ /dev/null @@ -1,138 +0,0 @@ ---- -title: Using router extensibility features in Kubernetes -subtitle: Learn how to deploy a self-hosted router (GraphOS Router or Apollo Router Core) in Kubernetes with extensibility features -description: How to deploy the Apollo GraphOS Router or Apollo Router Core in Kubernetes with extensibility features. ---- - -import ElasticNotice from '../../../../shared/elastic-notice.mdx'; - - - -The router supports two extensibility options to customize the router's behavior. The extensibility features are: - -- [Rhai scripting](/graphos/routing/customization/rhai) -- [External coprocessors](/router/customizations/coprocessor) - -## Deploy with Rhai scripts - -The router supports [Rhai scripting](/graphos/routing/customization/rhai) to add custom functionality. - -Enabling Rhai scripts in your deployed router requires mounting an extra volume for your Rhai scripts and getting your scripts onto the volume. That can be done by following steps in [a separate example for creating a custom in-house router chart](https://github.com/apollographql/in-house-router-example). The example creates a new (in-house) chart that depends on the released router chart, and the new chart has templates that add the necessary configuration to allow Rhai scripts for a deployed router. - - - Ideally this would a separate example fully within the docs, however the `in-house-router-example` is public and the example is a good one so it isn't worth duplicating the effort as of now. - - -## Deploying with a coprocessor - -You have two options to consider when deploying a coprocessor. - -* [Deploy as a sidecar container](#deploy-as-a-sidecar-container) -* [Deploy as a separate Kubernetes `Deployment`](#deploying-using-a-separate-deployment) - -Consider the following when deciding which option to use: - -* The sidecar container option is the simplest and most common way to deploy a coprocessor. It allows you to run the coprocessor in the same pod as the router, which can simplify networking and configuration. -* The separate `Deployment` option allows you to run the coprocessor in a different pod, which can be useful if you want to scale the coprocessor independently of the router. - -### Deploy as a sidecar container - -The router supports [external coprocessing](/router/customizations/coprocessor) to run custom logic on requests throughout the [router's request-handling lifecycle](/graphos/routing/customization/rhai/#router-request-lifecycle). - -A deployed coprocessor can have its own application image and container in the router pod. - -To configure a coprocessor and its container for your deployed router through a YAML configuration file: - -1. Create a YAML file, `coprocessor_values.yaml`, to contain additional values that override default values. -1. Edit `coprocessor_values.yaml` to configure a coprocessor for the router. For reference, follow the [typical](/router/customizations/coprocessor#typical-configuration) and [minimal](/router/customizations/coprocessor#minimal-configuration) configuration examples, and apply them to `router.configuration.coprocessor`. - - - - - - - -1. Edit `coprocessor_values.yaml` to add a container for the coprocessor. - - ```yaml title="coprocessor_values.yaml" - extraContainers: - - name: # name of deployed container - image: # name of application image - ports: - - containerPort: # must match port of router.configuration.coprocessor.url - env: [] # array of environment variables - ``` - -1. Deploy the router with the additional YAML configuration file. For example, starting with the `helm install` command from the basic deployment step, append `--values coprocessor_values.yaml`: - - ```bash - helm install --namespace --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --values coprocessor_values.yaml - ``` - -### Deploying using a separate `Deployment` - -Deploying as a separate `Deployment` can take shape in two ways: - -* Using an entirely separate Helm chart. -* Using the router's Helm chart as a dependency and adding a new `Deployment` template - * This option is more complex but allows you to customize the router's Helm chart and add your own templates whilst keeping the coporcessor's deployment alongside the router's. - -#### Separate Helm chart - -In the case of using a separate Helm chart, a `coprocessor` chart would be deployed independently of the router. This chart would contain the configuration for the coprocessor's deployment. An example folder structure might look like: - -``` -charts/ -├── coprocessor/ -│ ├── Chart.yaml -│ ├── values.yaml -│ ├── templates/ -│ │ ├── deployment.yaml -│ │ ├── service.yaml -│ │ └── ... -│ └── ... -├── router/ -│ ├── values.yaml -│ └── ... -``` - - -The `router` chart would be the router's Helm chart, which you can deploy as described in the [Kubernetes deployment guide](/graphos/routing/kubernetes/quickstart). - -#### Using the router's Helm chart as a dependency - -In the case of using the router's Helm chart as a dependency, you can create a new template in the `templates` folder of the `router` Helm chart. This template would contain the configuration for the coprocessor's deployment. - -The `Chart.yaml` file for the router would include: - -```yaml -dependencies: - - name: router - version: 2.2.1 - repository: oci://ghcr.io/apollographql/helm-charts -``` - -An example folder structure might look like: - -``` -charts/ -├── router/ -│ ├── Chart.yaml -│ ├── values.yaml -│ ├── templates/ -│ │ ├── deployment.yaml -│ │ ├── service.yaml -│ │ └── ... -│ └── ... -``` - -In the above example, the `router` chart would be the router's Helm chart, which you can deploy as described in the [Kubernetes deployment guide](/graphos/routing/kubernetes/quickstart). The `templates` folder would contain the configuration for the coprocessor's deployment. Within the `values.yaml` you can then nest the necessary configuration under the `router` key, such as: - -```values.yaml -router: - configuration: - coprocessor: - url: http://: -``` - - diff --git a/docs/source/routing/self-hosted/kubernetes/metrics.mdx b/docs/source/routing/self-hosted/kubernetes/metrics.mdx deleted file mode 100644 index a9be29111d..0000000000 --- a/docs/source/routing/self-hosted/kubernetes/metrics.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Metrics endpoints -subtitle: Learn how to use a self-hosted router (GraphOS Router or Apollo Router Core) in Kubernetes with metrics endpoints -description: Use the Apollo GraphOS Router or Apollo Router Core in Kubernetes with metrics endpoints and considerations when doing so. ---- - -import ElasticNotice from '../../../../shared/elastic-notice.mdx'; - - - -The router supports [metrics endpoints for Prometheus and OpenTelemetry protocol (OTLP)](/router/configuration/telemetry/exporters/metrics/overview). The default deployment doesn't enable metrics endpoints because the router chart disables both Prometheus (explicitly) and OTLP (by omission). - -To enable metrics endpoints in your deployed router through a YAML configuration file: - -1. Create a YAML file, `my_values.yaml`, to contain additional values that override default values. -1. Edit `my_values.yaml` to enable metrics endpoints: - - ```yaml title="my_values.yaml" - router: - configuration: - telemetry: - metrics: - prometheus: - enabled: true - listen: 0.0.0.0:9090 - path: "/metrics" - otlp: - temporality: cumulative # default; if using DataDog, use temporality: delta - endpoint: - ``` - - - - Although this example enables both Prometheus and OTLP, in practice it's common to enable only one endpoint. - - - - * `router.configuration.telemetry.metrics.prometheus` was already configured but disabled (`enabled: false`) by default. This configuration sets `enabled: true`. - * `router.configuration.telemetry.metrics.otlp` is enabled by inclusion. - * `router.configuration.telemetry.temporality` by default is `temporality: cumulative` and is a good choice for most metrics consumers. For DataDog, use `temporality: delta`. - -1. Deploy the router with the additional YAML configuration file. For example, starting with the `helm install` command from the basic deployment step, append `--values my_values.yaml`: - - ```bash - helm install --namespace --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --values my_values.yaml - ``` diff --git a/docs/source/routing/self-hosted/kubernetes/other-considerations.mdx b/docs/source/routing/self-hosted/kubernetes/other-considerations.mdx deleted file mode 100644 index 6304bd3e31..0000000000 --- a/docs/source/routing/self-hosted/kubernetes/other-considerations.mdx +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Other considerations for hosting the router in Kubernetes -subtitle: Learn about other considerations for hosting the router in Kubernetes, including Istio and resources -description: Other considerations for hosting the router in Kubernetes. ---- - -import ElasticNotice from '../../../../shared/elastic-notice.mdx'; - - - -There are a few other considerations to keep in mind when hosting the router in Kubernetes. These include: - -* [Using Istio](#deploying-in-kubernetes-with-istio) -* [Troubleshooting a hosted router](#troubleshooting-a-hosted-router) - -## Deploying in Kubernetes with Istio - -[Istio](https://istio.io/) is a service mesh for Kubernetes which is often installed on a cluster for its traffic-shaping abilities. While Apollo dopes not specifically recommend or support Istio, nor does Apollo provide specific instructions for installing the Router in a cluster with Istio, there is a known consideration to make when configuring Istio. - -Consideration and additional configuration may be necessary as a consequence of how Istio does its sidecar injection. Without additional configuration, Istio may attempt to reconfigure the network interface at the same time the router is starting, which will result in a failure to start. - -This is not specifically a router issue and Istio has instructions on how to manage the matter in a general sense in their [own documentation](https://istio.io/latest/docs/ops/common-problems/injection/#pod-or-containers-start-with-network-issues-if-istio-proxy-is-not-ready). Their suggestion prevents the startup of all other containers in a pod until Istio itself is ready. Apollo recommends this approach when using Istio. - -## Troubleshooting a hosted router - - - -To manage the system resources you need to deploy the router on Kubernetes: - -* Read [Managing router resources in Kubernetes](/technotes/TN0016-router-resource-management/). -* Use the [router resource estimator](/technotes/TN0045-router_resource_estimator/). - - - -### Pods terminating due to memory pressure - -If your deployment of routers is terminating due to memory pressure, you can add router cache metrics to monitor and remediate your system: - -1. Add and track the following metrics to your monitoring system: - - * `apollo.router.cache.storage.estimated_size` - * `apollo.router.cache.size` - * ratio of `apollo.router.cache.hit.time.count` to `apollo.router.cache.miss.time.count` - -2. Observe and monitor the metrics: - - * Observe the `apollo.router.cache.storage.estimated_size` to see if it grows over time and correlates with pod memory usage. - * Observe the ratio of cache hits to misses to determine if the cache is being effective. - -3. Based on your observations, try some remediating adjustments: - - * Lower the cache size if the cache reaches near 100% hit-rate but the cache size is still growing. - * Increase the pod memory if the cache hit rate is low and the cache size is still growing. - * Lower the cache size if the latency of query planning cache misses is acceptable and memory availability is limited. diff --git a/docs/source/routing/self-hosted/kubernetes/quickstart.mdx b/docs/source/routing/self-hosted/kubernetes/quickstart.mdx deleted file mode 100644 index 6794e1a561..0000000000 --- a/docs/source/routing/self-hosted/kubernetes/quickstart.mdx +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Kubernetes quickstaart -subtitle: Learn how to deploy a self-hosted router (GraphOS Router or Apollo Router Core) in Kubernetes using Helm charts -description: Deploy the Apollo GraphOS Router or Apollo Router Core in Kubernetes using Helm charts. Customize configurations, enable metrics, and choose values for migration. ---- - -import ElasticNotice from '../../../../shared/elastic-notice.mdx'; -import HelmShowOutput from '../../../../shared/helm-show-router-output.mdx'; -import CoprocTypicalConfig from '../../../../shared/coproc-typical-config.mdx'; - -The following guide provide the steps to: - -* Get the router Helm chart from the Apollo container repository. -* Deploy a router with a basic Helm chart. -* Configure chart values to export metrics, enable Rhai scripting, and deploy a coprocessor. -* Choose chart values that best suit migration from a gateway to the router. - - - -## Prerequisites - - - -This guide assumes you are familiar with Kubernetes and Helm. If you are not familiar with either, you can find a [Kubernetes tutorial](https://kubernetes.io/docs/tutorials/) and a [Helm tutorial](https://helm.sh/docs/intro/quickstart/) to get started. - - - -* A GraphOS graph set up in your Apollo account. If you don't have a graph, you can create one in the [Apollo Studio](https://studio.apollographql.com/). -* [Helm](https://helm.sh/docs/intro/install/) **version 3.x or higher** installed on your local machine. -* A Kubernetes cluster with access to the internet. - -### GraphOS graph - -Set up your self-hosted graph and get its [graph ref](/router/configuration/overview/#apollo_graph_ref) and [API key](/router/configuration/overview/#apollo_graph_ref). - -If you need a guide to set up your graph, you can follow [the self-hosted router quickstart](/graphos/quickstart/self-hosted) and complete [step 1 (Set up Apollo tools)](/graphos/quickstart/self-hosted/#1-set-up-apollo-tools), [step 4 (Obtain your subgraph schemas)](/graphos/quickstart/self-hosted/#4-obtain-your-subgraph-schemas), and [step 5 (Publish your subgraph schemas)](/graphos/quickstart/self-hosted/#5-publish-your-subgraph-schemas). - -### Kubernetes cluster - -If you don't have a Kubernetes cluster, you can set one up using [kind](https://kind.sigs.k8s.io/) or [minikube](https://minikube.sigs.k8s.io/docs/) locally, or by referring to your cloud provider's documentation. - -## Quickstart - -To deploy the router, run the `helm install` command with an argument for the OCI image in the container repository. Optionally, you can add arguments for the `values.yaml` configuration file and/or additional arguments to override specific configuration values. - -```bash -helm install --namespace apollo-router --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router -``` - -The necessary arguments for specific configuration values: - -* `--set managedFederation.graphRef=""`. The reference to your managed graph (`id@variant`), the same value as the [`APOLLO_GRAPH_REF` environment variable](/router/configuration/overview/#apollo_graph_ref). -* `--set managedFederation.apiKey=""`. The API key to your managed graph, the same value as the [`APOLLO_KEY` environment variable](/router/configuration/overview/#apollo_key). - -Some optional but recommended arguments: - -* `--namespace `. The namespace scope for this deployment. -* `--version `. The version of the router to deploy. If not specified by `helm install`, the latest version is installed. - -### Verify deployment - -Verify that your router is one of the deployed releases with the `helm list` command. If you deployed with the `--namespace ` option, you can list only the releases within your namespace: - -```bash -helm list --namespace -``` -## Deployed architecture - -The default deployed architecture will be (when using a coprocessor): - -```mermaid -flowchart LR; - clients(Clients); - subgraph "Kubernetes cluster"; - lb(["Load Balancer"]) - router_a(["Router"]); - coproc_a(["Coprocessor"]); - router_b(["Router"]); - coproc_b(["Coprocessor"]); - router_a <-.-> coproc_a; - router_b <-.-> coproc_b; - end; - clients -.->|Query| lb; - lb -.-> router_a & router_b; - class clients secondary; -``` - -## Router Helm chart configuration - - Apollo provides an application Helm chart with each release of Apollo Router Core in GitHub. Since the router version v0.14.0, Apollo has released the router Helm chart as an [Open Container Initiative (OCI)](https://helm.sh/docs/topics/registries/) image in the GitHub container registry. - - - -The path to the OCI router chart is `oci://ghcr.io/apollographql/helm-charts/router` and tagged with the applicable router release version. For example, router version `v.2.2.1`'s Helm chart would be `oci://ghcr.io/apollographql/helm-charts/router:2.2.1`. - - - -You customize a deployed router with the same [command-line options and YAML configuration options](/router/configuration/overview) using different Helm CLI options and YAML keys through a [values file](https://helm.sh/docs/chart_template_guide/values_files/). - -Each router chart has a defult `values.yaml` file with router and deployment settings. The released, unedited file has a few explicit settings, including: - -* Default container ports for the router's [HTTP server](/router/configuration/overview/#listen-address), [health check endpoint](/router/configuration/health-checks), and [metrics endpoint](/router/configuration/telemetry/exporters/metrics/overview). -* A command-line argument to enable [hot reloading of the router](/router/configuration/overview/#--hr----hot-reload). -* A single replica. - - - -The values of the Helm chart for Apollo Router Core v2.2.1 in the GitHub container repository, as output by the `helm show` command: - -```bash -helm show values oci://ghcr.io/apollographql/helm-charts/router -``` - - - - - -## Separate configurations per environment - -To support your different deployment configurations for different environments (development, staging, production, etc.), Apollo recommends separating your configuration values into separate files: - -- A **common** file, which contains values that apply across all environments. -- A unique **environment** file per environment, which includes and overrides the values from the common file while adding new environment-specific values. - -The `helm install` command applies each `--values ` option in the order you set them within the command. Therefore, a common file must be set before an environment file so that the environment file's values are applied last and override the common file's values. - -For example, this command deploys with a `common_values.yaml` file applied first and then a `prod_values.yaml` file: - -```bash -helm install --namespace --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --values common_values.yaml --values prod_values.yaml -``` \ No newline at end of file From e990d234df221ddb74fdc61d84e33d5effec401e Mon Sep 17 00:00:00 2001 From: Lucas Leadbetter <5595530+lleadbet@users.noreply.github.com> Date: Tue, 20 May 2025 11:37:26 -0500 Subject: [PATCH 6/7] pathing updates --- .../containerization/kubernetes/extensibility.mdx | 2 -- .../self-hosted/containerization/kubernetes/metrics.mdx | 2 -- .../containerization/kubernetes/other-considerations.mdx | 2 -- .../self-hosted/containerization/kubernetes/quickstart.mdx | 5 ++--- 4 files changed, 2 insertions(+), 9 deletions(-) diff --git a/docs/source/routing/self-hosted/containerization/kubernetes/extensibility.mdx b/docs/source/routing/self-hosted/containerization/kubernetes/extensibility.mdx index 4dbc7a743e..0616a8ae0f 100644 --- a/docs/source/routing/self-hosted/containerization/kubernetes/extensibility.mdx +++ b/docs/source/routing/self-hosted/containerization/kubernetes/extensibility.mdx @@ -4,8 +4,6 @@ subtitle: Learn how to deploy a self-hosted router (GraphOS Router or Apollo Rou description: How to deploy the Apollo GraphOS Router or Apollo Router Core in Kubernetes with extensibility features. --- -import ElasticNotice from '../../../../shared/elastic-notice.mdx'; - The router supports two extensibility options to customize the router's behavior. The extensibility features are: diff --git a/docs/source/routing/self-hosted/containerization/kubernetes/metrics.mdx b/docs/source/routing/self-hosted/containerization/kubernetes/metrics.mdx index a9be29111d..bd5a280052 100644 --- a/docs/source/routing/self-hosted/containerization/kubernetes/metrics.mdx +++ b/docs/source/routing/self-hosted/containerization/kubernetes/metrics.mdx @@ -4,8 +4,6 @@ subtitle: Learn how to use a self-hosted router (GraphOS Router or Apollo Router description: Use the Apollo GraphOS Router or Apollo Router Core in Kubernetes with metrics endpoints and considerations when doing so. --- -import ElasticNotice from '../../../../shared/elastic-notice.mdx'; - The router supports [metrics endpoints for Prometheus and OpenTelemetry protocol (OTLP)](/router/configuration/telemetry/exporters/metrics/overview). The default deployment doesn't enable metrics endpoints because the router chart disables both Prometheus (explicitly) and OTLP (by omission). diff --git a/docs/source/routing/self-hosted/containerization/kubernetes/other-considerations.mdx b/docs/source/routing/self-hosted/containerization/kubernetes/other-considerations.mdx index 6304bd3e31..a6d0474969 100644 --- a/docs/source/routing/self-hosted/containerization/kubernetes/other-considerations.mdx +++ b/docs/source/routing/self-hosted/containerization/kubernetes/other-considerations.mdx @@ -4,8 +4,6 @@ subtitle: Learn about other considerations for hosting the router in Kubernetes, description: Other considerations for hosting the router in Kubernetes. --- -import ElasticNotice from '../../../../shared/elastic-notice.mdx'; - There are a few other considerations to keep in mind when hosting the router in Kubernetes. These include: diff --git a/docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx b/docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx index 6794e1a561..0f1f9ab62c 100644 --- a/docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx +++ b/docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx @@ -4,9 +4,8 @@ subtitle: Learn how to deploy a self-hosted router (GraphOS Router or Apollo Rou description: Deploy the Apollo GraphOS Router or Apollo Router Core in Kubernetes using Helm charts. Customize configurations, enable metrics, and choose values for migration. --- -import ElasticNotice from '../../../../shared/elastic-notice.mdx'; -import HelmShowOutput from '../../../../shared/helm-show-router-output.mdx'; -import CoprocTypicalConfig from '../../../../shared/coproc-typical-config.mdx'; +import HelmShowOutput from '../../../../../shared/helm-show-router-output.mdx'; +import CoprocTypicalConfig from '../../../../../shared/coproc-typical-config.mdx'; The following guide provide the steps to: From 45b491656ac391d2bc3d8b94b484355c353ab75f Mon Sep 17 00:00:00 2001 From: Lucas Leadbetter <5595530+lleadbet@users.noreply.github.com> Date: Wed, 21 May 2025 09:47:51 -0400 Subject: [PATCH 7/7] Update docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx Co-authored-by: Gary Pennington --- .../self-hosted/containerization/kubernetes/quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx b/docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx index 0f1f9ab62c..3f1abbfe00 100644 --- a/docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx +++ b/docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx @@ -1,5 +1,5 @@ --- -title: Kubernetes quickstaart +title: Kubernetes quickstart subtitle: Learn how to deploy a self-hosted router (GraphOS Router or Apollo Router Core) in Kubernetes using Helm charts description: Deploy the Apollo GraphOS Router or Apollo Router Core in Kubernetes using Helm charts. Customize configurations, enable metrics, and choose values for migration. ---