×

适用于 Red Hat OpenShift 的 cert-manager 运算符支持使用自动化证书管理环境 (ACME) CA 服务器(例如 *Let’s Encrypt*)来颁发证书。显式凭据是通过在Issuer API 对象中指定密钥详细信息来配置的。环境凭据是从环境、元数据服务或本地文件中提取的,这些文件未在Issuer API 对象中显式配置。

Issuer 对象是命名空间作用域的。它只能从同一命名空间颁发证书。您还可以使用ClusterIssuer 对象跨集群中的所有命名空间颁发证书。

定义ClusterIssuer 对象的示例 YAML 文件
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: acme-cluster-issuer
spec:
  acme:
    ...

默认情况下,您可以将ClusterIssuer 对象与环境凭据一起使用。要将Issuer 对象与环境凭据一起使用,必须为 cert-manager 控制器启用--issuer-ambient-credentials 设置。

关于 ACME 发行者

适用于 Red Hat OpenShift 的 cert-manager 运算符的 ACME 发行者类型表示自动化证书管理环境 (ACME) 证书颁发机构 (CA) 服务器。ACME CA 服务器依赖于一个 *挑战* 来验证客户端是否拥有正在请求证书的域名。如果挑战成功,适用于 Red Hat OpenShift 的 cert-manager 运算符可以颁发证书。如果挑战失败,适用于 Red Hat OpenShift 的 cert-manager 运算符不会颁发证书。

*Let’s Encrypt* 和互联网 ACME 服务器不支持私有 DNS 区域。

支持的 ACME 挑战类型

适用于 Red Hat OpenShift 的 cert-manager 运算符支持以下 ACME 发行者的挑战类型

HTTP-01

使用 HTTP-01 挑战类型,您可以在域中的 HTTP URL 端点提供计算的密钥。如果 ACME CA 服务器可以从 URL 获取密钥,则可以验证您为域的所有者。

有关更多信息,请参阅上游 cert-manager 文档中的HTTP01

HTTP-01 需要 Let’s Encrypt 服务器能够访问集群的路由。如果内部或私有集群位于代理之后,则证书颁发的 HTTP-01 验证将失败。

HTTP-01 挑战仅限于 80 端口。有关更多信息,请参阅HTTP-01 挑战(Let’s Encrypt)。

DNS-01

使用 DNS-01 挑战类型,您可以在 DNS TXT 记录中提供计算的密钥。如果 ACME CA 服务器可以通过 DNS 查询获取密钥,则可以验证您为域的所有者。

有关更多信息,请参阅上游 cert-manager 文档中的DNS01

支持的 DNS-01 提供商

适用于 Red Hat OpenShift 的 cert-manager 运算符支持以下 ACME 发行者的 DNS-01 提供商

  • Amazon Route 53

  • Azure DNS

    适用于 Red Hat OpenShift 的 cert-manager 运算符不支持使用 Microsoft Entra ID Pod 身份向 Pod 分配托管身份。

  • Google Cloud DNS

  • Webhook

    Red Hat 在 OpenShift Container Platform 上使用带有 cert-manager 的外部 Webhook 测试和支持 DNS 提供商。以下 DNS 提供商已在 OpenShift Container Platform 上经过测试和支持

    使用未列出的 DNS 提供商可能适用于 OpenShift Container Platform,但 Red Hat 未对其进行测试,因此 Red Hat 不支持该提供商。

配置ACME颁发者以解决HTTP-01挑战

您可以使用适用于 Red Hat OpenShift 的 cert-manager Operator 设置 ACME 颁发者以解决 HTTP-01 挑战。此过程使用Let’s Encrypt 作为 ACME CA 服务器。

先决条件
  • 您具有作为具有cluster-admin 角色的用户访问集群的权限。

  • 您有一个要公开的服务。在此过程中,该服务名为sample-workload

