Prior to installation, the system must be bootstrapped with certain system credentials and certificates. There are a few alternative ways to perform this task. System CredentialsThe system credentials can be provided to the system in the following ways: - Manually creating a Kubernetes Secret in advance.
- Providing the information as Helm values.
- Letting the system randomly generate the information.
These options are explained in the following sections. Necessary system credentials for Secret or Helm, respectively, are listed in the table. These credentials for database and system level API need to be provided before installation can complete: | Secret Parameter | Helm Parameter | Description |
|---|
| jdbcUser | platform.db.jdbcUser | User to authenticate to system database. | jdbcPassword | platform.db.jdbcPassword | Password to authenticate to system database. | mzownerPassword | oracle.mzownerPassword
postgres.mzownerPassword | Schema owner password to authenticate to system database. | postgresqlPassword | postgres.adminPassword | Postgres database admin password. | oraclePassword | oracle.adminPassword | Oracle database admin password. | tlsKeystorePassword | platform.tls.key.storepassword | System keystore password. Also used in cert-manager requests. | tlsKeyPassword | platform.tls.key.password | System key password. Also used in cert-manager requests. |
Kubernetes SecretCredentials can be written into a Secret object named env-secrets prior to installation. | Info |
|---|
| title | Example - Secret object |
|---|
|
| Code Block |
|---|
$ kubectl create secret generic env-secrets -n <namespace> \
--from-literal=jdbcUser=jdbcuser \
--from-literal=jdbcPassword=jdbcpassword \
--from-literal=mzownerPassword=mzownerpassword \
--from-literal=postgresqlPassword=postgrespassword \
--from-literal=tlsKeystorePassword=keystorepassword \
--from-literal=tlsKeyPassword=keypassword
|
|
Helm ValuesCredentials can also be provided through values to Helm, by providing them in values.yaml or by passing them on the command line. | Info |
|---|
| title | Example - Helm credentials |
|---|
|
| Code Block |
|---|
$ helm install <release_name> ./usage-engine-private-edition --wait --timeout=5m --namespace <namespace> \
--set platform.db.jdbcUser=<user> \
--set platform.db.jdbcPassword="<password>" \
--set postgres.mzownerPassword="<password>" \
--set postgres.adminPassword="<password>" \
--set platform.tls.key.storepassword="<password>" \
--set platform.tls.key.password="<password>"
|
|
| Note |
|---|
| Be aware that storing secret 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. |
RandomIf neither Secret nor Helm values are used to provide credentials, the required values are automatically populated with random data. For users with access rights, the randomized credentials can be retrieved by doing: | Code Block |
|---|
$ kubectl get secret/env-secrets -n <namespace> -o yaml |
The values are stored base64 encoded and need to be decoded to be viewed. | Info |
|---|
|
| Code Block |
|---|
$ kubectl get secrets/env-secrets -n <namespace> --template={{.data.jdbcPassword}} | base64 -d |
|
CertificatesUsage Engine requires a certificate to provide encryption on the public (external) interfaces. This certificate can be provided through a few different methods; cert-manager, Secret, and Disk Based Keystore. The method used is controlled through the following parameters in values.yaml: | Info |
|---|
| title | Example - Configuration of certificate method in values.yaml |
|---|
|
| Code Block |
|---|
| platform:
tls:
enabled: true
cert:
# Public certificate can be provided through one of methods: 'secret', 'certManager' or 'key' (not recommended)
public: certManager |
|
Kubernetes cert-managerThe most automated and secure way to provide certificates to the system is to use the Kubernetes tool cert-manager. Follow the instruction in the link below to install cert-manager: https://cert-manager.io/docs/installation/ 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 be defining an Issuer or ClusterIssuer resource and referring that one from values.yaml.
| Info |
|---|
| title | Example - Configuration in values.yaml to enable cert-manager based keystore |
|---|
|
| Code Block |
|---|
| tls:
cert:
public: certManager
certManager:
public:
issuer:
name: letsencrypt-prod
kind: ClusterIssuer
domain: mz10.example.com
keystore:
password:
key: tlsKeyPassword
name: env-secrets |
|
For a list of supported CA Issuer or ClusterIssuer types, see https://cert-manager.io/docs/configuration/ The following example configures a ClusterIssuer CA towards the free public CA provided Letsencrypt in an AWS deployment. | Info |
|---|
| title | Example - ClusterIssuer CA configuration |
|---|
|
| Code Block |
|---|
| apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
# The ACME server URL
server: https://acme-v02.api.letsencrypt.org/directory
# Email address used for ACME registration
email: admin@example.com
# Name of a secret used to store the ACME account private key
privateKeySecretRef:
name: letsencrypt-prod
solvers:
# example: cross-account zone management for example.com
# this solver uses ambient credentials (i.e. inferred from the environment or EC2 Metadata Service)
# to assume a role in a different account
- selector:
dnsZones:
- "mz10.example.com"
dns01:
route53:
hostedZoneID: XXXXXXXXXXXX
region: eu-west-1 |
|
SecretIf you do not want to automate the certificate provisioning with cert-manager, you can instead manually install a public certificate in a Secret and refer the installation to that Secret. | Info |
|---|
| title | Example - Configuration in values.yaml to enable Secret based keystore |
|---|
|
| Code Block |
|---|
| platform:
tls:
cert:
public: secret
secret:
public:
name: mz-cert
keystore:
alias: certificate |
|
The Secret must include a keystore file (keystore.jks) in JKS format as well as separate files for key (tls.key) and certificate (tls.crt). The script below shows how these can be generated and stored in the Secret. Note that this will generate a self-signed certificate, which is not suitable for use in publicly exposed interfaces. Make sure to set the parameters in the beginning of the script before using. | Info |
|---|
| title | Example - How to generate a self-signed certificate |
|---|
|
| Code Block |
|---|
| #!/bin/bash
KEY_PASSWORD=DefaultKeystorePWD
STORE_PASSWORD=DefaultKeystorePWD
DNAME=CN=exampledomain.com,O=Example
K8S_NAMESPACE=<namespace>
rm -f keystore.p12 keystore.jks tls.crt tls.key
keytool -genkey -keystore keystore.jks -storepass $STORE_PASSWORD -keypass $KEY_PASSWORD -alias certificate -keyalg RSA -keysize 2048 -dname $DNAME
keytool -importkeystore -srckeystore keystore.jks -srcstorepass $STORE_PASSWORD -srckeypass $KEY_PASSWORD -destkeystore keystore.p12 -deststoretype PKCS12 -srcalias certificate -deststorepass $STORE_PASSWORD -destkeypass $KEY_PASSWORD
openssl pkcs12 -in keystore.p12 -nokeys -out tls.crt -password pass:$KEY_PASSWORD
openssl pkcs12 -in keystore.p12 -nodes -nocerts -out tls.key -password pass:$KEY_PASSWORD
kubectl create secret generic mz-cert --namespace $K8S_NAMESPACE --from-file=keystore.jks --from-file=tls.key --from-file=tls.crt |
|
Disk Based KeystoreCertificates and keys can also be stored in keystore files on persistent disk. This option is the least secure and is deprecated. It is kept solely for backward compatibility reasons. | Info |
|---|
| title | Example - Configuration in values.yaml to enable disk based keystore |
|---|
|
| Code Block |
|---|
| platform:
tls:
cert:
public: key
key:
alias: certificate
|
|
| 