Approver Policy Enterprise Venafi plugin¶

Approver Policy Enterprise includes a Venafi plugin which allows it to connect to a Venafi Control Plane server and apply the policy settings of a particular policy folder or issuing template. The Approver Policy Enterprise project uses Venafi Connection project to configure connections to the Venafi Control Plane.

Creating a certificate request policy containing a Venafi plugin configuration¶

The sample below assumes that the following Venafi Connection certificate request exists: namespace: venafi name: application-team-1-connection

    apiVersion: policy.cert-manager.io/v1alpha1
    kind: CertificateRequestPolicy
    metadata:
      ame: venafi-policy1
    spec:
      allowed:
        commonName:
          value: "*"
        dnsNames:
          values: ["*"]
        usages:
          - "signing"
          - "digital signature"
          - "server auth"
      plugins:
        venafi:
          values:
            venafiConnectionName: application-team-1-connection
            zone: "application-name\\issuing-template-name"
      selector:
        issuerRef: {}

After the connection defined in the Venafi Connection certificate request tests without errors, the certificate request policy can check the specified zone and becomes Ready.

    $ kubectl wait --for=condition=Ready  certificaterequestpolicy venafi-policy1
    certificaterequestpolicy.policy.cert-manager.io/application-name condition met

If it doesn't attain the Ready state, use kubectl describe to see what is wrong. E.g.:

    $ kubectl describe certificaterequestpolicy tpp-policy1
    ...
    Warning  NotReady  5s (x2 over 5s)
    policy.cert-manager.io  CertificateRequestPolicy is not ready for approval evaluation: spec.plugins.tpp.values: Invalid value: "while
    getting zone configuration for policy: while creating vcert client: vcert error: your data contains problems: auth error: failed to
    authenticate: can't determine valid credentials set": Retrying in 1m0s

In this example you can see that the credentials are invalid or are missing. If you edit the Secret and add the correct the credentials, they will be rechecked within 1 minute and the CertificateRequestPolicy will then become Ready.

Creating an approved certificate¶

Once the CertificateRequestPolicy is Ready, you can create a certificate which is allowed by your policy in Venafi Control Plane:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: approved-certificate
spec:
  commonName: hello.world
  dnsNames:
    - "hello.world"
    - "example.hello.world"
  privateKey:
    algorithm: RSA
    size: 4096
  issuerRef:
    name: my-issuer
    kind: Issuer
    group: cert-manager.io

$ cmctl create certificaterequest approved-certificate --from-certificate-file cert-approve.yaml

You see an event that says that the certificate request was approved:

$ kubectl get events
LAST SEEN   TYPE      REASON           OBJECT                                    MESSAGE
2m2s        Normal    Approved         certificaterequest/approved-certificate   Approved by CertificateRequestPolicy: "application-name\issuing-template-name"

Creating a denied certificate¶

The instructions depend on whether TLS Protect Datacenter or TLS Protect Cloud is being used. For detailed instructions, please refer to the corresponding documentation.

Periodic configuration and connection health checks¶

As a Kubernetes platform administrator, having installed a certificate request policy, you need to know that Approver Policy Enterprise continues to be able to connect to the Venafi API, and that it continues to be able to download the Venafi policy settings. You also need to know about any problems before they affect the approval of certificate request resources.

The Approver Policy Enterprise Venafi plugin periodically performs a health check which connects to the Venafi API and downloads the policy configuration. It reports errors via the CertificateRequestPolicy.Status and with structured log messages. You can set up your monitoring systems to either check the Ready condition in the CertificateRequestPolicy.Status, or set up alerts when errors are logged by the Approver Policy Enterprise component.

You can configure the interval between health checks using the --venafi-ready-check-interval flag. The default interval is 1 hour.

If you need to reduce the frequency of Venafi API requests you can increase this interval, but this delays your alerts and it takes longer for you to be notified if there is a problem with the connection to the Venafi API.

For more information, see Approver Policy Enterprise administration.

Troubleshooting configuration and connection validation¶

The Approver Policy Enterprise Venafi plugin connects to a Venafi API server and downloads policy data. If there is a failure (e.g. a connection failure, authentication error or a download failure), then certificate request resources is denied and isn't processed by cert-manager.

You can use kubectl describe to examine the Ready condition and Event resources associated with a particular certificate request policy. The CertificateRequestPolicy.Status is updated when ever the CertificateRequestPolicy is created or modified.