步骤
  1. 创建一个 ACME 集群颁发者。

    1. 创建一个定义ClusterIssuer 对象的 YAML 文件。

      示例acme-cluster-issuer.yaml 文件
      apiVersion: cert-manager.io/v1
      kind: ClusterIssuer
      metadata:
        name: letsencrypt-staging                                        (1)
      spec:
        acme:
          preferredChain: ""
          privateKeySecretRef:
            name: <secret_for_private_key>                               (2)
          server: https://acme-staging-v02.api.letsencrypt.org/directory (3)
          solvers:
          - http01:
              ingress:
                ingressClassName: openshift-default                                 (4)
      1 为集群颁发者提供一个名称。
      2 <secret_private_key> 替换为存储 ACME 帐户私钥的密钥的名称。
      3 指定访问 ACME 服务器directory 端点的 URL。此示例使用Let’s Encrypt 暂存环境。
      4 指定 Ingress 类。
    2. 可选:如果您在不指定ingressClassName 的情况下创建对象,请使用以下命令修补现有的 Ingress

      $ oc patch ingress/<ingress-name> --type=merge --patch '{"spec":{"ingressClassName":"openshift-default"}}' -n <namespace>
    3. 通过运行以下命令创建ClusterIssuer 对象

      $ oc create -f acme-cluster-issuer.yaml
  2. 创建一个 Ingress 以公开用户工作负载的服务。

    1. 创建一个定义Namespace 对象的 YAML 文件。

      示例namespace.yaml 文件
      apiVersion: v1
      kind: Namespace
      metadata:
        name: my-ingress-namespace (1)
      1 指定 Ingress 的命名空间。
    2. 通过运行以下命令创建Namespace 对象

      $ oc create -f namespace.yaml
    3. 创建一个定义Ingress 对象的 YAML 文件。

      示例ingress.yaml 文件
      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: sample-ingress                                           (1)
        namespace: my-ingress-namespace                                (2)
        annotations:
          cert-manager.io/cluster-issuer: letsencrypt-staging          (3)
          acme.cert-manager.io/http01-ingress-class: openshift-default (4)
      spec:
        ingressClassName: openshift-default                            (5)
        tls:
        - hosts:
          - <hostname>                                                 (6)
          secretName: sample-tls                                       (7)
        rules:
        - host: <hostname>                                             (8)
          http:
            paths:
            - path: /
              pathType: Prefix
              backend:
                service:
                  name: sample-workload                                (9)
                  port:
                    number: 80
      1 指定 Ingress 的名称。
      2 指定您为 Ingress 创建的命名空间。
      3 指定您创建的集群颁发者。
      4 指定 Ingress 类。
      5 指定 Ingress 类。
      6 <hostname> 替换为要与证书关联的主题替代名称。此名称用于向证书添加 DNS 名称。
      7 指定用于存储已创建证书的密钥。
      8 <hostname> 替换为主机名。您可以使用<host_name>.<cluster_ingress_domain> 语法来利用*.<cluster_ingress_domain> 通配符 DNS 记录和为集群提供服务的证书。例如,您可以使用apps.<cluster_base_domain>。否则,您必须确保为所选主机名存在 DNS 记录。
      9 指定要公开的服务的名称。此示例使用名为sample-workload 的服务。
    4. 通过运行以下命令创建Ingress 对象

      $ oc create -f ingress.yaml

使用 AWS Route53 的显式凭据配置 ACME 颁发者

您可以使用适用于 Red Hat OpenShift 的 cert-manager Operator 设置自动证书管理环境 (ACME) 颁发者,以使用 AWS 上的显式凭据解决 DNS-01 挑战。此过程使用Let’s Encrypt 作为 ACME 证书颁发机构 (CA) 服务器,并显示如何使用 Amazon Route 53 解决 DNS-01 挑战。

先决条件
  • 您必须提供显式的accessKeyIDsecretAccessKey 凭据。有关更多信息,请参阅上游 cert-manager 文档中的Route53

    您可以在未在 AWS 上运行的 OpenShift Container Platform 集群中使用具有显式凭据的 Amazon Route 53。

