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:
venafiname:application-team-1-connectionapiVersion: 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 metIf it doesn't attain the Ready state, use
kubectl describeto 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 1m0sIn 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 Approver Policy Enterprise is unable to connect to the Venafi API, it retries the connection using an exponential backoff algorithm. The backoff interval is doubled each time, up to a maximum of 16 minutes between retries. During this time, the VenafiConnection.Status and CertificateRequestPolicy.Status are updated to indicate that the policy is not ready. However, for a period of --venafi-policy-cache-duration (default 1 minute), the controller is still able to use the last downloaded policy (thanks to caching), preventing an outage.
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.