Background

This document provides step-by-step instructions for properly editing the values.yaml file to deploy Virtru's Customer Key Server (CKS) using Helm in a Kubernetes environment. Follow these guidelines to ensure your values.yaml file is correctly formatted, particularly for secrets like the authTokenJson and RSA keys.

Prerequisites

Follow the CKS deployment method: Virtru Private Keystore (for Virtru Solutions) - Standard Linux Server.

Installation Steps

Pulling the helm chart

To get started with your helm chart, create a local directory to store your chart. Then run the following command to add Virtru's helm charts to your local helm repo:

helm repo add virtru-charts https://virtru-corp.github.io/virtru-charts/

To view your helm repos, run:

helm repo list

You should see virtru-charts added from the URL https://virtru-corp.github.io/virtru-charts/.

To download a chart for editing, run the following command:

helm pull virtru-charts/cks --untar

You should see a directory called cks created inside of your working directory.

Create secrets

There are a number of ways that Kubernetes secrets can be managed. If you do not have an existing external secret manager for your Kubernetes clusters, you can create secrets by using the appSecrets section of the values.yaml file.

Please note we recommend that you consider using an external secrets manager. Creating secrets via the values.yaml is a default option to help get your CKS up and running more quickly.

Updating `values.yaml` file

This section will detail potential changes that you will need to make to your values.yaml file.

The values.yaml file is where all of the CKS configuration will occur. This is where the environment variables and secret values will be configured.

These values will be generated by running the CKS setup wizard on a Linux server. The steps are outlined in our public docs at Virtru Private Keystore (for Virtru Solutions): Install - First Instance, Linux Server. Once you complete running the CKS wizard in a Linux server, you’ll want to save the contents of the send_to_virtru.tar.gz tar ball and use the information in there in order to build your values.yaml file contents for your K8s deployment. Once the script has been completed successfully, the file send_to_virtru.tar.gz will be in your /var/virtru/cks directory. This file will contain the required information so that Virtru can communicate with your CKS appliance.

Next, please send the send_to_virtru.tar.gz zip file to the Virtru Deployment Team via the Virtru Secure Share. The information in this file will be used to get your CKS connected to the Virtru production environment once a go-live date has been coordinated between your organization and Virtru.

Depending on your environment, you will need to add annotations to:

Apply your CA-signed certificate
Designate load balancer configurations
Expose your load balancer to the internet

General Configuration

Replica Count & Revision History: Set replicaCount and revisionHistoryLimit according to your availability and rollback strategy needs.
- replicaCount: Set the number of CKS replicas. For production environments, a value greater than one is recommended for high availability.
- revisionHistoryLimit: Adjust this to control the number of old ReplicaSets kept for rollback.
Image Configuration: Specify the CKS image repository, pull policy, and tag. The default repository is:

Service Account

Service Account Creation: Decide whether a Kubernetes service account should be created.
- Only modify if you understand the need for specific Kubernetes service account configurations.

Ingress Configuration

Domain Configuration: Essential for exposing CKS externally. Update the hosts.host to match your CKS FQDN. Replace fqdn.yourdomain.com with your actual domain under ingress.hosts.host.
TLS Configuration: Configure TLS if necessary under ingress.tls by uncommenting and setting the appropriate values.

App Configuration

Virtru Organization ID: Set virtruOrgId with your Virtru organization's ID. Contact your Virtru Deployment Engineer for this information. This is required as of v1.8.11
Logging and Key Management: Configure logging, key management, and authentication settings under appConfig.

Secrets Management

authTokenJson Configuration:
- appSecrets: This section is crucial and requires careful attention to ensure that your secrets are correctly formatted as strings.
  - The authTokenJson must be formatted as a base64 encoded JSON string. You will find the value in cks/var/virtru/cks/token-store cat tokens.jsonon the linux server. Another way to acquire this value is to copy the AUTH_TOKEN_STORAGE_IN_MEMORY_TOKEN_JSON in cks/var/virtru/cks/env vim cks.env
  - Below is an example showing how to format the JSON data correctly in your values.yaml:
```
appSecrets:
  virtruAuth:
    data:
      authTokenJson: |
        dmFsdWU=
```
RSA Keys Configuration:
- RSA keys must be formatted correctly.
  - For the public key (rsa001.pub), replace <rsa001 public key> with your actual public key content.
  - For the private key (rsa001.pem), replace your private key (rsa001 private key). Update your secrets to match the values from your local CKS config as mapped below.
    
    Filename Value from CKS setup script
    
    hmac-auth env/cks.env => AUTH_TOKEN_STORAGE_IN_MEMORY_TOKEN_JSON
    
    rsa001.pub keys/rsa001.pub
    
    rsa001.pem keys/rsa001.pem
    
    You can have multiple RSA keypairs on your CKS as long as they follow the naming convention rsa###.pub and rsa###.pem for all public/private keypairs.
    
    Note: Indentation matters for a multiline string; ensure proper indentation for your CKS key secrets.
  - Example format for RSA keys:
```
appSecrets:
  virtruKeys:
    data:
      rsa001.pub: |
        -----BEGIN PUBLIC KEY-----
        <rsa001 public key>
        -----END PUBLIC KEY-----
      rsa001.pem: |
        -----BEGIN RSA PRIVATE KEY-----
        <rsa001 private key>  
        -----END RSA PRIVATE KEY-----
```

External Secret Management

External Secrets: Consider using an external secret manager for enhanced security. If you prefer to use external secrets, uncomment and configure the externalAppSecrets section.

Installing the Virtru Private Keystore

Use a standard helm install command to deploy your CKS. An example command is listed below:

helm install -n virtru -f ./values.yaml cks ./ --create-namespace

Additional Config to go live

Refer to standard documentation for CKS configuration. You can get your endpoints to set as smart hosts by running the following command:

kubectl -n virtru get services

And there should be public endpoints you can use when relaying mail to your new gateways.

Post-Deployment

After successfully deploying the Virtru Private Keystore, monitor the status of your pods to ensure they are running correctly. Use kubectl commands to check pod statuses and review logs for any errors or warnings.

To list the pods enter the command below:

kubectl get pods -n virtru

helm list -n virtru
kubectl logs <pod-name> -f -n virtru

Filename	Value from CKS setup script
`hmac-auth`	`env/cks.env => AUTH_TOKEN_STORAGE_IN_MEMORY_TOKEN_JSON`
`rsa001.pub`	`keys/rsa001.pub`
`rsa001.pem`	`keys/rsa001.pem`