步骤
  1. 可选:覆盖 DNS-01 自我检查的名称服务器设置。

    仅当目标公共托管区域与集群的默认私有托管区域重叠时,才需要此步骤。

    1. 通过运行以下命令编辑CertManager 资源

      $ oc edit certmanager cluster
    2. 添加包含以下覆盖参数的spec.controllerConfig 部分

      apiVersion: operator.openshift.io/v1alpha1
      kind: CertManager
      metadata:
        name: cluster
        ...
      spec:
        ...
        controllerConfig:                                (1)
          overrideArgs:
            - '--dns01-recursive-nameservers-only'       (2)
            - '--dns01-recursive-nameservers=1.1.1.1:53' (3)
      1 添加spec.controllerConfig 部分。
      2 指定仅使用递归名称服务器,而不是检查与该域关联的权威名称服务器。
      3 提供一个以逗号分隔的<host>:<port> 名称服务器列表,以查询 DNS-01 自我检查。您必须使用1.1.1.1:53 值以避免公共和私有区域重叠。
    3. 保存文件以应用更改。

  2. 可选:为颁发者创建一个命名空间

    $ oc new-project <issuer_namespace>
  3. 通过运行以下命令创建一个密钥来存储您的 AWS 凭据

    $ oc create secret generic aws-secret --from-literal=awsSecretAccessKey=<aws_secret_access_key> \ (1)
        -n my-issuer-namespace
    1 <aws_secret_access_key> 替换为您的 AWS 密钥访问密钥。
  4. 创建一个颁发者

    1. 创建一个定义Issuer 对象的 YAML 文件

      示例issuer.yaml 文件
      apiVersion: cert-manager.io/v1
      kind: Issuer
      metadata:
        name: <letsencrypt_staging>                                        (1)
        namespace: <issuer_namespace>                                   (2)
      spec:
        acme:
          server: https://acme-staging-v02.api.letsencrypt.org/directory (3)
          email: "<email_address>"                                       (4)
          privateKeySecretRef:
            name: <secret_private_key>                                   (5)
          solvers:
          - dns01:
              route53:
                accessKeyID: <aws_key_id>                                (6)
                hostedZoneID: <hosted_zone_id>                           (7)
                region: <region_name>                                    (8)
                secretAccessKeySecretRef:
                  name: "aws-secret"                                     (9)
                  key: "awsSecretAccessKey"                              (10)
      1 为颁发者提供一个名称。
      2 指定您为颁发者创建的命名空间。
      3 指定访问 ACME 服务器directory 端点的 URL。此示例使用Let’s Encrypt 暂存环境。
      4 <email_address> 替换为您的电子邮件地址。
      5 <secret_private_key> 替换为存储 ACME 帐户私钥的密钥的名称。
      6 <aws_key_id> 替换为您的 AWS 密钥 ID。
      7 <hosted_zone_id> 替换为您的托管区域 ID。
      8 <region_name> 替换为 AWS 区域名称。例如,us-east-1
      9 指定您创建的密钥的名称。
      10 指定您创建的密钥中存储 AWS 密钥访问密钥的密钥。
    2. 通过运行以下命令创建Issuer 对象

      $ oc create -f issuer.yaml

使用 AWS 上的环境凭据配置 ACME 颁发者

您可以使用适用于 Red Hat OpenShift 的 cert-manager Operator 设置 ACME 颁发者,以使用 AWS 上的环境凭据解决 DNS-01 挑战。此过程使用Let’s Encrypt 作为 ACME CA 服务器,并显示如何使用 Amazon Route 53 解决 DNS-01 挑战。

先决条件
  • 如果您的集群配置为使用 AWS 安全令牌服务 (STS),则您已按照为适用于 Red Hat OpenShift 的 AWS 安全令牌服务集群的 cert-manager Operator 配置云凭据部分中的说明操作。

  • 如果您的集群不使用 AWS STS,则您已按照在 AWS 上为适用于 Red Hat OpenShift 的 cert-manager Operator 配置云凭据部分中的说明操作。

