企业官网建设流程全解析

本指南以 stable/gcloud-endpoints/README.md 为主体，结合仓库内 values.yaml、deployment.yaml、service.yaml 等模板源码，系统讲解如何用 Helm 在 Google Kubernetes Engine（GKE）上部署 Google Cloud Endpoints（ESP，Extensible Service Proxy），为基于 Open API（Swagger）规范的 API 提供认证、监控与流量代理能力。读完本文，你将掌握该 Chart 的全部配置参数、安装卸载流程，以及参数与 ESP 运行时命令行参数、容器端口、Kubernetes Service 之间的完整映射关系。

1. Chart 背景与定位

Google Cloud Endpoints 是一个基于 NGINX 的代理（ESP，Extensible Service Proxy），用于在 Google Cloud 上开发、部署、保护并监控 API。本 Chart 的作用是在 Kubernetes 集群中创建一个 Google Cloud Endpoints 的 Deployment 与 Service，将集群内对 API 的请求代理到后端应用，并接入 Google 的服务控制与认证体系。

需要特别说明的事实（依据 Chart.yaml）：

• 该 Chart 当前版本为0.1.2，appVersion为1，engine为gotpl；
• 该 Chart 已被标记为deprecated: true，原因是长期无人维护且 e2e 测试失败（Chart 注释中明确提及 PR #2149 即为例证）；仓库根目录的 PROCESSES.md 描述了 Chart 弃用与重新启用（undeprecate）的流程；
• 官方 README 同时注明：本 Chart 依据 Google 文档创建，但不是 Google 官方支持或维护的产品。

因此，本文既介绍其标准用法，也会在最后给出使用与迁移建议，帮助读者在知情前提下决策是否采用。

2. 工作原理：从 Deployment 到 ESP 参数注入

模板渲染的核心在 deployment.yaml。它创建一个extensions/v1beta1的 Deployment，容器名为endpoints，镜像取自{{ .Values.image }}（默认b.gcr.io/endpoints/endpoints-runtime:1）。容器启动后，所有配置项通过**命令行参数（args）**注入 ESP 运行时，模板中每个参数都使用if (.Values.xxx)守卫，即只有显式设置了对应 value，参数才会被注入：

2.1 端口定义与默认行为

模板对端口有一套明确的缺省逻辑（见 deployment.yaml 中ports段落）：

• 若设置了httpPort：暴露名为http的 containerPort；
• 若未设置httpPort、http2Port、sslPort三者：则默认暴露8080端口，名为http（这也是 values.yaml 注释中"默认 httpPort 8080"的由来）；
• 若设置了http2Port：额外暴露名为http2的 containerPort；
• 若设置了sslPort：额外暴露名为https的 containerPort；
• 若设置了statusPort：暴露名为status的 containerPort。

2.2 健康检查

只要设置了statusPort，模板就会自动为容器配置存活与就绪探针（见 deployment.yaml）：

• livenessProbe与readinessProbe均以 HTTP GET 方式请求/endpoints_status；
• initialDelaySeconds: 5，timeoutSeconds: 1。

这意味着 ESP 的/endpoints_status健康端点被 Kubernetes 用来判断 Pod 存活与就绪，任何自定义 NGINX 配置都不得屏蔽该路径。

3. 前置条件

按 README.md 的 Prerequisites 章节，部署前需要满足：

1. 一个运行在Google Container Engine（GKE）上的 Kubernetes 集群；
2. 一份 API 的Open API（Swagger）规范 YAML 文件；
3. 先通过以下命令部署 Open API 规范，并记下返回的Project ID 与版本号：

$ gcloud beta service-management deploy swagger.yaml

部署时用到的service参数通常形如project-id.appspot.com，version即上一步获得的版本号。

4. 安装 Chart

4.1 快速安装（TL;DR）

一行命令即可完成最小化安装（README.md 的 TL;DR 章节）：

$ helm install stable/gcloud-endpoints --set service=project-id.appspot.com,version=version-number,backend=backendapi.default.svc.cluster.local

其中：

