Venafi

介绍

Venafi Issuer 类型允许您从 Venafi 作为服务 (VaaS) 和 Venafi 信任保护平台 (TPP) 实例获取证书。

您可以在同一个集群中安装多个不同的 Venafi Issuer 类型，包括 Venafi 作为服务和 TPP 颁发者类型的混合。这使您可以灵活地使用您使用的 Venafi 帐户类型。

使用 Venafi Issuer 提供自动化证书续签和管理功能，用于管理 Certificates。

单个 Venafi Issuer 代表一个 Venafi 'zone'，因此您必须为每个要使用的 zone 创建一个 Issuer 资源。zone 是一个将管理证书签发的策略与关于证书在 Venafi 中的组织方式的信息结合在一起的单个实体，用于识别业务应用程序并建立所有权。

您可以将 Issuer 资源配置为仅在单个命名空间内签发证书，或在整个集群范围内签发证书（使用 ClusterIssuer 资源）。有关 Issuer 和 ClusterIssuer 资源之间区别的更多信息，请阅读 命名空间 部分。

创建 Venafi 作为服务的 Issuer

如果您尚未创建 Venafi 作为服务的帐户，请在该页面上创建 页面，并从您的用户首选项中复制 API 密钥。然后，您可能希望创建自定义 CA 帐户和签发模板，或选择使用为测试自动创建的默认值（分别为“内置 CA”和“默认”）。最后，您需要创建一个应用程序来建立对您的 cert-manager Issuer 请求的所有证书的所有权，并将签发模板分配给它。

记下应用程序名称和签发模板的 API 别名，因为它们共同构成了 Issuer 配置所需的 'zone'。

为了设置 Venafi 作为服务的 Issuer，您必须首先创建一个包含您的 Venafi 作为服务的 API 凭据的 Kubernetes Secret 资源。

$ kubectl create secret generic \
       vaas-secret \
       --namespace='NAMESPACE OF YOUR ISSUER RESOURCE' \
       --from-literal=apikey='YOUR_VAAS_API_KEY_HERE'

注意：如果您要将颁发者配置为 ClusterIssuer 资源，以便在整个集群中提供 Certificates，您必须将 --namespace 参数设置为 cert-manager，它是默认的 Cluster Resource Namespace。可以通过 cert-manager 控制器组件上的 --cluster-resource-namespace 标志配置 Cluster Resource Namespace。

cert-manager 将使用此 API 密钥代表您与 Venafi 作为服务交互。

创建 API 密钥 Secret 后，您可以创建 Issuer 或 ClusterIssuer 资源。如果您要创建 ClusterIssuer 资源，您必须将 kind 字段更改为 ClusterIssuer，并删除 metadata.namespace 字段。

在对内容进行修改后，将以下内容保存到名为 vaas-issuer.yaml 的文件中。

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: vaas-issuer
  namespace: <NAMESPACE YOU WANT TO ISSUE CERTIFICATES IN>
spec:
  venafi:
    zone: "My Application\My CIT" # Set this to <Application Name>\<Issuing Template Alias>
    cloud:
      apiTokenSecretRef:
        name: vaas-secret
        key: apikey

然后，您可以使用 kubectl create 创建 Issuer。

$ kubectl create -f vaas-issuer.yaml

使用 kubectl describe 验证 Issuer 是否已正确初始化。

$ kubectl get issuer vaas-issuer --namespace='NAMESPACE OF YOUR ISSUER RESOURCE' -o wide
NAME           READY   STATUS                 AGE
vaas-issuer    True    Venafi issuer started  2m

您现在可以使用新配置的 Venafi Issuer 和 Venafi 作为服务签发证书。

阅读 请求证书 文档，以获取有关如何创建证书资源的更多信息。

创建 Venafi 信任保护平台 Issuer

Venafi 信任保护平台集成允许您从正确配置的 Venafi TPP 实例获取证书。

设置类似于上面的 Venafi 作为服务的配置，但是一些连接参数略有不同。

注意：您必须允许您的 TPP 策略中的“用户提供的 CSR”，因为这是目前 cert-manager 支持的唯一类型。

更具体地说，“CSR 处理”的有效配置为

• “用户提供的 CSR”已选中并解锁，
• “用户提供的 CSR”已选中并锁定，
• “服务生成的 CSR”已选中并解锁。

当使用“服务生成的 CSR”已选中并解锁时，策略文件夹中存在的默认 CSR 配置将覆盖证书资源的配置。主题 DN、密钥算法和密钥大小将被策略文件夹中设置的值覆盖。

当“服务生成的 CSR”已选中并锁定时，证书签发将系统地失败，并显示以下消息

400 PKCS#10 data will not be processed. Policy "\VED\Policy\foo" is locked to a Server Generated CSR.

为了设置 Venafi 信任保护平台 Issuer，您必须首先创建一个包含您的 Venafi TPP API 凭据的 Kubernetes Secret 资源。

访问令牌身份验证

1. 设置令牌身份验证.

   注意：不要选择“启用刷新令牌”并设置很长的“令牌有效期（天）”。cert-manager 的 Venafi Issuer 不支持刷新令牌功能。