If the policy has been downloaded successfully, you will see something like:

$ kubectl describe certificaterequestpolicy application-team-1
...
Status:
  Conditions:
    Message:               CertificateRequestPolicy is ready for approval evaluation
    Reason:                Ready
    Status:                True
    Type:                  Ready
...
Events:
  Type    Reason  Age                 From                    Message
  ----    ------  ----                ----                    -------
  Normal  Ready   42m (x12 over 19h)  policy.cert-manager.io  CertificateRequestPolicy is ready for approval evaluation

If the connection failed, a message similar to the following is displayed:

$ kubectl describe certificaterequestpolicy application-team-1
Status:
  Conditions:
    Message:               CertificateRequestPolicy is not ready for approval evaluation: spec.plugins.venafi.values: Invalid value: "while getting zone configuration for policy: connection is not ready yet (Venafi self-test failed): error authenticating with Venafi: vcert error: server error: server unavailable: Get \"https://api.venafi.cloud/v1/useraccounts\": dial tcp: lookup api.venafi.cloud on 10.96.0.10:53: server misbehaving": Retrying in 1h0m0s
    Reason:                NotReady
    Status:                False
    Type:                  Ready
...
Events:
  Type     Reason    Age                    From                    Message
  ----     ------    ----                   ----                    -------
  Warning  NotReady  112s (x76 over 6m55s)  policy.cert-manager.io  CertificateRequestPolicy is not ready for approval evaluation: spec.plugins.venafi.values: Invalid value: "while getting zone configuration for policy: connection is not ready yet (Venafi self-test failed): error authenticating with Venafi: vcert error: server error: server unavailable: Get \"https://api.venafi.cloud/v1/useraccounts\": dial tcp: lookup api.venafi.cloud on 10.96.0.10:53: server misbehaving": Retrying in 1h0m0s

You can also check the status of the venaficonnection resource, as follows:

$ kubectl describe -n venafi venaficonnection
...
Status:
  Conditions:
    Last Transition Time:  2023-03-24T09:50:46Z
    Message:               connection is not ready yet (Venafi self-test failed): error authenticating with Venafi: vcert error: server error: server unavailable: Get "https://api.venafi.cloud/v1/useraccounts": net/http: request canceled (Client.Timeout exceeded while awaiting headers)

And you can check the Approver Policy Enterprise logs, as follows:

$ kubectl logs -n venafi deploy/cert-manager-approver-policy cert-manager-approver-policy
...
E0324 09:50:46.172533       1 plugin.go:286] venafi/evaluate "msg"="Internal CertificateRequestPolicy evaluation error" "error"="while getting zone configuration for policy: connection is not ready yet (Venafi self-test failed): error authenticating with Venafi: vcert error: server error: server unavailable: Get \"https://api.venafi.cloud/v1/useraccounts\": net/http: request canceled (Client.Timeout exceeded while awaiting headers)" "UID"="2405bccb-c445-4291-a9d5-4a63dc99a5b2" "certificaterequest"={"Namespace":"application-team-1","Name":"service-1-4xwxw"} "description"="The VenafiConnection is invalid." "policy"={"Namespace":"","Name":"application-team-1"}
I0324 09:50:46.176662       1 recorder.go:103] controller-manager/events "msg"="No policy approved this request: [application-team-1: Internal CertificateRequestPolicy evaluation error: 2405bccb-c445-4291-a9d5-4a63dc99a5b2]" "object"={"kind":"CertificateRequest","namespace":"application-team-1","name":"service-1-4xwxw","uid":"20d6ae73-0889-4850-8a91-331f264f3c32","apiVersion":"cert-manager.io/v1","resourceVersion":"112056"} "reason"="Denied" "type"="Warning"

If you create a certificate request while there is a Venafi connection failure, you may see that your certificate request is denied and an associated generic Warning Event:

$ kubectl describe cr -n application-team-1 service-1-4xwxw
...
Events:
  Type     Reason              Age    From                                                Message
  ----     ------              ----   ----                                                -------
...
  Warning  Denied              7m11s  policy.cert-manager.io                              No policy approved this request: [application-team-1: Internal CertificateRequestPolicy evaluation error: 2405bccb-c445-4291-a9d5-4a63dc99a5b2]

The warning message deliberately omits the specific details of the error, because the details may reveal sensitive infrastructure details. Instead, the message contains a UUID which can be shared with the platform administrator, so that they can diagnose the problem by looking up that UUID in the logs.