Deploy a Firefly in Kubernetes¶

As the Kubernetes platform administrator for the environment where Firefly will be deployed, you will need to consult with the TLS Protect Datacenter administrator to understand how Firefly should operate.

This is important to ensure that you configure Firefly properly. Your TLS Protect Datacenter administrator will need to provide you with the following information:

TLS Protect Datacenter URL: This is the base URL of the TLS Protect Datacenter instance that you have configured to manage Firefly.
Authentication type: This is the authentication method that Firefly will use to authenticate with TLS Protect Datacenter. In this example, it is OIDC authentication. For username & password authentication, you will also need to get the credentials.
Naming pattern for the Firefly instances: The Firefly instances have names that are included in the common name of the required subordinate CA certificates. This naming pattern can be used to distinguish between different Firefly instances.
Name of the Firefly security configuration: This is the name or the full DN of the security configuration that was pushed in the previous section to TLS Protect Datacenter. In our example, this is firefly\\security-config.
Usage of HSM: This indicates whether a Hardware Security Module (HSM) will be required to generate and store the private key for the subordinate CA certificate of Firefly.

In addition, you need to consider the following:

How clients will request certificates from Firefly. The options include:
- Firefly will act as a server, exposing HTTP-based protocols to allow clients to request certificates over protocols such as REST API.
- Firefly will serve as a cert-manager issuer within the Kubernetes cluster.
If an HSM is required, you must follow the guide at Building a container image for Firefly that uses an HSM to build the container image.
Whether the TLS Protect Datacenter is using a publicly trusted TLS certificate for its API, allowing Firefly to operate without the need to specify a custom trusted CA bundle.

Deploying using Helm¶

A Helm chart is available for Firefly, allowing users to easily deploy and configure it.

Before you begin

You need all the following software installed on your local machine:
- helm
- kubectl
- cmctl
You need to install cert-manager in your cluster, because Firefly operates as a cert-manager issuer and expects to be able to interact with cert-manager Custom Resources.

Review the Venafi End User License Agreement. In the last step you will agree to abide by these Terms.
Create a Kubernetes namespace called venafi.
```
kubectl create ns venafi
```
If needed, deploy the Venafi Connection CRD.
How to check the Venafi Connection CRD is deployed

For OIDC authentication to the TLS Protect Datacenter, Firefly uses a VenafiConnection custom resource. This custom resource can be created once the VenafiConnection CRD has been deployed. The CRD may have already been deployed as part of the installation of other components that depend on the VenafiConnection CRD, such as the Venafi Enhanced Issuer or Venafi Kubernetes Agent. If it has not been deployed, you will need to do so manually.

To check if the VenafiConnection CRD is deployed, run:
```
kubectl get crd venaficonnections.jetstack.io
```
If the CRD is deployed, you should see details about the VenafiConnection CRD. If it is not deployed, the command will return an error indicating that the CRD does not exist.

To install the VenafiConnection CRD, either specify venafiConnection.include: true in the values file when installing Firefly, or install it directly using the command below:
```
helm install venafi-connection oci://registry.venafi.cloud/charts/venafi-connection\
  --namespace venafi\
  --version v0.4.0
```
If needed, configure a custom trust CA bundle when the TLS Protect Datacenter is using a non-publicly trusted TLS certificate for its API.
Create a custom CA bundle

Place the CA chain of the TLS certificate used by your TLS Protect Datacenter instance into a file named cacerts.pem. Then, store it as a Kubernetes Secret using the following command:
```
kubectl create secret generic ca-bundle-cert \
  --namespace venafi \
  "--from-file=ca-bundle-cert=cacerts.pem"
```
Create a firefly.values.yaml file with the following content. This file includes the minimum configuration. For more options and detailed configuration, see the Firefly configuration YAML reference page.
firefly.values.yaml
```
acceptTerms: true
deployment:
  extraVolumes: # (1)!
  - name: ca-bundle-cert
    secret:
      secretName: ca-bundle-cert
  extraVolumeMounts: # (2)!
  - mountPath: /etc/ssl/certs/
    name: ca-bundle-cert
  config:
    bootstrap:
      tpp:
        enabled: true
        csr:
          instanceNaming: Instance1 Location1 # (3)!
        configurationDN: firefly\\security-config # (4)!
        connection:
          create: true # (5)!
          name: tpp-connection
          url: https://tpp.example.com/ # (6)!
          serviceAccountToken: # (7)!
            enabled: true
    controller:
      enabled: true # (8)!
      certManager:
        caRootChainPopulation: false # (9)! 
        checkApproval: true # (10)!
```
1. Omit this section if TLS Protect Datacenter is using a publicly trusted TLS certificate for its API.
2. Omit this section if TLS Protect Datacenter is using a publicly trusted TLS certificate for its API.
3. The naming pattern for the Firefly instances.
4. The name of the Firefly security configuration.
5. If set to true, a VenafiConnection will be created with the specified name and authentication method.
6. The TLS Protect Datacenter URL.
7. The OIDC authentication type.
8. Set to false if you don't want Firefly to act as a Kubernetes Controller and process cert-manager Certificate resources.
9. Set to true if you want to automatically populate the status.ca field with the CA information.
10. Set to false if you want Firefly to process CertificateRequest resources without waiting for approval.

Install Firefly using Helm

helm install prod oci://registry.venafi.cloud/public/venafi-images/helm/firefly \
    --namespace venafi \
    --values firefly.values.yaml \
    --version v1.6.0

Verifying the installation¶

Verify the installation using cmctl to create a test certificate.

First, create a file called certificate.yaml containing your desired test certificate:

certificate.yaml

kind: Certificate
apiVersion: cert-manager.io/v1
metadata:
  annotations:
    firefly.venafi.com/policy-name: Policy # (1)!
spec:
  commonName: example.com # (2)!
  issuerRef:
    name: firefly
    kind: Issuer
    group: firefly.venafi.com

This value must match the policy name defined in the security configuration.
This value must comply with the subject.commonName.allowedValues of the policy.

Use cmctl to create a cert-manager CertificateRequest and wait for the signed certificate:
```
cmctl create certificaterequest my-cr \
  --from-certificate-file certificate.yaml \
  --fetch-certificate
```
If successful, cmctl will print the filename of a .key and a .crt file. You can examine the signed X.509 certificate using openssl, as follows:
```
openssl x509  -in my-cr.crt -noout -text
```