Kubernetes Quickstart
Learn how to deploy a self-hosted router in Kubernetes using Helm charts
Use the Operator when you need:
- Production-grade deployments with declarative configuration management
- Simplified management of multiple routers, supergraphs, and subgraphs
- Support for complex architectures including single-cluster, multi-cluster, and hybrid configurations
- Integration with existing CI/CD workflows through deploy-only patterns
This guide uses Helm charts to deploy a self-hosted router in Kubernetes. Using Helm is suitable for quick deployments, testing, or when you prefer direct Helm chart management.
This guide shows how to:
Get the router Helm chart from the Apollo container repository.
Deploy a router with a basic Helm chart.
Prerequisites
A GraphOS graph set up in your Apollo account. If you don't have a graph, you can create one in the GraphOS Studio.
Helm version 3.x or higher installed on your local machine.
A Kubernetes cluster with access to the internet.
GraphOS graph
Set up your self-hosted graph and get its graph ref and API key.
If you need a guide to set up your graph, you can follow the self-hosted router quickstart and complete step 1 (Set up Apollo tools), step 4 (Obtain your subgraph schemas), and step 5 (Publish your subgraph schemas).
Kubernetes cluster
If you don't have a Kubernetes cluster, you can set one up using kind or minikube locally, or by referring to your cloud provider's documentation.
Quickstart
To deploy the router, run the helm install command with an argument for the router's OCI image URL. Optionally, you can add arguments for the values.yaml configuration file and/or additional arguments to override specific configuration values.
1helm install <name_for_install> --namespace apollo-router --set managedFederation.apiKey="<graph-api-key>" --set managedFederation.graphRef="<graph-ref>" oci://ghcr.io/apollographql/helm-charts/routerThe necessary arguments for specific configuration values:
--set managedFederation.graphRef="<graph-ref>": The reference to your managed graph (id@variant), the same value as theAPOLLO_GRAPH_REFenvironment variable.--set managedFederation.apiKey="<graph-api-key>": The API key to your managed graph, the same value as theAPOLLO_KEYenvironment variable.
Some optional but recommended arguments:
--namespace <router-namespace>. The namespace scope for this deployment.--version <router-version>. The version of the router to deploy. If not specified byhelm install, the latest version is installed.
Verify deployment
Verify that your router is one of the deployed releases with the helm list command. If you deployed with the --namespace <router-namespace> option, you can list only the releases within your namespace:
1helm list --namespace <router-namespace>Deployed architecture
The default deployed architecture will be:
Router Helm chart configuration
Apollo provides an application Helm chart with each release of Apollo Router Core in GitHub. Since the router version v0.14.0, Apollo has released the router Helm chart as an Open Container Initiative (OCI) image in the GitHub container registry.
oci://ghcr.io/apollographql/helm-charts/router and tagged with the applicable router release version. For example, router version v2.3.0's Helm chart would be oci://ghcr.io/apollographql/helm-charts/router:2.3.0.You customize a deployed router with the same command-line options and YAML configuration options using different Helm CLI options and YAML keys through a values file.
Each router chart has a defult values.yaml file with router and deployment settings. The released, unedited file has a few explicit settings, including:
Default container ports for the router's HTTP server, health check endpoint, and metrics endpoint.
A command-line argument to enable hot reloading of the router.
A single replica.
Click to expand values.yaml for router v2.3.0
helm show command:1helm show values oci://ghcr.io/apollographql/helm-charts/router1# Default values for router.
2# This is a YAML-formatted file.
3# Declare variables to be passed into your templates.
4
5replicaCount: 1
6
7# -- See https://www.apollographql.com/docs/graphos/reference/router/configuration#yaml-config-file for yaml structure
8router:
9 configuration:
10 supergraph:
11 listen: 0.0.0.0:4000
12 health_check:
13 listen: 0.0.0.0:8088
14
15 args:
16 - --hot-reload
17
18managedFederation:
19 # -- If using managed federation, the graph API key to identify router to Studio
20 apiKey:
21 # -- If using managed federation, use existing Secret which stores the graph API key instead of creating a new one.
22 # If set along `managedFederation.apiKey`, a secret with the graph API key will be created using this parameter as name
23 existingSecret:
24 # -- If using managed federation, the name of the key within the existing Secret which stores the graph API key.
25 # If set along `managedFederation.apiKey`, a secret with the graph API key will be created using this parameter as key, defaults to using a key of `managedFederationApiKey`
26 existingSecretKeyRefKey:
27 # -- If using managed federation, the variant of which graph to use
28 graphRef: ""
29
30# This should not be specified in values.yaml. It's much simpler to use --set-file from helm command line.
31# e.g.: helm ... --set-file supergraphFile="location of your supergraph file"
32supergraphFile:
33
34# An array of extra environmental variables
35# Example:
36# extraEnvVars:
37# - name: APOLLO_ROUTER_SUPERGRAPH_PATH
38# value: /etc/apollo/supergraph.yaml
39# - name: APOLLO_ROUTER_LOG
40# value: debug
41#
42extraEnvVars: []
43extraEnvVarsCM: ""
44extraEnvVarsSecret: ""
45
46# An array of extra VolumeMounts
47# Example:
48# extraVolumeMounts:
49# - name: rhai-volume
50# mountPath: /dist/rhai
51# readonly: true
52extraVolumeMounts: []
53
54# An array of extra Volumes
55# Example:
56# extraVolumes:
57# - name: rhai-volume
58# configMap:
59# name: rhai-config
60#
61extraVolumes: []
62
63image:
64 repository: ghcr.io/apollographql/router
65 pullPolicy: IfNotPresent
66 # Overrides the image tag whose default is the chart appVersion.
67 tag: ""
68
69containerPorts:
70 # -- If you override the port in `router.configuration.server.listen` then make sure to match the listen port here
71 http: 4000
72 # -- For exposing the metrics port when running a serviceMonitor for example
73 metrics: 9090
74 # -- For exposing the health check endpoint
75 health: 8088
76
77# -- An array of extra containers to include in the router pod
78# Example:
79# extraContainers:
80# - name: coprocessor
81# image: acme/coprocessor:1.0
82# ports:
83# - containerPort: 4001
84extraContainers: []
85
86# -- An array of init containers to include in the router pod
87# Example:
88# initContainers:
89# - name: init-myservice
90# image: busybox:1.28
91# command: ["sh"]
92initContainers: []
93
94# -- A map of extra labels to apply to the resources created by this chart
95# Example:
96# extraLabels:
97# label_one_name: "label_one_value"
98# label_two_name: "label_two_value"
99extraLabels: {}
100
101lifecycle: {}
102# preStop:
103# exec:
104# command:
105# - /bin/bash
106# - -c
107# - sleep 10
108
109imagePullSecrets: []
110nameOverride: ""
111fullnameOverride: ""
112
113serviceAccount:
114 # Specifies whether a service account should be created
115 create: true
116 # Annotations to add to the service account
117 annotations: {}
118 # The name of the service account to use.
119 # If not set and create is true, a name is generated using the fullname template
120 name: ""
121
122podAnnotations: {}
123deploymentAnnotations: {}
124
125podSecurityContext:
126 {}
127 # fsGroup: 2000
128
129securityContext:
130 {}
131 # capabilities:
132 # drop:
133 # - ALL
134 # readOnlyRootFilesystem: true
135 # runAsNonRoot: true
136 # runAsUser: 1000
137
138service:
139 type: ClusterIP
140 port: 80
141 annotations: {}
142 targetport: http
143
144serviceMonitor:
145 enabled: false
146
147ingress:
148 enabled: false
149 className: ""
150 annotations: {}
151 # kubernetes.io/ingress.class: nginx
152 # kubernetes.io/tls-acme: "true"
153 hosts:
154 - host: chart-example.local
155 paths:
156 - path: /
157 pathType: ImplementationSpecific
158 tls: []
159 # - secretName: chart-example-tls
160 # hosts:
161 # - chart-example.local
162
163# set to true to enable istio's virtualservice
164virtualservice:
165 enabled: false
166 # namespace: ""
167 # gatewayName: "" # Deprecated in favor of gatewayNames
168 # gatewayNames: []
169 # - "gateway-1"
170 # - "gateway-2"
171 # Hosts: "" # configurable but will default to '*'
172 # - somehost.domain.com
173 # http:
174 # main:
175 # # set enabled to true to add
176 # # the default matcher of `exact: "/" or prefix: "/graphql"`
177 # # with the <$fullName>.<.Release.Namespace>.svc.cluster.local destination
178 # enabled: true
179 # # use additionals to provide your custom virtualservice rules
180 # additionals: []
181 # - name: "default-nginx-routes"
182 # match:
183 # - uri:
184 # prefix: "/foo"
185 # rewrite:
186 # uri: /
187 # route:
188 # - destination:
189 # host: my.custom.backend.svc.cluster.local
190 # port:
191 # number: 80
192
193# set to true and provide configuration details if you want to make external https calls through istio's virtualservice
194serviceentry:
195 enabled: false
196 # hosts:
197 # a list of external hosts you want to be able to make https calls to
198 # - api.example.com
199
200resources:
201 {}
202 # We usually recommend not to specify default resources and to leave this as a conscious
203 # choice for the user. This also increases chances charts run on environments with little
204 # resources, such as Minikube. If you do want to specify resources, uncomment the following
205 # lines, adjust them as necessary, and remove the curly braces after 'resources:'.
206 # limits:
207 # cpu: 100m
208 # memory: 128Mi
209 # requests:
210 # cpu: 100m
211 # memory: 128Mi
212
213autoscaling:
214 enabled: false
215 minReplicas: 1
216 maxReplicas: 100
217 targetCPUUtilizationPercentage: 80
218 # targetMemoryUtilizationPercentage: 80
219 #
220 # Specify container-specific HPA scaling targets
221 # Only available in 1.27+ (https://kubernetes.io/blog/2023/05/02/hpa-container-resource-metric/)
222 # containerBased:
223 # - name: <container name>
224 # type: cpu
225 # targetUtilizationPercentage: 75
226
227# -- Sets the [rolling update strategy parameters](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-update-deployment). Can take absolute values or % values.
228rollingUpdate:
229 {}
230# Defaults if not set are:
231# maxUnavailable: 25%
232# maxSurge: 25%
233
234nodeSelector: {}
235
236tolerations: []
237
238affinity: {}
239
240# -- Sets the [pod disruption budget](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) for Deployment pods
241podDisruptionBudget: {}
242
243# -- Set to existing PriorityClass name to control pod preemption by the scheduler
244priorityClassName: ""
245
246# -- Sets the [termination grace period](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#hook-handler-execution) for Deployment pods
247terminationGracePeriodSeconds: 30
248
249probes:
250 # -- Configure readiness probe
251 readiness:
252 initialDelaySeconds: 0
253 # -- Configure liveness probe
254 liveness:
255 initialDelaySeconds: 0
256
257# -- Sets the [topology spread constraints](https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints/) for Deployment pods
258topologySpreadConstraints: []
259
260# -- Sets the restart policy of pods
261restartPolicy: AlwaysSeparate configurations per environment
To support your different deployment configurations for different environments (development, staging, production, etc.), Apollo recommends separating your configuration values into separate files:
A common file, which contains values that apply across all environments.
A unique environment file per environment, which includes and overrides the values from the common file while adding new environment-specific values.
The helm install command applies each --values <values-file> option in the order you set them within the command. Therefore, a common file must be set before an environment file so that the environment file's values are applied last and override the common file's values.
For example, this command deploys with a common_values.yaml file applied first and then a prod_values.yaml file:
1helm install <name_for_install> --namespace <router-namespace> --set managedFederation.apiKey="<graph-api-key>" --set managedFederation.graphRef="<graph-ref>" oci://ghcr.io/apollographql/helm-charts/router --version <router-version> --values router/values.yaml --values common_values.yaml --values prod_values.yaml