Appearance
在 Kubernetes 中首次部署 SSL 证书并启用 HTTPS
本文介绍如何将已签发证书保存到 TLS Secret,并在网站现有的 Ingress 或 Gateway 上启用 HTTPS。网站后端和原有路由继续使用,只补充证书引用及必要的 HTTPS 监听配置。
操作流程: 找到网站入口 → 创建 TLS Secret → 配置 HTTPS → 检查网站访问。
下文输出摘自测试集群的实际执行结果,域名统一替换为 trustasia.com,资源名称与本文示例对齐,省略无关记录和字段。IP、运行时长以你的实际输出为准。
本教程仅用于操作引导与示例演示。读者应自行评估生产环境的网络架构、HTTPS 入口、软件版本、部署方式及业务要求,对文中的命令、配置和脚本进行适配,并在测试环境验证后再应用于生产环境。
第一步:确认网站和现有入口
在平时管理该集群的终端中,先确认 kubectl 当前连接的是目标集群:
bash
kubectl config current-context根据网站当前使用的入口,只执行下面对应的一组查询,将名称和命名空间替换为实际值。
使用 Ingress: 查看原网站的 Ingress,确认 spec.rules 中的网站域名和后端 Service。
bash
kubectl get ingress web-ingress -n web -o yaml使用 Gateway: 查看原 Gateway 和 HTTPRoute,确认监听名称、网站域名及后端 Service。
bash
kubectl get gateway web-gateway -n web -o yaml
kubectl get httproute web -n web -o yaml不清楚资源名称时,可使用 kubectl get ingress -A,或 kubectl get gateway,httproute -A 查找。无需为了部署证书重新创建后端 Service 或检查整套应用清单。
| 记录什么 | 本文示例 | 后续用途 |
|---|---|---|
| 网站入口所在 Namespace | web | Secret 和入口放在同一 Namespace |
| 网站实际域名 | trustasia.com | HTTPS 入口配置和浏览器访问 |
| 原后端 Service 及其端口 | web-service:80 | 沿用原路由中的后端,不是 Pod 端口 |
| 新证书 Secret 名称 | web-tls | 第二步创建,第三步引用 |
将后续示例中的名称统一替换为实际值,并按入口类型备份原部署清单:使用 Ingress 时备份 Ingress 清单,使用 Gateway 时备份 Gateway 和 HTTPRoute 清单。
第二步:创建 TLS Secret
使用 PEM 格式的完整证书链和匹配私钥。已有文件时直接继续;尚未取得文件时,可参考获取证书文件。使用 KeyManager 时选择 Nginx(PEM) 格式并解压导出包;这里仅使用其文件格式,无需安装 Nginx。
将证书链和匹配私钥文件传到运行 kubectl 的机器,保存在仅允许必要管理员访问的目录中。下面的 --cert 填完整证书链路径,--key 填匹配私钥的路径,文件名以实际文件为准。
示例使用已有 web Namespace、名为 web-tls 的新 Secret、trustasia.com 和已有 web-service:80,请统一替换为实际值。先确认目标 Secret 不存在;已存在时先核对其用途及管理方,不直接覆盖。
bash
kubectl get namespace web
kubectl get secret web-tls -n web查询目标 Secret 时,应返回 NotFound,表示该 Secret 尚不存在。如果返回的是权限或连接错误,请先解决错误,再继续操作。未创建时的实测输出如下(名称已对齐):
text
Error from server (NotFound): secrets "web-tls" not found这里的 NotFound 表示这个名字尚未使用,可以继续创建:
bash
kubectl create secret tls web-tls -n web \
--cert=/root/cert-files/fullchain.pem \
--key=/root/cert-files/privkey.pem
kubectl get secret web-tls -n web确认 Secret 类型为 kubernetes.io/tls。本文将 Secret 与 Gateway 或 Ingress 放在同一 Namespace;Service 也在该 Namespace 中,不涉及跨命名空间引用。
创建成功的实测输出(名称已对齐):
text
secret/web-tls created
NAME TYPE DATA AGE
web-tls kubernetes.io/tls 2 0sDATA=2 表示包含证书和私钥两个数据项。记下 NAME=web-tls,下一步用这个名称配置入口引用,再检查加载结果。
第三步:首次配置 HTTPS 入口
根据网站现有入口,只执行下面对应的一节:使用 Gateway 的网站选择“使用 Gateway”,使用 Ingress 的网站选择“使用 Ingress”。在原入口上补充 HTTPS 配置,并引用第二步创建的 Secret,无需另建一套入口。
配置后,确认入口控制器监听并对外提供所选 HTTPS 端口,防火墙和安全组允许客户端访问。
使用 Gateway
打开网站原有的 Gateway 和 HTTPRoute 部署清单,在原 HTTP 监听(listener)旁新增 HTTPS 监听,并让该网站的 HTTPRoute 同时关联新增的监听。下面展示相关配置片段及其位置,请将示例名称替换为原清单中的实际值,并保留其他监听和路由。将修改后的完整清单保存为 gateway.yaml:
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: web-gateway
namespace: web
spec:
gatewayClassName: REPLACE_WITH_GATEWAY_CLASS
listeners:
- name: http
hostname: trustasia.com
port: 80
protocol: HTTP
allowedRoutes:
namespaces:
from: Same
# 新增 HTTPS listener,引用第二步的 Secret
- name: https
hostname: trustasia.com
port: 443
protocol: HTTPS
tls:
mode: Terminate
certificateRefs:
- group: ""
kind: Secret
name: web-tls
allowedRoutes:
namespaces:
from: Same
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: web
namespace: web
spec:
parentRefs:
- name: web-gateway
sectionName: http
# 让原网站路由也接收新 HTTPS listener 的请求
- name: web-gateway
sectionName: https
hostnames:
- trustasia.com
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: web-service
port: 80按以下对应关系填写,不要用示例覆盖网站完整业务配置:
namespace、Gateway 和 HTTPRoute 的name:沿用原资源的 Namespace 和名称。gatewayClassName:沿用原 Gateway 的值。- 所有
trustasia.com:网站实际域名。 certificateRefs.name:第二步创建的 Secret 名称。backendRefs:沿用原 Service 名称和服务端口;路由中的matches匹配规则也应保留。
示例原路由只关联 http,因此增加了关联 https 的一项。原 parentRefs 没有 sectionName 时会关联适用的监听,无需为同一个 Gateway 重复添加;原来使用其他监听名称时沿用实际值。
本例由 Gateway 接收 HTTPS 请求,再通过 HTTP 转发给后端 Service。后端要求 HTTPS 时,需要另外配置回源连接。
bash
kubectl apply --dry-run=server -f gateway.yaml
kubectl apply -f gateway.yaml
kubectl describe gateway web-gateway -n web
kubectl describe httproute web -n web检查 Gateway 的状态,确认 Accepted=True、Programmed=True,且 HTTPS 监听的 ResolvedRefs=True。再检查 HTTPRoute 对应父级的状态,确认 Accepted=True、ResolvedRefs=True。不清楚裸机集群的入口地址时,先按裸机入口说明确认客户端能够访问的地址,再决定是否修改 DNS。
describe gateway 的实测输出节选如下。每组 Status 和后面的 Type 要一起看:
text
Status:
Conditions:
Status: True
Type: Accepted
Status: True
Type: Programmed
Listeners:
Conditions:
Status: True
Type: ResolvedRefs
Name: https这些状态表示控制器已接受 Gateway 配置并完成相应配置下发,且 https 监听中的资源引用已成功解析。查看 describe httproute 的输出时,检查 Status → Parents → Conditions:
text
Status:
Parents:
Conditions:
Status: True
Type: Accepted
Status: True
Type: ResolvedRefs这两项为 True 表示控制器已接受路由配置,且相关资源引用已成功解析。接下来检查网站访问是否正常。
使用 Ingress
打开网站原有的 Ingress 部署清单,在 spec 下增加 tls,与原 rules 同级。下面展示相关配置片段及其位置:
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: web
spec:
ingressClassName: REPLACE_WITH_EXISTING_INGRESS_CLASS
# 新增:引用第二步创建的 TLS Secret
tls:
- hosts:
- trustasia.com
secretName: web-tls
# 以下沿用原网站路由
rules:
- host: trustasia.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web-service
port:
number: 80name、namespace、ingressClassName 和 rules 使用原配置,只为目标域名增加 tls 引用。hosts 填原 rules.host 中的网站域名,secretName 填第二步的 Secret 名称。已有其他 TLS 配置时继续保留。
将修改后的完整清单保存为 ingress.yaml,在集群管理终端执行:
bash
kubectl apply --dry-run=server -f ingress.yaml
kubectl apply -f ingress.yaml
kubectl describe ingress web-ingress -n web名称和 Namespace 换成实际值。确认 TLS 部分列出对应域名和 Secret,后端仍是原网站 Service,然后进入第四步。
describe ingress 实测输出节选:
text
Name: web-ingress
Namespace: web
Ingress Class: tutorial-traefik
TLS:
web-tls terminates trustasia.com
Rules:
Host Path Backends
---- ---- --------
trustasia.com
/ web-service:80 (<后端 Pod 地址>:80,...)重点看 TLS 行的 web-tls 和 trustasia.com 是否对应第二步的 Secret 与网站域名;Backends 的 web-service:80 应仍是原后端。括号里是当前后端地址,不需要抄到证书配置中。
第四步:检查网站访问
新增网站 DNS 记录时,将域名指向实际入口;已有记录则核对它与当前访问路径是否一致。使用 CDN、WAF 或负载均衡时,分别检查前置平台和 HTTPS 集群入口的证书与连接。
在自己的电脑上打开浏览器,访问 https://trustasia.com/。域名换成第三步配置的网站域名;入口端口不是 443 时加上实际端口,例如 https://trustasia.com:8443/。
- 打开的是自己的网站,浏览器没有“连接不安全”或证书错误提示。
- 点击地址栏左侧的网站信息按钮查看证书,确认域名、有效期与本次部署的证书一致。
- 浏览常用页面,确认图片和页面样式显示正常,登录等业务功能可用。
以上均正常,就完成了 HTTPS 部署。网站显示旧证书或使用 CDN 等代理时,按证书检查说明核对实际入口。
访问异常时恢复配置
入口配置失败时,按原发布流程撤销本次新增的监听和路由关联,或使用备份恢复原 Gateway、HTTPRoute 或 Ingress 清单,再确认原 HTTP 访问及其他已有业务恢复正常。不要删除共享的 Secret、Namespace 或入口控制器。本次新建的 Secret 若已不被任何入口使用,可核对后单独清理。日常换证时只更新相应证书资源,无需重新部署网站。
后续自动更新
手动部署完成后,请根据证书到期时间安排更新。如需自动更新,可继续阅读Kubernetes 自动申请与更新指南。配置前,请确认现有 Secret 由谁维护、保存哪个域名的证书,以及被哪些入口引用,避免手动操作与自动化工具同时更新同一 Secret。
补充:尚未准备好 Gateway 入口时
以下说明适用于需要安装网关组件,或配置裸机集群入口地址的环境。已有正常运行的 Gateway 或 Ingress 时可跳过。请沿用集群现有的安装和配置管理方式,不要覆盖其他人管理的资源。
展开 Gateway 安装与裸机入口配置说明
补齐 Gateway 组件
Gateway API CRD 只定义资源,还需 Gateway Controller 处理流量。以下 Envoy Gateway v1.9.1 示例仅适用于集群版本兼容、资源充足,且既未安装 Gateway API CRD、也未安装 Envoy Gateway 的环境。已有 CRD 或 Controller 时由管理员沿用原安装方式维护,不重复应用。
bash
kubectl apply --server-side -f \
https://github.com/envoyproxy/gateway/releases/download/v1.9.1/install.yaml
kubectl wait -n envoy-gateway-system --timeout=10m \
--for=condition=Available deployment/envoy-gateway若 kubectl get gatewayclass 为空,保存以下内容为 gatewayclass.yaml,由管理员应用:
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: envoy-web
spec:
controllerName: gateway.envoyproxy.io/gatewayclass-controllerbash
kubectl apply -f gatewayclass.yaml
kubectl describe gatewayclass envoy-web确认 Accepted=True,第三步 Gateway 的 spec.gatewayClassName 使用实际确认的 GatewayClass,例如 envoy-web。接着关联已有网站 Service,配置 Gateway,并检查其对外入口地址。
裸机集群如何提供入口
云环境通常由负载均衡器分配入口地址。裸机或本地虚拟机缺少相应能力时,代理 Service 的 EXTERNAL-IP 可能一直为 <pending>。生产环境应按实际网络选择负载均衡或其他入口方案。以下节点 IP 示例适用于客户端可直达节点的实验网络;公网访问需另行提供公网地址和转发路径。
下面仅适用于 Envoy Gateway。用 192.0.2.10 占位,请换为客户端可达、且 443 不与其他服务冲突的实际节点 IP。若 externalTrafficPolicy 为 Local,无本地代理 Pod 的节点可能丢弃请求;示例用 Cluster 策略允许跨节点转发。
保存以下内容为 envoy-proxy.yaml,Namespace 按网站实际位置替换:
yaml
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
name: web-proxy
namespace: web
spec:
provider:
type: Kubernetes
kubernetes:
envoyService:
externalTrafficPolicy: Clusterbash
kubectl apply -f envoy-proxy.yaml在第三步 gateway.yaml 的 Gateway spec 中合并 infrastructure 和 addresses,不加到 HTTPRoute 中:
yaml
spec:
gatewayClassName: envoy-web
infrastructure:
parametersRef:
group: gateway.envoyproxy.io
kind: EnvoyProxy
name: web-proxy
addresses:
- type: IPAddress
value: 192.0.2.10 # 替换为实际入口节点 IP
listeners:
# 保留第三步示例中完整的 HTTPS listener将上方片段合并到原清单,保留完整监听和 HTTPRoute,再应用完整的 gateway.yaml。使用 Cluster 策略时,后端可能无法获取原始客户端 IP。Service 的调整应通过控制器支持的配置完成,避免被后续同步覆盖。
bash
kubectl get gateway web-gateway -n web
kubectl get svc -n envoy-gateway-system \
-l gateway.envoyproxy.io/owning-gateway-namespace=web,gateway.envoyproxy.io/owning-gateway-name=web-gateway \
-o custom-columns=NAME:.metadata.name,POLICY:.spec.externalTrafficPolicy,EXTERNAL-IP:.spec.externalIPs此示例的 POLICY 应为 Cluster。修改 DNS 前,可用以下命令将本次请求发送到指定节点,同时保留证书域名和信任链校验:
bash
curl --noproxy '*' --resolve trustasia.com:443:192.0.2.10 \
--connect-timeout 10 --max-time 20 -fS https://trustasia.com/替换域名、IP 和业务路径。--resolve 只影响本次请求,不改 DNS;--noproxy '*' 避免本机代理绕开指定地址,不使用 -k。确认返回目标业务后,按第四步完成验收。超时先检查路由、防火墙、443 及代理 Pod;其他网关实现不照搬 EnvoyProxy 配置。
