SENSE-O on 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 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 to achieve 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 publicly 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 is 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. This is primarily 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 is 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>'

1.2.5. Credential Store Key

Workflows that use encrypted credentials need a master key in the application environment. The locally verified orchestrator chart 2.2.0 reads SENSE_CRED_KEY from the Secret selected by global.credSecret, using the entry named by credStore.masterKey (default: cred-master-key). Verify that your chosen chart version contains this mapping; these instructions do not establish its availability in older or published chart versions.

1. Prepare a protected file containing the current versioned key string, following Configure the Credential Store. Preserve the matching key for an existing database; generating a replacement without retaining old keys can strand encrypted credentials.

2. When initially creating the service-password Secret above, include this additional argument:

   --from-file=cred-master-key=/secure/path/to/credential-store.key

   Use the real protected file path. If the Secret already exists, update it through your existing secret-management process while preserving its other entries. The file contains the application’s <version>:<base64-key> text; --from-file handles Kubernetes Secret encoding. Do not base64-encode the entire string again in the file.

3. Point global.credSecret at that Secret. If its key entry has another name, select it with:

   credStore:
     masterKey: cred-master-key

4. After a key configuration change, ensure the application runs in a new process so it loads the updated Secret value. In Admin Settings → Credentials, confirm Store Active, the expected Key Version, and no key or verification warnings. A running Pod alone does not prove credential-store readiness.

Chart configuration limits

The verified chart 2.2.0 makes this Secret entry optional; its absence allows the Pod to start with the credential store unavailable. It exposes only the current inline key. It does not provide previous-key variables, credential key-file mounts, the reveal-disable switch, or generic environment/volume extension values.

The application’s rotation and file-input support therefore needs additional chart wiring or a separately verified deployment overlay. Do not replace an existing database’s key using this current-key setting alone. The configuration guide distinguishes application support from deployment support.

2. Configuration

With the prerequisite 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.

To initialize a pristine deployment from archive files, see Initializing with an Archive before the first run of the chart.

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.

---