• service：形如project-id.appspot.com的 Endpoints 服务名；
• version：服务配置版本号；
• backend：后端 API 的 Kubernetes Service 地址，如backendapi.default.svc.cluster.local。

4.2 指定 release 名称安装

使用--name指定 release 名（例如my-release）：

$ helm install --name my-release stable/gcloud-endpoints --set service=project-id.appspot.com,version=version-number,backend=backendapi.svc.cluster.local

提示：使用helm list可以查看所有已部署的 release。

4.3 通过 values 文件安装

当参数较多时，推荐将配置写入 YAML 文件再以-f传入：

$ helm install --name my-release -f values.yaml stable/gcloud-endpoints

提示：可以直接使用仓库自带的默认配置 values.yaml 作为模板，在其基础上按需修改。

4.4 安装后的访问方式

Chart 的 NOTES.txt 会根据serviceType给出三种不同的访问指引：

• NodePort：先取节点端口与节点 IP，再访问http://$NODE_IP:$NODE_PORT/：

export NODE_PORT=$(kubectl get --namespace <namespace> -o jsonpath="{.spec.ports[0].nodePort}" services <release>-gcloud-endpoints) export NODE_IP=$(kubectl get nodes --namespace <namespace> -o jsonpath="{.items[0].status.addresses[0].address}") echo http://$NODE_IP:$NODE_PORT/

• LoadBalancer：LoadBalancer IP 可能需要几分钟才就绪，可执行kubectl get svc -w <release>-gcloud-endpoints观察状态；就绪后：

export SERVICE_IP=$(kubectl get svc --namespace <namespace> <release>-gcloud-endpoints -o jsonpath='{.status.loadBalancer.ingress[0].ip}') echo http://$SERVICE_IP/

• ClusterIP（values.yaml 的默认值）：通过 port-forward 访问：

export POD_NAME=$(kubectl get pods --namespace <namespace> -l "app=<release>-gcloud-endpoints" -o jsonpath="{.items[0].metadata.name}") echo http://127.0.0.1:8080/ kubectl port-forward $POD_NAME 8080:80

注意：Service 名称是 release 名与 chart 名拼接后再做 24 字符截断的结果（见 _helpers.tpl 中fullname的定义），实际名称以渲染结果为准。

5. 卸载 Chart

卸载（删除）名为my-release的 release：

$ helm delete my-release

该命令会移除与该 Chart 关联的所有 Kubernetes 组件并删除该 release。

6. 配置参数详解

6.1 完整参数表

以下表格完整继承自 README.md 的 Configuration 章节：

6.2 以仓库实际 values.yaml 为准的补充说明

需要指出，README 参数表与仓库实际默认值存在两处差异，应以 values.yaml 为准：

1. 镜像：values.yaml 中实际默认镜像是b.gcr.io/endpoints/endpoints-runtime:1（README 表格写的是:0.3）；
2. Service 类型：values.yaml 中serviceType的默认值是ClusterIP，注释明确建议："对于 minikube，设置为 NodePort，其他环境使用 LoadBalancer"。

values.yaml 还包含以下在参数表中未单列、但实际生效的默认值：

statusPort: 8090 resources: requests: memory: 128Mi cpu: 100m

即状态端口默认8090，资源请求默认内存128Mi、CPU100m。

6.3 逐参数深入说明

image / imagePullPolicy

• image：ESP 运行时镜像。默认b.gcr.io/endpoints/endpoints-runtime:1。
• imagePullPolicy：未设置时由 Kubernetes 默认规则决定——若 image tag 为latest则为Always，否则为IfNotPresent（deployment.yaml 中通过{{ default "" .Values.imagePullPolicy | quote }}渲染，空值交由平台默认）。可以通过 deployment.yaml 确认其注入方式。

backend

后端 API 地址，ESP 将收到的请求代理转发至此。默认localhost:8081；若后端为 gRPC 服务，须使用grpc://前缀，例如grpc://localhost:8081（见 values.yaml 注释）。典型的跨命名空间写法为backendapi.default.svc.cluster.local这类完整 DNS 名。

service / version / serviceConfigURL

三者共同决定 ESP 如何获取服务配置：

