Customize installation settings

5 minute read

You must use Helm parameters to customize Streams during its installation. Any customization must be done before you install Helm.

Options to manage Helm parameters

You can manage your custom Helm parameters in different ways, and the best way depends on your use case. The following are some options that you can use to customize your installation:

• By way of a custom values file (recommended).
• By setting a key value when running the installation or upgrade commands.
• By editing any value in the values.yaml files.

Our recommendation is that you create a custom values file, for example, my-values.yaml, where you can overwrite parameters and pass on the file to the installation or upgrade commands. For example:

helm install -f values.yaml -f values-ha.yaml -f my-values.yaml <name> <chart>

• The last values file in this command overwrites any conflicting parameter.

Another option is to use --set key=value when running the installation or upgrade commands. For example:

helm install <name> <chart> --set key=value

Finally, you can edit the values.yaml or values-ha.yaml files and change any values you need.

Use a custom Docker registry

In some cases, you may want to use your own docker registry to retrieve Streams docker images. For example, when you K8s cluster has limited access to internet.

The following code is an example of how to set up a custom registry:

export NAMESPACE="my-namespace"
export REGISTRY_SECRET_NAME="my-registry-secret-name"
export REGISTRY_SERVER="my-registry-server"
export REGISTRY_USERNAME="my-registry-username"
export REGISTRY_PASSWORD="my-registry-password"

kubectl create secret docker-registry "${REGISTRY_SECRET_NAME}" --docker-server="${REGISTRY_SERVER}"  --docker-username="${REGISTRY_USERNAME}" --docker-password="${REGISTRY_PASSWORD}" -n "${NAMESPACE}"

Then you must set the helm parameters imagePullSecrets[0].name and images.repository accordingly to your custom registry. For more information, see Streams parameters.

Custom embedded Mariadb security settings

By default, both TLS and TDE encrypt modes are enabled for the embedded MariaDB server. This section shows how you can disable one or the other, or both.

Enable TLS only

Follow these steps to enable TSL only:

1. Create a secret containing the TLS certificates, for example:

   export NAMESPACE="my-namespace"
   kubectl create secret generic streams-database-secret --from-file=CA_PEM=ca.pem --from-file=SERVER_CERT_PEM=server-cert.pem --from-file=SERVER_KEY_PEM=server-key.pem -n "${NAMESPACE}"
   

2. Set the Helm parameter embeddedMariadb.encryption.enabled to false.

Enable TDE only

Follow these steps to enable TDE only:

1. Create a secret containing the TDE keyfile, for example:

   export NAMESPACE="my-namespace"
   kubectl create secret generic streams-database-secret --from-file=KEYFILE=keyfile -n "${NAMESPACE}"
   

2. Set the Helm parameter embeddedMariadb.tls.enabled to false.

Disable all security features

To disable MariaDB encryption and TLS, you must set the following Helm parameters:

• embeddedMariadb.tls.enabled and embeddedMariadb.encryption.enabled to false
• embeddedMariadb.master.extraEnvVarsSecret and embeddedMariadb.slave.extraEnvVarsSecret to null

Custom embedded kafka security settings

Streams requires you to enable both SASL/SCRAM authentication (using the SHA-512 hash functions) and TLS, or neither of the two.

To disable all security features provided by kafka, you must set the following Helm parameters:

• embeddedKafka.auth.clientProtocol to plaintext
• embeddedKafka.auth.interBrokerProtocol to plaintext
• embeddedKafka.auth.sasl.mechanisms to plain
• embeddedKafka.auth.sasl.interBrokerMechanism to plain
• embeddedKafka.auth.sasl.jaas.clientPasswordSecret to null
• embeddedKafka.extraEnvVars to null
• embeddedKafka.extraVolumes to null
• embeddedKafka.extraVolumeMounts to null

Custom externalized Mariadb security settings

Depending on your MariaDB specification, you can enable either One-Way TLS or Two-Way TLS, or you can disabled all security features.

