在 Kubernetes 上部署

学习如何部署一个自托管的路由器（GraphOS 路由器或Apollo 路由器核心）在 Kubernetes 中使用 Helm 图表。

以下指南提供了以下步骤：

• 从 Apollo 容器存储库中获取 路由器 Helm 图表。
• 使用基本 Helm 图表部署 路由器。
• 配置图表值以导出度量、启用 Rhai 脚本和部署协处理器。
• 选择最适合从网关迁移到 路由器的图表值。

关于路由器 Helm 图表

Helm是 Kubernetes（k8s）的包管理器。Apollo 为 GitHub 中的每个 Apollo 路由器核心版本提供应用程序 Helm 图表。自路由器版本 0.14.0 以来，Apollo 以 GitHub 容器存储库中的 开放容器倡议（OCI）镜像的形式发布了路由器 Helm 图表。

您可以通过相同的 命令行选项和 YAML 配置来自定义已部署的 路由器，但分别在不同的 Helm CLI 选项和 YAML 键下。

基本部署

按照此指南使用 Helm 部署 Router，以安装每个路由器版本中提供的提供的基本图表。

每个 路由器图表都有一个 values.yaml 文件，包含 路由器和部署设置。已发布且未编辑的文件包含一些明确的设置，包括：

• 路由器的默认容器端口用于 HTTP 服务器's HTTP 服务器, 健康检查端点, 以及 度量端点。
• 命令行 参数 用于启用路由器的 热重载。
• 单个副本。

1
helm show values oci://ghcr.io/apollographql/helm-charts/router

1
Pulled: ghcr.io/apollographql/helm-charts/router:1.31.0
2
Digest: sha256:26fbe98268456935cac5b51d44257bf96c02ee919fde8d47a06602ce2cda66a3
3
# Default values for router.
4
# This is a YAML-formatted file.
5
# Declare variables to be passed into your templates.
6

7
replicaCount: 1
8

9
# -- See https://apollo.graphql.net.cn/docs/router/configuration/overview/#yaml-config-file for yaml structure
10
router:
11
  configuration:
12
    supergraph: # HTTP server
13
      listen: 0.0.0.0:80
14
    health_check:
15
      listen: 0.0.0.0:8088
16
    telemetry:
17
      metrics:
18
        prometheus:
19
          enabled: false
20
          listen: 0.0.0.0:9090
21
          path: "/metrics"
22

23
  args:
24
  - --hot-reload
25

26
managedFederation:
27
  # -- If using managed federation, the graph API key to identify router to Studio
28
  apiKey:
29
  # -- If using managed federation, use an existing secret which stores the graph API key instead of creating a new one.
30
  # If set along `managedFederation.apiKey`, a secret with the graph API key will be created using this parameter as name
31
  existingSecret:
32
  # -- If using managed federation, the variant of which graph to use
33
  graphRef: ""
34

35
# This should not be specified in values.yaml. It's much simpler to use --set-file from helm command line.
36
# e.g.: helm ... --set-file supergraphFile="location of your supergraph file"
37
supergraphFile:
38

39
# An array of extra environmental variables
40
# Example:
41
# extraEnvVars:
42
#   - name: APOLLO_ROUTER_SUPERGRAPH_PATH
43
#     value: /etc/apollo/supergraph.yaml
44
#   - name: APOLLO_ROUTER_LOG
45
#     value: debug
46
#
47
extraEnvVars: []
48
extraEnvVarsCM: ''
49
extraEnvVarsSecret: ''
50

51
# An array of extra VolumeMounts
52
# Example:
53
# extraVolumeMounts:
54
#   - name: rhai-volume
55
#     mountPath: /dist/rhai
56
#     readonly: true
57
extraVolumeMounts: []
58

59
# An array of extra Volumes
60
# Example:
61
# extraVolumes:
62
#   - name: rhai-volume
63
#     configMap:
64
#       name: rhai-config
65
#
66
extraVolumes: []
67