• 显式设置service（Endpoints 服务名，形如project-id.appspot.com）与version（配置版本号）是最直接的方式；
• 若两者省略但设置了serviceConfigURL，ESP 从该 URL 拉取服务配置；
• 若都不设置，ESP 会联系集群的元数据服务自动获取服务名与版本（见 values.yaml 中对应注释）。

httpPort / http2Port / sslPort

控制 ESP 对外监听协议：

• httpPort：HTTP/1.x 端口，默认值逻辑为"当http2Port与sslPort均未提供时为8080"；
• http2Port：HTTP/2 端口，不能与 HTTP/1.x 端口相同；
• sslPort：HTTPS 端口，同时接受 HTTP/1.x 与 HTTP/2 连接。

三者均未设置时，模板回退暴露容器端口8080（见 deployment.yaml）。

statusPort

ESP 状态端口，默认8090。状态信息通过 HTTP/1.x 的/endpoints_status路径暴露，同时被用作存活/就绪探针的探测路径。README 参数表注明该端口"不对外暴露"（not exposed），仅作为容器内部健康检查使用。

serviceAccountKey

服务账号密钥 JSON 文件路径。ESP 用它访问 Service Control（计费/监控/限流）与 Service Management（配置下发）。省略时，ESP 会联系元数据服务获取访问令牌（见 values.yaml 注释）。该参数通过--service_account_key注入容器命令行（见 deployment.yaml）。

nginxConfig

自定义 NGINX 配置文件路径，通过--nginx_config注入，用于覆盖 ESP 默认的 NGINX 行为（见 deployment.yaml）。注意不要屏蔽/endpoints_status健康端点。

serviceType

Kubernetes Service 类型（ClusterIP/NodePort/LoadBalancer）。service.yaml 依据该值渲染 Service 的type字段；不同类型的访问方式见本文 4.4 节。

resources

容器资源请求与限制，默认requests: memory 128Mi / cpu 100m。模板通过 _helpers.tpl 中定义的递归toYaml辅助函数将resources对象渲染进 Deployment 的resources字段。

7. Service 端口映射

service.yaml 定义了对外 Service 端口与容器端口的映射关系，与 deployment.yaml 中的端口定义一一对应：

Service 的 selector 匹配app: {{ template "fullname" . }}标签，fullname由 release 名与 chart 名拼接并截断为 24 字符（见 _helpers.tpl）。Deployment 的 selector 同样使用该标签，保证 Pod 与 Service 正确关联。

8. 注意事项与使用建议

1. Chart 已弃用：当前 Chart 标记为deprecated: true（见 Chart.yaml），原因是无人维护与 e2e 测试失败。新项目应优先评估 Google 官方推荐的替代部署方式（如 ESPv2 相关方案）；如需继续使用本 Chart，请自行验证模板在当前集群版本（尤其是 Deployment API 从extensions/v1beta1演进）下的兼容性。
2. 非 Google 官方产品：Chart 依据 Google 文档创建但并非 Google 官方支持维护，使用前应做好风险评估。
3. API 版本陈旧：模板使用extensions/v1beta1的 Deployment API（见 deployment.yaml），在较新版本的 Kubernetes 集群上可能无法直接应用，需自行适配为apps/v1。
4. 健康端点：/endpoints_status同时承担存活与就绪探针职责，自定义nginxConfig时务必保留该路径。
5. 密钥安全：serviceAccountKey对应服务账号密钥 JSON 文件，生产环境建议结合 Kubernetes Secret 挂载，避免将密钥直接写入 values 明文配置。

9. 参考

• Chart 默认配置 values.yaml：所有参数的完整注释与默认值；
• Deployment 模板 deployment.yaml：ESP 命令行参数注入、端口定义与健康检查；
• Service 模板 service.yaml：对外端口映射与 Service 类型；
• 辅助模板 _helpers.tpl：名称生成与toYaml递归渲染；
• NOTES.txt：三种 Service 类型下的访问指引；
• Chart.yaml：Chart 元数据与弃用状态；
• PROCESSES.md：仓库维护流程（含 Chart 弃用/恢复机制）。