带注释的 Ingress 资源

apiVersion: networking.k8s.io/v1
kind: Ingress

cert-manager 的一个常见用例是请求 TLS 签名证书来保护您的 Ingress 资源。这可以通过简单地向您的 Ingress 资源添加注释来完成，cert-manager 将帮助您创建 Certificate 资源。cert-manager 的一个小子组件 ingress-shim 负责此操作。

工作原理

子组件 ingress-shim 会监视集群中的 Ingress 资源。如果它观察到一个带有在支持的注释部分中描述的注释的 Ingress，它将确保 Certificate 资源存在于 Ingress 的命名空间中，资源名称在 tls.secretName 字段中提供，并且配置如 Ingress 中所描述。例如

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    # add an annotation indicating the issuer to use.
    cert-manager.io/cluster-issuer: nameOfClusterIssuer
  name: myIngress
  namespace: myIngress
spec:
  rules:
  - host: example.com
    http:
      paths:
      - pathType: Prefix
        path: /
        backend:
          service:
            name: myservice
            port:
              number: 80
  tls: # < placing a host in the TLS config will determine what ends up in the cert's subjectAltNames
  - hosts:
    - example.com
    secretName: myingress-cert # < cert-manager will store the created certificate in this secret.

支持的注释

您可以在 Ingress 资源上指定以下注释，以触发自动创建 Certificate 资源

cert-manager.io/issuer: 应该为该 Ingress 颁发所需证书的发行者的名称。

⚠️ 此注释不会假设命名空间范围内的发行者。它将默认为 cert-manager.io 发行者，但是对于外部发行者类型，这应该用于命名空间范围和集群范围的发行者类型。

⚠️ 如果使用命名空间范围内的发行者，那么发行者 *必须* 与 Ingress 资源位于同一个命名空间。
cert-manager.io/cluster-issuer: 要获取该 Ingress 所需证书的 cert-manager.io ClusterIssuer 的名称。Ingress 所在的命名空间无关紧要，因为 ClusterIssuer 是非命名空间资源。

⚠️ 此注释是用于引用 cert-manager.io ClusterIssuer 的快捷方式，无需指定组和种类。它 *不* 旨在用于指定外部集群范围的发行者，对于那些，请使用 cert-manager.io/issuer 注释。
cert-manager.io/issuer-kind: 外部发行者资源的种类，例如 AWSPCAIssuer。这仅对于树外发行者是必需的。
cert-manager.io/issuer-group: 外部发行者控制器的 API 组，例如 awspca.cert-manager.io。这仅对于树外发行者是必需的。
kubernetes.io/tls-acme: "true": 此注释需要对 ingress-shim 进行额外的配置见下文。即，必须将默认发行者指定为 ingress-shim 容器的参数。
acme.cert-manager.io/http01-ingress-class: 此注释允许您配置将用于解决此 Ingress 的挑战的 Ingress 类。当您试图保护内部服务并需要使用与 Ingress 不同的 Ingress 类来解决挑战时，自定义此项很有用。如果未指定，并且 acme-http01-edit-in-place 注释未设置，则默认为 Issuer 资源中定义的 Ingress 类。
acme.cert-manager.io/http01-edit-in-place: "true": 此项控制是否对 Ingress 进行 '就地' 修改，或者专门为 HTTP01 挑战创建一个新的 Ingress。如果存在，并且设置为 "true"，则将修改现有的 Ingress。任何其他值或注释的缺失都假定为 "false"。此注释还将在创建的证书上添加注释 "cert-manager.io/issue-temporary-certificate": "true"，这将导致临时证书设置在生成的 Secret 上，直到最终签名的证书返回为止。这对于保持与 ingress-gce 组件的兼容性很有用。
cert-manager.io/common-name: (可选) 此注释允许您为要生成的证书配置 spec.commonName。
cert-manager.io/email-sans: (可选) 此注释允许您为要生成的证书配置 spec.emailAddresses 字段。支持以逗号分隔的值，例如 "me@example.com,you@example.com"
cert-manager.io/subject-organizations: (可选) 此注释允许您为要生成的证书配置 spec.subject.organizations 字段。支持以逗号分隔的值，例如 "Company 1,Company 2"
cert-manager.io/subject-organizationalunits: (可选) 此注释允许您为要生成的证书配置 spec.subject.organizationalUnits 字段。支持以逗号分隔的值，例如 "IT Services,Cloud Services"
cert-manager.io/subject-countries: (可选) 此注释允许您为要生成的证书配置 spec.subject.countries 字段。支持以逗号分隔的值，例如 "Country 1,Country 2"
cert-manager.io/subject-provinces: (可选) 此注释允许您为要生成的证书配置 spec.subject.provinces 字段。支持以逗号分隔的值，例如 "Province 1,Province 2"
cert-manager.io/subject-localities: (可选) 此注释允许您为要生成的证书配置 spec.subject.localities 字段。支持以逗号分隔的值，例如 "City 1,City 2"
cert-manager.io/subject-postalcodes: (可选) 此注释允许您为要生成的证书配置 spec.subject.postalCodes 字段。支持以逗号分隔的值，例如 "123ABC,456DEF"
cert-manager.io/subject-streetaddresses: (可选) 此注释允许您为要生成的证书配置 spec.subject.streetAddresses 字段。支持以逗号分隔的值，例如 "123 Example St,456 Other Blvd"
cert-manager.io/subject-serialnumber: (可选) 此注释允许您为要生成的证书配置 spec.subject.serialNumber 字段。支持以逗号分隔的值，例如 "10978342379280287615,1111144445555522228888"
cert-manager.io/duration: (可选) 此注释允许您为要生成的证书配置 spec.duration 字段。
cert-manager.io/renew-before: (可选) 此注释允许您为要生成的证书配置 spec.renewBefore 字段。
cert-manager.io/usages: (可选) 此注释允许您为要生成的证书配置 spec.usages 字段。传递一个包含以逗号分隔的值的字符串，例如 "key agreement,digital signature, server auth"
cert-manager.io/revision-history-limit: (可选) 此注释允许您配置 spec.revisionHistoryLimit 字段，以限制要为证书保留的 CertificateRequest 的数量。最小值为 1。如果未设置，则将保留所有 CertificateRequest。
cert-manager.io/private-key-algorithm: (可选) 此注释允许您配置 spec.privateKey.algorithm 字段，以设置证书私钥生成的算法。有效值为 RSA、ECDSA 和 Ed25519。如果未设置，将使用算法 RSA。
cert-manager.io/private-key-encoding: (可选) 此注释允许您配置 spec.privateKey.encoding 字段，以设置证书私钥生成的编码。有效值为 PKCS1 和 PKCS8。如果未设置，将使用算法 PKCS1。
cert-manager.io/private-key-size: (可选) 此注释允许您配置 spec.privateKey.size 字段以设置证书的私钥大小。如果算法设置为 RSA，有效值为 2048、4096 或 8192，如果未指定，则默认为 2048。如果算法设置为 ECDSA，有效值为 256、384 或 521，如果未指定，则默认为 256。如果算法设置为 Ed25519，则忽略大小。
cert-manager.io/private-key-rotation-policy: (可选) 此注释允许您配置 spec.privateKey.rotationPolicy 字段以设置证书私钥的轮换策略。有效值为 Never 和 Always。如果未设置，将使用轮换策略 Never。

