Cert-manager - Networking4all ACME Documentation

Integration guide for cert-manager on Kubernetes and OpenShift with the Networking4all ACME server

Cert-manager is a popular solution for X.509 certificate management for Kubernetes and OpenShift which includes support for ACME.
In this section we will provide you with some starter resources you can modify to get up and running with the Networking4all ACME server.

Creating a ClusterIssuer resource for ACME

If you prefer namespace-scoped configuration, you can use an Issuer instead of a ClusterIssuer. The configuration is otherwise identical, aside from the kind and namespace metadata.

Some acknowledgements before we begin:

our cert-manager namespace during these examples will be called cert-manager
the ACME server we use will be from the test environment as we highly recommend you to test there before you use this in production
any solvers you set in your resource will be entirely up to you but be aware that any http01/dns01 solver will suffice as we always validate your domains through the DNS record you created before

Create the EAB secret

Before we can add our ClusterIssuer resource we need to create a secret which will hold the ACME secret you received as part of your ACME credentials. We will then reference this secret under keySecretRef when we add our externalAccountBinding information to the ClusterIssuer resource later.

kubectl create secret generic eab-secret --from-literal secret=<YOUR-ACME-SECRET-HERE> -n cert-manager

Create the ClusterIssuer resource

We now have our ACME secret stored in eab-secret and can create the ClusterIssuer resource:

cluster-issuer-networking4all-dv.yaml

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: test-acme-networking4all-com-dv
spec:
  acme:
    email: user@example.com
    server: https://test-acme.networking4all.com/dv
    externalAccountBinding:
      keyID: <YOUR-ACME-KID-HERE>
      keySecretRef:
        name: eab-secret
        key: secret
  privateKeySecretRef:
    name: test-acme-networking4all-com-dv
  solvers:
  - dns01:
    cloudflare:
      email: nonsense@example.com
      apiTokenSecretRef:
        name: cf-secret
        key: cf-token

You might need to create several unique ClusterIssuer resources when you plan on ordering more than one type of product. You would then change name: test-acme-networking4all-com-dv and server: https://test-acme.networking4all.com/dv in the additional resources to reference the different products while keeping the externalAccountBinding section the same.

Note that you also have to update the externalAccountBinding information in the situation where you need to order an OV certificate for a different organization. Every organization has its own set of credentials, this way we can properly validate OV certificates for subsidiary organizations. This also has the added benefit of you being able to distribute unique credentials to subsidiary organizations that need to manage their own certificate requests on a different infrastructure than your own.

Creating a Certificate resource

The following is a certificate resource for example.com and its SAN www.example.com which will be ordered through the ClusterIssuer we created before.

certificate-example-com.yaml

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com
  namespace: default
spec:
  secretName: example-com-tls
  duration: 4776h   # 199 days - note that this will change in the near future
  renewBefore: 240h # 10 days  - keep this value under 16 days to prevent unnecessary reissues
  issuerRef:
    name: test-acme-networking4all-com-dv
    kind: ClusterIssuer
  commonName: example.com
  dnsNames:
    - example.com
    - www.example.com

Applying the resources

Now that we have created the resources we can apply them:

kubectl apply -f /your/directory/issuers/cluster-issuer-networking4all-dv.yaml
kubectl apply -f /your/directory/certificates/certificate-example-com.yaml

After a short moment your certificate should be issued:

kubectl get certificate example-com

During your testing phase a quick way to restart the certificate procurement is by deleting the certificate secret like so:

kubectl delete secret example-com-tls

This should immediately start a new attempt of acquiring the certificate from our ACME server.