步骤
  1. 可选:覆盖 DNS-01 自我检查的名称服务器设置。

    仅当目标公共托管区域与集群的默认私有托管区域重叠时,才需要此步骤。

    1. 通过运行以下命令编辑CertManager 资源

      $ oc edit certmanager cluster
    2. 添加包含以下覆盖参数的spec.controllerConfig 部分

      apiVersion: operator.openshift.io/v1alpha1
      kind: CertManager
      metadata:
        name: cluster
        ...
      spec:
        ...
        controllerConfig:                                (1)
          overrideArgs:
            - '--dns01-recursive-nameservers-only'       (2)
            - '--dns01-recursive-nameservers=1.1.1.1:53' (3)
      1 添加spec.controllerConfig 部分。
      2 指定仅使用递归名称服务器,而不是检查与该域关联的权威名称服务器。
      3 提供一个以逗号分隔的<host>:<port> 名称服务器列表,以查询 DNS-01 自我检查。您必须使用1.1.1.1:53 值以避免公共和私有区域重叠。
    3. 保存文件以应用更改。

  2. 可选:为颁发者创建一个命名空间

    $ oc new-project <issuer_namespace>
  3. 修改CertManager 资源以添加--issuer-ambient-credentials 参数

    $ oc patch certmanager/cluster \
      --type=merge \
      -p='{"spec":{"controllerConfig":{"overrideArgs":["--issuer-ambient-credentials"]}}}'
  4. 创建一个颁发者

    1. 创建一个定义Issuer 对象的 YAML 文件

      示例issuer.yaml 文件
      apiVersion: cert-manager.io/v1
      kind: Issuer
      metadata:
        name: <letsencrypt_staging>                                        (1)
        namespace: <issuer_namespace>                                   (2)
      spec:
        acme:
          server: https://acme-staging-v02.api.letsencrypt.org/directory (3)
          email: "<email_address>"                                       (4)
          privateKeySecretRef:
            name: <secret_private_key>                                   (5)
          solvers:
          - dns01:
              route53:
                hostedZoneID: <hosted_zone_id>                           (6)
                region: us-east-1
      1 为颁发者提供一个名称。
      2 指定您为颁发者创建的命名空间。
      3 指定访问 ACME 服务器directory 端点的 URL。此示例使用Let’s Encrypt 暂存环境。
      4 <email_address> 替换为您的电子邮件地址。
      5 <secret_private_key> 替换为存储 ACME 帐户私钥的密钥的名称。
      6 <hosted_zone_id> 替换为您的托管区域 ID。
    2. 通过运行以下命令创建Issuer 对象

      $ oc create -f issuer.yaml

使用 GCP Cloud DNS 的显式凭据配置 ACME 颁发者

您可以使用适用于 Red Hat OpenShift 的 cert-manager Operator 设置 ACME 颁发者,以使用 GCP 上的显式凭据解决 DNS-01 挑战。此过程使用Let’s Encrypt 作为 ACME CA 服务器,并显示如何使用 Google CloudDNS 解决 DNS-01 挑战。

先决条件
  • 您已设置具有 Google CloudDNS所需角色的 Google Cloud 服务帐户。有关更多信息,请参阅上游 cert-manager 文档中的Google CloudDNS

    您可以在未在 GCP 上运行的 OpenShift Container Platform 集群中使用具有显式凭据的 Google CloudDNS。

步骤
  1. 可选:覆盖 DNS-01 自我检查的名称服务器设置。

    仅当目标公共托管区域与集群的默认私有托管区域重叠时,才需要此步骤。

    1. 通过运行以下命令编辑CertManager 资源

      $ oc edit certmanager cluster
    2. 添加包含以下覆盖参数的spec.controllerConfig 部分

      apiVersion: operator.openshift.io/v1alpha1
      kind: CertManager
      metadata:
        name: cluster
        ...
      spec:
        ...
        controllerConfig:                                (1)
          overrideArgs:
            - '--dns01-recursive-nameservers-only'       (2)
            - '--dns01-recursive-nameservers=1.1.1.1:53' (3)
      1 添加spec.controllerConfig 部分。
      2 指定仅使用递归名称服务器,而不是检查与该域关联的权威名称服务器。
      3 提供一个以逗号分隔的<host>:<port> 名称服务器列表,以查询 DNS-01 自我检查。您必须使用1.1.1.1:53 值以避免公共和私有区域重叠。
    3. 保存文件以应用更改。

  2. 可选:为颁发者创建一个命名空间

    $ oc new-project my-issuer-namespace
  3. 通过运行以下命令创建一个密钥来存储您的 GCP 凭据

    $ oc create secret generic clouddns-dns01-solver-svc-acct --from-file=service_account.json=<path/to/gcp_service_account.json> -n my-issuer-namespace
  4. 创建一个颁发者

    1. 创建一个定义Issuer 对象的 YAML 文件

      示例issuer.yaml 文件
      apiVersion: cert-manager.io/v1
      kind: Issuer
      metadata:
        name: <acme_dns01_clouddns_issuer> (1)
        namespace: <issuer_namespace> (2)
      spec:
        acme:
          preferredChain: ""
          privateKeySecretRef:
            name: <secret_private_key> (3)
          server: https://acme-staging-v02.api.letsencrypt.org/directory (4)
          solvers:
          - dns01:
              cloudDNS:
                project: <project_id> (5)
                serviceAccountSecretRef:
                  name: clouddns-dns01-solver-svc-acct (6)
                  key: service_account.json (7)
      1 为颁发者提供一个名称。
      2 <issuer_namespace> 替换为您的颁发者命名空间。
      3 <secret_private_key> 替换为存储 ACME 帐户私钥的密钥的名称。
      4 指定访问 ACME 服务器directory 端点的 URL。此示例使用Let’s Encrypt 暂存环境。
      5 <project_id> 替换为包含 Cloud DNS 区域的 GCP 项目的名称。
      6 指定您创建的密钥的名称。
      7 指定您创建的密钥中存储 GCP 密钥访问密钥的密钥。
    2. 通过运行以下命令创建Issuer 对象

      $ oc create -f issuer.yaml

