前言
kubernetes 集群默认安装的证书是自签发证书,浏览器访问会发出安全提醒。
本文记录了利用 dnspod 、 cert-manager 、let’s encrytp 等开源组件,实现泛域名证书的自动生成、续期管理,为现有kubernetes 集群应用启动 HTTPS,提高系统安全性。
架构
在 Kubernetes 集群中使用 HTTPS 协议,需要一个证书管理器、一个证书自动签发服务
cert-manager 是一个云原生证书管理开源项目,用于在 Kubernetes 集群中提供 HTTPS 证书并自动续期,支持 Let’s Encrypt, HashiCorp Vault 这些免费证书的签发。在Kubernetes集群中,我们可以通过 Kubernetes Ingress 和 Let’s Encrypt 实现外部服务的自动化 HTTPS。
Issuers/ClusterIssuers:定义使用什么证书颁发机构 (CA) 来去颁发证书,Issuers 和 ClusterIssuers 区别是: issuers 是一个名称空间级别的资源,只能用来签发自己所在 namespace 下的证书,ClusterIssuer 是个集群级别的资源 可以签发任意 namespace 下的证书
Certificate:定义所需的 X.509 证书,该证书将更新并保持最新。Certificate 是一个命名空间资源,当 Certificate 被创建时,它会去创建相应的 CertificateRequest 资源来去申请证书。
安装证书管理器
安装证书管理器比较简单,直接执行以下脚本就可以了。
kubectl create ns cert-manager
helm uninstall cert-manager -n cert-manager
helm install cert-manager jetstack/cert-manager \
-n cert-manager \
--version v1.8.0 \
--set installCRDs=true \
--set prometheus.enabled=false \
--set 'extraArgs={--dns01-recursive-nameservers-only,--dns01-recursive-nameservers=119.29.29.29:53\,8.8.8.8:53}'
配置证书管理器
选择证书颁发者
cert-manager支持以下几种证书颁发者
- SelfSigned
- CA
- Vault
- Venafi
- External
- ACME
我们选择使用ACME来颁发证书。
选择证书校验方式
常用的校验方式有 HTTP-01 、DNS-01 。
DNS-01 校验原理
DNS-01 的校验原理是利用 DNS 提供商的 API Key 拿到 DNS 控制权限, 在 Let’s Encrypt 为 ACME 客户端提供令牌后,ACME 客户端 (cert-manager) 将创建从该令牌和我的帐户密钥派生的 TXT 记录,并将该记录放在 _acme-challenge。 然后 Let’s Encrypt 将向 DNS 系统查询该记录,如果找到匹配项,就可以颁发证书。此方法支持泛域名证书。
HTTP-01 校验原理
HTTP-01 的校验原理是给域名指向的 HTTP 服务增加一个临时 location ,Let’s Encrypt 会发送 http 请求,参数中 YOUR_DOMAIN 就是被校验的域名,TOKEN 是 ACME 协议的客户端负责放置的文件,ACME 客户端就是 cert-manager,它通过修改或创建 Ingress 规则来增加这个临时校验路径并指向提供 TOKEN 的服务。Let’s Encrypt 会对比 TOKEN 是否符合预期,校验成功后就会颁发证书。此方法仅适用于给使用 Ingress 暴露流量的服务颁发证书,不支持泛域名证书。
优劣对比
HTTP-01 的校验方式的优点是: 配置简单通用,不管使用哪个 DNS 提供商都可以使用相同的配置方法;缺点是:需要依赖 Ingress,如果服务不是通过 Ingress 暴露的就不适用,而且不支持泛域名证书。
DNS-01 的校验方式的优点是没有 HTTP-01 校验方式缺点,不依赖 Ingress,也支持泛域名;缺点就是不同 DNS 提供商的配置方式不一样,而且只有 cert-manager 支持的 DNS 提供商才可以选择这种方式。
Cert-manager 支持使用外部 webhook 的接入 DNS 提供商,正好公司使用 dnspod 属于支持的行列。我们可以选择 DNS-01 。
配置
HTTP-01 配置示例
这个配置示例仅供参考,使用这种方式,有多少的 ingress 服务,就需要申请多少张证书 ,比较麻烦,但是配置较为简单,不依赖 DNS 服务商。
1. 创建 CA 群集证书颁发者
证书管理器需要 Issuer 或 ClusterIssuer 资源,才能颁发证书。 这两种 Kubernetes 资源的功能完全相同,区别在于 Issuer 适用于单一命名空间,而 ClusterIssuer 适用于所有命名空间。
ClusterIssuer.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt
spec:
acme:
email: xxxx@xyz.cn
server: https://acme-v02.api.letsencrypt.org/directory
privateKeySecretRef:
name: issuer-account-key
solvers:
- http01:
ingress:
class: nginx
说明:
- metadata.name: 是我们创建的签发机构的名称,后面我们创建证书的时候会引用它
- spec.acme.email: 是你自己的邮箱,证书快过期的时候会有邮件提醒,不过 cert-manager 会利用 acme 协议自动给我们重新颁发证书来续期
- spec.acme.server: 是 acme 协议的服务端,我们使用 Let’s Encrypt
- spec.acme.privateKeySecretRef: 指示此签发机构的私钥将要存储到哪个 Secret 对象中
- spec.acme.solvers: 这里指示签发机构校验方式,有 http01 和 dns01 两种,该字段下配置的 class 和 name 只能同时存在一个, class 指定使用的 ingress class 名称, name 比较少用,通常用于 kubernetes 的 ingress。
kubectl apply -f ClusterIssuer.yaml -n cert-manager
2. 创建 ingress 服务
ingreess-wikijs.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
cert-manager.io/cluster-issuer: letsencrypt
nginx.ingress.kubernetes.io/proxy-body-size: "0"
name: ingress-wikijs
spec:
ingressClassName: nginx
rules:
- host: wiki.xyz.cn
http:
paths:
- backend:
service:
name: wikijs
port:
number: 3000
path: /
pathType: Prefix
tls:
- hosts:
- wikijs.xyz.cn
secretName: ingress-wikijs-tls
注意:
在 annotations 里 设置cert-manager.io/cluster-issuer
为签名创建的集群证书颁发者 letsencrypt
使用 yaml 文件创建 ingress 后,就可以使用该 ingress 对外提供 https 服务了。
# 创建 ingress
kubectl apply -f ingress-wikijs.yaml -n infra
# 查看证书是否自动创建成功
kubectl -n infra get certificate
DNS01配置示例
使用这种方式需要 DNS 服务商支持通过 API 创建 DNS 记录,正好我的 DNS 服务商是 dnspod 支持,因此在我们的及群里,最终采用了这种方式。
这个方式的配置会比较麻烦,踩了很久的坑,主要是因为我的集群启用了本地 DNS 服务器,默认 cert-manager 会通过本地 DNS 服务器去验证通过 API 创建的 DNS txt记录,会一直检查不到新增的 txt 记录,造成在 challenge 阶段就一直 pendding。解决方案附后。
1. 在 dnspod 创建 API ID 和 API Token
参考dnspod 云官方文档
记录下创建的 API ID 和 API Token 。
<API ID >
<API Token>
2. 安装 cert-manager-webhook-dnspod
使用 helm 安装 roc/cert-manager-webhook-dnspod。
helm repo add roc https://charts.imroc.cc
helm uninstall cert-manager-webhook-dnspod -n cert-manager
helm install cert-manager-webhook-dnspod roc/cert-manager-webhook-dnspod \
-n cert-manager \
--set clusterIssuer.secretId=<API ID > \
--set clusterIssuer.secretKey=<API Token> \
--set clusterIssuer.email=xxxx@xyz.cn
3. 创建泛域名证书
xyz-crt.yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: xyz-crt
spec:
secretName: xyz-crt
issuerRef:
name: dnspod
kind: ClusterIssuer
group: cert-manager.io
dnsNames:
- "*.xyz.cn"
创建集群证书颁发者
k apply -f xyz-crt.yaml -n infra
4. 验证证书
查看证书是否创建成功
[root@ks-master infra]# kubectl get Certificate -n cert-manager
NAME READY SECRET AGE
cert-manager-webhook-dnspod-ca True cert-manager-webhook-dnspod-ca 18m
cert-manager-webhook-dnspod-webhook-tls True cert-manager-webhook-dnspod-webhook-tls 18m
xyz-crt True xyz-crt 3m12s
以上可以看出 xyz-crt 已经创建成功, READY 状态也是 True。
查看证书对应的域名
[root@ks-master infra]# kubectl describe Certificate xyz-crt -n cert-manager
Name: xyz-crt
Namespace: cert-manager
Labels: <none>
Annotations: <none>
API Version: cert-manager.io/v1
Kind: Certificate
Metadata:
Creation Timestamp: 2022-05-07T14:19:07Z
Generation: 1
Managed Fields:
API Version: cert-manager.io/v1
Fields Type: FieldsV1
fieldsV1:
f:status:
.:
f:conditions:
Manager: cert-manager-certificates-trigger
Operation: Update
Subresource: status
Time: 2022-05-07T14:19:07Z
API Version: cert-manager.io/v1
Fields Type: FieldsV1
fieldsV1:
f:metadata:
f:annotations:
.:
f:kubectl.kubernetes.io/last-applied-configuration:
f:spec:
.:
f:dnsNames:
f:issuerRef:
.:
f:group:
f:kind:
f:name:
f:secretName:
Manager: kubectl-client-side-apply
Operation: Update
Time: 2022-05-07T14:19:07Z
API Version: cert-manager.io/v1
Fields Type: FieldsV1
fieldsV1:
f:status:
f:revision:
Manager: cert-manager-certificates-issuing
Operation: Update
Subresource: status
Time: 2022-05-07T14:19:14Z
API Version: cert-manager.io/v1
Fields Type: FieldsV1
fieldsV1:
f:status:
f:conditions:
k:{"type":"Ready"}:
.:
f:lastTransitionTime:
f:message:
f:observedGeneration:
f:reason:
f:status:
f:type:
f:notAfter:
f:notBefore:
f:renewalTime:
Manager: cert-manager-certificates-readiness
Operation: Update
Subresource: status
Time: 2022-05-07T14:19:14Z
Resource Version: 4784901
UID: f2c9be82-f4cb-4243-b2c3-19f64242cc91
Spec:
Dns Names:
*.xyz.cn
Issuer Ref:
Group: cert-manager.io
Kind: ClusterIssuer
Name: dnspod
Secret Name: xyz-crt
Status:
Conditions:
Last Transition Time: 2022-05-07T14:19:14Z
Message: Certificate is up to date and has not expired
Observed Generation: 1
Reason: Ready
Status: True
Type: Ready
Not After: 2022-08-05T13:19:11Z
Not Before: 2022-05-07T13:19:12Z
Renewal Time: 2022-07-06T13:19:11Z
Revision: 1
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Issuing 4m35s cert-manager-certificates-trigger Issuing certificate as Secret does not exist
Normal Generated 4m35s cert-manager-certificates-key-manager Stored new private key in temporary Secret resource "xyz-crt-4ml59"
Normal Requested 4m35s cert-manager-certificates-request-manager Created new CertificateRequest resource "xyz-crt-r76wp"
Normal Issuing 4m28s cert-manager-certificates-issuing The certificate has been successfully issued
[root@ks-master infra]#
从 Certificate 的描述信息可以看到,这个证书是对应所有 *.xyz.cn 的泛域名。所以可以直接用在集群的任何地方。
查看证书内容
[root@ks-master infra]# kubectl describe secret xyz-crt -n cert-manager
Name: xyz-crt
Namespace: cert-manager
Labels: <none>
Annotations: cert-manager.io/alt-names: *.xyz.cn
cert-manager.io/certificate-name: xyz-crt
cert-manager.io/common-name: *.xyz.cn
cert-manager.io/ip-sans:
cert-manager.io/issuer-group: cert-manager.io
cert-manager.io/issuer-kind: ClusterIssuer
cert-manager.io/issuer-name: dnspod
cert-manager.io/uri-sans:
Type: kubernetes.io/tls
Data
====
tls.crt: 5587 bytes
tls.key: 1675 bytes
TLS 证书保存在 cert-manager 命名空间里的 xyz-crt secret。可以供所有 *.xyz.cn 的服务使用。
其他
这个过程中,最大的坑是,我的集群使用了自建的 DNS 服务器,默认 cert-manager 会使用这个集群的自建 DNS SERVER 进行证书发行的验证,虽然通过调用 dnspod 的 webook 在 腾讯云 DNS 服务器上创建的 _acme-challenge 握手数据,但是在我的 自建 DNS 里是查不到的,所以会一直卡 pending 状态,
[root@ks-master infra]# kubectl get challenge -A
NAMESPACE NAME STATE DOMAIN AGE
cert-manager xyz-crt-f9kp6-381578565-136350475 pending xyz.cn 24s
查看原因是:
Waiting for DNS-01 challenge propagation: DNS record for "xyz.cn" not yet
[root@ks-master infra]# kcm describe challenge xyz-crt-f9kp6-381578565-136350475
Name: xyz-crt-f9kp6-381578565-136350475
Namespace: cert-manager
Labels: <none>
Annotations: <none>
API Version: acme.cert-manager.io/v1
Kind: Challenge
---
中间略
---
Status:
Presented: true
Processing: true
Reason: Waiting for DNS-01 challenge propagation: DNS record for "xyz.cn" not yet propagated
State: pending
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Started 41s cert-manager-challenges Challenge scheduled for processing
Normal Presented 39s cert-manager-challenges Presented challenge using DNS-01 challenge mechanism
查了很多资料,在官网上找到解决方案。办法是让 cert-manager 强制使用指定的 DNS 服务器进行握手验证。
我是用的是 helm 安装 cert-manager,所以添加一下 set 参数
--set 'extraArgs={--dns01-recursive-nameservers-only,--dns01-recursive-nameservers=119.29.29.29:53\,8.8.8.8:53}'
使用 TLS 证书配置 ingress
设置 ingress
kind: Ingress
apiVersion: networking.k8s.io/v1
metadata:
name: wikijs
namespace: infra
annotations:
nginx.ingress.kubernetes.io/proxy-body-size: '0'
spec:
ingressClassName: nginx
tls:
- hosts:
- wiki.xyz.cn
secretName: xyz-crt
rules:
- host: wiki.xyz.cn
http:
paths:
- path: /
pathType: ImplementationSpecific
backend:
service:
name: wikijs
port:
number: 3000
测试
以上配置完成后,就可以使用 https 来访问新的 wiki.js 服务了。