68
image:
69
  repository: ghcr.io/apollographql/router
70
  pullPolicy: IfNotPresent
71
  # Overrides the image tag whose default is the chart appVersion.
72
  tag: ""
73

74
containerPorts:
75
  # -- If you override the port in `router.configuration.server.listen` then make sure to match the listen port here
76
  http: 80
77
  # -- For exposing the metrics port when running a serviceMonitor for example
78
  metrics: 9090
79
  # -- For exposing the health check endpoint
80
  health: 8088
81

82
# -- An array of extra containers to include in the router pod
83
# Example:
84
# extraContainers:
85
#   - name: coprocessor
86
#     image: acme/coprocessor:1.0
87
#     ports:
88
#       - containerPort: 4001
89
extraContainers: []
90

91
# -- An array of init containers to include in the router pod
92
# Example:
93
# initContainers:
94
#   - name: init-myservice
95
#     image: busybox:1.28
96
#     command: ["sh"]
97
initContainers: []
98

99
# -- A map of extra labels to apply to the resources created by this chart
100
# Example:
101
# extraLabels:
102
#   label_one_name: "label_one_value"
103
#   label_two_name: "label_two_value"
104
extraLabels: {}
105

106
lifecycle: {}
107
#  preStop:
108
#    exec:
109
#      command:
110
#        - /bin/bash
111
#        - -c
112
#        - sleep 10
113

114
imagePullSecrets: []
115
nameOverride: ""
116
fullnameOverride: ""
117

118
serviceAccount:
119
  # Specifies whether a service account should be created
120
  create: true
121
  # Annotations to add to the service account
122
  annotations: {}
123
  # The name of the service account to use.
124
  # If not set and create is true, a name is generated using the fullname template
125
  name: ""
126

127
podAnnotations: {}
128

129
podSecurityContext: {}
130
  # fsGroup: 2000
131

132
securityContext: {}
133
  # capabilities:
134
  #   drop:
135
  #   - ALL
136
  # readOnlyRootFilesystem: true
137
  # runAsNonRoot: true
138
  # runAsUser: 1000
139

140
service:
141
  type: ClusterIP
142
  port: 80
143
  annotations: {}
144

145
serviceMonitor:
146
  enabled: false
147

148
ingress:
149
  enabled: false
150
  className: ""
151
  annotations: {}
152
    # kubernetes.io/ingress.class: nginx
153
    # kubernetes.io/tls-acme: "true"
154
  hosts:
155
    - host: chart-example.local
156
      paths:
157
        - path: /
158
          pathType: ImplementationSpecific
159
  tls: []
160
  #  - secretName: chart-example-tls
161
  #    hosts:
162
  #      - chart-example.local
163

164
# set to true to enable istio's virtualservice
165
virtualservice:
166
  enabled: false
167
  # namespace: ""
168
  # gatewayName: ""
169
  # http:
170
  #   main:
171
  #     # set enabled to true to add
172
  #     # the default matcher of `exact: "/" or prefix: "/graphql"`
173
  #     # with the <$fullName>.<.Release.Namespace>.svc.cluster.local destination
174
  #     enabled: true
175
  #   # use additionals to provide your custom virtualservice rules
176
  #   additionals: []
177
  #   - name: "default-nginx-routes"
178
  #       match:
179
  #         - uri:
180
  #             prefix: "/foo"
181
  #       rewrite:
182
  #         uri: /
183
  #       route:
184
  #         - destination:
185
  #             host: my.custom.backend.svc.cluster.local
186
  #             port:
187
  #               number: 80
188

189
# set to true and provide configuration details if you want to make external https calls through istio's virtualservice
190
serviceentry:
191
  enabled: false
192
  # hosts:
193
  # a list of external hosts you want to be able to make https calls to
194
  #   - api.example.com
195

196
resources: {}
197
  # We usually recommend not to specify default resources and to leave this as a conscious