使用GCP环境凭据配置ACME颁发者

您可以使用Red Hat OpenShift的cert-manager Operator来设置ACME颁发者,以使用GCP环境凭据解决DNS-01挑战。此过程使用Let’s Encrypt作为ACME CA服务器,并演示如何使用Google CloudDNS解决DNS-01挑战。

先决条件
  • 如果您的集群配置为使用GCP工作负载身份,则您已按照为使用GCP工作负载身份的Red Hat OpenShift cert-manager Operator配置云凭据部分中的说明操作。

  • 如果您的集群不使用GCP工作负载身份,则您已按照在GCP上为Red Hat OpenShift cert-manager Operator配置云凭据部分中的说明操作。

步骤
  1. 可选:覆盖 DNS-01 自我检查的名称服务器设置。

    仅当目标公共托管区域与集群的默认私有托管区域重叠时,才需要此步骤。

    1. 通过运行以下命令编辑CertManager 资源

      $ oc edit certmanager cluster
    2. 添加包含以下覆盖参数的spec.controllerConfig 部分

      apiVersion: operator.openshift.io/v1alpha1
      kind: CertManager
      metadata:
        name: cluster
        ...
      spec:
        ...
        controllerConfig:                                (1)
          overrideArgs:
            - '--dns01-recursive-nameservers-only'       (2)
            - '--dns01-recursive-nameservers=1.1.1.1:53' (3)
      1 添加spec.controllerConfig 部分。
      2 指定仅使用递归名称服务器,而不是检查与该域关联的权威名称服务器。
      3 提供一个以逗号分隔的<host>:<port> 名称服务器列表,以查询 DNS-01 自我检查。您必须使用1.1.1.1:53 值以避免公共和私有区域重叠。
    3. 保存文件以应用更改。

  2. 可选:为颁发者创建一个命名空间

    $ oc new-project <issuer_namespace>
  3. 修改CertManager 资源以添加--issuer-ambient-credentials 参数

    $ oc patch certmanager/cluster \
      --type=merge \
      -p='{"spec":{"controllerConfig":{"overrideArgs":["--issuer-ambient-credentials"]}}}'
  4. 创建一个颁发者

    1. 创建一个定义Issuer 对象的 YAML 文件

      示例issuer.yaml 文件
      apiVersion: cert-manager.io/v1
      kind: Issuer
      metadata:
        name: <acme_dns01_clouddns_issuer> (1)
        namespace: <issuer_namespace>
      spec:
        acme:
          preferredChain: ""
          privateKeySecretRef:
            name: <secret_private_key> (2)
          server: https://acme-staging-v02.api.letsencrypt.org/directory (3)
          solvers:
          - dns01:
              cloudDNS:
                project: <gcp_project_id> (4)
      1 为颁发者提供一个名称。
      2 <secret_private_key> 替换为存储 ACME 帐户私钥的密钥的名称。
      3 指定访问 ACME 服务器directory 端点的 URL。此示例使用Let’s Encrypt 暂存环境。
      4 <gcp_project_id>替换为包含Cloud DNS区域的GCP项目的名称。
    2. 通过运行以下命令创建Issuer 对象

      $ oc create -f issuer.yaml