After ensuring the compatibility with your MariaDB server, choose one of the following options to enable or disable the security features.

Enable One-Way TLS

Follow these steps to enable One-Way TLS:

1. Provide the CA certificate by creating a secret:

   export NAMESPACE="my-namespace"
   kubectl create secret generic streams-database-secret --from-file=CA_PEM=ca.pem -n "${NAMESPACE}"
   

2. Set the Helm parameter externalizedMariadb.tls.twoWay to false.

Enable Two-way TLS

To enable Two-Way TLS, you must provide the CA certificate, the server certificate, and the server key by creating a secret:

export NAMESPACE="my-namespace"
kubectl create secret generic streams-database-secret --from-file=CA_PEM=ca.pem --from-file=SERVER_CERT_PEM=server-cert.pem --from-file=SERVER_KEY_PEM=server-key.pem -n "${NAMESPACE}"

Disable TLS

To disable TLS, you must set the Helm parameter externalizedMariadb.tls.enabled to false.

Disable externalized Kafka security settings

Currently, Streams works only with SASL/SCRAM authentication (using the SHA-512 hash functions) and TLS enabled, or neither of the two.

To disable all security features provided by kafka, you must set the following Helm parameters externalizedKafka.auth.clientProtocol to plaintext.

Custom ingress controller settings

This section describes the customizations available for the embedded ingress controller.

Custom ingress controller security settings

If you don’t provide a certificate, SSL will be enabled with a NGINX embedded fake SSL certificate.

To provide a SSL/TLS certificate for the domain name you are using (either CN or SAN fields should match the ingress.host Helm parameter), run the following command:

export NAMESPACE="my-namespace"
export INGRESS_TLS_KEY_PATH="my-key-path"
export INGRESS_TLS_CHAIN_PATH="my-chain-path"

kubectl create secret tls streams-ingress-tls-secret --key=${INGRESS_TLS_KEY_PATH} --cert="${INGRESS_TLS_CHAIN_PATH}" -n "${NAMESPACE}"

To disable SSL/TLS, you must set the Helm parameter ingress.tlsenabled to false.

Custom ingress controller CORS

To enable CORS, you must set the Helm parameter ingress.annotations."nginx.ingress.kubernetes.io/enable-cors" to "true". For example, add the following line to the Helm Chart installation command:

--set-string "ingress.annotations.nginx\.ingress\.kubernetes\.io/enable-cors"="true"

• Ensure to enter --set-string
• Ensure to use double quotation marks around the annotations parameter. For more information, see Ingress Helm parameters.

Then, you can configure CORS by adding annotations to the ingress parameter. For example, you can specify a value to the cors allow origin configuration with the ingress.annotations."nginx.ingress.kubernetes.io/cors-allow-origin" parameter.

For example, to allow cross origin request from the domain name https://origin-site.com, add the following line to the Helm Chart installation command:

--set "ingress.annotations.nginx\.ingress\.kubernetes\.io/cors-allow-origin"="https://origin-site.com"

For more information, see Nginx documentation.

Activate Subscriber SSE security

To secure SSE subscriptions, you must perform the following steps:

1. Provide an existing RSA public and private key pair or create a new one as following:

   openssl genrsa -out key.pem 2048
   openssl rsa -in key.pem -outform PEM -pubout -out cert.pem
   

2. Create a kubernetes secret to store the RSA key pair:

   kubectl create secret generic streams-subscriber-sse-jwt-secret --from-file=key=key.pem --from-file=cert=cert.pem -n "${NAMESPACE}"
   

3. Activate SSE subscriber Access Token generation and validation. To secure SSE subscriptions (disabled by default) add the provided values-secured-subscriber-sse.yaml values file to your Helm install command line. For example:

       helm install "${HELM_RELEASE_NAME}" . -f values.yaml -f values-secured-subscriber-sse.yaml -n "${NAMESPACE}"