Page Comparison

System Database

Anchor
system-database-preparations system-database-preparations

The Usage Engine Private Edition helm chart is capable of automatically creating the system database at install time. However, that assumes that you are able to supply database administrator credentials (see Bootstrapping System Credentials).

If, for one reason or another, you are unable to supply that, the system database must be created manually prior to installing the Usage Engine Private Edition helm chart.

A tool called uepe-sys-db-tool.jar is provided to facilitate this.

To use it, simply go to Release Information, download it for the relevant version, and then execute it like this:

java -jar uepe-sys-db-tool.jar

The instructions on screen will guide you through the process of configuring the database, and once done, a set of database scripts will be generated. These database scripts can then be used to create the system database.

TLS

Anchor
tls-preparations tls-preparations

It is recommended to install Usage Engine Private Edition with TLS enabled, and there are two different ways of providing the required certificate:

• Cert-manager

• Secret

Here follows an explanation of the preparations required for each of the two.

cert-manager

The most automated and secure way to provide the certificate is to use https://cert-manager.io/ .

If it is not already installed in your Kubernetes cluster, follow these instructions on how to install the cert-manager https://cert-manager.io/docs/installation/helm/ chart. Make sure to install a version that is listed in the Compatibility Matrix.

helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.14.4 \
  --set serviceAccount.create=false \
  --set serviceAccount.name=cert-manager

Cert-manager must be backed by a certificate authority (CA) to sign the certificates. Once configured with a CA, cert-manager will automatically sign and renew certificates for the system as needed. Configuring cert-manager with a CA is done by creating an Issuer or ClusterIssuer resource (this resource will be referenced later when installing Usage Engine Private Edition).

Refer to https://cert-manager.io/docs/configuration/ for a all the details.

It’s also possible to use an issuer specifiction that will issue a self-signed certificate:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: example-issuer
spec:
  selfSigned: {}

Note that this is only recommended for testing purposes and not in production.

Regardless of the chosen issuer specification, to create the issuer, simply put the specification in a yaml file (here we call it example-issuer.yaml), and then execute a command like this:

kubectl apply -f example-issuer.yaml

Based on the example above the created ClusterIssuer can be inspected like this:

kubectl get clusterissuers example-issuer -o yaml

Bootstrapping System Credentials

Anchor
bootstrapping-system-credentials bootstrapping-system-credentials

Usage Engine Private Edition uses a number of system credentials in order to function as expected.

These system credentials are kept in a Kubernetes secret called env-secrets located in the same namespace as where Usage Engine Private Edition is being installed.

This secret can be populated in three different ways:

• Manually creating and populating it prior to installing Usage Engine Private Edition.

• Providing the credential(s) as helm values at install time. In which case the secret will be automatically created (if it does not already exist) and populated with the corresponding helm value(s). Be aware that storing credentials in a values.yaml file in version control is not secure. If you still need to do this you should consider using tools like https://github.com/mozilla/sops .

• Letting it be automatically populated at install time. In which case the secret will be automatically created and populated. Passwords will consist of eight randomly generated characters.

Note that the three options are not mutually exclusive. It is possible to populate some credentials in advance, some through helm values, and let some be automatically generated.

Here follows an explanation of the system credentials used by Usage Engine Private Edition:

This is an example of how to create and populate the secret with some credentials:

kubectl create secret generic env-secrets -n <namespace> \
--from-literal=jdbcPassword=<your chosen jdbc password> \
--from-literal=mzownerPassword=<your chosen mzowner password>

To inspect the content of the secret, simply execute the following command:

kubectl get secret/env-secrets -n <namespace> -o yaml

To retrieve a given credential in cleartext, simply execute a command like this:

kubectl get secrets/env-secrets -n <namespace> --template={{.data.jdbcPassword}} | base64 -d