使用Microsoft Azure DNS显式凭据配置ACME颁发者

您可以使用Red Hat OpenShift的cert-manager Operator来设置ACME颁发者,以使用Microsoft Azure上的显式凭据解决DNS-01挑战。此过程使用Let’s Encrypt作为ACME CA服务器,并演示如何使用Azure DNS解决DNS-01挑战。

先决条件
  • 您已为Azure DNS设置了具有所需角色的服务主体。有关更多信息,请参阅上游cert-manager文档中的Azure DNS

    您可以针对不在Microsoft Azure上运行的OpenShift Container Platform集群执行此过程。

步骤
  1. 可选:覆盖 DNS-01 自我检查的名称服务器设置。

    仅当目标公共托管区域与集群的默认私有托管区域重叠时,才需要此步骤。

    1. 通过运行以下命令编辑CertManager 资源

      $ oc edit certmanager cluster
    2. 添加包含以下覆盖参数的spec.controllerConfig 部分

      apiVersion: operator.openshift.io/v1alpha1
      kind: CertManager
      metadata:
        name: cluster
        ...
      spec:
        ...
        controllerConfig:                                (1)
          overrideArgs:
            - '--dns01-recursive-nameservers-only'       (2)
            - '--dns01-recursive-nameservers=1.1.1.1:53' (3)
      1 添加spec.controllerConfig 部分。
      2 指定仅使用递归名称服务器,而不是检查与该域关联的权威名称服务器。
      3 提供一个以逗号分隔的<host>:<port> 名称服务器列表,以查询 DNS-01 自我检查。您必须使用1.1.1.1:53 值以避免公共和私有区域重叠。
    3. 保存文件以应用更改。

  2. 可选:为颁发者创建一个命名空间

    $ oc new-project my-issuer-namespace
  3. 通过运行以下命令创建秘密来存储您的Azure凭据

    $ oc create secret generic <secret_name> --from-literal=<azure_secret_access_key_name>=<azure_secret_access_key_value> \   (1) (2) (3)
        -n my-issuer-namespace
    1 <secret_name>替换为您的秘密名称。
    2 <azure_secret_access_key_name>替换为您的Azure秘密访问密钥名称。
    3 <azure_secret_access_key_value>替换为您的Azure秘密密钥。
  4. 创建一个颁发者

    1. 创建一个定义Issuer 对象的 YAML 文件

      示例issuer.yaml 文件
      apiVersion: cert-manager.io/v1
      kind: Issuer
      metadata:
        name: <acme-dns01-azuredns-issuer>   (1)
        namespace: <issuer_namespace>   (2)
      spec:
        acme:
          preferredChain: ""
          privateKeySecretRef:
            name: <secret_private_key> (3)
          server: https://acme-staging-v02.api.letsencrypt.org/directory (4)
          solvers:
          - dns01:
              azureDNS:
                clientID: <azure_client_id> (5)
                clientSecretSecretRef:
                  name: <secret_name> (6)
                  key: <azure_secret_access_key_name> (7)
                subscriptionID: <azure_subscription_id> (8)
                tenantID: <azure_tenant_id> (9)
                resourceGroupName: <azure_dns_zone_resource_group> (10)
                hostedZoneName: <azure_dns_zone> (11)
                environment: AzurePublicCloud
      1 为颁发者提供一个名称。
      2 <issuer_namespace> 替换为您的颁发者命名空间。
      3 <secret_private_key> 替换为存储 ACME 帐户私钥的密钥的名称。
      4 指定访问 ACME 服务器directory 端点的 URL。此示例使用Let’s Encrypt 暂存环境。
      5 <azure_client_id>替换为您的Azure客户端ID。
      6 <secret_name>替换为客户端密钥的名称。
      7 <azure_secret_access_key_name>替换为客户端密钥名称。
      8 <azure_subscription_id>替换为您的Azure订阅ID。
      9 <azure_tenant_id>替换为您的Azure租户ID。
      10 <azure_dns_zone_resource_group>替换为Azure DNS区域资源组的名称。
      11 <azure_dns_zone>替换为Azure DNS区域的名称。
    2. 通过运行以下命令创建Issuer 对象

      $ oc create -f issuer.yaml