使用多个 Ingress 生成多个证书

如果您需要从多个 Ingress 生成证书，请确保它具有颁发者注释。除了注释之外，每个 Ingress 还必须拥有唯一的 tls.secretName

可选配置

ingress-shim 子组件会作为安装的一部分自动部署。

如果您想使用旧的 kube-lego kubernetes.io/tls-acme: "true" 注释以实现完全自动化的 TLS，您需要在部署 cert-manager 时配置一个默认的 Issuer。这可以通过在使用 Helm 部署时添加以下 --set 来完成

--set ingressShim.defaultIssuerName=letsencrypt-prod \
   --set ingressShim.defaultIssuerKind=ClusterIssuer \
   --set ingressShim.defaultIssuerGroup=cert-manager.io

或者通过将以下参数添加到 cert-manager 部署的 podTemplate 容器参数。

- --default-issuer-name=letsencrypt-prod
  - --default-issuer-kind=ClusterIssuer
  - --default-issuer-group=cert-manager.io

在上面的示例中，cert-manager 将创建 Certificate 资源，这些资源会引用 ClusterIssuer letsencrypt-prod，用于所有具有 kubernetes.io/tls-acme: "true" 注释的 Ingress。

通过注释配置的颁发者优先于默认颁发者。如果通过 CLI 标志配置了默认颁发者，并且 cert-manager.io/cluster-issuer 或 cert-manager.io/issuer 注释也已添加到 Ingress 中，则创建的 Certificate 将引用通过注释配置的颁发者。

有关部署 cert-manager 的更多信息，请阅读安装指南。

故障排除

如果您在应用 ingress-shim 注释后没有看到创建 Certificate 资源，请检查是否至少设置了 cert-manager.io/issuer 或 cert-manager.io/cluster-issuer。如果您想使用 kubernetes.io/tls-acme: "true"，请确保已检查以上所有步骤，如果问题未解决，您可能需要查看 cert-manager pod 日志中的错误。

面向开发人员的内部机制图

[1] https://cert-manager.k8s.ac.cn/docs/usage/certificate