Skip to content

在 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 或检查整套应用清单。

记录什么本文示例后续用途
网站入口所在 NamespacewebSecret 和入口放在同一 Namespace
网站实际域名trustasia.comHTTPS 入口配置和浏览器访问
原后端 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      0s

DATA=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: 80

name、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/。

  1. 打开的是自己的网站,浏览器没有“连接不安全”或证书错误提示。
  2. 点击地址栏左侧的网站信息按钮查看证书,确认域名、有效期与本次部署的证书一致。
  3. 浏览常用页面,确认图片和页面样式显示正常,登录等业务功能可用。

以上均正常,就完成了 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-controller
bash
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: Cluster
bash
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 配置。