Kubernetes

This document outlines the intended or primary deployment procedure for the SENSE Orchestrator on Kubernetes, via the use of Helm.

1. Prerequisites

Before deploying the SENSE Orchestrator onto Kubernetes, there are a few steps that are required to setup Helm and establish important infrastructure components and secrets ahead of the actual Helm chart.

Note that all of the following kubectl and helm commands assume that this installation is occurring within a namespace called sense. You may replace this with whichever existing namespace you wish to use, though we recommend creating a separate namespace for resource isolation and management purposes.

1.1 Helm Configuration

Naturally, you will need an installation of Helm present on your machine in order to accomplish this task. This installation requires Helm v3 to proceed, and instructions on how to install Helm for your platform can be found at https://helm.sh/docs/intro/install/.

Once you have Helm installed, you will need to add the SENSE Helm chart repository to your local client. To do so, run the following commands:

helm repo add sense-helm https://stackv.github.io/sense-helm/
helm repo update

1.2 External Secrets

This installation process requires the pre-creation of sensitive secrets before deploying the chart. Future versions of the SENSE Orchestrator chart will provide optional values-based configurations for automatic secret management.

Some of the following steps may not be necessary for your particular installation, such as not requiring a registry credential while using publically-available images. Additionally, feel free to adjust the names of the resources created, noting them for later when it comes time to establish the helm values file.

1.2.1. Registry Credentials

Some installations may leverage private or bespoke images of the SENSE Orchestrator. If so, you will need to create a registry credential secret.

kubectl create secret docker-registry sense-regcred -n sense \
  --docker-server=https://index.docker.io/v1/ \
  --docker-username='<USERNAME>' \
  --docker-password='<PASSWORD>' \
  --docker-email='<EMAIL>'

1.2.2. Client Keystore

The SENSE Orchestrator leverages client certificate authentication for various RMs and driver interactions. To facilitate this, the keystore must be provided as a secret.

In cases where you know the Orchestrator does not require any client certificates, or you do not yet have the client keystore provided to you, you may skip this step and configure the Orchestrator to create an empty placeholder keystore instead.

# Ensure that you have the client.keystore file locally.
kubectl create secret generic sense-client-keystore -n sense \
  --from-file=client.keystore=./client.keystore

1.2.3. OAuth Configuration

In order to secure the application, the Orchestrator relies on an external Keycloak authentication server, and requires configuration to enable the system-level service account used for administrative operations. The Keycloak host, client ID and secret should be provided to you, or you may have established them in a separate guide.

kubectl create secret generic sense-kc-auth -n sense \
    --from-literal=host='<HOST>' \
    --from-literal=client='<CLIENT_ID>' \
    --from-literal=client-secret='<CLIENT_SECRET>'

1.2.4. Service Passwords

Finally, there are a set of passwords that the Orchestrator will use to both initialize and connect to various services, that are currently not included in the values.yaml file to keep configuration isolation high as we proceed through development of the charts. Any password that is not needed can be left as-is. The current list of password keys are used for the following:

• The TLS password is used to access the client keystore specified above, or to secure a new one if the secret is not present.
• The MySQL password is used to initialize and secure the database's root user.
• The Mail password is optionally used to access the configured mail-from account, detailed later.

kubectl create secret generic sense-passwords -n sense \
    --from-literal=tls-password='<TLS_PASSWORD>' \
    --from-literal=mysql-password='<DB_PASSWORD>' \
    --from-literal=mail-password='<MAIL_PASSWORD>'

2. Configuration

With the prerequisiste secrets settled, we can now move onto configuration of the Helm chart itself. As with any Helm chart, the configuration of our deployment will be contained within a values.yaml file. It is common to version this file to the specific deployment or application you are configuring, such as sense-o-aws.values.yaml.

To start with, you can view the chart's default values via the helm show values sense-helm/sense-orchestrator command. If using an older version of the chart, make sure to append the version tag at the end to receive the correct values.

Piping this to a new file will give us a basis for us to start our configuration:

helm show values sense-helm/sense-orchestrator > sense-o.values.yaml

The full details of what each configuration value means can be found within the parameters section of the chart's README, accessed similarly via helm show readme sense-helm/sense-orchestrator, but below is an example of what is commonly configured and what can be left to default, including the secret names we've established above and some documenting comments.

global:
  namespace: sense # Not needed, but can be helpful to be explicit.
  domain: sense-o.aws-example-domain.com # The reachable domain the Orchestrator will be available on.
  credSecret: sense-passwords # Set this to the secret created earlier with our various service passwords.
image:
  repository: virnao/stackv-orchestrator # Can be used to pull from a custom private repository.
  tag: aws-elk # Can be used to pull from a custom image tag.
  pullSecrets:
    - name: sense-regcred # Set this to the secret created earlier to access the private repository.
auth:
  clientSecret: sense-kc-auth # Set this to the secret created earlier for the Keycloak authentication details.
issuer:
  enabled: true # In this case, we enable the Issuer resource but leave its settings to default.
java:
  memory: 4G # This overrides the JVM memory limit, generally you should set it to 1 or 2 gigs below the resource limit.
resources:
  requests:
    cpu: 600m
    memory: 4Gi
  limits:
    cpu: 2000m
    memory: 6Gi
tls:
  keystoreSecret: sense-client-keystore # Set this to the secret created earlier for the client certificate keystore.
mysql:
  pvcName: app-mysql-pvc # In this case we already have an existing PVC, and so want to avoid creating a new one.

3. Deployment

With our values file configured, deployment is now a matter of using Helm as with any other chart. For example, to deploy the Orchestrator with a release name of sense-o, we can simply run:

helm install sense-o sense-helm/sense-orchestrator -f orchestrator.values.yaml`

For more information on using Helm to manage deployments, refer to their documentation, such as their helpful Cheat Sheet found at https://helm.sh/docs/intro/CheatSheet.

---