198
  # choice for the user. This also increases chances charts run on environments with little
199
  # resources, such as Minikube. If you do want to specify resources, uncomment the following
200
  # lines, adjust them as necessary, and remove the curly braces after 'resources:'.
201
  # limits:
202
  #   cpu: 100m
203
  #   memory: 128Mi
204
  # requests:
205
  #   cpu: 100m
206
  #   memory: 128Mi
207

208
autoscaling:
209
  enabled: false
210
  minReplicas: 1
211
  maxReplicas: 100
212
  targetCPUUtilizationPercentage: 80
213
  # targetMemoryUtilizationPercentage: 80
214

215
nodeSelector: {}
216

217
tolerations: []
218

219
affinity: {}
220

221
# -- Sets the [pod disruption budget](https://kubernetes.ac.cn/docs/tasks/run-application/configure-pdb/) for Deployment pods
222
podDisruptionBudget: {}
223

224
# -- Set to existing PriorityClass name to control pod preemption by the scheduler
225
priorityClassName: ""
226

227
# -- Sets the [termination grace period](https://kubernetes.ac.cn/docs/concepts/containers/container-lifecycle-hooks/#hook-handler-execution) for Deployment pods
228
terminationGracePeriodSeconds: 30
229

230
probes:
231
  # -- Configure readiness probe
232
  readiness:
233
    initialDelaySeconds: 0
234
  # -- Configure liveness probe
235
  liveness:
236
    initialDelaySeconds: 0

设置 Helm

1. 安装 Helm 版本 3.x。路由器的 Helm 图表需要 Helm v3.x。

   ⓘ 注意

   您的Kubernetes版本必须与Helm v3兼容。详细信息，请参阅Helm版本支持策略。

2. 使用Helm登录到GitHub的Apollo容器注册库。

   • 获取GitHub OCI令牌并将其保存在环境变量GITHUB_OCI_TOKEN中。有关说明，请参照认证到GitHub容器注册库指南。

   • 使用helm registry login命令，使用您保存的GITHUB_OCI_TOKEN和GitHub用户名：

     Bash

     1
     echo ${GITHUB_OCI_TOKEN} | helm registry login -u <username> --password-stdin ghcr.io

     复制

3. 登录后，使用helm show values命令显示最新的router图表值来验证您对注册库的访问权限：

   Bash

   1
   helm show values oci://ghcr.io/apollographql/helm-charts/router

   复制

设置集群

安装工具并为您的Kubernetes集群提供基础设施。

例如，请参阅从Apollo的参考架构设置。该指南提供了您可参考的步骤，包括收集云平台（GCP或AWS）的帐户和凭证、提供资源以及部署您的子图。

设置图

设置您的自托管图并获取其图引用和API密钥。

如果您需要设置图的指南，您可以按照自托管路由快速启动和完成以下步骤：步骤 1 （设置 Apollo 工具）步骤 1（设置 Apollo 工具），步骤 4（获取您的子图模式）步骤 4（获取您的子图模式）以及步骤 5（发布您的子图模式）步骤 5（发布您的子图模式）。

部署路由器

要部署路由器，请使用带有容器仓库中 OCI 图像的参数、values.yaml配置文件的参数以及覆盖特定配置值的附加参数helm install命令。

1
helm 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

用于特定配置值所需的参数：

• --set managedFederation.graphRef="<graph-ref>"。你的管理图引用（id@variant），与APOLLO_GRAPH_REF环境变量的值相同。
• --set managedFederation.apiKey="<graph-api-key>"。您的管理图的 API 键，与APOLLO_KEY环境变量的值相同。

一些可选但推荐使用的参数：

• --namespace <router-namespace>。此部署的命名空间范围。
• --version <router-version>。要部署的路由器版本。如果不使用helm install指定，则安装最新版本。

验证部署

使用helm list命令验证您的路由器是否是部署的版本之一。

