Installing Keyfactor ACME in Containers Under Kubernetes

When Keyfactor ACME is installed in a containerized implementation, it runs in two containers (one short-lived) under Kubernetes and is managed with a Helm chart.

The artifactory for Keyfactor ACME images can be found in the following JFrog repository:

Setup Kubernetes Resources

The following steps copy necessary files and create Kubernetes secrets to prepare for the Keyfactor ACME install.

1. On your Kubernetes server, create a directory from which you will run the install. For example:

   sudo mkdir /opt/kyf_acme

2. If desired, create a namespace for Keyfactor ACME resources and containers in Kubernetes. For example:

   sudo kubectl create namespace keyfactor-acme

3. Create a ConfigMap in Kubernetes containing CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. root and issuing certificates for all CAs relevant to this instance of Keyfactor ACME, which have been placed in the root trust store of the Kubernetes server (see Prepare Certificate Root Trusts).

   Once the host’s trust store is updated with all the certificates you will need, create the ConfigMap. For example:

   sudo kubectl create ConfigMap ca-roots --namespace keyfactor-acme --from-file=/etc/ssl/certs/ca-certificates.crt
   Note:  The standard path to the trusted root store will vary depending on your Linux implementation.

4. Create a secret in Kubernetes for the credentials you will use to authenticate to the Keyfactor artifactory. For example:

   sudo kubectl create secret docker-registry image-creds --namespace keyfactor-acme --docker-server=repo.keyfactor.com --docker-username=YourRepoUsername --docker-password=YouSuperSecretRepoAPIKeyorToken --docker-email=my.email@my-domain.com
   Note:  For artifactory credentials or more information, check with your Keyfactor Client Success Manager or contact support@keyfactor.com.

5. Create a secret in Kubernetes to allow Keyfactor ACME to authenticate to Keyfactor Command (see Preparing). For example:

   For example, using an OAuth identity provider:

   sudo kubectl create secret generic oauth-secret --namespace keyfactor-acme --from-literal=client-secret=Your_ACME_Client_Secret

   For example, using a Basic authentication credential:

   sudo kubectl create secret generic basic-secret --namespace keyfactor-acme --from-literal=client-secret=Your_ACME_User_Password

6. Create secrets in Kubernetes for the connection string used to access your SQL server. For example:

   sudo kubectl create secret generic connection-strings -n keyfactor-acme --from-literal=connection-key="Data Source=<SQL_MACHINE_FQDN>;Initial Catalog=<SQL_DB_NAME>;Integrated Security=False;Persist Security Info=True;User ID=<USERNAME>;Password=<PASSWORD>;"
   Note:  If you prefer, you may specify the SQL server name, database name, username, and password in the values file directly instead, but Keyfactor recommends using a secret for best security practice.

7. Prepare and create secrets in Kubernetes for the TLS TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. certificate that will secure communications to the Keyfactor ACME server. For example:

   1. Acquire the TLS certificate using the Fully Qualified Domain Name (FQDN) of the server or alias used for the Kubernetes cluster where your Keyfactor ACME implementation will be installed. This is the name that you will use to access Keyfactor ACME via a browser for management purposes.

   2. Copy the certificate together with its private key Private keys are used in cryptography (symmetric and asymmetric) to encrypt or sign content. In asymmetric cryptography, they are used together in a key pair with a public key. The private or secret key is retained by the key's creator, making it highly secure. to your working directory on the Kubernetes server.

   3. Depending on the method you used to acquire your certificate, you may need to manipulate it on the Kubernetes server to get it into the correct format. You need separate PEM A PEM format certificate file is a base64-encoded certificate. Since it's presented in ASCII, you can open it in any text editor. PEM certificates always begin and end with entries like ---- BEGIN CERTIFICATE---- and ----END CERTIFICATE----. PEM certificates can contain a single certificate or a full certifiate chain and may contain a private key. In general, extensions of .cer and .crt are certificate files with no private key, .key is a separate private key file, and .pem is both a certificate and private key.-encoded unencrypted private key and certificate files. If your certificate is a PKCS#12 A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers. file, you can use OpenSSL commands similar to the following to extract the certificate and key:

      Extract just the certificate, not any chain certificates or the key:

      sudo openssl pkcs12 -in /opt/kyf_acme/acme_cert.pfx -clcerts -nokeys -out /opt/kyf_acme/acme_cert.crt

      Extract just the key:

      sudo openssl pkcs12 -in /opt/kyf_acme/acme_cert.pfx -nocerts -out /opt/kyf_acme/acme_cert_key.pem

      Decrypt the key:

      sudo openssl rsa -in /opt/kyf_acme/acme_cert_key.pem -out /opt/kyf_acme/acme_cert_key-plain.pem
      Important:  The decrypted key file should be handled carefully and stored securely. Once the secret is created (next step), the decrypted key file should be removed.

   4. Create the secrets for the certificate. For example:

      kubectl create secret tls ingress-tls --namespace keyfactor-acme --cert /opt/kyf_acme/acme_cert.crt --key /opt/kyf_acme/acme_cert_key-plain.pem

