Install Keyfactor Command in Containers Under Kubernetes

When Keyfactor Command is installed in a containerized implementation, it runs in multiple containers under Kubernetes and is managed with a Helm chart.

The artifactory for Keyfactor Command 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 Command install.

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

   sudo mkdir /opt/kyf_command

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

   sudo kubectl create namespace keyfactor-command

3. Copy your Keyfactor Command license file to your working directory on the Kubernetes server. This license file should be provided to you by Keyfactor and should have the extension cmslicense.

4. 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 in the environment that will have any relationship with Keyfactor Command and placed in the root trust store of the Kubernetes server (see Configure Certificate Chain Trusts for CAs).

   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-command --from-file=/etc/ssl/certs/ca-certificates.crt
   Note:  The standard path to the trusted root store will vary depending on your Linux implementation.

5. 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-command --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.

6. Create a secret in Kubernetes for your license file (see Licensing). For example:

   sudo kubectl create secret generic command-license --namespace keyfactor-command --from-file=license-content=/opt/kyf_command/your-license-file.cmslicense

7. Create secrets in Kubernetes to allow Keyfactor Command to authenticate to your OAuth provider (see Selecting an Identity Provider for Keyfactor Command). This requires typically two clients in your OAuth provider and two secrets (see Grant Access and Create Service Accounts for Keyfactor Command). If you’re using the same client for both roles, the secret must still be specified twice. For example:

   sudo kubectl create secret generic idp-secrets --namespace keyfactor-command --from-literal=client-secret=Your_Primary_OIDC_Client_Secret --from-literal=command-api-client-secret=Your_Secondary_API_Query_Client_Secret

   If you’re using the same client for both roles, the secret must still be specified twice.

8. Create secrets in Kubernetes for connection strings used to access your SQL server. For example:

   sudo kubectl create secret generic connection-strings -n keyfactor-command --from-literal=ef="metadata=res://*/EFModels.csdl\\|res://*/EFModels.ssdl\\|res://*/EFModels.msl;provider=Microsoft.Data.SqlClient;provider connection string='Data Source=<SQL_MACHINE_FQDN>;Initial Catalog=<SQL_DB_NAME>;Integrated Security=False;User ID=<USERNAME>;Password=<PASSWORD>;Encrypt=true;Persist Security Info=True;Command Timeout=360;Multiple Active Result Sets=True;Application Name=EntityFramework'" --from-literal=sqlDirect="Data Source=<SQL_MACHINE_FQDN>;Initial Catalog=<SQL_DB_NAME>;Integrated Security=False;Persist Security Info=True;Command Timeout=360;User ID=<USERNAME>;Password=<PASSWORD>;Encrypt=true;"
   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.

9. 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 Command 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 Command implementation will be installed. This is the name that you will use to access Keyfactor Command via a browser for management purposes and via the Keyfactor API An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command..

   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_command/command_cert.pfx -clcerts -nokeys -out /opt/kyf_command/command_cert.crt

      Extract just the key:

      sudo openssl pkcs12 -in /opt/kyf_command/command_cert.pfx -nocerts -out /opt/kyf_command/command_cert_key.pem

      Decrypt the key:

      sudo openssl rsa -in /opt/kyf_command/command_cert_key.pem -out /opt/kyf_command/command_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-command --cert /opt/kyf_command/command_cert.crt --key /opt/kyf_command/command_cert_key-plain.pem

10. If you’re using one or more Keyfactor CA Connector The Keyfactor CA Connector is installed in the customer environment to provide a connection between a CA and Keyfactor Command when a direct connection is not possible. It is supported on both Windows and Linux and has versions for Microsoft (Windows only) or EJBCA CAs. Clients to communicate with Microsoft CAs, create a secret for RabbitMQ. First, determine whether you will be authenticating to RabbitMQ using Basic authentication or OAuth authentication. For example, if you’re using Basic authentication:

    kubectl create secret generic rabbit-secret --namespace keyfactor-command --from-literal=job-queue-password=Your-RabbitMQ-BasicAuth-Password

    For example, if you're using OAuth authentication:

    kubectl create secret generic rabbit-secret --namespace keyfactor-command --from-literal=job-queue-client-secret=Your-RabbitMQ-OAuth-Client-Secret

    You can create both secrets in one secrets file if desired:

    kubectl create secret generic rabbit-secrets --namespace keyfactor-command --from-literal=job-queue-password=Your-RabbitMQ-BasicAuth-Password --from-literal=job-queue-client-secret=Your-RabbitMQ-OAuth-Client-Secret

Helm Chart Customization

Keyfactor Command 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 112: Keyfactor Command 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 config maps created in the previous section. Fields and values in the caConnector section will vary depending on your identity provider (see Values File Settings for Containers Under Kubernetes).

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

# The hostname should be a valid hostname resolvable to your Kubernetes machine.
hostName: "COMMAND HOSTNAME"

# The idp section here provides Keyfactor Identity Provider as an example. Fields will vary depending on your OAuth provider.
dbupgradetool:
  appSettings:
    console:
      general:
        cookieExpiration: 5
        sessionExpiration: 60
  idp:
    authenticationScheme: 'AUTH SCHEME'
    displayName: 'IDP_DISPLAYNAME'
    discoveryDocumentEndpoint: 'https://IDP_HOSTNAME/auth/realms/Keyfactor/.well-known/openid-configuration'
    providerType: 'Generic'
    api:
      clientId: 'Command-API-Query'
      secretName: idp-secrets
      clientSecretSecretKey: command-api-client-secret
    audience: 'Command-OIDC-Client'
    nameClaimType: 'preferred_username'
    uniqueClaimType: 'sub'
    fallbackUniqueClaimType: 'cid'
    roleClaimType: 'groups'
    clientId: 'Command-OIDC-Client'
    secretName: idp-secrets
    clientSecretSecretKey: client-secret
    timeout: 5

  # The adminUser is the default administrative user who has access to Keyfactor Command initially
  adminUser:
    identityProvider: 'IDP_DISPLAYNAME'
    claimType: 'OAuthSubject'
    claimValue: 'ADMIN_USER_SUB_CLAIM_VALUE'
    description: 'ADMIN_USER_DESCRIPTION'

  # Select either basic or OAuth authentication for the CA Connector and uncomment the appropriate section. This is used for Microsoft CAs.
  caConnector:
    configureCAConnector: true
    jobQueueUseOAuth: true
    basic:
      username: rabbit-svc
      secretName: rabbit-secrets
      passwordSecretKey: job-queue-password
    #oAuth:
    #  clientId: RabbitMQ
    #  secretName: rabbit-secrets
    #  clientSecretSecretKey: job-queue-client-secret
    #jobQueueTokenURL: "https://IDP_HOSTNAME/realms/Keyfactor/protocol/openid-connect/token"
    jobQueueUrl: "amqps://JOB_QUEUE_HOSTNAME"
    jobQueueValidateOnSave: true

  # Your Keyfactor Command license file.
  license:
    secretName: command-license
    secretKey: license-content

ingress:
  tlsSecretName: ingress-tls

workloadDefaults:
  logLevel: INFO
  image:
    pullSecrets:
    - name: image-creds

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

Install

To install Keyfactor Command 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_command/values-local.yaml
   sudo chmod 400 /opt/kyf_command/values-local.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_command/values-local.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-command --values values-local.yaml oci://repo.keyfactor.com/charts/command --version 1.0.0