From 0755ced4fa808c8fbbadfd6983b8b6f227eb6d11 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Fri, 29 Sep 2023 16:55:47 -0700 Subject: [PATCH 01/21] WIP: add router helm and k8s deployment content from dogfooding --- docs/shared/helm-show-router-output.mdx | 238 ++++++++++++++ docs/shared/k8s-manual-config.mdx | 185 +++++++++++ docs/shared/router-common-config.mdx | 210 ++++++++++++ docs/source/config.json | 4 +- docs/source/containerization/docker.mdx | 9 +- docs/source/containerization/kubernetes.mdx | 338 ++++++++------------ docs/source/containerization/overview.mdx | 19 +- docs/source/migrating-from-gateway.mdx | 13 +- 8 files changed, 790 insertions(+), 226 deletions(-) create mode 100644 docs/shared/helm-show-router-output.mdx create mode 100644 docs/shared/k8s-manual-config.mdx create mode 100644 docs/shared/router-common-config.mdx diff --git a/docs/shared/helm-show-router-output.mdx b/docs/shared/helm-show-router-output.mdx new file mode 100644 index 0000000000..90516afd68 --- /dev/null +++ b/docs/shared/helm-show-router-output.mdx @@ -0,0 +1,238 @@ +```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 +router: + configuration: + supergraph: + listen: 0.0.0.0:80 + health_check: + listen: 0.0.0.0:8088 + telemetry: + metrics: + prometheus: + enabled: false + listen: 0.0.0.0:9090 + path: "/metrics" + + args: + - --hot-reload + +managedFederation: + # -- If using managed federation, the graph API key to identify router to Studio + apiKey: + # -- 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 variant of which graph to use + graphRef: "" + +# This should not be specified in values.yaml. It's much simpler to use --set-file from helm command line. +# e.g.: helm ... --set-file supergraphFile="location of your supergraph file" +supergraphFile: + +# An array of extra environmental variables +# Example: +# extraEnvVars: +# - name: APOLLO_ROUTER_SUPERGRAPH_PATH +# value: /etc/apollo/supergraph.yaml +# - name: APOLLO_ROUTER_LOG +# value: debug +# +extraEnvVars: [] +extraEnvVarsCM: '' +extraEnvVarsSecret: '' + +# An array of extra VolumeMounts +# Example: +# extraVolumeMounts: +# - name: rhai-volume +# mountPath: /dist/rhai +# readonly: true +extraVolumeMounts: [] + +# An array of extra Volumes +# Example: +# extraVolumes: +# - name: rhai-volume +# configMap: +# name: rhai-config +# +extraVolumes: [] + +image: + repository: ghcr.io/apollographql/router + pullPolicy: IfNotPresent + # Overrides the image tag whose default is the chart appVersion. + tag: "" + +containerPorts: + # -- If you override the port in `router.configuration.server.listen` then make sure to match the listen port here + http: 80 + # -- For exposing the metrics port when running a serviceMonitor for example + metrics: 9090 + # -- For exposing the health check endpoint + health: 8088 + +# -- An array of extra containers to include in the router pod +# Example: +# extraContainers: +# - name: coprocessor +# image: acme/coprocessor:1.0 +# ports: +# - containerPort: 4001 +extraContainers: [] + +# -- An array of init containers to include in the router pod +# Example: +# initContainers: +# - name: init-myservice +# image: busybox:1.28 +# command: ["sh"] +initContainers: [] + +# -- A map of extra labels to apply to the resources created by this chart +# Example: +# extraLabels: +# label_one_name: "label_one_value" +# label_two_name: "label_two_value" +extraLabels: {} + +lifecycle: {} +# preStop: +# exec: +# command: +# - /bin/bash +# - -c +# - sleep 10 + +imagePullSecrets: [] +nameOverride: "" +fullnameOverride: "" + +serviceAccount: + # Specifies whether a service account should be created + create: true + # Annotations to add to the service account + annotations: {} + # The name of the service account to use. + # If not set and create is true, a name is generated using the fullname template + name: "" + +podAnnotations: {} + +podSecurityContext: {} + # fsGroup: 2000 + +securityContext: {} + # capabilities: + # drop: + # - ALL + # readOnlyRootFilesystem: true + # runAsNonRoot: true + # runAsUser: 1000 + +service: + type: ClusterIP + port: 80 + annotations: {} + +serviceMonitor: + enabled: false + +ingress: + enabled: false + className: "" + annotations: {} + # kubernetes.io/ingress.class: nginx + # kubernetes.io/tls-acme: "true" + hosts: + - host: chart-example.local + paths: + - path: / + pathType: ImplementationSpecific + tls: [] + # - secretName: chart-example-tls + # hosts: + # - chart-example.local + +# set to true to enable istio's virtualservice +virtualservice: + enabled: false + # namespace: "" + # gatewayName: "" + # http: + # main: + # # set enabled to true to add + # # the default matcher of `exact: "/" or prefix: "/graphql"` + # # with the <$fullName>.<.Release.Namespace>.svc.cluster.local destination + # enabled: true + # # use additionals to provide your custom virtualservice rules + # additionals: [] + # - name: "default-nginx-routes" + # match: + # - uri: + # prefix: "/foo" + # rewrite: + # uri: / + # route: + # - destination: + # host: my.custom.backend.svc.cluster.local + # port: + # number: 80 + +# set to true and provide configuration details if you want to make external https calls through istio's virtualservice +serviceentry: + enabled: false + # hosts: + # a list of external hosts you want to be able to make https calls to + # - api.example.com + +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 + # lines, adjust them as necessary, and remove the curly braces after 'resources:'. + # limits: + # cpu: 100m + # memory: 128Mi + # requests: + # cpu: 100m + # memory: 128Mi + +autoscaling: + enabled: false + minReplicas: 1 + maxReplicas: 100 + targetCPUUtilizationPercentage: 80 + # targetMemoryUtilizationPercentage: 80 + +nodeSelector: {} + +tolerations: [] + +affinity: {} + +# -- Sets the [pod disruption budget](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) for Deployment pods +podDisruptionBudget: {} + +# -- Set to existing PriorityClass name to control pod preemption by the scheduler +priorityClassName: "" + +# -- Sets the [termination grace period](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#hook-handler-execution) for Deployment pods +terminationGracePeriodSeconds: 30 + +probes: + # -- Configure readiness probe + readiness: + initialDelaySeconds: 0 + # -- Configure liveness probe + liveness: + initialDelaySeconds: 0 +``` diff --git a/docs/shared/k8s-manual-config.mdx b/docs/shared/k8s-manual-config.mdx new file mode 100644 index 0000000000..d5f0b4b430 --- /dev/null +++ b/docs/shared/k8s-manual-config.mdx @@ -0,0 +1,185 @@ +```yaml +--- +# Source: router/templates/serviceaccount.yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: release-name-router + labels: + helm.sh/chart: router-1.30.1 + app.kubernetes.io/name: router + app.kubernetes.io/instance: release-name + app.kubernetes.io/version: "v1.30.1" + app.kubernetes.io/managed-by: Helm +--- +# Source: router/templates/secret.yaml +apiVersion: v1 +kind: Secret +metadata: + name: "release-name-router" + labels: + helm.sh/chart: router-1.30.1 + app.kubernetes.io/name: router + app.kubernetes.io/instance: release-name + app.kubernetes.io/version: "v1.30.1" + app.kubernetes.io/managed-by: Helm +data: + managedFederationApiKey: "UkVEQUNURUQ=" +--- +# Source: router/templates/configmap.yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: release-name-router + labels: + helm.sh/chart: router-1.30.1 + app.kubernetes.io/name: router + app.kubernetes.io/instance: release-name + app.kubernetes.io/version: "v1.30.1" + app.kubernetes.io/managed-by: Helm +data: + configuration.yaml: | + health_check: + listen: 0.0.0.0:8088 + supergraph: + listen: 0.0.0.0:80 + telemetry: + metrics: + common: + resources: + service.name: release-name-router + prometheus: + enabled: true + listen: 0.0.0.0:9090 + path: /metrics +--- +# Source: router/templates/service.yaml +apiVersion: v1 +kind: Service +metadata: + name: release-name-router + labels: + helm.sh/chart: router-1.30.1 + app.kubernetes.io/name: router + app.kubernetes.io/instance: release-name + app.kubernetes.io/version: "v1.30.1" + app.kubernetes.io/managed-by: Helm +spec: + type: ClusterIP + ports: + - port: 80 + targetPort: http + protocol: TCP + name: http + - port: 8088 + targetPort: health + protocol: TCP + name: health + selector: + app.kubernetes.io/name: router + app.kubernetes.io/instance: release-name +--- +# Source: router/templates/deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: release-name-router + labels: + helm.sh/chart: router-1.30.1 + app.kubernetes.io/name: router + app.kubernetes.io/instance: release-name + app.kubernetes.io/version: "v1.30.1" + app.kubernetes.io/managed-by: Helm + + annotations: + prometheus.io/path: /metrics + prometheus.io/port: "9090" + prometheus.io/scrape: "true" +spec: + replicas: 1 + selector: + matchLabels: + app.kubernetes.io/name: router + app.kubernetes.io/instance: release-name + template: + metadata: + annotations: + kubectl.kubernetes.io/default-container: router + labels: + app.kubernetes.io/name: router + app.kubernetes.io/instance: release-name + spec: + serviceAccountName: release-name-router + securityContext: + {} + containers: + - name: router + securityContext: + {} + image: "ghcr.io/apollographql/router:v1.30.1" + imagePullPolicy: IfNotPresent + args: + - --hot-reload + - --config + - /app/configuration.yaml + env: + - name: APOLLO_KEY + valueFrom: + secretKeyRef: + name: "release-name-router" + key: managedFederationApiKey + optional: true + - name: APOLLO_GRAPH_REF + value: REDACTED + ports: + - name: http + containerPort: 80 + protocol: TCP + - name: health + containerPort: 8088 + protocol: TCP + lifecycle: + {} + livenessProbe: + httpGet: + path: "/health?live" + port: 8088 + initialDelaySeconds: 0 + readinessProbe: + httpGet: + path: "/health?ready" + port: 8088 + initialDelaySeconds: 0 + resources: + {} + volumeMounts: + - name: router-configuration + mountPath: /app/ + readOnly: true + volumes: + - name: router-configuration + configMap: + name: release-name-router + terminationGracePeriodSeconds: 30 +--- +# Source: router/templates/tests/test-connection.yaml +apiVersion: v1 +kind: Pod +metadata: + name: "release-name-router-test-connection" + labels: + helm.sh/chart: router-1.30.1 + app.kubernetes.io/name: router + app.kubernetes.io/instance: release-name + app.kubernetes.io/version: "v1.30.1" + app.kubernetes.io/managed-by: Helm + annotations: + "helm.sh/hook": test +spec: + containers: + - name: netcat + image: busybox + command: ['nc'] + args: ['-vz','-w','1','release-name-router:80'] + restartPolicy: Never +``` diff --git a/docs/shared/router-common-config.mdx b/docs/shared/router-common-config.mdx new file mode 100644 index 0000000000..4dda647bf1 --- /dev/null +++ b/docs/shared/router-common-config.mdx @@ -0,0 +1,210 @@ +```yaml +# Common values. Overridden by in-house configurations. +# This is a YAML-formatted file. +# Declare variables to be passed into your templates. + +# Anything we set here applies to the in-house-router chart, and +# all configuration that we set here is pushed to all sub-charts +# (because of the way Helm works: +# https://helm.sh/docs/chart_template_guide/subcharts_and_globals/) + +# Set fullnameOverride here for virtualservice to use +fullnameOverride: router + +router: + serviceAccount: + # We do that ourselves in permissions.yaml + create: false + name: router + fullnameOverride: router + router: + args: [--hot-reload] + configuration: + limits: + experimental_http_max_request_bytes: 20000000 #20MB + traffic_shaping: + router: + timeout: 6min + all: + experimental_enable_http2: false # to disable for all subgraphs + timeout: 5min + supergraph: + introspection: true + # We are intentionally DISABLING DEFER SUPPORT in the Router until + # we are out of our transition period from the Gateway to the Router. + defer_support: false + listen: 0.0.0.0:80 + path: /graphql + # We keep subgraph errors on in our own environment, always. + include_subgraph_errors: + all: true + cors: + allow_credentials: true + expose_headers: + - logged_in + - identity + headers: + all: + request: + - propagate: + named: "x-api-key" + - propagate: + named: "apollo-sudo" + - propagate: + named: "x-request-id" + - propagate: + named: "x-ot-span-context" + - propagate: + named: "x-cloud-trace-context" + - propagate: + named: "grpc-trace-bin" + subgraphs: + linter: + request: + - propagate: + named: apollographql-client-name + - propagate: + named: apollographql-client-version + - propagate: + named: apollo-client-name + - propagate: + named: apollo-client-version + kotlin: + request: + - propagate: + named: apollographql-client-name + - propagate: + named: apollographql-client-version + - propagate: + named: apollo-client-name + - propagate: + named: apollo-client-version + rhai: + scripts: /dist/rhai + main: in-house.rhai + telemetry: + apollo: + batch_processor: + # default 5s + scheduled_delay: 3s + # default 1 + max_concurrent_exports: 100 + max_export_batch_size: 512 + # default 30s + max_export_timeout: 10s + max_queue_size: 2048 + metrics: + prometheus: + enabled: false + otlp: + temporality: delta + endpoint: "${env.NODE_IP}:4317" + # Enabling this both includes the `apollo-trace-id` value on the HTTP response, + # but also creates "Response Header" nodes in the trace that we send to Studio. + # This should allow us to correlate traces from Studio to logs: + # https://www.apollographql.com/docs/router/configuration/tracing/#trace-id + tracing: + propagation: + zipkin: true + trace_context: true + experimental_response_trace_id: + enabled: true + coprocessor: + timeout: 3s + url: http://127.0.0.1:4001 + router: + request: + body: true + headers: true + method: true + path: true + response: + body: true + context: true + headers: true + status_code: true + subgraph: + all: + response: + headers: true + body: true + extraContainers: + - name: apilogger + image: "us-central1-docker.pkg.dev/platform-cross-environment/platform-docker/apilogger:{{ .Values.global.apilogger.release }}" + imagePullPolicy: IfNotPresent + ports: + - containerPort: 4001 + env: + - name: NODE_OPTIONS + value: "--max-old-space-size=768" + - name: NODE_ENV + value: production + - name: NODE_NAME + valueFrom: + fieldRef: + fieldPath: spec.nodeName + - name: POD_NAME + valueFrom: + fieldRef: + fieldPath: metadata.name + - name: STACK + value: "{{ .Values.global.apilogger.stack }}" + resources: + limits: + cpu: "1.5" + memory: 1Gi + requests: + cpu: "1" + memory: 1Gi + extraLabels: + tags.datadoghq.com/service: "router" + tags.datadoghq.com/version: "{{ .Chart.AppVersion | quote }}" + extraVolumeMounts: + - name: rhai-volume + mountPath: /dist/rhai + readOnly: true + extraVolumes: + - name: rhai-volume + configMap: + # Provide the name of the ConfigMap containing the files you want + # to add to the container + name: rhai-config + probes: + # -- Configure readiness probe + readiness: + initialDelaySeconds: 1 + # -- Configure liveness probe + liveness: + initialDelaySeconds: 1 + autoscaling: + enabled: true + minReplicas: 2 + maxReplicas: 12 + targetCPUUtilizationPercentage: 75 + affinity: + podAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 50 + podAffinityTerm: + labelSelector: + matchExpressions: + - key: app.kubernetes.io/name + operator: In + values: + - router-domain-ingress + - router-internal-domain-ingress + topologyKey: "kubernetes.io/hostname" + podAntiAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + podAffinityTerm: + labelSelector: + matchExpressions: + - key: app.kubernetes.io/name + operator: NotIn + values: + - router + topologyKey: "kubernetes.io/hostname" + podDisruptionBudget: + minAvailable: 2 +``` diff --git a/docs/source/config.json b/docs/source/config.json index 73d6f03a0c..350b6503d1 100644 --- a/docs/source/config.json +++ b/docs/source/config.json @@ -101,8 +101,8 @@ }, "Containerization": { "Overview": "/containerization/overview", - "Docker": "/containerization/docker", - "Kubernetes": "/containerization/kubernetes" + "Deploy on Kubernetes": "/containerization/kubernetes", + "Run with Docker": "/containerization/docker" }, "Managed Federation": { "Overview": "https://www.apollographql.com/docs/federation/managed-federation/overview", diff --git a/docs/source/containerization/docker.mdx b/docs/source/containerization/docker.mdx index ad0727adfe..f272063a2b 100644 --- a/docs/source/containerization/docker.mdx +++ b/docs/source/containerization/docker.mdx @@ -4,14 +4,15 @@ description: Using docker to run router images --- import { Link } from "gatsby"; +import ElasticNotice from '../../shared/elastic-notice.mdx'; -The default behaviour of the router images is suitable for a quickstart or development scenario. You'll need to know how to customize this default behaviour if you wish to do any of the following. + -> Note: The Apollo Router is made available under the Elastic License v2.0 (ELv2). Read [our licensing page](https://www.apollographql.com/docs/resources/elastic-license-v2-faq/) for more details. +The default behaviour of the router images is suitable for a quickstart or development scenario. You'll need to know how to customize this default behaviour if you wish to do any of the following. -Note: The [docker documentation](https://docs.docker.com/engine/reference/run/) for the run command may be helpful when reading through the examples. +The [docker documentation](https://docs.docker.com/engine/reference/run/) for the run command may be helpful when reading through the examples. -Note: The exact image version to use is your choice depending on which release you wish to use. In the following examples, replace `` with your chosen version. e.g.: `v1.30.1` +The exact image version to use is your choice depending on which release you wish to use. In the following examples, replace `` with your chosen version. e.g.: `v1.30.1` ## Override the configuration diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index a6722eef8b..d796d6dc3a 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -1,246 +1,157 @@ --- -title: Kubernetes and the router -description: Using router images with kubernetes +title: Deploy on Kubernetes +description: Self-hosted deployment of Apollo Router on Kubernetes --- import { Link } from 'gatsby'; +import ElasticNotice from '../../shared/elastic-notice.mdx'; +import HelmShowOutput from '../../shared/helm-show-router-output.mdx'; +import K8SManualConfig from '../../shared/k8s-manual-config.mdx'; +import RouterCommonConfig from '../../shared/router-common-config.mdx'; -## Sample Kubernetes Configuration + -> Note: The Apollo Router is made available under the Elastic License v2.0 (ELv2). This applies to its source code and all distributions, including versions installed via Helm charts. Read [our licensing page](https://www.apollographql.com/docs/resources/elastic-license-v2-faq/) for more details. +Learn about deploying a self-hosted supergraph with GraphOS and the Apollo Router on Kubernetes (k8s). Use Helm charts for the router, one with common configuration and another with custom, in-house configuration. -### Helm +This guide covers: -[Helm](https://helm.sh) is the package manager for kubernetes. +* Explaining the Helm chart for Apollo Router +* Setting up your cluster and self-hosted router +* Configuring the router Helm chart and installing the router package -There is a complete [helm chart definition](https://github.com/apollographql/router/tree/v1.30.1/helm/chart/router) in the repo which illustrates how to use helm to deploy the router in kubernetes. -In both the following examples, we are using helm to install the router: - - into namespace "router-deploy" (create namespace if it doesn't exist) - - with helm install name "router-test" - - with support for prometheus enabled +## About the router Helm chart -#### Using helm chart from our Open Container Initiative (OCI) registry +[Helm](https://helm.sh) is a package manager for Kubernetes. You create a Helm _chart_ to describe the resources in a package, then you install the chart with Helm to deploy the package on Kubernetes. -Starting with release 0.14.0, each time we release the router, we'll release -our helm chart and store it in the same OCI registry in which we store our -router docker images. +Apollo provides an application Helm chart with each release of Apollo Router in GitHub. The chart for the latest release of the router is available [here](https://github.com/apollographql/router/tree/v1.31.1/helm/chart/router). -You can use helm to install charts from an OCI registry as follows: +Since version 0.14.0 of the router, Apollo has also released a Helm chart for the router 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`. + +The released Helm chart sets specific values for the router, including: +* Coprocessor +* Header propagation +* Max request sizes +* Hot reload +* CORS +* Metrics and labels + + + +The values of the Helm chart for Apollo Router v1.31.0 in the GitHub container repository, as output by the `helm show` command: ```bash -helm install --set router.configuration.telemetry.metrics.prometheus.enabled=true --set managedFederation.apiKey="REDACTED" --set managedFederation.graphRef="REDACTED" --create-namespace --namespace router-deploy router-test oci://ghcr.io/apollographql/helm-charts/router --version 1.0.0-rc.8 --values router/values.yaml +helm show values oci://ghcr.io/apollographql/helm-charts/router ``` -For more details about using helm with OCI based registries, see [here](https://helm.sh/docs/topics/registries/) + -#### Using helm chart from your filesystem + -You would run this command from "repo"/helm/chart directory. +### Separate common and environment-specific configurations -(where "repo" is the directory containing your checked out router github repository) +To support different deployment configurations for different environments (development, staging, production, etc.), Apollo recommends separating your configuration values into separate Helm charts: -```bash -helm install --set router.configuration.telemetry.metrics.prometheus.enabled=true --set managedFederation.apiKey="REDACTED" --set managedFederation.graphRef="REDACTED" --create-namespace --namespace router-deploy router-test router --values router/values.yaml -``` +- A **common** chart, containing values that apply across all environments. +- Unique **environment** charts, each including the common chart and overriding common values with environment-specific values or adding new values. + + +## Deploy router with Helm + +### Install Helm + +* Install [Helm](https://helm.sh/docs/intro/install/) **version 3**. The Apollo Router's Helm chart requires Helm v3. + +> ⚠️ 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). + +### Set up cluster + +Install the tools and provision the infrastructure for your Kubernetes cluster. + +For example, see the [Setup from Apollo's Build a Supergraph tutorial](https://github.com/apollosolutions/build-a-supergraph/tree/main/01-setup#01---setup). It provides steps you can reference for gathering accounts and credentials for your cloud platform (GCP or AWS), provisioning resources, and deploying your subgraphs. + +(TODO: refine the steps between this #set-up-cluster and the next #set-up-self-hosted-router) + +### Set up self-hosted router + +Set up a self-hosted router by following the [first six steps of the self-hosted router quickstart](/graphos/quickstart/self-hosted), and stopping when you reach step [7. Deploy your router and connect clients](https://www.apollographql.com/docs/graphos/quickstart/self-hosted/#7-deploy-your-router-and-connect-clients). + +## Customize router charts + + + + + + + +(TODO: explain common config settings) + +## Install router Helm chart + +You can install the router chart from either a local repository or the container registry. + +### Install chart from container registry + +* Login to the container registry by following the guide to [authenticating to the GitHub container registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry). + +* After logging in, verify your access to the registry by showing the latest router chart from `helm`: -Once executed, you can check the status of the helm deploy: + ```bash + helm show values oci://ghcr.io/apollographql/helm-charts/router + ``` + +* Install the OCI image from the GiHub container registry: + + ```bash title="OCI registry" + helm install --set router.configuration.telemetry.metrics.prometheus.enabled=true --set managedFederation.apiKey="" --set managedFederation.graphRef="" --create-namespace --namespace router-deploy router-test oci://ghcr.io/apollographql/helm-charts/router --version 1.0.0-rc.8 --values router/values.yaml + ``` + +### Install Helm chart from local repository + +* Clone the [router repository](https://github.com/apollographql/router). + +* Change to the directory in your local repo with the router chart: + + ```bash + cd /helm/chart + ``` + +* Install the local chart, `router`: + + ```bash title="Local repository" + helm install --set router.configuration.telemetry.metrics.prometheus.enabled=true --set managedFederation.apiKey="" --set managedFederation.graphRef="" --create-namespace --namespace router-deploy router-test router --values router/values.yaml + ``` + + (TODO: clean up and describe the used helm install flags) + + ``` + In both the following examples, we are using helm to install the router: + - into namespace "router-deploy" (create namespace if it doesn't exist) + - with helm install name "router-test" + - with support for prometheus enabled + ``` + +## Verify Helm chart deployment + +After the router Helm chart has been installed, you can check on the status of the Helm deployment: ```bash helm list --namespace router-deploy ``` +## TODO (other topics to add) + ### Kubernetes Configuration -If you aren't familiar with helm, the following example illustrates how you could do the same thing manually or as a base for kustomize. +If you aren't familiar with Helm, the following example illustrates how you could do the same thing manually or as a base for [kustomize](https://kustomize.io/). -Note: This example is generated using the helm template capability to generate the required kubernetes configuration from our helm chart. After generation, it is edited to remove the Helm management annotations. + + +This example is generated using `helm template` to generate the required Kubernetes configuration from our Helm chart (with Helm management annotations removed). + + + -```yaml ---- -# Source: router/templates/serviceaccount.yaml -apiVersion: v1 -kind: ServiceAccount -metadata: - name: release-name-router - labels: - helm.sh/chart: router-1.30.1 - app.kubernetes.io/name: router - app.kubernetes.io/instance: release-name - app.kubernetes.io/version: "v1.30.1" - app.kubernetes.io/managed-by: Helm ---- -# Source: router/templates/secret.yaml -apiVersion: v1 -kind: Secret -metadata: - name: "release-name-router" - labels: - helm.sh/chart: router-1.30.1 - app.kubernetes.io/name: router - app.kubernetes.io/instance: release-name - app.kubernetes.io/version: "v1.30.1" - app.kubernetes.io/managed-by: Helm -data: - managedFederationApiKey: "UkVEQUNURUQ=" ---- -# Source: router/templates/configmap.yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: release-name-router - labels: - helm.sh/chart: router-1.30.1 - app.kubernetes.io/name: router - app.kubernetes.io/instance: release-name - app.kubernetes.io/version: "v1.30.1" - app.kubernetes.io/managed-by: Helm -data: - configuration.yaml: | - health_check: - listen: 0.0.0.0:8088 - supergraph: - listen: 0.0.0.0:80 - telemetry: - metrics: - common: - resources: - service.name: release-name-router - prometheus: - enabled: true - listen: 0.0.0.0:9090 - path: /metrics ---- -# Source: router/templates/service.yaml -apiVersion: v1 -kind: Service -metadata: - name: release-name-router - labels: - helm.sh/chart: router-1.30.1 - app.kubernetes.io/name: router - app.kubernetes.io/instance: release-name - app.kubernetes.io/version: "v1.30.1" - app.kubernetes.io/managed-by: Helm -spec: - type: ClusterIP - ports: - - port: 80 - targetPort: http - protocol: TCP - name: http - - port: 8088 - targetPort: health - protocol: TCP - name: health - selector: - app.kubernetes.io/name: router - app.kubernetes.io/instance: release-name ---- -# Source: router/templates/deployment.yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: release-name-router - labels: - helm.sh/chart: router-1.30.1 - app.kubernetes.io/name: router - app.kubernetes.io/instance: release-name - app.kubernetes.io/version: "v1.30.1" - app.kubernetes.io/managed-by: Helm - - annotations: - prometheus.io/path: /metrics - prometheus.io/port: "9090" - prometheus.io/scrape: "true" -spec: - replicas: 1 - selector: - matchLabels: - app.kubernetes.io/name: router - app.kubernetes.io/instance: release-name - template: - metadata: - annotations: - kubectl.kubernetes.io/default-container: router - labels: - app.kubernetes.io/name: router - app.kubernetes.io/instance: release-name - spec: - serviceAccountName: release-name-router - securityContext: - {} - containers: - - name: router - securityContext: - {} - image: "ghcr.io/apollographql/router:v1.30.1" - imagePullPolicy: IfNotPresent - args: - - --hot-reload - - --config - - /app/configuration.yaml - env: - - name: APOLLO_KEY - valueFrom: - secretKeyRef: - name: "release-name-router" - key: managedFederationApiKey - optional: true - - name: APOLLO_GRAPH_REF - value: REDACTED - ports: - - name: http - containerPort: 80 - protocol: TCP - - name: health - containerPort: 8088 - protocol: TCP - lifecycle: - {} - livenessProbe: - httpGet: - path: "/health?live" - port: 8088 - initialDelaySeconds: 0 - readinessProbe: - httpGet: - path: "/health?ready" - port: 8088 - initialDelaySeconds: 0 - resources: - {} - volumeMounts: - - name: router-configuration - mountPath: /app/ - readOnly: true - volumes: - - name: router-configuration - configMap: - name: release-name-router - terminationGracePeriodSeconds: 30 ---- -# Source: router/templates/tests/test-connection.yaml -apiVersion: v1 -kind: Pod -metadata: - name: "release-name-router-test-connection" - labels: - helm.sh/chart: router-1.30.1 - app.kubernetes.io/name: router - app.kubernetes.io/instance: release-name - app.kubernetes.io/version: "v1.30.1" - app.kubernetes.io/managed-by: Helm - annotations: - "helm.sh/hook": test -spec: - containers: - - name: netcat - image: busybox - command: ['nc'] - args: ['-vz','-w','1','release-name-router:80'] - restartPolicy: Never -``` ## The health endpoint @@ -257,8 +168,11 @@ If you had a router running on your localhost, with default health-check configu curl "http://localhost:8088/health" + ## Using `istio` with the router The [istio service mesh](https://istio.io/) is a very popular choice for enhanced traffic routing within Kubernetes. `istio-proxy` pod injection can cause an [issue](https://github.com/apollographql/router/issues/3533) in the router. The router may start executing at the same time that istio is reconfiguring networking for the router pod. This is an issue with `istio`, not the router, and you can resolve it by following the advice in [istio's injection documentation](https://istio.io/latest/docs/ops/common-problems/injection/#pod-or-containers-start-with-network-issues-if-istio-proxy-is-not-ready). + + diff --git a/docs/source/containerization/overview.mdx b/docs/source/containerization/overview.mdx index 0b13cdbbb2..166ac55565 100644 --- a/docs/source/containerization/overview.mdx +++ b/docs/source/containerization/overview.mdx @@ -1,14 +1,27 @@ --- title: Containerizing the Apollo Router +description: Running Apollo Router images in containers --- import ElasticNotice from '../../shared/elastic-notice.mdx'; -> More details about Apollo Router images are available [on GitHub](https://github.com/apollographql/router/pkgs/container/router). + -Each release of the Apollo Router includes both default and debug images. Each image for a release contains the same build. Debug images have helpful debugging utilities installed and run the router under the control of heaptrack (https://github.com/KDE/heaptrack). +Apollo provides container images of the Apollo Router [on GitHub](https://github.com/apollographql/router/pkgs/container/router). - +Each release of the Apollo Router includes both default (production) and debug images. While each image for a release contains the same build, the debug images have helpful debugging utilities installed and run the router under the control of heaptrack (https://github.com/KDE/heaptrack). + +## Example running router with Docker + +To run the router, your Docker container must have the `APOLLO_GRAPH_REF` and `APOLLO_KEY` environment variables set to your graph's reference and ID, respectively. (TODO: link to env var reference) + +- The reference of your graph in Apollo's registry (``). +- The [graph API key](https://www.apollographql.com/docs/studio/api-keys/#graph-api-keys) that Apollo Server should use to authenticate with Apollo Studio. You can set this with the `APOLLO_KEY` environment variable. (``). + +- `graphRef`: A reference of your graph in Apollo's registry, such as `graph-id@my-variant` or just `graph-id`. You can set this with the `APOLLO_GRAPH_REF` environment variable. +- `graphId`: The ID of your graph in Apollo's registry. You can set this with the `APOLLO_GRAPH_ID` environment variable. You may not specify this if you specify the graph ref. + +- Set your `APOLLO_GRAPH_REF` and `APOLLO_KEY` Here's a basic example of running a router image with Docker (make sure to replace `` with whichever version you want to use, such as `v1.4.0`): diff --git a/docs/source/migrating-from-gateway.mdx b/docs/source/migrating-from-gateway.mdx index 3bff1fe21d..c27c169cb4 100644 --- a/docs/source/migrating-from-gateway.mdx +++ b/docs/source/migrating-from-gateway.mdx @@ -1,20 +1,23 @@ --- -title: Moving to the Apollo Router from @apollo/gateway +title: Gateway migration guide +decription: Migrating to the Apollo Router from `@apollo/gateway` --- If you have a federated supergraph that currently uses the Node.js `@apollo/gateway` library, this article describes how to move that supergraph to the Rust-based Apollo Router. We recommend the Apollo Router over `@apollo/gateway` for all supergraphs, because it provides significant performance improvements. -> Moving to the Apollo Router from `@apollo/gateway` requires zero changes to your subgraphs! +> **Tip**: Moving to the Apollo Router from `@apollo/gateway` requires zero changes to your subgraphs. ## What's different? -Unlike `@apollo/gateway`, the Apollo Router is packaged as a _static, standalone binary_. To customize its behavior, you pass it a [YAML configuration file](./configuration/overview/#yaml-config-file) at startup. If you start the router with the `--hot-reload` flag (or set the `APOLLO_ROUTER_HOT_RELOAD` environment variable to `true`), you can even modify that configuration without a restart. +Whereas `@apollo/gateway` is an npm package, the Apollo Router is packaged as a _static, standalone binary_. -You _can_ download the Apollo Router source and use it as a library in a larger project. However, our goal is to remove the need to write custom code in your graph router (which is always necessary with `@apollo/gateway`). Instead, the Apollo Router exposes the most common critical features via declarative configuration. +The Apollo Router exposes the most common critical features via declarative configuration. You customize the router with a [YAML configuration file](./configuration/overview/#yaml-config-file) that takes effect at startup. Configurations can be modified and take effect without restart if you either start the router with the `--hot-reload` flag or set the `APOLLO_ROUTER_HOT_RELOAD` environment variable to `true`. + +> You _can_ download the Apollo Router source and use it as a library in a larger project. However, our goal is to remove the need to write custom code in your graph router, which is always necessary with `@apollo/gateway`. ## Take inventory of your gateway configuration -The `@apollo/gateway` library is an extension to the [Apollo Server](/apollo-server/) library, and you need to consider your existing configuration of _both_ libraries when moving to the Apollo Router. For example, you might be customizing which HTTP headers your subgraphs receive from client requests, or passing specific headers _back_ to the client from specific subgraphs. +The `@apollo/gateway` library is an extension to the [Apollo Server](/apollo-server/) library, and you need to consider your existing configuration of _both_ gateway and server libraries when moving to the Apollo Router. For example, you might need to consider your customizations for the HTTP headers your subgraphs receive from client requests, or for passing specific headers _back_ to the client from specific subgraphs. Because the Apollo Router uses an entirely different configuration mechanism, you should make a checklist of your gateway's custom behaviors to make sure those behaviors all remain when your migration is complete. From 985f837065e1c973d90c0d1ac9c2faf82c6538ca Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Mon, 2 Oct 2023 16:49:03 -0700 Subject: [PATCH 02/21] WIP: add common config --- docs/source/containerization/kubernetes.mdx | 173 ++++++++++++++++---- 1 file changed, 145 insertions(+), 28 deletions(-) diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index d796d6dc3a..315314ac10 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -9,26 +9,21 @@ import HelmShowOutput from '../../shared/helm-show-router-output.mdx'; import K8SManualConfig from '../../shared/k8s-manual-config.mdx'; import RouterCommonConfig from '../../shared/router-common-config.mdx'; - - -Learn about deploying a self-hosted supergraph with GraphOS and the Apollo Router on Kubernetes (k8s). Use Helm charts for the router, one with common configuration and another with custom, in-house configuration. - -This guide covers: +Learn how to deploy a self-hosted supergraph with GraphOS and the Apollo Router on Kubernetes: -* Explaining the Helm chart for Apollo Router -* Setting up your cluster and self-hosted router -* Configuring the router Helm chart and installing the router package +* Get the Helm chart provided with each release of the router. +* Divide a router configuration between one chart for common settings across all environments, and a separate chart for each specific environment. +* Choose chart settings that best migrate from gateway to the router. +* Install your Helm charts to deploy the router. + ## About the router Helm chart -[Helm](https://helm.sh) is a package manager for Kubernetes. You create a Helm _chart_ to describe the resources in a package, then you install the chart with Helm to deploy the package on Kubernetes. - -Apollo provides an application Helm chart with each release of Apollo Router in GitHub. The chart for the latest release of the router is available [here](https://github.com/apollographql/router/tree/v1.31.1/helm/chart/router). +[Helm](https://helm.sh) is a package manager for Kubernetes. You create a Helm _chart_ to describe the resources in a package then install the chart with Helm to deploy the package on Kubernetes (k8s). -Since version 0.14.0 of the router, Apollo has also released a Helm chart for the router 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`. +Apollo provides an application Helm chart with each release of Apollo Router in GitHub. Each released Helm chart sets specific values for the router, including: -The released Helm chart sets specific values for the router, including: * Coprocessor * Header propagation * Max request sizes @@ -36,7 +31,18 @@ The released Helm chart sets specific values for the router, including: * CORS * Metrics and labels - + +## Get the router Helm chart + +The Helm chart for each release of the Apollo Router is available from the router's GitHub repository in `/helm/chart/router`. + +> For example, the Helm chart of the latest release of the router is available [here](https://github.com/apollographql/router/tree/v1.31.1/helm/chart/router). + +Since the router v0.14.0, Apollo has also released a Helm chart for the router 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`. + + The values of the Helm chart for Apollo Router v1.31.0 in the GitHub container repository, as output by the `helm show` command: @@ -48,13 +54,133 @@ helm show values oci://ghcr.io/apollographql/helm-charts/router -### Separate common and environment-specific configurations +## 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 (`values.yaml`): + +- 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 chart while adding new environment-specific values. + +### Common value configuration + +Configuring a `values.yaml` file for settings common across environments. + + + + + + + +(TODO: explain `fullnameOverride`) -To support different deployment configurations for different environments (development, staging, production, etc.), Apollo recommends separating your configuration values into separate Helm charts: +Setting router command-line arguments and YAML config file keys/values. -- A **common** chart, containing values that apply across all environments. -- Unique **environment** charts, each including the common chart and overriding common values with environment-specific values or adding new values. +```yaml title="values.yaml" +router: + router: + # args: router binary command-line args + args: [] + # configuration: router config + configuration: + ... +``` + +Configure Rhai script path and entry point. +```yaml title="values.yaml" +router: + router: + configuration: + rhai: + scripts: + main: .rhai +``` + +Configure metrics endpoints. + +```yaml title="values.yaml" +router: + router: + configuration: + telemetry: + metrics: + prometheus: + enabled: true + otlp: + temporality: delta + endpoint: +``` + +Coprocessor container configuration + +```yaml title="values.yaml" +router: + router: + configuration: + coprocessor: + timeout: 3s + url: : + router: + request: + ... + response: + ... + subgraph: + extraContainers: + - name: + image: + ports: + - containerPort: + env: + ... + +``` + +#### Configuring migration from gateway + +The gateway's maximum supported request size is 20MB, which is different than the router's default maximum request size, so it needs to be configured. + +```yaml title="values.yaml" +router: + router: + configuration: + limits: + experimental_http_max_request_bytes: 20000000 #20MB +``` + +The router's timeout is increased to accommodate slow subgraphs. Only HTTP 1.1 suport is enabled. + +```yaml title="values.yaml" +router: + router: + configuration: + traffic_shaping: + router: + timeout: 6min + all: + experimental_enable_http2: false + timeout: 5min +``` + +Support for `@defer` is unsupported in gateway, so it needs to be disabled in the router. + +```yaml title="values.yaml" +router: + router: + configuration: + supergraph: + defer_support: false +``` + +The gateway propagates subgraph errors to clients, but the router doesn't by default, so it needs to be configured to propagate subgraph errors. + +```yaml title="values.yaml" +router: + router: + configuration: + include_subgraph_errors: + all: true +``` ## Deploy router with Helm @@ -68,7 +194,7 @@ To support different deployment configurations for different environments (devel Install the tools and provision the infrastructure for your Kubernetes cluster. -For example, see the [Setup from Apollo's Build a Supergraph tutorial](https://github.com/apollosolutions/build-a-supergraph/tree/main/01-setup#01---setup). It provides steps you can reference for gathering accounts and credentials for your cloud platform (GCP or AWS), provisioning resources, and deploying your subgraphs. +> For example, see the [Setup from Apollo's Build a Supergraph tutorial](https://github.com/apollosolutions/build-a-supergraph/tree/main/01-setup#01---setup). It provides steps you can reference for gathering accounts and credentials for your cloud platform (GCP or AWS), provisioning resources, and deploying your subgraphs. (TODO: refine the steps between this #set-up-cluster and the next #set-up-self-hosted-router) @@ -76,15 +202,6 @@ For example, see the [Setup from Apollo's Build a Supergraph tutorial](https://g Set up a self-hosted router by following the [first six steps of the self-hosted router quickstart](/graphos/quickstart/self-hosted), and stopping when you reach step [7. Deploy your router and connect clients](https://www.apollographql.com/docs/graphos/quickstart/self-hosted/#7-deploy-your-router-and-connect-clients). -## Customize router charts - - - - - - - -(TODO: explain common config settings) ## Install router Helm chart From f4a8efecee4c4fdb8c146a5f27587d574c26d99e Mon Sep 17 00:00:00 2001 From: Edward Huang <18322228+shorgi@users.noreply.github.com> Date: Tue, 3 Oct 2023 05:53:34 -0700 Subject: [PATCH 03/21] Update docs/source/containerization/kubernetes.mdx Co-authored-by: Gary Pennington --- docs/source/containerization/kubernetes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index 315314ac10..fb4c5d8b0c 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -38,7 +38,7 @@ The Helm chart for each release of the Apollo Router is available from the route > For example, the Helm chart of the latest release of the router is available [here](https://github.com/apollographql/router/tree/v1.31.1/helm/chart/router). -Since the router v0.14.0, Apollo has also released a Helm chart for the router as an [Open Container Initiative (OCI)](https://helm.sh/docs/topics/registries/) image in the GitHub Container registry. +Since the router v0.14.0, Apollo has also released a Helm chart for the router as an [Open Container Initiative (OCI)](https://helm.sh/docs/topics/registries/) image in our GitHub Container registry. > The path to the OCI router chart is `oci://ghcr.io/apollographql/helm-charts/router`. From 16658be4b6c4799292ea6c7329eefde63b686ca1 Mon Sep 17 00:00:00 2001 From: Edward Huang <18322228+shorgi@users.noreply.github.com> Date: Tue, 3 Oct 2023 05:53:48 -0700 Subject: [PATCH 04/21] Update docs/source/containerization/kubernetes.mdx Co-authored-by: Gary Pennington --- docs/source/containerization/kubernetes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index fb4c5d8b0c..f3380815c7 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -42,7 +42,7 @@ Since the router v0.14.0, Apollo has also released a Helm chart for the router a > The path to the OCI router chart is `oci://ghcr.io/apollographql/helm-charts/router`. - + The values of the Helm chart for Apollo Router v1.31.0 in the GitHub container repository, as output by the `helm show` command: From b2e933faebf8ed99570ef563285bd23f9b9b2194 Mon Sep 17 00:00:00 2001 From: Edward Huang <18322228+shorgi@users.noreply.github.com> Date: Tue, 3 Oct 2023 05:53:58 -0700 Subject: [PATCH 05/21] Update docs/source/containerization/kubernetes.mdx Co-authored-by: Gary Pennington --- docs/source/containerization/kubernetes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index f3380815c7..7b604f2f9f 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -65,7 +65,7 @@ To support your different deployment configurations for different environments ( Configuring a `values.yaml` file for settings common across environments. - + From 2e5f6e7fc03f5f8d3bf51602559340f3a7fce50e Mon Sep 17 00:00:00 2001 From: Edward Huang <18322228+shorgi@users.noreply.github.com> Date: Tue, 3 Oct 2023 05:54:11 -0700 Subject: [PATCH 06/21] Update docs/source/containerization/kubernetes.mdx Co-authored-by: Gary Pennington --- docs/source/containerization/kubernetes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index 7b604f2f9f..32590dc39e 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -205,7 +205,7 @@ Set up a self-hosted router by following the [first six steps of the self-hosted ## Install router Helm chart -You can install the router chart from either a local repository or the container registry. +You can install the router chart from either a local repository or the Apollo container registry. ### Install chart from container registry From 4ec2938ac20c415b4e9fdbdf4ccb264ee796b06f Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Tue, 3 Oct 2023 16:53:20 -0700 Subject: [PATCH 07/21] Refine content, from basic deployment to customizing for metrics, Rhai, and coprocessor --- docs/source/containerization/kubernetes.mdx | 342 +++++++++----------- 1 file changed, 148 insertions(+), 194 deletions(-) diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index 32590dc39e..85d1ea367c 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -9,40 +9,34 @@ import HelmShowOutput from '../../shared/helm-show-router-output.mdx'; import K8SManualConfig from '../../shared/k8s-manual-config.mdx'; import RouterCommonConfig from '../../shared/router-common-config.mdx'; -Learn how to deploy a self-hosted supergraph with GraphOS and the Apollo Router on Kubernetes: +Learn how to deploy the Apollo Router nd the Apollo Router for a self-hosted supergraph with GraphOS: -* Get the Helm chart provided with each release of the router. -* Divide a router configuration between one chart for common settings across all environments, and a separate chart for each specific environment. -* Choose chart settings that best migrate from gateway to the router. -* Install your Helm charts to deploy the router. +* 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 set up a coprocessor. +* Choose chart values that best migrate from gateway to the router. ## About the router Helm chart -[Helm](https://helm.sh) is a package manager for Kubernetes. You create a Helm _chart_ to describe the resources in a package then install the chart with Helm to deploy the package on Kubernetes (k8s). +[Helm](https://helm.sh) is a package manager for Kubernetes (k8s). Apollo provides an application Helm chart with each release of Apollo Router 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 our GitHub container registry. -Apollo provides an application Helm chart with each release of Apollo Router in GitHub. Each released Helm chart sets specific values for the router, including: - -* Coprocessor -* Header propagation -* Max request sizes -* Hot reload -* CORS -* Metrics and labels +> The path to the OCI router chart is `oci://ghcr.io/apollographql/helm-charts/router`. +You customize a router deployment by both setting command-line options and editing YAML configuration files. -## Get the router Helm chart +## Basic deployment -The Helm chart for each release of the Apollo Router is available from the router's GitHub repository in `/helm/chart/router`. +Follow this guide to deploy the Apollo Router by using Helm to install the basic chart provided with each router release. -> For example, the Helm chart of the latest release of the router is available [here](https://github.com/apollographql/router/tree/v1.31.1/helm/chart/router). +Each router chart has a `values.yaml` file with router and deployment settings. The released, unedited file has a few explicit settings, including: -Since the router v0.14.0, Apollo has also released a Helm chart for the router as an [Open Container Initiative (OCI)](https://helm.sh/docs/topics/registries/) image in our GitHub Container registry. +* Default container ports for the router's (supergraph) [HTTP server](../../configuration/overview/#listen-address), [health check endpoint](../../configuration/health-checks), and [metrics endpoint](../../configuration/metrics). +* Command-line argument to enable [hot reloading of the router](../../configuration/overview/#--hr----hot-reload). +* A single replica. -> The path to the OCI router chart is `oci://ghcr.io/apollographql/helm-charts/router`. - - + The values of the Helm chart for Apollo Router v1.31.0 in the GitHub container repository, as output by the `helm show` command: @@ -54,242 +48,202 @@ helm show values oci://ghcr.io/apollographql/helm-charts/router -## Separate configurations per environment +### Set up Helm -To support your different deployment configurations for different environments (development, staging, production, etc.), Apollo recommends separating your configuration values into separate files (`values.yaml`): +* Install [Helm](https://helm.sh/docs/intro/install/) **version 3.x**. The Apollo Router's Helm chart requires Helm v3.x. -- 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 chart while adding new environment-specific values. +> ⚠️ 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). -### Common value configuration +* Log in with Helm to the Apollo container registry in GitHub. + + * Get a GitHub OCI token and save it in an environment variable, `GITHUB_OCI_TOKEN`. For reference, follow the guide for [authenticating to the GitHub container registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry). -Configuring a `values.yaml` file for settings common across environments. + * Log in with the `helm registry login` command, using your saved `GITHUB_OCI_TOKEN` and GitHub username: - + ```bash + echo ${GITHUB_OCI_TOKEN} | helm registry login -u --password-stdin ghcr.io + ``` - +* After logging in, verify your access to 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 + ``` -(TODO: explain `fullnameOverride`) +### Set up cluster -Setting router command-line arguments and YAML config file keys/values. +Install the tools and provision the infrastructure for your Kubernetes cluster. -```yaml title="values.yaml" -router: - router: - # args: router binary command-line args - args: [] - # configuration: router config - configuration: - ... -``` +> For example, see the [Setup from Apollo's Build a Supergraph tutorial](https://github.com/apollosolutions/build-a-supergraph/tree/main/01-setup#01---setup). It provides steps you can reference for gathering accounts and credentials for your cloud platform (GCP or AWS), provisioning resources, and deploying your subgraphs. -Configure Rhai script path and entry point. +### Set up router -```yaml title="values.yaml" -router: - router: - configuration: - rhai: - scripts: - main: .rhai -``` +Set up the router by following the [first six steps of the self-hosted router quickstart](/graphos/quickstart/self-hosted) (stopping when you reach step [7. Deploy your router and connect clients](https://www.apollographql.com/docs/graphos/quickstart/self-hosted/#7-deploy-your-router-and-connect-clients)). -Configure metrics endpoints. +### Deploy router -```yaml title="values.yaml" -router: - router: - configuration: - telemetry: - metrics: - prometheus: - enabled: true - otlp: - temporality: delta - endpoint: -``` - -Coprocessor container configuration - -```yaml title="values.yaml" -router: - router: - configuration: - coprocessor: - timeout: 3s - url: : - router: - request: - ... - response: - ... - subgraph: - extraContainers: - - name: - image: - ports: - - containerPort: - env: - ... +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 --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --namespace ``` +The necessary arguments for specific configuration values: -#### Configuring migration from gateway - -The gateway's maximum supported request size is 20MB, which is different than the router's default maximum request size, so it needs to be configured. - -```yaml title="values.yaml" -router: - router: - configuration: - limits: - experimental_http_max_request_bytes: 20000000 #20MB -``` +* **Graph ref**. The reference to your managed graph (`id@variant`), the same value as the [`APOLLO_GRAPH_REF` environment variable](../../configuration/overview/#apollo_graph_ref). Used by `helm install` to set `managedFederation.graphRef`. +* **Graph API key**. The API key to your managed graph, the same value as the [`APOLLO_KEY` environment variable](../../configuration/overview/#apollo_key). Used by `helm install` to set `managedFederation.apiKey`. -The router's timeout is increased to accommodate slow subgraphs. Only HTTP 1.1 suport is enabled. +Some optional arguments: -```yaml title="values.yaml" -router: - router: - configuration: - traffic_shaping: - router: - timeout: 6min - all: - experimental_enable_http2: false - timeout: 5min -``` +* **Router version**. The version of the router to deploy. If not specified by `helm install`, the latest version is installed. +* **Namespace**. The namespace scope for this deployment. -Support for `@defer` is unsupported in gateway, so it needs to be disabled in the router. +### Verify deployment -```yaml title="values.yaml" -router: - router: - configuration: - supergraph: - defer_support: false -``` +Verify that your router is one of the deployed releases with the `helm list` command. -The gateway propagates subgraph errors to clients, but the router doesn't by default, so it needs to be configured to propagate subgraph errors. +If you deployed with the `--namespace ` option, you can list only the releases within your namespace: -```yaml title="values.yaml" -router: - router: - configuration: - include_subgraph_errors: - all: true +```bash +helm list --namespace ``` -## Deploy router with Helm - -### Install Helm - -* Install [Helm](https://helm.sh/docs/intro/install/) **version 3**. The Apollo Router's Helm chart requires Helm v3. - -> ⚠️ 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). - -### Set up cluster - -Install the tools and provision the infrastructure for your Kubernetes cluster. - -> For example, see the [Setup from Apollo's Build a Supergraph tutorial](https://github.com/apollosolutions/build-a-supergraph/tree/main/01-setup#01---setup). It provides steps you can reference for gathering accounts and credentials for your cloud platform (GCP or AWS), provisioning resources, and deploying your subgraphs. - -(TODO: refine the steps between this #set-up-cluster and the next #set-up-self-hosted-router) +## Deploy with metrics endpoints -### Set up self-hosted router +The router supports [metrics endpoints for Prometheus and OTLP](../../configuration/metrics)(OpenTelemetry protocol). A [basic deployment](#basic-deployment) doesn't enable metrics endpoints, because the router chart disables both Prometheus (explicitly) and OTLP (by omission). -Set up a self-hosted router by following the [first six steps of the self-hosted router quickstart](/graphos/quickstart/self-hosted), and stopping when you reach step [7. Deploy your router and connect clients](https://www.apollographql.com/docs/graphos/quickstart/self-hosted/#7-deploy-your-router-and-connect-clients). +To enable metrics endpoints in your deployed router through a YAML configuration file: +* Create a YAML file, `my_values.yaml`, to contain additional values that override default values. +* Edit the file with values to enable metrics endpoints: -## Install router Helm chart - -You can install the router chart from either a local repository or the Apollo container registry. - -### Install chart from container registry + ```yaml title="my_values.yaml" + router: + configuration: + telemetry: + metrics: + prometheus: + enabled: true + listen: 0.0.0.0:9090 + path: "/metrics" + otlp: + temporality: delta + endpoint: + ``` -* Login to the container registry by following the guide to [authenticating to the GitHub container registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry). + * `router.telemetry.metrics.prometheus` was already configured but disabled (`enabled: false`) by default. This configuration sets `enabled: true`. + * `router.telemetry.metrics.otlp` is enabled by inclusion. -* After logging in, verify your access to the registry by showing the latest router chart from `helm`: +* 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 show values oci://ghcr.io/apollographql/helm-charts/router - ``` - -* Install the OCI image from the GiHub container registry: - - ```bash title="OCI registry" - helm install --set router.configuration.telemetry.metrics.prometheus.enabled=true --set managedFederation.apiKey="" --set managedFederation.graphRef="" --create-namespace --namespace router-deploy router-test oci://ghcr.io/apollographql/helm-charts/router --version 1.0.0-rc.8 --values router/values.yaml + helm install --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --namespace --values my_values.yaml ``` -### Install Helm chart from local repository +## Deploy with Rhai scripts -* Clone the [router repository](https://github.com/apollographql/router). +The router supports [Rhai scripting](../../customizations/rhai) to add custom functionality. -* Change to the directory in your local repo with the router chart: +To enable Rhai scripts in your deployed router through a YAML configuration file: - ```bash - cd /helm/chart - ``` +* Create a YAML file, `my_values.yaml`, to contain additional values that override default values. +* Edit the file with values to enable Rhai scripts: -* Install the local chart, `router`: - - ```bash title="Local repository" - helm install --set router.configuration.telemetry.metrics.prometheus.enabled=true --set managedFederation.apiKey="" --set managedFederation.graphRef="" --create-namespace --namespace router-deploy router-test router --values router/values.yaml + ```yaml title="my_values.yaml" + router: + configuration: + rhai: + scripts: + main: ``` - (TODO: clean up and describe the used helm install flags) +* 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`: - ``` - In both the following examples, we are using helm to install the router: - - into namespace "router-deploy" (create namespace if it doesn't exist) - - with helm install name "router-test" - - with support for prometheus enabled + ```bash + helm install --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --namespace --values my_values.yaml ``` -## Verify Helm chart deployment +## Deploy with a coprocessor -After the router Helm chart has been installed, you can check on the status of the Helm deployment: +The router supports [external coprocessing](../../customizations/coprocessor) to run custom logic on requests throughout the [router's request-handling lifecycle](../../customizations/rhai/#router-request-lifecycle). -```bash -helm list --namespace router-deploy -``` +A deployed coprocessor has its own application image and container in the router pod. -## TODO (other topics to add) +To configure a coprocessor and its container for your deployed router through a YAML configuration file: -### Kubernetes Configuration +* Create a YAML file, `my_values.yaml`, to contain additional values that override default values. +* Edit the file to configure a coprocessor for the router. For reference, follow the [typical](../../customizations/coprocessor#typical-configuration) and [minimal](../../customizations/coprocessor#minimal-configuration) configuration examples, and apply them to `router.configuration.coprocessor`. -If you aren't familiar with Helm, the following example illustrates how you could do the same thing manually or as a base for [kustomize](https://kustomize.io/). +```yaml title="my_values.yaml" +router: + configuration: + # minimal coprocessor configuration + coprocessor: + url: http://127.0.0.1:8081 # Replace with the URL of your coprocessor's HTTP endpoint. + router: + request: + headers: false +``` +* Edit the file 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 +``` - +* 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`: -This example is generated using `helm template` to generate the required Kubernetes configuration from our Helm chart (with Helm management annotations removed). + ```bash + helm install --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --namespace --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: -## The health endpoint +- 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 chart while adding new environment-specific values. -The router supports a health endpoint. You can see from the examples above how it can be used in a kubernetes deployment. +An environment file should include the common file. -If you had a router running on port 8088 on your localhost, you could exercise the health endpoint as follows: +For example, deploy with a `common_values.yaml` file applied first and then a `prod_values.yaml` file: ```bash -curl "http://localhost:8088/health" -{"status":"UP"} +helm install --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --namespace --values common_values.yaml --values prod_values.yaml ``` -If you had a router running on your localhost, with default health-check configuration, you could exercise the health endpoint as follows: +## Configure for migration from gateway -curl "http://localhost:8088/health" +* The gateway's maximum supported request size is 20MB, which is different than the router's default maximum request size, so it needs to be configured. + ```yaml title="values.yaml" + router: + configuration: + limits: + experimental_http_max_request_bytes: 20000000 #20MB + ``` -## Using `istio` with the router - -The [istio service mesh](https://istio.io/) is a very popular choice for enhanced traffic routing within Kubernetes. +* The router's timeout is increased to accommodate slow subgraphs. Only HTTP 1.1 suport is enabled. -`istio-proxy` pod injection can cause an [issue](https://github.com/apollographql/router/issues/3533) in the router. The router may start executing at the same time that istio is reconfiguring networking for the router pod. This is an issue with `istio`, not the router, and you can resolve it by following the advice in [istio's injection documentation](https://istio.io/latest/docs/ops/common-problems/injection/#pod-or-containers-start-with-network-issues-if-istio-proxy-is-not-ready). +```yaml title="values.yaml" +router: + configuration: + traffic_shaping: + router: + timeout: 6min + all: + experimental_enable_http2: false + timeout: 5min +``` +* The gateway propagates subgraph errors to clients, but the router doesn't by default, so it needs to be configured to propagate subgraph errors. +```yaml title="values.yaml" +router: + configuration: + include_subgraph_errors: + all: true +``` From b58d150809297b20857366e41a611d2ce84a89f4 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Tue, 3 Oct 2023 17:05:13 -0700 Subject: [PATCH 08/21] copyedits --- docs/source/containerization/kubernetes.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index 85d1ea367c..57c362a12a 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -9,12 +9,12 @@ import HelmShowOutput from '../../shared/helm-show-router-output.mdx'; import K8SManualConfig from '../../shared/k8s-manual-config.mdx'; import RouterCommonConfig from '../../shared/router-common-config.mdx'; -Learn how to deploy the Apollo Router nd the Apollo Router for a self-hosted supergraph with GraphOS: +Learn how to deploy the Apollo Router, for a self-hosted supergraph with GraphOS, on Kubernetes by using Helm: * 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 set up a coprocessor. -* Choose chart values that best migrate from gateway to the router. +* Choose chart values that best migrate from a gateway to the router. From 4b866428a4f026156c98a4053195a5c45f66dfab Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Wed, 4 Oct 2023 12:32:16 -0700 Subject: [PATCH 09/21] copyedit and update from review comment --- docs/source/containerization/kubernetes.mdx | 28 +++++++++++---------- docs/source/migrating-from-gateway.mdx | 6 ++++- 2 files changed, 20 insertions(+), 14 deletions(-) diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index 57c362a12a..737ea28acf 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -9,11 +9,11 @@ import HelmShowOutput from '../../shared/helm-show-router-output.mdx'; import K8SManualConfig from '../../shared/k8s-manual-config.mdx'; import RouterCommonConfig from '../../shared/router-common-config.mdx'; -Learn how to deploy the Apollo Router, for a self-hosted supergraph with GraphOS, on Kubernetes by using Helm: +Learn how to deploy the Apollo Router, for a self-hosted supergraph with GraphOS, on Kubernetes by using Helm charts: * 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 set up a coprocessor. +* Configure chart values to export metrics, enable Rhai scripting, and deploy a coprocessor. * Choose chart values that best migrate from a gateway to the router. @@ -24,7 +24,7 @@ Learn how to deploy the Apollo Router, for a self-hosted supergraph with GraphOS > The path to the OCI router chart is `oci://ghcr.io/apollographql/helm-charts/router`. -You customize a router deployment by both setting command-line options and editing YAML configuration files. +You customize a router deployment with the same [command-line options and YAML configuration for router](../../configuration/overview) but under different Helm CLI options and YAML keys. ## Basic deployment @@ -85,17 +85,17 @@ Set up the router by following the [first six steps of the self-hosted router qu 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 --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --namespace +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: * **Graph ref**. The reference to your managed graph (`id@variant`), the same value as the [`APOLLO_GRAPH_REF` environment variable](../../configuration/overview/#apollo_graph_ref). Used by `helm install` to set `managedFederation.graphRef`. * **Graph API key**. The API key to your managed graph, the same value as the [`APOLLO_KEY` environment variable](../../configuration/overview/#apollo_key). Used by `helm install` to set `managedFederation.apiKey`. -Some optional arguments: +Some optional but recommended arguments: -* **Router version**. The version of the router to deploy. If not specified by `helm install`, the latest version is installed. * **Namespace**. The namespace scope for this deployment. +* **Router version**. The version of the router to deploy. If not specified by `helm install`, the latest version is installed. ### Verify deployment @@ -136,7 +136,7 @@ To enable metrics endpoints in your deployed router through a YAML configuration * 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 --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --namespace --values my_values.yaml + 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 @@ -159,7 +159,7 @@ To enable Rhai scripts in your deployed router through a YAML configuration file * 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 --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --namespace --values my_values.yaml + 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 a coprocessor @@ -197,7 +197,7 @@ extraContainers: * 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 --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --namespace --values my_values.yaml + 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 @@ -207,17 +207,19 @@ To support your different deployment configurations for different environments ( - 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 chart while adding new environment-specific values. -An environment file should include the common file. +In a `helm install` command, each `--values ` option is applied in the order within the command. Therefore, a common file must be set before an environment file in the `helm install` command, so that the environment file's values are applied last and override the commond file's values as intended. For example, deploy with a `common_values.yaml` file applied first and then a `prod_values.yaml` file: ```bash -helm install --set managedFederation.apiKey="" --set managedFederation.graphRef="" oci://ghcr.io/apollographql/helm-charts/router --version --values router/values.yaml --namespace --values common_values.yaml --values prod_values.yaml +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 ``` ## Configure for migration from gateway -* The gateway's maximum supported request size is 20MB, which is different than the router's default maximum request size, so it needs to be configured. +When [migrating from `@apollo/gateway` to the Apollo Router](../migrating-from-gateway), consider the following tips to maximize the compatibility of your router deployment. + +* The gateway's maximum supported request size is 20MB, while the router's default maximum request size is less. For compatibility, set the deployed router's maximium request size to 20MB: ```yaml title="values.yaml" router: @@ -239,7 +241,7 @@ router: timeout: 5min ``` -* The gateway propagates subgraph errors to clients, but the router doesn't by default, so it needs to be configured to 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: diff --git a/docs/source/migrating-from-gateway.mdx b/docs/source/migrating-from-gateway.mdx index c27c169cb4..41fb7e9157 100644 --- a/docs/source/migrating-from-gateway.mdx +++ b/docs/source/migrating-from-gateway.mdx @@ -1,6 +1,6 @@ --- title: Gateway migration guide -decription: Migrating to the Apollo Router from `@apollo/gateway` +description: Migrating to the Apollo Router from @apollo/gateway --- If you have a federated supergraph that currently uses the Node.js `@apollo/gateway` library, this article describes how to move that supergraph to the Rust-based Apollo Router. We recommend the Apollo Router over `@apollo/gateway` for all supergraphs, because it provides significant performance improvements. @@ -130,6 +130,10 @@ The Apollo Router currently supports two types of customizations that hook into Examples for each are provided in their respective documentation, and in the [Router repo](https://github.com/apollographql/router/tree/main/examples). +## Kubernetes deployment + +For migrating to the Apollo Router deployed on Kubernetes, see some tips for [configuring your router deployment](./containerization/kubernetes/#configure-for-migration-from-gateway). + ## Reporting migration issues If you encounter a migration issue that isn't resolved by this article, please search for existing [GitHub discussions](https://github.com/apollographql/router/discussions/) and start a new discussion if you don't find what you're looking for. From 6ecc695f0770257ec0324a01b7c6f0516fcc03aa Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Wed, 4 Oct 2023 21:52:28 -0700 Subject: [PATCH 10/21] Reorganize content in overview and docker. Add k8s overview flowchart. --- docs/source/containerization/docker.mdx | 51 +++++++++++++++++---- docs/source/containerization/kubernetes.mdx | 23 +++++++++- docs/source/containerization/overview.mdx | 51 ++++++--------------- 3 files changed, 77 insertions(+), 48 deletions(-) diff --git a/docs/source/containerization/docker.mdx b/docs/source/containerization/docker.mdx index f272063a2b..c42ed0ae7e 100644 --- a/docs/source/containerization/docker.mdx +++ b/docs/source/containerization/docker.mdx @@ -1,18 +1,49 @@ --- -title: Docker and the router -description: Using docker to run router images +title: Run on Docker +description: Run the Apollo Router on Docker --- import { Link } from "gatsby"; import ElasticNotice from '../../shared/elastic-notice.mdx'; +Follow examples in this guide to learn how to run an Apollo Router container image on Docker: + +* Run with default configuration. +* Customize your configuration to override the default configuration. +* Debug your containerized router. +* Build your own router Docker image. + -The default behaviour of the router images is suitable for a quickstart or development scenario. You'll need to know how to customize this default behaviour if you wish to do any of the following. +> **Notes** +> * The [documentation](https://docs.docker.com/engine/reference/run/) for the `docker run` command is a helpful reference for the examples in this guide. +> * The exact image version to use is your choice depending on which release you wish to use. In the following examples, replace `` with your chosen version, for example `v1.32.0` + +## Basic example running router with Docker + +To run the router, your Docker container must have the `APOLLO_GRAPH_REF` and `APOLLO_KEY` environment variables set to your graph's reference and ID, respectively. + +- The reference of your graph in Apollo's registry (``). +- The [graph API key](https://www.apollographql.com/docs/studio/api-keys/#graph-api-keys) that Apollo Server should use to authenticate with Apollo Studio. You can set this with the `APOLLO_KEY` environment variable. (``). + +- `graphRef`: A reference of your graph in Apollo's registry, such as `graph-id@my-variant` or just `graph-id`. You can set this with the `APOLLO_GRAPH_REF` environment variable. +- `graphId`: The ID of your graph in Apollo's registry. You can set this with the `APOLLO_GRAPH_ID` environment variable. You may not specify this if you specify the graph ref. + +- Set your `APOLLO_GRAPH_REF` and `APOLLO_KEY` + +Here's a basic example of running a router image with Docker (make sure to replace `` with whichever version you want to use, such as `v1.4.0`): + +```bash title="Docker" +docker run -p 4000:4000 \ + --env APOLLO_GRAPH_REF="" \ + --env APOLLO_KEY="" \ + --rm \ + ghcr.io/apollographql/router: +``` -The [docker documentation](https://docs.docker.com/engine/reference/run/) for the run command may be helpful when reading through the examples. +This command downloads your supergraph schema from Apollo and uses a default configuration that listens for connections on port `4000`. -The exact image version to use is your choice depending on which release you wish to use. In the following examples, replace `` with your chosen version. e.g.: `v1.30.1` +For more complex configuration (such as overriding subgraph URLs or propagating headers), see [Configuring the Apollo Router](../configuration/overview/). ## Override the configuration @@ -82,11 +113,11 @@ docker run -p 4000:4000 \ ghcr.io/apollographql/router:-debug ``` -The router will run under the control of heaptrack. The heaptrack output will be saved to the /data directory. The output can be analyzed directly using `heaptrack_gui` or `heaptrack_print` or shared with Apollo support staff. +The router will run under the control of heaptrack. The heaptrack output will be saved to the `/data` directory. The output can be analyzed directly using `heaptrack_gui` or `heaptrack_print` or shared with Apollo support. ## Specifying the supergraph -If we don't want to use uplink to retrieve our subgraph, we can manually specify the details. +If we don't want to use [Apollo Uplink](/federation/managed-federation/uplink/) to retrieve our subgraph, we can manually specify the details. ```bash docker run -p 4000:4000 \ @@ -95,11 +126,11 @@ docker run -p 4000:4000 \ ghcr.io/apollographql/router: -c config/router.yaml -s schema/local.graphql ``` -Note: In this example we have to mount the local definition of the supergraph into our image AND specify the location of the file. It doesn't have to be mounted in the /dist/schema directory, but it's a reasonable location to use. We must specify the configuration file location as well, since overriding the default params will override our default config file location. In this case, since we don't want to change our router configuration but want to make sure it's used, we just specify the default location of the default configuration. +In this example, we have to mount the local definition of the supergraph into our image, _and_ specify the location of the file. It doesn't have to be mounted in the `/dist/schema` directory, but it's a reasonable location to use. We must specify the configuration file location as well, since overriding the default params will override our default config file location. In this case, since we don't want to change our router configuration but want to make sure it's used, we just specify the default location of the default configuration. ## Building your own container -> This section is aimed at developers familiar with tooling such as `docker` and `git` who wish to make their own DIY container images. The script documented here is not a part of the router product, but an illustrative example of what's involved in making your own images. +> **Note:** This section is aimed at developers familiar with tooling such as `docker` and `git` who wish to make their own DIY container images. The script documented here is not a part of the router product, but an illustrative example of what's involved in making your own images. In the `dockerfiles/diy` directory, we now provide a script, `build_docker_image.sh` which illustrates how to build your own docker images from either our released tarballs or from a git commit hash or tag. Here's how to use it: @@ -124,4 +155,4 @@ Usage: build_docker_image.sh [-b [-r ]] [-d] [] build_docker_image.sh -d v0.9.1 ``` -Note: The script has to be run from the `dockerfiles/diy` directory because it makes assumptions about the relative availability of various files. The example uses [debian:bullseye-slim image](https://hub.docker.com/_/debian/) for the final image build. Feel free to modify the script to use images which better suit your own needs, but be careful if using the [-d] flag since it makes the assumption that there is a `heaptrack` package available to install. +The script has to be run from the `dockerfiles/diy` directory because it makes assumptions about the relative availability of various files. The example uses [debian:bullseye-slim image](https://hub.docker.com/_/debian/) for the final image build. Feel free to modify the script to use images which better suit your own needs, but be careful if using the [-d] flag since it makes the assumption that there is a `heaptrack` package available to install. diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index 737ea28acf..972e0a50ff 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -9,7 +9,26 @@ import HelmShowOutput from '../../shared/helm-show-router-output.mdx'; import K8SManualConfig from '../../shared/k8s-manual-config.mdx'; import RouterCommonConfig from '../../shared/router-common-config.mdx'; -Learn how to deploy the Apollo Router, for a self-hosted supergraph with GraphOS, on Kubernetes by using Helm charts: +Learn how to deploy the Apollo Router, for a self-hosted supergraph with GraphOS, on Kubernetes by using Helm charts. + +```mermaid +flowchart LR; + clients(Clients); + subgraph "Kubernetes cluster"; + proxy(["Proxy"]) + router_a(["Apollo Router"]); + coproc_a(["Coprocessor"]); + router_b(["Apollo Router"]); + coproc_b(["Coprocessor"]); + router_a <-.-> coproc_a; + router_b <-.-> coproc_b; + end; + clients -.->|Query| proxy; + proxy -.-> router_a & router_b; + class clients secondary; +``` + +The following guides provide you the steps to: * Get a router Helm chart from the Apollo container repository. * Deploy a router with a basic Helm chart. @@ -24,7 +43,7 @@ Learn how to deploy the Apollo Router, for a self-hosted supergraph with GraphOS > The path to the OCI router chart is `oci://ghcr.io/apollographql/helm-charts/router`. -You customize a router deployment with the same [command-line options and YAML configuration for router](../../configuration/overview) but under different Helm CLI options and YAML keys. +You customize a deployed router with the same [command-line options and YAML configuration](../../configuration/overview) but under different Helm CLI options and YAML keys. ## Basic deployment diff --git a/docs/source/containerization/overview.mdx b/docs/source/containerization/overview.mdx index 166ac55565..a823e3d3aa 100644 --- a/docs/source/containerization/overview.mdx +++ b/docs/source/containerization/overview.mdx @@ -1,51 +1,30 @@ --- title: Containerizing the Apollo Router -description: Running Apollo Router images in containers +description: Run Apollo Router images in containers --- import ElasticNotice from '../../shared/elastic-notice.mdx'; - - -Apollo provides container images of the Apollo Router [on GitHub](https://github.com/apollographql/router/pkgs/container/router). - -Each release of the Apollo Router includes both default (production) and debug images. While each image for a release contains the same build, the debug images have helpful debugging utilities installed and run the router under the control of heaptrack (https://github.com/KDE/heaptrack). - -## Example running router with Docker - -To run the router, your Docker container must have the `APOLLO_GRAPH_REF` and `APOLLO_KEY` environment variables set to your graph's reference and ID, respectively. (TODO: link to env var reference) +Apollo provides container images of the Apollo Router. Containerizing the Apollo Router enables it to be run in a cluster and gain all its advantages of portability, scalability, and high availability. Containers can also simplify and speed up local development. -- The reference of your graph in Apollo's registry (``). -- The [graph API key](https://www.apollographql.com/docs/studio/api-keys/#graph-api-keys) that Apollo Server should use to authenticate with Apollo Studio. You can set this with the `APOLLO_KEY` environment variable. (``). - -- `graphRef`: A reference of your graph in Apollo's registry, such as `graph-id@my-variant` or just `graph-id`. You can set this with the `APOLLO_GRAPH_REF` environment variable. -- `graphId`: The ID of your graph in Apollo's registry. You can set this with the `APOLLO_GRAPH_ID` environment variable. You may not specify this if you specify the graph ref. - -- Set your `APOLLO_GRAPH_REF` and `APOLLO_KEY` - -Here's a basic example of running a router image with Docker (make sure to replace `` with whichever version you want to use, such as `v1.4.0`): + -```bash title="Docker" -docker run -p 4000:4000 \ - --env APOLLO_GRAPH_REF="" \ - --env APOLLO_KEY="" \ - --rm \ - ghcr.io/apollographql/router: -``` +## About the Apollo Router container image -This command downloads your supergraph schema from Apollo and uses a default configuration that listens for connections on port `4000`. +Apollo provides container images of the Apollo Router [on GitHub](https://github.com/apollographql/router/pkgs/container/router) in its container repository. The router images are based on [debian:bullseye-slim](https://hub.docker.com/_/debian/), which is designed to provide constrained, secure, and small images. -For more complex configuration (such as overriding subgraph URLs or propagating headers), see [Configuring the Apollo Router](../configuration/overview/). +Each release of the Apollo Router includes both default (production) and debug images. While each image for a release contains the same build, the debug images have helpful debugging utilities installed and run the router under the control of heaptrack (https://github.com/KDE/heaptrack). -For examples of using router images in specific environments, see the guides for [Docker](./docker/) and [Kubernetes](./kubernetes/). +The layout of a router image file: -## Image file layout +* A `/dist` directory, containing the router executable and licensing details. +* A `dist/config` directory, containing a default configuration file, `router.yaml`. +* A `/dist/schema` directory for convenient mounting of a locally defined supergraph schema. -* The router executable is located in the `/dist` directory. -* A default configuration file, `router.yaml`, is located in the `dist/config` directory. -* There is also a `/dist/schema` directory for convenient mounting of a locally defined supergraph schema. -* Licensing details are also available in the `/dist` directory. +## Next steps -## Image build +The default behavior of a router image is suitable for a basic deployment or development scenario. -Apollo Router images are based on [debian:bullseye-slim](https://hub.docker.com/_/debian/), which is designed to provide constrained, secure, and small images. +For examples of customizing and deploying router images in specific environments, see the guides for: +* [Deploying on Kubernetes](./kubernetes/). +* [Running on Docker](./docker/) From 96227553aa3642069475e3a711ca065a9be67973 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Wed, 4 Oct 2023 22:12:13 -0700 Subject: [PATCH 11/21] Add changeset --- .changesets/docs_eh_docs_k8s_deployment.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changesets/docs_eh_docs_k8s_deployment.md diff --git a/.changesets/docs_eh_docs_k8s_deployment.md b/.changesets/docs_eh_docs_k8s_deployment.md new file mode 100644 index 0000000000..53806d5dcd --- /dev/null +++ b/.changesets/docs_eh_docs_k8s_deployment.md @@ -0,0 +1,5 @@ +### Updated documentation for deploying router ([PR #3943](https://github.com/apollographql/router/pull/3943)) + +Updated documentation for containerized router deployments, with guides and examples for [deploying on Kubernetes](https://www.apollographql.com/docs/router/containerization/kubernetes) and [running on Docker](https://www.apollographql.com/docs/router/containerization/docker). + +By [@shorgi](https://github.com/shorgi) in https://github.com/apollographql/router/pull/3943 From 1fcf343c1d17c9ca4b38618fcf2e486f47e39fa0 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Thu, 5 Oct 2023 11:15:34 -0700 Subject: [PATCH 12/21] Change to (shared) typical coprocessor config example --- docs/shared/coproc-typical-config.mdx | 47 +++++++++++++++++++ docs/source/containerization/kubernetes.mdx | 13 ++---- docs/source/customizations/coprocessor.mdx | 50 ++------------------- 3 files changed, 53 insertions(+), 57 deletions(-) create mode 100644 docs/shared/coproc-typical-config.mdx diff --git a/docs/shared/coproc-typical-config.mdx b/docs/shared/coproc-typical-config.mdx new file mode 100644 index 0000000000..a9812d47c3 --- /dev/null +++ b/docs/shared/coproc-typical-config.mdx @@ -0,0 +1,47 @@ +```yaml title="router.yaml" +coprocessor: + url: http://127.0.0.1:8081 # Required. Replace with the URL of your coprocessor's HTTP endpoint. + timeout: 2s # The timeout for all coprocessor requests. Defaults to 1 second (1s) + router: # This coprocessor hooks into the `RouterService` + request: # By including this key, the `RouterService` sends a coprocessor request whenever it first receives a client request. + headers: true # These boolean properties indicate which request data to include in the coprocessor request. All are optional and false by default. + body: false + context: false + sdl: false + path: false + method: false + response: # By including this key, the `RouterService` sends a coprocessor request whenever it's about to send response data to a client (including incremental data via @defer). + headers: true + body: false + context: false + sdl: false + status_code: false + supergraph: # This coprocessor hooks into the `SupergraphService` + request: # By including this key, the `SupergraphService` sends a coprocessor request whenever it first receives a client request. + headers: true # These boolean properties indicate which request data to include in the coprocessor request. All are optional and false by default. + body: false + context: false + sdl: false + method: false + response: # By including this key, the `SupergraphService` sends a coprocessor request whenever it's about to send response data to a client (including incremental data via @defer). + headers: true + body: false + context: false + sdl: false + status_code: false + subgraph: + all: + request: # By including this key, the `SubgraphService` sends a coprocessor request whenever it is about to make a request to a subgraph. + headers: true # These boolean properties indicate which request data to include in the coprocessor request. All are optional and false by default. + body: false + context: false + uri: false + method: false + service_name: false + response: # By including this key, the `SubgraphService` sends a coprocessor request whenever receives a subgraph response. + headers: true + body: false + context: false + service_name: false + status_code: false +``` diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index 0df6fd993e..2c7efab549 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -8,6 +8,7 @@ import ElasticNotice from '../../shared/elastic-notice.mdx'; import HelmShowOutput from '../../shared/helm-show-router-output.mdx'; import K8SManualConfig from '../../shared/k8s-manual-config.mdx'; import RouterCommonConfig from '../../shared/router-common-config.mdx'; +import CoprocTypicalConfig from '../../shared/coproc-typical-config.mdx'; Learn how to deploy the Apollo Router, for a self-hosted supergraph with GraphOS, on Kubernetes by using Helm charts. @@ -190,17 +191,9 @@ A deployed coprocessor has its own application image and container in the router To configure a coprocessor and its container for your deployed router through a YAML configuration file: * Create a YAML file, `my_values.yaml`, to contain additional values that override default values. -* Edit the file to configure a coprocessor for the router. For reference, follow the [typical](../../customizations/coprocessor#typical-configuration) and [minimal](../../customizations/coprocessor#minimal-configuration) configuration examples, and apply them to `router.configuration.coprocessor`. +* Edit the file to configure a coprocessor for the router. For reference, follow the [typical](../../customizations/coprocessor#typical-configuration) and [minimal](../../customizations/coprocessor#minimal-configuration) configuration examples, and apply them to `router.configuration.coprocessor`. For example, a typical configuration for a coprocessor: -```yaml title="my_values.yaml" -router: - configuration: - # minimal coprocessor configuration - coprocessor: - url: http://127.0.0.1:8081 # Replace with the URL of your coprocessor's HTTP endpoint. - router: - request: - headers: false + * Edit the file to add a container for the coprocessor. diff --git a/docs/source/customizations/coprocessor.mdx b/docs/source/customizations/coprocessor.mdx index 13d20c7fb0..fc9f20a547 100644 --- a/docs/source/customizations/coprocessor.mdx +++ b/docs/source/customizations/coprocessor.mdx @@ -3,6 +3,8 @@ title: External coprocessing in the Apollo Router description: Customize your router's behavior in any language --- +import CoprocTypicalConfig from '../../shared/coproc-typical-config.mdx'; + > ⚠️ **This is an [Enterprise feature](../enterprise-features/) of the Apollo Router.** It requires an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/). > > If your organization _doesn't_ currently have an Enterprise plan, you can test out this functionality by signing up for a free [Enterprise trial](/graphos/org/plans/#enterprise-trials). @@ -74,53 +76,7 @@ You configure external coprocessing in your router's [YAML config file](../confi This example configuration sends commonly used request and response details to your coprocessor (see the comments below for explanations of each field): -```yaml title="router.yaml" -coprocessor: - url: http://127.0.0.1:8081 # Required. Replace with the URL of your coprocessor's HTTP endpoint. - timeout: 2s # The timeout for all coprocessor requests. Defaults to 1 second (1s) - router: # This coprocessor hooks into the `RouterService` - request: # By including this key, the `RouterService` sends a coprocessor request whenever it first receives a client request. - headers: true # These boolean properties indicate which request data to include in the coprocessor request. All are optional and false by default. - body: false - context: false - sdl: false - path: false - method: false - response: # By including this key, the `RouterService` sends a coprocessor request whenever it's about to send response data to a client (including incremental data via @defer). - headers: true - body: false - context: false - sdl: false - status_code: false - supergraph: # This coprocessor hooks into the `SupergraphService` - request: # By including this key, the `SupergraphService` sends a coprocessor request whenever it first receives a client request. - headers: true # These boolean properties indicate which request data to include in the coprocessor request. All are optional and false by default. - body: false - context: false - sdl: false - method: false - response: # By including this key, the `SupergraphService` sends a coprocessor request whenever it's about to send response data to a client (including incremental data via @defer). - headers: true - body: false - context: false - sdl: false - status_code: false - subgraph: - all: - request: # By including this key, the `SubgraphService` sends a coprocessor request whenever it is about to make a request to a subgraph. - headers: true # These boolean properties indicate which request data to include in the coprocessor request. All are optional and false by default. - body: false - context: false - uri: false - method: false - service_name: false - response: # By including this key, the `SubgraphService` sends a coprocessor request whenever receives a subgraph response. - headers: true - body: false - context: false - service_name: false - status_code: false -``` + ### Minimal configuration From 82ff6980d76654f69636ba15cc0bda19e2b61010 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Thu, 5 Oct 2023 11:32:52 -0700 Subject: [PATCH 13/21] copyedit to address review comments --- docs/source/containerization/kubernetes.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index 2c7efab549..a2b30cd9b5 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -240,7 +240,7 @@ When [migrating from `@apollo/gateway` to the Apollo Router](../migrating-from-g experimental_http_max_request_bytes: 20000000 #20MB ``` -* The router's timeout is increased to accommodate slow subgraphs. Only HTTP 1.1 suport is enabled. +* The router's timeout is increased to accommodate subgraph operations with high latency. ```yaml title="values.yaml" router: @@ -249,7 +249,6 @@ router: router: timeout: 6min all: - experimental_enable_http2: false timeout: 5min ``` From 5f3e2711f38add59fb92d3f01207f9a98d01bb25 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Thu, 5 Oct 2023 14:06:30 -0700 Subject: [PATCH 14/21] Copyedit and address review comments --- docs/source/containerization/docker.mdx | 10 +++--- docs/source/containerization/kubernetes.mdx | 40 ++++++++------------- docs/source/containerization/overview.mdx | 4 +-- 3 files changed, 21 insertions(+), 33 deletions(-) diff --git a/docs/source/containerization/docker.mdx b/docs/source/containerization/docker.mdx index c42ed0ae7e..e3ce4e7258 100644 --- a/docs/source/containerization/docker.mdx +++ b/docs/source/containerization/docker.mdx @@ -1,12 +1,12 @@ --- -title: Run on Docker -description: Run the Apollo Router on Docker +title: Run in Docker +description: Run the Apollo Router in Docker --- import { Link } from "gatsby"; import ElasticNotice from '../../shared/elastic-notice.mdx'; -Follow examples in this guide to learn how to run an Apollo Router container image on Docker: +Follow examples in this guide to learn how to run an Apollo Router container image in Docker: * Run with default configuration. * Customize your configuration to override the default configuration. @@ -19,7 +19,7 @@ Follow examples in this guide to learn how to run an Apollo Router container ima > * The [documentation](https://docs.docker.com/engine/reference/run/) for the `docker run` command is a helpful reference for the examples in this guide. > * The exact image version to use is your choice depending on which release you wish to use. In the following examples, replace `` with your chosen version, for example `v1.32.0` -## Basic example running router with Docker +## Basic example running router in Docker To run the router, your Docker container must have the `APOLLO_GRAPH_REF` and `APOLLO_KEY` environment variables set to your graph's reference and ID, respectively. @@ -31,7 +31,7 @@ To run the router, your Docker container must have the `APOLLO_GRAPH_REF` and `A - Set your `APOLLO_GRAPH_REF` and `APOLLO_KEY` -Here's a basic example of running a router image with Docker (make sure to replace `` with whichever version you want to use, such as `v1.4.0`): +Here's a basic example of running a router image in Docker (make sure to replace `` with whichever version you want to use, such as `v1.4.0`): ```bash title="Docker" docker run -p 4000:4000 \ diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index a2b30cd9b5..6ecc821a51 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -1,6 +1,6 @@ --- -title: Deploy on Kubernetes -description: Self-hosted deployment of Apollo Router on Kubernetes +title: Deploy in Kubernetes +description: Self-hosted deployment of Apollo Router in Kubernetes --- import { Link } from 'gatsby'; @@ -10,7 +10,7 @@ import K8SManualConfig from '../../shared/k8s-manual-config.mdx'; import RouterCommonConfig from '../../shared/router-common-config.mdx'; import CoprocTypicalConfig from '../../shared/coproc-typical-config.mdx'; -Learn how to deploy the Apollo Router, for a self-hosted supergraph with GraphOS, on Kubernetes by using Helm charts. +Learn how to deploy the Apollo Router, for a self-hosted supergraph with GraphOS, in Kubernetes by using Helm charts. ```mermaid flowchart LR; @@ -96,9 +96,11 @@ Install the tools and provision the infrastructure for your Kubernetes cluster. > For example, see the [Setup from Apollo's Build a Supergraph tutorial](https://github.com/apollosolutions/build-a-supergraph/tree/main/01-setup#01---setup). It provides steps you can reference for gathering accounts and credentials for your cloud platform (GCP or AWS), provisioning resources, and deploying your subgraphs. -### Set up router +### Set up graph -Set up the router by following the [first six steps of the self-hosted router quickstart](/graphos/quickstart/self-hosted) (stopping when you reach step [7. Deploy your router and connect clients](https://www.apollographql.com/docs/graphos/quickstart/self-hosted/#7-deploy-your-router-and-connect-clients)). +Set up your self-hosted graph and get its [graph ref](../../configuration/overview/#apollo_graph_ref) and [API key](../../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 @@ -150,8 +152,11 @@ To enable metrics endpoints in your deployed router through a YAML configuration endpoint: ``` - * `router.telemetry.metrics.prometheus` was already configured but disabled (`enabled: false`) by default. This configuration sets `enabled: true`. - * `router.telemetry.metrics.otlp` is enabled by inclusion. + > ⚠️ **Note**: 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`. * 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`: @@ -163,24 +168,7 @@ To enable metrics endpoints in your deployed router through a YAML configuration The router supports [Rhai scripting](../../customizations/rhai) to add custom functionality. -To enable Rhai scripts in your deployed router through a YAML configuration file: - -* Create a YAML file, `my_values.yaml`, to contain additional values that override default values. -* Edit the file with values to enable Rhai scripts: - - ```yaml title="my_values.yaml" - router: - configuration: - rhai: - scripts: - main: - ``` - -* 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 - ``` +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 (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 @@ -231,7 +219,7 @@ helm install --namespace --set managedFederation.apiKey=" Date: Fri, 6 Oct 2023 09:01:17 -0700 Subject: [PATCH 15/21] Apply suggestions from code review Co-authored-by: Maria Elisabeth Schreiber --- docs/shared/helm-show-router-output.mdx | 2 +- docs/shared/router-common-config.mdx | 20 ++++++++++---------- docs/source/containerization/docker.mdx | 16 ++++++++-------- docs/source/containerization/kubernetes.mdx | 12 ++++++------ 4 files changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/shared/helm-show-router-output.mdx b/docs/shared/helm-show-router-output.mdx index 90516afd68..76fc662b22 100644 --- a/docs/shared/helm-show-router-output.mdx +++ b/docs/shared/helm-show-router-output.mdx @@ -27,7 +27,7 @@ router: managedFederation: # -- If using managed federation, the graph API key to identify router to Studio apiKey: - # -- If using managed federation, use existing Secret which stores the graph API key instead of creating a new one. + # -- If using managed federation, use an 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 variant of which graph to use diff --git a/docs/shared/router-common-config.mdx b/docs/shared/router-common-config.mdx index 4dda647bf1..46d1164ad2 100644 --- a/docs/shared/router-common-config.mdx +++ b/docs/shared/router-common-config.mdx @@ -3,17 +3,17 @@ # This is a YAML-formatted file. # Declare variables to be passed into your templates. -# Anything we set here applies to the in-house-router chart, and -# all configuration that we set here is pushed to all sub-charts -# (because of the way Helm works: -# https://helm.sh/docs/chart_template_guide/subcharts_and_globals/) +# Anything set here applies to the in-house-router chart, and +# all configuration that set here is pushed to all sub-charts +# because of the way Helm works: +# https://helm.sh/docs/chart_template_guide/subcharts_and_globals/ # Set fullnameOverride here for virtualservice to use fullnameOverride: router router: serviceAccount: - # We do that ourselves in permissions.yaml + # The service account is created permissions.yaml create: false name: router fullnameOverride: router @@ -30,12 +30,12 @@ router: timeout: 5min supergraph: introspection: true - # We are intentionally DISABLING DEFER SUPPORT in the Router until - # we are out of our transition period from the Gateway to the Router. + # this intentionally disables `@defer` support in the router until + # until the transition from the gateway to the router is complete. defer_support: false listen: 0.0.0.0:80 path: /graphql - # We keep subgraph errors on in our own environment, always. + # We recommend keeping subgraph errors on in your own environment, always. include_subgraph_errors: all: true cors: @@ -101,7 +101,7 @@ router: endpoint: "${env.NODE_IP}:4317" # Enabling this both includes the `apollo-trace-id` value on the HTTP response, # but also creates "Response Header" nodes in the trace that we send to Studio. - # This should allow us to correlate traces from Studio to logs: + # This allows us to correlate traces from Studio to logs: # https://www.apollographql.com/docs/router/configuration/tracing/#trace-id tracing: propagation: @@ -166,7 +166,7 @@ router: extraVolumes: - name: rhai-volume configMap: - # Provide the name of the ConfigMap containing the files you want + # Provide the name of the ConfigMap containing the files # to add to the container name: rhai-config probes: diff --git a/docs/source/containerization/docker.mdx b/docs/source/containerization/docker.mdx index e3ce4e7258..18d9bee38c 100644 --- a/docs/source/containerization/docker.mdx +++ b/docs/source/containerization/docker.mdx @@ -1,23 +1,23 @@ --- title: Run in Docker -description: Run the Apollo Router in Docker +description: Run the Apollo Router container image in Docker --- import { Link } from "gatsby"; import ElasticNotice from '../../shared/elastic-notice.mdx'; -Follow examples in this guide to learn how to run an Apollo Router container image in Docker: +This guide provides the following examples of running an Apollo Router container image in Docker: * Run with default configuration. -* Customize your configuration to override the default configuration. +* Customizing your configuration to override the default configuration. * Debug your containerized router. -* Build your own router Docker image. +* Building your own router Docker image. > **Notes** > * The [documentation](https://docs.docker.com/engine/reference/run/) for the `docker run` command is a helpful reference for the examples in this guide. -> * The exact image version to use is your choice depending on which release you wish to use. In the following examples, replace `` with your chosen version, for example `v1.32.0` +> * The exact image version to use depends on which release you wish to use. In the following examples, replace `` with your chosen version, for example `v1.32.0`. ## Basic example running router in Docker @@ -31,7 +31,7 @@ To run the router, your Docker container must have the `APOLLO_GRAPH_REF` and `A - Set your `APOLLO_GRAPH_REF` and `APOLLO_KEY` -Here's a basic example of running a router image in Docker (make sure to replace `` with whichever version you want to use, such as `v1.4.0`): +Here's a basic example of running a router image in Docker. Make sure to replace `` with whichever version you want to use, such as `v1.4.0`. ```bash title="Docker" docker run -p 4000:4000 \ @@ -43,7 +43,7 @@ docker run -p 4000:4000 \ This command downloads your supergraph schema from Apollo and uses a default configuration that listens for connections on port `4000`. -For more complex configuration (such as overriding subgraph URLs or propagating headers), see [Configuring the Apollo Router](../configuration/overview/). +For more complex configurations, such as overriding subgraph URLs or propagating headers, see [Configuring the Apollo Router](../configuration/overview/). ## Override the configuration @@ -113,7 +113,7 @@ docker run -p 4000:4000 \ ghcr.io/apollographql/router:-debug ``` -The router will run under the control of heaptrack. The heaptrack output will be saved to the `/data` directory. The output can be analyzed directly using `heaptrack_gui` or `heaptrack_print` or shared with Apollo support. +The router runs under the control of [heaptrack](https://github.com/KDE/heaptrack). The heaptrack output is saved to the `/data` directory. The output can be analyzed directly using `heaptrack_gui` or `heaptrack_print` or shared with Apollo support. ## Specifying the supergraph diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index 6ecc821a51..c012e803d8 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -10,7 +10,7 @@ import K8SManualConfig from '../../shared/k8s-manual-config.mdx'; import RouterCommonConfig from '../../shared/router-common-config.mdx'; import CoprocTypicalConfig from '../../shared/coproc-typical-config.mdx'; -Learn how to deploy the Apollo Router, for a self-hosted supergraph with GraphOS, in Kubernetes by using Helm charts. +Learn how to deploy a self-hosted Apollo Router in Kubernetes using Helm charts. ```mermaid flowchart LR; @@ -29,7 +29,7 @@ flowchart LR; class clients secondary; ``` -The following guides provide you the steps to: +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. @@ -48,12 +48,12 @@ You customize a deployed router with the same [command-line options and YAML con ## Basic deployment -Follow this guide to deploy the Apollo Router by using Helm to install the basic chart provided with each router release. +Follow this guide to deploy the Apollo 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 (supergraph) [HTTP server](../../configuration/overview/#listen-address), [health check endpoint](../../configuration/health-checks), and [metrics endpoint](../../configuration/metrics). -* Command-line argument to enable [hot reloading of the router](../../configuration/overview/#--hr----hot-reload). +* A command-line argument to enable [hot reloading of the router](../../configuration/overview/#--hr----hot-reload). * A single replica. @@ -94,13 +94,13 @@ helm show values oci://ghcr.io/apollographql/helm-charts/router Install the tools and provision the infrastructure for your Kubernetes cluster. -> For example, see the [Setup from Apollo's Build a Supergraph tutorial](https://github.com/apollosolutions/build-a-supergraph/tree/main/01-setup#01---setup). It provides steps you can reference for gathering accounts and credentials for your cloud platform (GCP or AWS), provisioning resources, and deploying your subgraphs. +For an example, see the [Setup from Apollo's Build a Supergraph tutorial](https://github.com/apollosolutions/build-a-supergraph/tree/main/01-setup#01---setup). It provides steps you can reference for gathering accounts and credentials for your cloud platform (GCP or AWS), provisioning resources, and deploying your subgraphs. ### Set up graph Set up your self-hosted graph and get its [graph ref](../../configuration/overview/#apollo_graph_ref) and [API key](../../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). +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 From fb16ac67846c75e83c08c4abc005b7054d104060 Mon Sep 17 00:00:00 2001 From: Edward Huang <18322228+shorgi@users.noreply.github.com> Date: Fri, 6 Oct 2023 13:14:11 -0700 Subject: [PATCH 16/21] Apply suggestions from code review Co-authored-by: Maria Elisabeth Schreiber --- docs/source/containerization/overview.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/source/containerization/overview.mdx b/docs/source/containerization/overview.mdx index 76e14966b4..b84df29318 100644 --- a/docs/source/containerization/overview.mdx +++ b/docs/source/containerization/overview.mdx @@ -5,7 +5,7 @@ description: Run Apollo Router images in containers import ElasticNotice from '../../shared/elastic-notice.mdx'; -Apollo provides container images of the Apollo Router. Containerizing the Apollo Router enables it to be run in a cluster and gain all its advantages of portability, scalability, and high availability. Containers can also simplify and speed up local development. +Apollo provides container images of the Apollo Router. By containerizing the router, you can run it in a cluster and leverage the portability, scalability, and high availability benefits of containerization. Containers can also simplify and speed up local development. @@ -13,13 +13,13 @@ Apollo provides container images of the Apollo Router. Containerizing the Apollo Apollo provides container images of the Apollo Router [on GitHub](https://github.com/apollographql/router/pkgs/container/router) in its container repository. The router images are based on [debian:bullseye-slim](https://hub.docker.com/_/debian/), which is designed to provide constrained, secure, and small images. -Each release of the Apollo Router includes both default (production) and debug images. While each image for a release contains the same build, the debug images have helpful debugging utilities installed and run the router under the control of heaptrack (https://github.com/KDE/heaptrack). +Each release of the Apollo Router includes both default (production) and debug images. While each image for a release contains the same build, the debug images have helpful debugging utilities installed and run the router under the control of [heaptrack](https://github.com/KDE/heaptrack). -The layout of a router image file: +A router image has the following layout: -* A `/dist` directory, containing the router executable and licensing details. -* A `dist/config` directory, containing a default configuration file, `router.yaml`. -* A `/dist/schema` directory for convenient mounting of a locally defined supergraph schema. +* A `/dist` directory containing the router executable and licensing details +* A `dist/config` directory containing a default configuration file, `router.yaml` +* A `/dist/schema` directory for conveniently mounting a locally defined supergraph schema ## Next steps From 6ddf6fbb5f16dbf6154f4cfc067a2eee6e534c18 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Fri, 6 Oct 2023 13:49:51 -0700 Subject: [PATCH 17/21] address review comments --- docs/source/containerization/docker.mdx | 64 ++++++++++----------- docs/source/containerization/kubernetes.mdx | 8 +-- 2 files changed, 32 insertions(+), 40 deletions(-) diff --git a/docs/source/containerization/docker.mdx b/docs/source/containerization/docker.mdx index 18d9bee38c..506f208e74 100644 --- a/docs/source/containerization/docker.mdx +++ b/docs/source/containerization/docker.mdx @@ -8,37 +8,29 @@ import ElasticNotice from '../../shared/elastic-notice.mdx'; This guide provides the following examples of running an Apollo Router container image in Docker: -* Run with default configuration. +* Running with default configuration. * Customizing your configuration to override the default configuration. -* Debug your containerized router. +* Debugging your containerized router. * Building your own router Docker image. - - -> **Notes** -> * The [documentation](https://docs.docker.com/engine/reference/run/) for the `docker run` command is a helpful reference for the examples in this guide. -> * The exact image version to use depends on which release you wish to use. In the following examples, replace `` with your chosen version, for example `v1.32.0`. - -## Basic example running router in Docker +The [documentation](https://docs.docker.com/engine/reference/run/) for the `docker run` command is a helpful reference for the examples in this guide. -To run the router, your Docker container must have the `APOLLO_GRAPH_REF` and `APOLLO_KEY` environment variables set to your graph's reference and ID, respectively. +The exact image version to use depends on which release you wish to use. In the following examples, replace `` with your chosen version, for example `v1.32.0`. -- The reference of your graph in Apollo's registry (``). -- The [graph API key](https://www.apollographql.com/docs/studio/api-keys/#graph-api-keys) that Apollo Server should use to authenticate with Apollo Studio. You can set this with the `APOLLO_KEY` environment variable. (``). + -- `graphRef`: A reference of your graph in Apollo's registry, such as `graph-id@my-variant` or just `graph-id`. You can set this with the `APOLLO_GRAPH_REF` environment variable. -- `graphId`: The ID of your graph in Apollo's registry. You can set this with the `APOLLO_GRAPH_ID` environment variable. You may not specify this if you specify the graph ref. +## Basic example running router in Docker -- Set your `APOLLO_GRAPH_REF` and `APOLLO_KEY` +To run the router, your Docker container must have the [`APOLLO_GRAPH_REF`](../../configuration/overview#apollo_graph_ref) and [`APOLLO_KEY`](configuration/overview#apollo_key) environment variables set to your graph ref and API key, respectively. -Here's a basic example of running a router image in Docker. Make sure to replace `` with whichever version you want to use, such as `v1.4.0`. +Here's a basic example of running a router image in Docker. Make sure to replace `` with whichever version you want to use, such as `v1.32.0`. ```bash title="Docker" docker run -p 4000:4000 \ - --env APOLLO_GRAPH_REF="" \ - --env APOLLO_KEY="" \ + --env APOLLO_GRAPH_REF="" \ + --env APOLLO_KEY="" \ --rm \ - ghcr.io/apollographql/router: + ghcr.io/apollographql/router: ``` This command downloads your supergraph schema from Apollo and uses a default configuration that listens for connections on port `4000`. @@ -47,40 +39,42 @@ For more complex configurations, such as overriding subgraph URLs or propagating ## Override the configuration -Our default Docker images include a basic configuration which can be seen [in our repository](https://github.com/apollographql/router/blob/main/dockerfiles/router.yaml). Inside the container, this file is located at `/dist/config/router.yaml`. +Apollo's default Docker images include a [basic router configuration](https://github.com/apollographql/router/blob/main/dockerfiles/router.yaml). Inside the container, this file is located at `/dist/config/router.yaml`. -If you wish to override the default configuration, it is important to consider and preserve aspects of the default configuration. In particular, it is generally important for the Router to bind to the special "listening address" of `0.0.0.0` (i.e., "all interfaces") to ensure the Router is exposed on a the network interface accessible outside of the local container; without this configuration, the Router will only listen on `localhost`. +If you wish to override the default configuration, it is important preserve aspects of the default configuration. In particular, it is generally important for the router to bind to and listen on the special address of `0.0.0.0` (for all interfaces) to ensure it's exposed on a network interface that's accessible outside of the local container. Without this configuration, the router will only listen on `localhost`. -You can provide your own configuration from the host environment to the Router by mounting your configuration to `/dist/config/router.yaml`, as follows: +You can provide your own configuration from the host environment to the router by mounting your configuration to `/dist/config/router.yaml` as follows: ```bash {4} docker run -p 4000:4000 \ - --env APOLLO_GRAPH_REF="" \ - --env APOLLO_KEY="" \ + --env APOLLO_GRAPH_REF="" \ + --env APOLLO_KEY="" \ --mount "type=bind,source=/home/user/router.yaml,target=/dist/config/router.yaml" \ --rm \ - ghcr.io/apollographql/router: + ghcr.io/apollographql/router: ``` -> Note: Both local and container paths must be specified as absolute paths. +> **Note:** Both local and container paths must be specified as absolute paths. -In this case we are mounting a file from the host system (`/home/user/router.yaml`) in place of the default configuration provided in the image at `/dist/config/router.yaml`. +In this example we are mounting a file from the host system (`/home/user/router.yaml`) in place of the default configuration provided in the image at `/dist/config/router.yaml`. -## Passing command-line arguments to the Router binary +## Passing command-line arguments to the router binary -By default, the `router` command invoked inside the published container does run not set any of the [available command-line options](../configuration/overview#command-line-options). If you want to set any of the available options, pass the desired options at end of the `docker run` command. For example, to start the Router using the `--log debug` argument, you can use the following `docker run` command: +By default, the `router` command invoked inside the published container doesn't set any of the [available command-line options](../configuration/overview#command-line-options). If you want to set any of the available options, pass the desired options at end of the `docker run` command. + +For example, to start the router using the `--log debug` argument, you can use the following `docker run` command: ```bash {5} docker run -p 4000:4000 \ - --env APOLLO_GRAPH_REF="" \ - --env APOLLO_KEY="" \ + --env APOLLO_GRAPH_REF="" \ + --env APOLLO_KEY="" \ --rm \ - ghcr.io/apollographql/router: --log debug + ghcr.io/apollographql/router: --log debug ``` ## Debugging your container -It's easy to debug your container by changing the `entrypoint` +You can debug your container by setting the `entrypoint` in a `docker run` command: ```bash docker run -p 4000:4000 \ @@ -100,7 +94,7 @@ dist# exit exit ``` -In this case, we've added interactive and tty flags and changed the entrypoint of the image to be a shell. +In this example, we've added both interactive and tty flags, and we've changed the entrypoint of the image to be a bash shell. ## Running the debug container to investigate memory issues @@ -117,7 +111,7 @@ The router runs under the control of [heaptrack](https://github.com/KDE/heaptrac ## Specifying the supergraph -If we don't want to use [Apollo Uplink](/federation/managed-federation/uplink/) to retrieve our subgraph, we can manually specify the details. +If you don't want to automatically update your supergraph via [Apollo Uplink](/federation/managed-federation/uplink/), or you don't have connectivity to access Apollo Uplink from your environment, you can manually specify the details of your supergraph in a `docker run` command: ```bash docker run -p 4000:4000 \ diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index c012e803d8..c1e3e0dbab 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -6,8 +6,6 @@ description: Self-hosted deployment of Apollo Router in Kubernetes import { Link } from 'gatsby'; import ElasticNotice from '../../shared/elastic-notice.mdx'; import HelmShowOutput from '../../shared/helm-show-router-output.mdx'; -import K8SManualConfig from '../../shared/k8s-manual-config.mdx'; -import RouterCommonConfig from '../../shared/router-common-config.mdx'; import CoprocTypicalConfig from '../../shared/coproc-typical-config.mdx'; Learn how to deploy a self-hosted Apollo Router in Kubernetes using Helm charts. @@ -16,7 +14,7 @@ Learn how to deploy a self-hosted Apollo Router in Kubernetes using Helm charts. flowchart LR; clients(Clients); subgraph "Kubernetes cluster"; - proxy(["Proxy"]) + lb(["Load Balancer"]) router_a(["Apollo Router"]); coproc_a(["Coprocessor"]); router_b(["Apollo Router"]); @@ -24,8 +22,8 @@ flowchart LR; router_a <-.-> coproc_a; router_b <-.-> coproc_b; end; - clients -.->|Query| proxy; - proxy -.-> router_a & router_b; + clients -.->|Query| lb; + lb -.-> router_a & router_b; class clients secondary; ``` From bc7351d56d540148fa9da0faa73d9e9c0a1fd722 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Fri, 6 Oct 2023 15:36:29 -0700 Subject: [PATCH 18/21] address review comments --- docs/source/containerization/docker.mdx | 9 ++-- docs/source/containerization/kubernetes.mdx | 52 +++++++++++---------- 2 files changed, 33 insertions(+), 28 deletions(-) diff --git a/docs/source/containerization/docker.mdx b/docs/source/containerization/docker.mdx index 506f208e74..18685eb642 100644 --- a/docs/source/containerization/docker.mdx +++ b/docs/source/containerization/docker.mdx @@ -8,9 +8,10 @@ import ElasticNotice from '../../shared/elastic-notice.mdx'; This guide provides the following examples of running an Apollo Router container image in Docker: -* Running with default configuration. +* Running a basic example with default configuration. * Customizing your configuration to override the default configuration. * Debugging your containerized router. +* Manually specifying a supergraph for your router. * Building your own router Docker image. The [documentation](https://docs.docker.com/engine/reference/run/) for the `docker run` command is a helpful reference for the examples in this guide. @@ -60,9 +61,9 @@ In this example we are mounting a file from the host system (`/home/user/router. ## Passing command-line arguments to the router binary -By default, the `router` command invoked inside the published container doesn't set any of the [available command-line options](../configuration/overview#command-line-options). If you want to set any of the available options, pass the desired options at end of the `docker run` command. +By default, the `router` command invoked inside the published container doesn't set any of the [available command-line options](../configuration/overview#command-line-options). To set them, append the desired option(s) to the `docker run` command. -For example, to start the router using the `--log debug` argument, you can use the following `docker run` command: +For example, to start the router using the `--log debug` option, use the following `docker run` command with the option added at the end: ```bash {5} docker run -p 4000:4000 \ @@ -96,7 +97,7 @@ exit In this example, we've added both interactive and tty flags, and we've changed the entrypoint of the image to be a bash shell. -## Running the debug container to investigate memory issues +### Running the debug container to investigate memory issues ```bash docker run -p 4000:4000 \ diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index c1e3e0dbab..3c56869a06 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -177,20 +177,24 @@ A deployed coprocessor has its own application image and container in the router To configure a coprocessor and its container for your deployed router through a YAML configuration file: * Create a YAML file, `my_values.yaml`, to contain additional values that override default values. -* Edit the file to configure a coprocessor for the router. For reference, follow the [typical](../../customizations/coprocessor#typical-configuration) and [minimal](../../customizations/coprocessor#minimal-configuration) configuration examples, and apply them to `router.configuration.coprocessor`. For example, a typical configuration for a coprocessor: +* Edit the file to configure a coprocessor for the router. For reference, follow the [typical](../../customizations/coprocessor#typical-configuration) and [minimal](../../customizations/coprocessor#minimal-configuration) configuration examples, and apply them to `router.configuration.coprocessor`. + + + + * Edit the file 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 -``` + ```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 + ``` * 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`: @@ -228,21 +232,21 @@ When [migrating from `@apollo/gateway` to the Apollo Router](../migrating-from-g * 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 -``` + ```yaml title="values.yaml" + router: + configuration: + traffic_shaping: + router: + timeout: 6min + all: + timeout: 5min + ``` * 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 -``` + ```yaml title="values.yaml" + router: + configuration: + include_subgraph_errors: + all: true + ``` From 5a089ef72cd8659688facbade38da977c9646326 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Mon, 9 Oct 2023 06:45:50 -0700 Subject: [PATCH 19/21] address review comment --- docs/source/containerization/docker.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/containerization/docker.mdx b/docs/source/containerization/docker.mdx index 18685eb642..7b260424ed 100644 --- a/docs/source/containerization/docker.mdx +++ b/docs/source/containerization/docker.mdx @@ -150,4 +150,4 @@ Usage: build_docker_image.sh [-b [-r ]] [-d] [] build_docker_image.sh -d v0.9.1 ``` -The script has to be run from the `dockerfiles/diy` directory because it makes assumptions about the relative availability of various files. The example uses [debian:bullseye-slim image](https://hub.docker.com/_/debian/) for the final image build. Feel free to modify the script to use images which better suit your own needs, but be careful if using the [-d] flag since it makes the assumption that there is a `heaptrack` package available to install. +The example uses [debian:bullseye-slim image](https://hub.docker.com/_/debian/) for the final image build. Feel free to modify the script to use images which better suit your own needs, but be careful if using the `-d` flag because it makes the assumption that there is a `heaptrack` package available to install. From 2cfd2114cb011684aa1ba692681c049c40698253 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Mon, 9 Oct 2023 07:17:49 -0700 Subject: [PATCH 20/21] address review comments --- docs/shared/helm-show-router-output.mdx | 2 +- docs/source/containerization/kubernetes.mdx | 110 +++++++++++--------- 2 files changed, 59 insertions(+), 53 deletions(-) diff --git a/docs/shared/helm-show-router-output.mdx b/docs/shared/helm-show-router-output.mdx index 76fc662b22..d0f7035d69 100644 --- a/docs/shared/helm-show-router-output.mdx +++ b/docs/shared/helm-show-router-output.mdx @@ -10,7 +10,7 @@ replicaCount: 1 # -- See https://www.apollographql.com/docs/router/configuration/overview/#yaml-config-file for yaml structure router: configuration: - supergraph: + supergraph: # HTTP server listen: 0.0.0.0:80 health_check: listen: 0.0.0.0:8088 diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index 3c56869a06..f6ecb57ebc 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -32,7 +32,7 @@ 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 migrate from a gateway to the router. +* Choose chart values that best suit migration from a gateway to the router. @@ -50,7 +50,7 @@ Follow this guide to deploy the Apollo Router using Helm to install the basic ch 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 (supergraph) [HTTP server](../../configuration/overview/#listen-address), [health check endpoint](../../configuration/health-checks), and [metrics endpoint](../../configuration/metrics). +* Default container ports for the router's [HTTP server](../../configuration/overview/#listen-address), [health check endpoint](../../configuration/health-checks), and [metrics endpoint](../../configuration/metrics). * A command-line argument to enable [hot reloading of the router](../../configuration/overview/#--hr----hot-reload). * A single replica. @@ -68,25 +68,25 @@ helm show values oci://ghcr.io/apollographql/helm-charts/router ### Set up Helm -* Install [Helm](https://helm.sh/docs/intro/install/) **version 3.x**. The Apollo Router's Helm chart requires Helm v3.x. +1. Install [Helm](https://helm.sh/docs/intro/install/) **version 3.x**. The Apollo 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). + > ⚠️ 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). -* Log in with Helm to the Apollo container registry in GitHub. +1. Log in with Helm to the Apollo container registry in GitHub. - * Get a GitHub OCI token and save it in an environment variable, `GITHUB_OCI_TOKEN`. For reference, follow the guide for [authenticating to the GitHub container registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry). + * Get a GitHub OCI token and save it in an environment variable, `GITHUB_OCI_TOKEN`. For reference, follow the guide for [authenticating to the GitHub container registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry). - * Log in with the `helm registry login` command, using your saved `GITHUB_OCI_TOKEN` and GitHub username: + * Log in with the `helm registry login` command, using your saved `GITHUB_OCI_TOKEN` and GitHub username: - ```bash - echo ${GITHUB_OCI_TOKEN} | helm registry login -u --password-stdin ghcr.io - ``` + ```bash + echo ${GITHUB_OCI_TOKEN} | helm registry login -u --password-stdin ghcr.io + ``` -* After logging in, verify your access to the registry by showing the latest router chart values with the `helm show values` command: +1. After logging in, verify your access to 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 - ``` + ```bash + helm show values oci://ghcr.io/apollographql/helm-charts/router + ``` ### Set up cluster @@ -109,13 +109,13 @@ helm install --namespace --set managedFederation.apiKey="`. 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 @@ -129,44 +129,44 @@ helm list --namespace ## Deploy with metrics endpoints -The router supports [metrics endpoints for Prometheus and OTLP](../../configuration/metrics)(OpenTelemetry protocol). A [basic deployment](#basic-deployment) doesn't enable metrics endpoints, because the router chart disables both Prometheus (explicitly) and OTLP (by omission). +The router supports [metrics endpoints for Prometheus and OpenTelemetry protocol (OTLP)](../../configuration/metrics). 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: -* Create a YAML file, `my_values.yaml`, to contain additional values that override default values. -* Edit the file with values 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: - ``` +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: + ``` - > ⚠️ **Note**: Although this example enables both Prometheus and OTLP, in practice it's common to enable only one endpoint. + > ⚠️ **Note**: 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`. + * `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`. -* 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`: +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 - ``` + ```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](../../customizations/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 (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. +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 @@ -176,8 +176,8 @@ A deployed coprocessor has its own application image and container in the router To configure a coprocessor and its container for your deployed router through a YAML configuration file: -* Create a YAML file, `my_values.yaml`, to contain additional values that override default values. -* Edit the file to configure a coprocessor for the router. For reference, follow the [typical](../../customizations/coprocessor#typical-configuration) and [minimal](../../customizations/coprocessor#minimal-configuration) configuration examples, and apply them to `router.configuration.coprocessor`. +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](../../customizations/coprocessor#typical-configuration) and [minimal](../../customizations/coprocessor#minimal-configuration) configuration examples, and apply them to `router.configuration.coprocessor`. @@ -185,7 +185,7 @@ To configure a coprocessor and its container for your deployed router through a -* Edit the file to add a container for the coprocessor. +1. Edit `my_values.yaml` to add a container for the coprocessor. ```yaml title="my_values.yaml" extraContainers: @@ -196,7 +196,7 @@ To configure a coprocessor and its container for your deployed router through a env: [] # array of environment variables ``` -* 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`: +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 @@ -207,7 +207,7 @@ To configure a coprocessor and its container for your deployed router through a 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 chart while adding new environment-specific values. +- A unique **environment** file per environment, which includes and overrides the values from the common file while adding new environment-specific values. In a `helm install` command, each `--values ` option is applied in the order within the command. Therefore, a common file must be set before an environment file in the `helm install` command, so that the environment file's values are applied last and override the commond file's values as intended. @@ -221,7 +221,9 @@ helm install --namespace --set managedFederation.apiKey=" Date: Mon, 9 Oct 2023 07:19:29 -0700 Subject: [PATCH 21/21] Apply suggestions from code review Co-authored-by: Maria Elisabeth Schreiber --- docs/source/containerization/kubernetes.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index f6ecb57ebc..1dee2c33a0 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -209,9 +209,9 @@ To support your different deployment configurations for different environments ( - 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. -In a `helm install` command, each `--values ` option is applied in the order within the command. Therefore, a common file must be set before an environment file in the `helm install` command, so that the environment file's values are applied last and override the commond file's values as intended. +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, deploy with a `common_values.yaml` file applied first and then a `prod_values.yaml` file: +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