Helm Chart Customization

Keyfactor ACME ships with a helm chart that contains most of the configuration needed to get up and running, but a few additional pieces of information are needed. These are provided via a separate values file that feeds into the helm chart so that the actual helm chart does not need to be edited. See the below values file. Some fields in this file are required, and others are optional.

Create an input file to the helm chart similar to the following, using the inputs as per Table 14: Keyfactor ACME Containerized Installation Values File Settings. Use a text editor to update the file, based on the below sample. For example:

The fields highlighted in red below indicate fields that need to be edited or that you may wish to edit. The fields highlighted in green indicate data provided with secrets or ConfigMaps created in the previous section.

# You can choose to supply connection info as plaintext or from an existing secret. Uncomment the appropriate section.
connectionStrings:
  existingSecretName: connection-strings
  existingSecretKey: connection-key
  #hostname: "SQL-HOSTNAME"
  #database: "DATABASE NAME"
  #username: "USERNAME"
  #password: "PASSWORD"

ingress:
  enabled: true
  hostname: "ACME-FQDN-HOSTNAME"
  tlsSecretName: ingress-tls
  className: nginx

# The workload defaults apply to the implementation as a whole (all containers)
workloadDefaults:
  volumes:
    - name: root-cas
      configMap:
        name: ca-roots
        items:
          - key: ca-certificates.crt
            path: ca-certificates.crt

  volumeMounts:
    - name: root-cas
      mountPath: /etc/ssl/certs/ca-certificates.crt
      subPath: ca-certificates.crt

  logLevel: INFO
  image:
    pullPolicy: Always
    pullSecrets:
      - name: image-creds

# Settings for the ACME server container
acme:
  image:
    name: acme
    path: /acme

# Settings for the short-lived ACME setup container
config:
  image:
    name: acme-config
  enrollmentUrl: https://COMMAND-FQDN-HOSTNAME/KeyfactorAPI
  commandConnection:
    oAuth:
      clientId: ACME
      clientSecret:
        secretName: oauth-secret
        secretKey: client-secret
      authority: 'https://appsrvr187.keyexample.com:5443/realms/Keyfactor'
      tokenUrl: 'https://appsrvr187.keyexample.com:5443/realms/Keyfactor/protocol/openid-connect/token'
      #scope:
      #audience:
  acmeConnection:
    authority: 'https://appsrvr186.keyexample.com:4443/realms/Keyfactor'
    jsonWebKeySetUri: 'https://appsrvr186.keyexample.com:4443/realms/Keyfactor/protocol/openid-connect/certs'
    nameClaimType: 'preferred_username'
    roleClaimType: 'groups'
    uniqueClaimType: 'sub'
  # Multiple claim types/values can be defined under superUsers. At least one must be defined.
  # All users/groups defined here will be granted the SuperAdmin role.
  superUsers:
    - claimType: sub
      claimValue: 9dc26f43-c694-45dc-8680-132db3aeb54f
    - claimType: client_id
      claimValue: ACME-Client
    - claimType: role
      claimValue: ACME-Super-Users
  forceUpgrade: false
  forceSecretReencryption: false

Install

To install Keyfactor ACME in containers under Kubernetes with a Helm chart:

1. Set the permissions on the values file such that the file is owned by root and readable only by root (this assumes your Kubernetes implementation is running as root, which is typical). For example:

   sudo chown root:root /opt/kyf_acme/values.yaml
   sudo chmod 400 /opt/kyf_acme/values.yaml
   Tip:  If you need to make edits to the values file, you will need to make the file writable again. For example:

   sudo chmod 600 /opt/kyf_acme/values.yaml

2. Login to the JFrog repository so that you may retrieve the helm chart. For example:

   sudo helm registry login repo.keyfactor.com --password YouSuperSecretRepoAPIKeyorToken --username YourRepoUsername

   Confirm that login completes successfully.

3. Run the install, giving the deployment a name and referencing your customized values file. For example:

   sudo helm install Helm_Deployment_Name --namespace keyfactor-acme --values values.yaml oci://repo.keyfactor.com/charts/command/acme --version 1.0.0