如果您使用了--namespace <router-namespace>选项，您只能列出您命名空间内的版本：

1
helm list --namespace <router-namespace>

带有指标端点的部署

路由器支持 Prometheus 和 OpenTelemetry 协议（OTLP）的指标端点。基本部署不启用指标端点，因为路由器图表明确禁用了 Prometheus（和 OTLP 通过省略）。

通过 YAML 配置文件在已部署的路由器中启用指标端点：

1. 创建一个my_values.yaml的 YAML 文件，以包含覆盖默认值的附加值。

2. 编辑my_values.yaml以启用指标端点：

   YAML

   my_values.yaml

   1
   router:
   2
     configuration:
   3
       telemetry:
   4
         metrics:
   5
           prometheus:
   6
             enabled: true
   7
             listen: 0.0.0.0:9090
   8
             path: "/metrics"
   9
           otlp:
   10
             temporality: delta
   11
             endpoint: <otlp-endpoint-addr>

   复制

   ⓘ 注意

   虽然这个例子中启用了 Prometheus 和 OTLP，但在实践中通常只启用一个端点。

   • router.configuration.telemetry.metrics.prometheus 已配置但默认禁用（enabled: false），此配置设置 enabled: true。
   • router.configuration.telemetry.metrics.otlp 已启用。
   • router.configuration.telemetry.temporality 默认是 temporality: cumulative，大多数指标消费者是一个不错的选择。对于DataDog，使用 temporality: delta。

3. 使用额外的YAML配置文件部署 router。例如，从基本部署步骤开始使用 helm install 命令，追加 --values my_values.yaml：

   Bash

   1
   helm 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 my_values.yaml

   复制

使用Rhai脚本来部署

router 支持使用Rhai脚本来添加自定义功能。

在部署 router 中启用Rhai脚本需要为你的Rhai脚本挂载额外的卷并将脚本放入卷中。可以通过遵循 创建自定义内部路由图表的单独示例 中的步骤。该示例创建了一个新的（内部）图表，它封装（并依赖于）已发布的 router 图表，并且新的图表具有添加必要配置的模板，从而使部署的 router 能够使用Rhai脚本。

使用协作处理器部署

router 支持 外部协作处理 在 router的请求处理生命周期 上运行自定义逻辑。

已部署的协作处理器在 router pod 中有自己的应用程序镜像和容器。

要通过YAML配置文件配置协作处理器和其容器为您部署的 router，请执行以下步骤：

1. 创建一个my_values.yaml的 YAML 文件，以包含覆盖默认值的附加值。

2. 编辑 my_values.yaml 以配置 router 的协作处理器。作为参考，遵循 典型 和 最小 配置示例，并将它们应用到 router.configuration.coprocessor。

   协作处理器的典型配置示例

   YAML

   router.yaml

   1
   coprocessor:
   2
     url: http://127.0.0.1:8081 # Required. Replace with the URL of your coprocessor's HTTP endpoint.
   3
     timeout: 2s # The timeout for all coprocessor requests. Defaults to 1 second (1s)
   4
     router: # This coprocessor hooks into the `RouterService`
   5
       request: # By including this key, the `RouterService` sends a coprocessor request whenever it first receives a client request.
   6
         headers: true # These boolean properties indicate which request data to include in the coprocessor request. All are optional and false by default.
   7
         body: false
   8
         context: false
   9
         sdl: false
   10
         path: false
   11
         method: false
   12
       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).
   13
         headers: true
   14
         body: false
   15
         context: false
   16
         sdl: false
   17
         status_code: false
   18
     supergraph: # This coprocessor hooks into the `SupergraphService`
   19
       request: # By including this key, the `SupergraphService` sends a coprocessor request whenever it first receives a client request.
   20
         headers: true # These boolean properties indicate which request data to include in the coprocessor request. All are optional and false by default.
   21
         body: false
   22
         context: false
   23
         sdl: false
   24
         method: false
   25
       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).
   26
         headers: true
   27
         body: false
   28
         context: false
   29
         sdl: false
   30
         status_code: false
   31
     subgraph:
   32
       all:
   33
         request: # By including this key, the `SubgraphService` sends a coprocessor request whenever it is about to make a request to a subgraph.
   34
           headers: true # These boolean properties indicate which request data to include in the coprocessor request. All are optional and false by default.
   35
           body: false
   36
           context: false
   37
           uri: false
   38
           method: false
   39
           service_name: false
   40
         response: # By including this key, the `SubgraphService` sends a coprocessor request whenever receives a subgraph response.
   41
           headers: true
   42
           body: false
   43
           context: false
   44
           service_name: false
   45
           status_code: false

   复制

