Configuration

Before issuing certificates, you’ll have to configure an Issuer or a ClusterIssuer resource. Issuers are a cert-manager concept that describe the entity that will be used to sign certificates. In horizon-issuer, an issuer references the following information:

  • the URL of an Horizon instance;

  • a reference to a secret with credentials for the Horizon instance;

  • the name of the profile that will be used to issue certificates;

  • other settings such as metadata and optional behaviors.

You can find more information about issuers in the cert-manager documentation. Two types of issuers are supported:

  • an Issuer object, which provides a namespace-scoped issuer. This is the best choice if you provide namespaces-as-a-service for your users and want to restrict what they can do with the issuer (for instance to allow them enrolling certificates on a single profile), or want them to manage their issuers themselves;

  • a ClusterIssuer object, which provides a cluster-scoped issuer. This is the best choice if you want to provide a single issuer for the entire cluster, allowing users to simply consume the configured issuer.

Either type of issuer support the same configuration parameters described below.

Configure Horizon

Depending on your desired authorization workflow, you’ll need to configure:

  • a WebRA profile on Horizon;

  • a principal (user or X509 certificate) with the ability to:

    • enroll certificates on the profile, either through the "Enroll" or "Request enroll" permission. In the latter case, certificates requests will be submitted for approval and marked as "Pending" in Kubernetes until approved or denied in Horizon.

    • renew certificates on the profile through the "Renew" permission;

    • optionally, revoke certificates on the profile through the "Revoke" permission, if you want to revoke certificates;

After granting the correct authorizations, provide your Horizon credentials in a secret you may create with :

$ kubectl create secret generic horizon-credentials \
  --from-literal=username=<horizon username> \
  --from-literal=password=<horizon password>

Alternatively, to authenticate using an X509 certificate, use a kubernetes.io/tls Secret instead:

$ kubectl create secret tls horizon-credentials \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key

Provision an issuer

You’re ready to create an Issuer or ClusterIssuer object depending on the scope you want to issue certificates on :

clusterissuer.yaml
apiVersion: horizon.evertrust.io/v1beta1
kind: ClusterIssuer
metadata:
    name: horizon-clusterissuer (1)
spec:
    url: <horizon instance URL> (2)
    authSecretName: horizon-credentials (3)
    profile: IssuerProfile (4)
1 Name of the ClusterIssuer object, used to reference it in Certificate resources.
2 URL of the Horizon instance to connect to.
3 Name of the secret containing Horizon credentials.
4 Name of the profile to use when issuing certificates.

Then, apply the issuer manifest with :

$ kubectl apply -f clusterissuer.yaml

Additional configuration

You may provide additional configuration options in the issuer spec.

Trust custom CAs

Your Horizon instance may be presenting a certificate issued by your custom CA. To trust that certificate, you may specify a CA bundle when creating the issuer through the caBundle field. You may also completely disable TLS verification by setting skipTLSVerify to true, this is however highly discouraged.

Example :

apiVersion: horizon.evertrust.io/v1beta1
kind: ClusterIssuer
spec:
  caBundle: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  skipTLSVerify: false

You can also mount your custom /etc/ssl/certs directory if you wish to have more control over the underlying OS trust store.

Revoke deleted certificates

By default, Horizon issuer does not revoke certificates deleted from Kubernetes as cert-manager can reuse the private key kept in the deleted certificate’s secret. If you want to revoke certificates are they are deleted, set the revokeCertificates property to true on your Issuer or ClusterIssuer object :

apiVersion: horizon.evertrust.io/v1beta1
kind: ClusterIssuer
spec:
  revokeCertificates: true

When doing so, you may want to clean up secrets as soon as certificates are revoked.

Use an outbound proxy

If you need to use an outbound proxy to reach your Horizon instance, you may specify it in the proxy field of your Issuer or ClusterIssuer object :

apiVersion: horizon.evertrust.io/v1beta1
kind: ClusterIssuer
spec:
  proxy: http://proxy.example.com:8080

Validate the certificate FQDN

In case you want to enforce the coherence of your infrastructure, we offer a DNS validation feature. When enabled, the issuer will check that a DNS entry matching the certificate CN and every DNS SANs exist. If not, the certificate will not be issued. To enable, add the following key to your Issuer object :

apiVersion: horizon.evertrust.io/v1beta1
kind: ClusterIssuer
spec:
  dnsChecker:
    server: 8.8.8.8:53