Configuring Enterprise Issuer for Next-Gen Trust Security¶

Once Enterprise Issuer is installed, configure it to issue certificates by creating a VenafiIssuer or VenafiClusterIssuer resource in your cluster.

Prerequisites¶

To configure Enterprise Issuer, you must have:

Enterprise Issuer installed in your cluster.
Connection for Next-Gen Trust Security (Connection resource) configured to authenticate with Next-Gen Trust Security (NGTS).
An Issuing Template created in NGTS.

Step 1: Create an issuer¶

Choose an issuer type, create a manifest that references Connection resource and your Issuing Template, and apply the manifest.

Namespaced vs cluster-scoped issuers

VenafiClusterIssuer is cluster-scoped and has no namespace. Any Connection resource referenced by a VenafiClusterIssuer must be in the same namespace as Enterprise Issuer.
VenafiIssuer is namespaced. Any Connection resource referenced by a VenafiIssuer must be in the same namespace as the VenafiIssuer resource or in a namespace explicitly allowed in the Connection resource resource definition.

Create one of the following issuers that references your VenafiConnection and specifies the Issuing Template to use:

VenafiClusterIssuer¶

Use VenafiClusterIssuer for cluster-wide access. The example below assumes a Connection resource named ngts-connection is in the venafi namespace.
ngts-cluster-issuer.yaml
```
apiVersion: jetstack.io/v1alpha1
kind: VenafiClusterIssuer
metadata:
  name: ngts-cluster-issuer
spec:
  venafiConnectionName: ngts-connection
  zone: "Issuing Template Name" # (1)!
```
1. Replace with the name of your NGTS Issuing Template.
VenafiIssuer — same namespace¶

Use VenafiIssuer for a single namespace. The example below assumes a Connection resource named ngts-connection is in the same namespace.
ngts-issuer.yaml
```
apiVersion: jetstack.io/v1alpha1
kind: VenafiIssuer
metadata:
  name: ngts-issuer
  namespace: venafi
spec:
  venafiConnectionName: ngts-connection
  zone: "Issuing Template Name" # (1)!
```
1. Replace with the name of your Issuing Template in NGTS.
VenafiIssuer — cross namespace¶

Use VenafiIssuer when the issuer and Connection resource are in different namespaces. The example below assumes a Connection resource named ngts-connection in the venafi namespace.

Grant cross-namespace access

Configure Connection resource's allowReferencesFrom field to allow access from the target namespace. See About cross-namespace access.
ngts-issuer-cross-ns.yaml
```
apiVersion: jetstack.io/v1alpha1
kind: VenafiIssuer
metadata:
  name: ngts-issuer
  namespace: application-team-1
spec:
  venafiConnectionName: ngts-connection
  venafiConnectionNamespace: venafi
  zone: "Issuing Template Name" # (1)!
```
1. Replace with the name of your Issuing Template in NGTS.
(Optional) Customize how certificates are named:

In NGTS, certificates with the same name are grouped into one certificate object, where the most recent request is the current state and older certificates are kept in the object's history. Choose the name carefully so certificates are grouped correctly.

Add the certificateNameExpression field to the issuer spec to set a custom CEL expression for the certificate object name. For example, base it on the namespace and name of the request:
```
  certificateNameExpression: >-
    request.namespace + "_" + request.name
```
You can also base it on a custom field, with fallbacks to other request attributes:
```
  certificateNameExpression: >- # (1)!
    optional.none().
      or(
        request.
          annotations[?"venafi.cert-manager.io/custom-fields"].
          orValue("[]").
          parseJSON().
          filter(x, x.name == "field-name-2")[?0].
          value
      ).
      or(request.?commonName).
      or(request.dnsNames[?0]).
      value()
```
1. certificateNameExpression sees only a request's annotations. Issuer-level custom fields are merged in later, so they aren't available here.
To see all request attributes you can use in the expression, run:
```
kubectl explain venafiissuer.spec.certificateNameExpression
```
Apply the manifest:
```
kubectl apply -f <manifest-file>.yaml
```

Step 2 (Optional): Customize certificate metadata¶

Customize the certificates your issuer produces with annotations that contain metadata. For example, you might add a specific business unit or environment.

You can add annotations at the issuer or certificate level. To do this, use the venafi.cert-manager.io/custom-fields annotation with a JSON array of {"name", "value"} objects, as shown in the following examples.

Annotations at both levels

If you add annotations on both the issuer and certificate level, Enterprise Issuer merges them. The certificate's value wins for any field with the same name and fields set on only one level are retained. The merged list is sorted by name.

Set custom fields on the issuer¶

Add the annotation to your VenafiIssuer or VenafiClusterIssuer to apply defaults for every certificate it issues.

ngts-cluster-issuer.yaml

apiVersion: jetstack.io/v1alpha1
kind: VenafiClusterIssuer
metadata:
  name: ngts-cluster-issuer
  annotations:
    venafi.cert-manager.io/custom-fields: |-
      [
        {"name": "Environment", "value": "Production"},
        {"name": "Division", "value": "Platform"}
      ]
spec:
  venafiConnectionName: ngts-connection
  zone: "Issuing Template Name" # (1)!

Replace with the name of your NGTS Issuing Template.

Override or add fields for a specific certificate¶

Add an annotation to an individual cert-manager Certificate resource to override the issuer defaults or add extra fields for that certificate only:

metadata:
  annotations:
    venafi.cert-manager.io/custom-fields: |-
      [
        {"name": "Division", "value": "Security"},
        {"name": "Environment", "value": "Staging"}
      ]

Invalid JSON

Malformed JSON in an issuer annotation fails every request against that issuer with a permanent error that names the issuer. Malformed JSON in a certificate annotation fails only that certificate's request.

Step 3: Request a test certificate¶

Create a cert-manager Certificate resource that references the issuer you created:

example-cert.yaml

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-cert
  namespace: venafi
spec:
  secretName: example-cert-tls
  commonName: example.com
  dnsNames:
  - example.com
  - www.example.com
  issuerRef:
    name: ngts-issuer # (1)!
    kind: VenafiIssuer # (2)!
    group: jetstack.io

Replace with the name of the VenafiIssuer or VenafiClusterIssuer you created.
Use VenafiClusterIssuer if you created a cluster-scoped resource.

Apply the manifest:

kubectl apply -f example-cert.yaml

Once applied, cert-manager requests a certificate from NGTS through Enterprise Issuer and Connection resource.

Step 4: Verify certificate issuance¶

Check the status of the certificate:
```
kubectl get certificate example-cert -n venafi
```
When the certificate has been issued, the READY column shows True:
```
NAME           READY   SECRET             AGE
example-cert   True    example-cert-tls   30s
```
If the certificate isn't ready after a few minutes, inspect the resources and see Troubleshooting Enterprise Issuer.
To verify the issued certificate, inspect the leaf certificate in the Secret:
```
kubectl get secret example-cert-tls -n venafi -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -text -noout
```
Verify the Subject, Issuer, and Subject Alternative Names.

Configuring Enterprise Issuer for Next-Gen Trust Security¶

Prerequisites¶

Step 1: Create an issuer¶

VenafiClusterIssuer¶

VenafiIssuer — same namespace¶

VenafiIssuer — cross namespace¶