3. 编辑 my_values.yaml 以添加一个用于协作处理器的容器。

   YAML

   my_values.yaml

   1
   extraContainers:
   2
     - name: <coprocessor-deployed-name> # name of deployed container
   3
       image: <coprocessor-app-image> # name of application image
   4
       ports:
   5
         - containerPort: <coprocessor-container-port> # must match port of router.configuration.coprocessor.url
   6
       env: [] # array of environment variables

   复制

4. 使用额外的YAML配置文件部署 router。例如，从基本部署步骤开始使用 helm install 命令，追加 --values my_values.yaml：

   Bash

   1
   helm 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 my_values.yaml

   复制

按环境分开配置

为了支持您在不同环境（开发、预发布、生产等）的不同部署配置，Apollo建议将您的配置值分开到单独的文件

• 一个 通用 文件，其中包含适用于所有环境的值。
• 每个环境一个 环境 文件，该文件包含通用文件中的值，并覆盖这些值，同时添加新的环境特定值。

helm install 命令按照你在命令中设置它们的顺序应用每个 --values <values-file> 选项。因此，在设置环境文件之前必须设置一个通用文件，以便首先应用环境文件的值，并覆盖通用文件的值。

例如，此命令先应用 common_values.yaml 文件，然后才应用 prod_values.yaml 文件：

1
helm 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

使用 Istio 在 Kubernetes 中部署

Istio 是 Kubernetes 的一个服务网格，通常由于其流量整形能力而安装在集群上。虽然我们 neither 特地推荐 nor 支持 Istio，也没有为在包含 Istio 的集群中安装 Router 提供具体的指令，但在配置 Istio 时存在一个已知考虑因素。

由于 Istio 的 sidecar 注入方式，可能需要考虑更多的配置和额外配置。如果没有额外的配置，Istio 可能会尝试同时重新配置网络接口和 router 启动，这将导致启动失败。

这不是一个 router 问题，Istio 在他们的 自己的文档 中以一般方式管理问题的说明。他们建议在 Istio 准备就绪之前防止 pod 中所有其他容器的启动。当使用 Istio 时，我们推荐这种方法。

针对网关迁移进行配置

当 从 @apollo/gateway 迁移到 router 时，考虑以下建议以最大限度地提高您的 router 部署的兼容性。

增加最大请求数据包字节

默认情况下，router 将其支持的最大请求数据包大小设置为 2MB，而 gateway 将其支持的最大请求数据包大小设置为 20MB。如果您的 gateway 默认接收大于 2MB 的请求，您可以通过以下配置确保 router 与您的 gateway 部署兼容。

1
router:
2
  configuration:
3
    limits:
4
      http_max_request_bytes: 20000000 #20MB

增加请求超时时间

router 的超时时间增加，以适应具有高延迟的 subgraph 操作。

1
router:
2
  configuration:
3
    traffic_shaping:
4
      router:
5
        timeout: 6min
6
      all:
7
        timeout: 5min

传递 subgraph 错误

gateway 将 subgraph 错误传递给客户端，但 router 默认不传递，因此需要配置以传递它们。

1
router:
2
  configuration:
3
    include_subgraph_errors:
4
      all: true