Usage

Now that your issuer is set up, you may reference it when issuing new certificates. This can be done by setting the issuerRef key on that certificate :

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: demo-cert
spec:
  commonName: demo.org
  secretName: demo-cert
  issuerRef:
    group: horizon.evertrust.io
    kind: ClusterIssuer
    name: horizon-clusterissuer

Of course, issuing certificates manually is not the usual way of requesting certificates through cert-manager. You can tap into the long list of integrations provided out of the box by cert-manager.

For instance, if you are using ingress-shim to secure your ingress resources, reference your issuer using the following annotations when creating your ingress :

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-ingress
  annotations:
    cert-manager.io/issuer-group: horizon.evertrust.io
    cert-manager.io/issuer-kind: ClusterIssuer
    cert-manager.io/issuer: horizon-clusterissuer
    cert-manager.io/common-name: demo.org
Be sure to set the cert-manager.io/common-name annotation as by default, ingress-shim will generate certificates without any DN. This will cause errors on Horizon’s side.

Configure certificate metadata

Horizon offers useful features to categorize and better understand your certificates through metadata. You may specify metadata at multiple levels. Values get overridden in the following order of precedence:

  1. Values set in the defaultTemplate object on an Issuer or ClusterIssuer object

  2. Values set on annotations either on the Ingress or Certificate object

  3. Values set in the overrideTemplate of an Issuer or ClusterIssuer object

Using defaultTemplate on an issuer

Default templates allows you to set default values for your certificates. These values will be used if no other value is set by the user on the resource they are issuing. On the Issuer or ClusterIssuer object, add the following key :

apiVersion: horizon.evertrust.io/v1beta1
kind: ClusterIssuer
spec:
  profile: IssuerProfile
  url: https://you.evertrust.io
  defaultTemplate:
    owner: owner-name
    team: team-name
    contactEmail: [email protected]
    labels:
      label-name1: label-value1
  authSecretName: horizon-credentials

On an Ingress or Certificate object

You may use the following annotations on ingresses that will be reflected onto the enrolled certificate :

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-name
  annotations:
    horizon.evertrust.io/owner: owner-name
    horizon.evertrust.io/team: team-name
    horizon.evertrust.io/contact-email: [email protected]
    horizon.evertrust.io/labels.label-name1: label-value1
    horizon.evertrust.io/labels.label-name2: label-value2

These values, if set, will take precedence over annotations on values set in the defaultTemplate key of the issuer.

Using overrideTemplate on an issuer

You may also want to ensure certain values are set on every certificate issued by a specific issuer. This can be done using the overrideTemplate key on an Issuer or ClusterIssuer object. These values will take precedence over any other value set on the issuer or on the resource being issued:

apiVersion: horizon.evertrust.io/v1beta1
kind: ClusterIssuer
spec:
  profile: IssuerProfile
  url: https://you.evertrust.io
  overrideTemplate:
    owner: owner-name
    team: team-name
    contactEmail: [email protected]
    labels:
      label-name1: label-value1
  authSecretName: horizon-credentials

These values, if set, will take precedence over annotations on an Ingress or Certificate object.