2. 创建一个具有足够权限在特定策略文件夹（zone）中管理和撤销证书的新用户。

   例如 k8s-xyz-automation

3. 创建一个新的应用程序集成

   创建一个名为 cert-manager 且具有相同 ID 的应用程序集成。将“API 访问设置”设置为 证书：读取、管理、撤销。

   “编辑访问”到新的应用程序集成，并允许之前创建的用户使用它。

4. 生成访问令牌

   vcert getcred \
     --username k8s-xyz-automation \
     --password somepassword \
     -u https://tpp.example.com/vedsdk \
     --client-id cert-manager \
     --scope "certificate:manage,revoke"

   这将打印一个访问令牌到 stdout。例如：

   vCert: 2020/10/07 16:34:27 Getting credentials
   access_token:  I69n.............y1VjNJT3o9U0Wko19g==
   access_token_expires:  2021-01-05T15:34:30Z

5. 将访问令牌保存到 Kubernetes 集群中的 Secret 中

$ kubectl create secret generic \
       tpp-secret \
       --namespace=<NAMESPACE OF YOUR ISSUER RESOURCE> \
       --from-literal=access-token='YOUR_TPP_ACCESS_TOKEN'

用户名/密码身份验证

⚠️ 当您提供 Venafi TPP 用户名和密码时，cert-manager 使用一种旧的身份验证方法，称为“API 密钥”，该方法已自 Venafi TPP 19.2 开始弃用。

从 Venafi TPP 22.2 开始，“API 密钥”默认情况下处于禁用状态。您需要联系 Venafi 客户支持，获取一个特殊的许可证密钥，以允许您重新启用“API 密钥”功能，以便您可以继续使用 cert-manager 的用户名和密码身份验证。

在 Venafi TPP 22.3 中，“API 密钥”功能将被永久删除，您需要改用访问令牌身份验证。

📖 阅读 Venafi 平台中已弃用的功能 和 计划弃用的功能，以获取更多信息。

$ kubectl create secret generic \
       tpp-secret \
       --namespace=<NAMESPACE OF YOUR ISSUER RESOURCE> \
       --from-literal=username='YOUR_TPP_USERNAME_HERE' \
       --from-literal=password='YOUR_TPP_PASSWORD_HERE'

注意：如果您要将颁发者配置为 ClusterIssuer 资源，以便在整个集群中签发 Certificates，您必须将 --namespace 参数设置为 cert-manager，它是默认的 Cluster Resource Namespace。可以通过 cert-manager 控制器组件上的 --cluster-resource-namespace 标志配置 Cluster Resource Namespace。

cert-manager 将使用这些凭据与您的 Venafi TPP 实例交互。用户名属性必须符合 <身份提供者>:<用户名> 格式。例如：local:admin。

创建包含凭据的 Secret 后，您可以创建 Issuer 或 ClusterIssuer 资源。如果您要创建 ClusterIssuer 资源，则必须将 kind 字段更改为 ClusterIssuer，并删除 metadata.namespace 字段。

在完成修改后，将以下内容保存到名为 tpp-issuer.yaml 的文件中。

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: tpp-issuer
  namespace: <NAMESPACE YOU WANT TO ISSUE CERTIFICATES IN>
spec:
  venafi:
    zone: \VED\Policy\devops\cert-manager # Set this to the Venafi policy folder you want to use
    tpp:
      url: https://tpp.venafi.example/vedsdk # Change this to the URL of your TPP instance
      caBundle: <base64 encoded string of caBundle PEM file, or empty to use system root CAs>
      ## Use only caBundle above or the caBundleSecretRef below. Secret can be created from a ca.crt file by running below command
      ## kubectl create secret generic custom-tpp-ca --from-file=/my/certs/ca.crt -n <cert-manager-namespace>
      # caBundleSecretRef:
      #  name: custom-tpp-ca
      #  key: ca.crt
      credentialsRef:
        name: tpp-secret

然后，您可以使用 kubectl create -f 创建 Issuer。

$ kubectl create -f tpp-issuer.yaml

使用 kubectl describe 验证 Issuer 是否已正确初始化。

$ kubectl describe issuer tpp-issuer --namespace='NAMESPACE OF YOUR ISSUER RESOURCE'

现在，您可以使用新配置的 Venafi Issuer 和 Trust Protection Platform 颁发证书。

阅读 请求证书 文档，以获取有关如何创建证书资源的更多信息。

Issuer 特定注释

自定义字段

从 v0.14 开始，您可以使用 Certificate 资源上的 venafi.cert-manager.io/custom-fields 注释将自定义字段传递给 Venafi（TPP 版本 v19.2 及更高版本）。该值是一个 JSON 编码的自定义字段对象数组，每个对象都有一个 name 和 value 键。例如

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com-certificate
  annotations:
    venafi.cert-manager.io/custom-fields: |-
      [
        {"name": "field-name", "value": "field value"},
        {"name": "field-name-2", "value": "field value 2"}
      ]
...