跳转至

Vault

Vault Issuer表示证书颁发机构保险库-可以是一个多用途秘密存储 用于为您的公开密码匙基础设施(PKI)签署证书。 Vault 是 cert-manager 的外部项目，因此，本指南假定它已正确配置和部署，可以进行签名。 您可以在这里阅读更多关于如何将 Vault 配置为证书颁发机构的信息.

这种Issuer类型通常用于以下情况:您的基础设施中已经使用了 Vault，或者您希望利用其特性集，而 CA 发行者本身无法提供这些特性集。

部署

所有 Vault 颁发者共享请求证书的公共配置，即服务器、路径和 CA 包:

  • Server is the URL whereby Vault is reachable.
  • Path is the Vault path that will be used for signing. Note that the path must use the sign endpoint.
  • CA bundle denotes an optional field containing a base64 encoded string of the Certificate Authority to trust the Vault connection. This is typically always required when using an https URL.

Below is an example of a configuration to connect a Vault server.

Warning: This configuration is incomplete as no authentication methods have been added.

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: vault-issuer
  namespace: sandbox
spec:
  vault:
    path: pki_int/sign/example-dot-com
    server: https://vault.local
    caBundle: <base64 encoded CA Bundle PEM file>
    auth: ...

Authenticating

In order to request signing of certificates by Vault, the issuer must be able to properly authenticate against it. cert-manager provides multiple approaches to authenticating to Vault which are detailed below.

Authenticating via an AppRole

An AppRole is a method of authenticating to Vault through use of its internal role policy system. This authentication method requires that the issuer has possession of the SecretID secret key, the RoleID of the role to assume, and the app role path. Firstly, the secret ID key must be stored within a Kubernetes Secret that resides in the same namespace as the Issuer, or otherwise inside the Cluster Resource Namespace in the case of a ClusterIssuer.

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: cert-manager-vault-approle
  namespace: sandbox
data:
  secretId: "MDI..."

Once the Secret has been created, the Issuer is ready to be deployed which references this Secret, as well as the data key of the field that stores the secret ID.

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: vault-issuer
  namespace: sandbox
spec:
  vault:
    path: pki_int/sign/example-dot-com
    server: https://vault.local
    caBundle: <base64 encoded caBundle PEM file>
    auth:
      appRole:
        path: approle
        roleId: "291b9d21-8ff5-..."
        secretRef:
          name: cert-manager-vault-approle
          key: secretId

Authenticating with a Token

This method of authentication uses a token string that has been generated from one of the many authentication backends that Vault supports. These tokens have an expiry and so need to be periodically refreshed. You can read more on Vault tokens here.

Note: cert-manager does not refresh these token automatically and so another process must be put in place to do this.

Firstly, the token is be stored inside a Kubernetes Secret inside the same namespace as the Issuer or otherwise in the Cluster Resource Namespace in the case of using a ClusterIssuer.

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: cert-manager-vault-token
  namespace: sandbox
data:
  token: "MjI..."

Once submitted, the Vault issuer is able to be created using token authentication by referencing this Secret along with the key of the field the token data is stored at.

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: vault-issuer
  namespace: sandbox
spec:
  vault:
    path: pki_int/sign/example-dot-com
    server: https://vault.local
    caBundle: <base64 encoded caBundle PEM file>
    auth:
      tokenSecretRef:
        name: cert-manager-vault-token
        key: token

Authenticating with Kubernetes Service Accounts

Vault can be configured so that applications can authenticate using Kubernetes Service Account Tokens. You find documentation on how to configure Vault to authenticate using Service Account Tokens here.

For the Vault issuer to use this authentication, cert-manager must get access to the token that is stored in a Kubernetes Secret. Kubernetes Service Account Tokens are already stored in Secret resources however, you must ensure that it is present in the same namespace as the Issuer, or otherwise in the Cluster Resource Namespace in the case of using a ClusterIssuer.

Note: In Kubernetes 1.24 onwards, the token secret is no longer created by default for the Service Account. In this case you need to manually create the secret resource. See this guide for more details.

This authentication method also expects a role field which is the Vault role that the Service Account is to assume, as well as an optional mountPath field which is the authentication mount path, defaulting to kubernetes.

Kubernetes version less than 1.24

The following example will be making use of the Service Account my-service-account. The secret data field key will be token if the Secret has been created by Kubernetes. The Vault role used is my-app-1, using the default mount path of /v1/auth/kubernetes

  1. Create the Service Account:
kubectl create serviceaccount -n sandbox vault-issuer
  1. Get the auto-generated Secret name:
kubectl get secret -o json | jq -r '.items[] | select(.metadata.annotations["kubernetes.io/service-account.name"] == "vault-issuer") | .metadata.name'
  1. Create the Issuer using that Secret name retrieved from the previous step:
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: vault-issuer
  namespace: sandbox
spec:
  vault:
    path: pki_int/sign/example-dot-com
    server: https://vault.local
    caBundle: <base64 encoded caBundle PEM file>
    auth:
      kubernetes:
        role: my-app-1
        mountPath: /v1/auth/kubernetes
        secretRef:
          name: <auto-generated secret name>
          key: token

Kubernetes version 1.24 and greater

This example is almost the same as above but adjusted for the change in Kubernetes 1.24 and above.

  1. Create the Service Account:
kubectl create serviceaccount -n sandbox vault-issuer
  1. Create the Secret resource for Kubernetes to populate the token value:
apiVersion: v1
kind: Secret
metadata:
  name: vault-issuer-token
  annotations:
    kubernetes.io/service-account.name: "vault-issuer"
type: kubernetes.io/service-account-token
data: {}
  1. Create the Issuer resource referencing the Secret resource:
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: vault-issuer
  namespace: sandbox
spec:
  vault:
    path: pki_int/sign/example-dot-com
    server: https://vault.local
    caBundle: <base64 encoded caBundle PEM file>
    auth:
      kubernetes:
        role: my-app-1
        mountPath: /v1/auth/kubernetes
        secretRef:
          name: vault-issuer-token
          key: token

Verifying the issuer Deployment

Once the Vault issuer has been deployed, it will be marked as ready if the configuration is valid. Replace issuers here with clusterissuers if that is what has been deployed.

$ kubectl get issuers vault-issuer -n sandbox -o wide
NAME          READY   STATUS          AGE
vault-issuer  True    Vault verified  2m

Certificates are now ready to be requested by using the Vault issuer named vault-issuer within the sandbox namespace.