Install ELMA365 stack

ELMA365 On-Premises can be installed in an existing Kubernetes cluster. ELMA365 is delivered in the form of Helm charts:

• elma365-stack: The full ELMA365 stack, including Helm packages elma365,elma365-dbs and elma365-addons;
• elma365: The ELMA365 application package;
• elma365-dbs: A set of databases and storage required for ELMA365. You can also use your own databases such as PostgreSQL, MongoDB, Redis, RabbitMQ, and S3 storage by providing connection strings in the elma365 values package. You can disable the installation of the corresponding components in the values.yaml file bu setting the false value, for example, for PostgreSQL global.postgresql.enabled. If all five components of the chart are set to false, the installation of this chart is not required.
• elma365-addons: Add-ons for ELMA365 Enterprise, including the Linkerd Service Mesh, Prometheus + Grafana monitoring system, as well as Descheduler, NodeLocal DNSCache, and the Security Audit module.

начало внимание

elma365-extension charts are no longer supported. Transition to elma365-dbs charts with new versions of databases is done using a dump and its restoration.

конец внимание 

Requirements for Kubernetes сonfiguration:

The installed version of the Kubernetes cluster must support Kubernetes API v.2 (Kubernetes version 1.19 - 1.26) and contain the following components: ingress-nginx controller, coredns, rbac, storageclass.

Installation is performed using Helm v.3.

Proxying from pods to the external network must be allowed.

Installation of ELMA365 using the elma365-stack chart

1. Add the ELMA365 Helm repository and extract the list of application package variables with all the necessary components into a file:

helm repo add elma365 https://charts.elma365.tech
helm repo update
helm show values elma365/elma365-stack > values-elma365-stack.yaml

2. Fill in the variables in the file values-elma365-stack.yaml, replacing at least the following parameters:

• elma365.global.host: the domain (FQDN) or IP address through which the system will be accessible.
• elma365.bootstrapCompany.email: the email of the administrator.
• elma365.bootstrapCompany.password: the password of the administrator.
• elma365.db.psqlUrl: the connection string to the PostgreSQL database.
• elma365.db.mongoUrl: the connection string to the MongoDB database for the application.
• elma365.db.vahterMongoUrl: the connection string to the MongoDB database for the authorization server.
• elma365.db.redisUrl: the connection string to Redis.
• elma365.db.amqpUrl: the connection string to RabbitMQ.
• elma365.db.s3.method: the method for S3 requests.
• elma365.db.s3.accesskeyid: the S3 username.
• elma365.db.s3.secretaccesskey: the password for the S3 user.
• elma365.db.s3.bucket: the S3 bucket.
• elma365.db.s3.backend.address: the S3 address.
• elma365.db.s3.backend.region: the S3 region.
• elma365.db.s3.ssl.enabled: enable SSL for S3.

3. If it is necessary to create a separate namespace, specify it in all installation commands.
4. Save the values-elma365-stack.yaml file for future updates.

Install databases

1. When using your own databases, you can skip the installation of built-in databases by changing the value in the global.elma365-dbs.enabled parameter to false in the file values-elma365-stack.yaml. In the case of using one or more external databases, such as PostgreSQL, you can skip its installation by changing the parameter global.postgresql.enabled to false.
2. Execute the installation of databases. At this step, it is necessary to disable the installation of the ELMA365 application with the following command (pay attention to the parameter --set global.elma365.enabled=false):

helm upgrade --install elma365-stack elma365/elma365-stack \
-f values-elma365-stack.yaml \
 --set global.elma365.enabled=false \
 --timeout=30m --wait \
 [-n namespace]

Install the ELMA365 application

1. If it is necessary to restore a dump before installing ELMA365, run the elma365db.sh script:

helm pull elma365/elma365-stack --untar
./elma365-stack/charts/elma365/elma365db.sh --restore --path /backup/path/ \
[--kubeconfig /path/to/config --context prod] [-n namespace]

2. Execute the installation of the ELMA365 application with the following command:

helm upgrade --install elma365-stack elma365/elma365-stack \
-f values-elma365-stack.yaml \
--timeout=30m --wait [-n namespace]

3. To create a dump, you can use the elma365db.sh script from the elma365 chart:

helm pull elma365/elma365-stack --untar
./elma365-stack/charts/elma365/elma365db.sh --dump --path /backup/path/ \
[--kubeconfig /path/to/config --context prod] [-n namespace]

Install monitoring tools (optional)

1. In the file values-elma365-stack.yaml  disable unused components by changing the value in the parameters global.linkerd2.enabled, global.descheduler.enabled, global.node-local-dns.enabled and global.audit.enabled to false, as their installation requires preliminary settings..
2. In the parameters elma365-addons.kube-prometheus-stack and elma365-addons.grafana specify the required namespace  for the monitoring service (for example, namespaceOverride: monitoring), the address at which the monitoring service will be available, and enable dashboards by changing the value in the parameter elma365.global.dashboard.enabled to true.
3. Create a namespace for the monitoring service with the following command:

kubectl create namespace monitoring

4. Perform the installation with the following command (pay attention to the parameter --set global.elma365-addons.enabled=true):

helm upgrade --install elma365-stack elma365/elma365-stack \
 -f values-elma365-stack.yaml \
 --set global.elma365-addons.enabled=true \
 --timeout=30m --wait \
  [-n namespace]

Install Linkerd and service auto-scaling (optional)

Linkerd is a dedicated infrastructure layer that helps manage communication between services, automatically encrypt connections, handle retries, and timeouts. It also provides telemetry (success rate, delays), and more..

1. Generate certificates using openssl by executing the commands below. Linkerd requires a trust anchor certificate and emitter certificates with the corresponding key to support mutual TLS connections between services. For all certificates, the ECDSA P-256 algorithm is required.

# Create CA private key
openssl ecparam -name prime256v1 -genkey -noout -out ca-private.pem
 
# Create CA public key
openssl ec -in ca-private.pem -pubout -out ca-public.pem
 
# Create a self-signed CA certificate
openssl req -x509 -new -key ca-private.pem -days 365 \
 -out ca.crt -subj "/CN=root.linkerd.cluster.local"
# Create emitter private key
openssl ecparam -name prime256v1 -genkey -noout -out issuer-private.pem
 
# Create emitter public key
openssl ec -in issuer-private.pem -pubout -out issuer-public.pem
 
# Create a certificate signing request
openssl req -new -key issuer-private.pem -out issuer.csr \
 -subj "/CN=identity.linkerd.cluster.local" \
 -addext basicConstraints=critical,CA:TRUE
 
# Create an emitter certificate by signing the CSR
openssl x509 \
    -extfile /etc/ssl/openssl.cnf \
    -extensions v3_ca \
    -req \
    -in issuer.csr \
    -days 180 \
    -CA ca.crt \
    -CAkey ca-private.pem \
    -CAcreateserial \
    -extensions v3_ca \
    -out issuer.crt
# Remove the certificate signing request
rm issuer.csr

2. In the file values-elma365-stack.yaml disable unused components by changing the value in the parameters global.kube-prometheus-stack.enabled, global.grafana.enabled, global.descheduler.enabled, global.node-local-dns.enabled and global.audit.enabled to false, as their installation requires preliminary settings.
3. In the parameters elma365-addons.linkerd2 specify the required namespace for the Linkerd service (for example, namespace: linkerd), the contents of the certificates, key, and the certificate expiration period crtExpiry. Note that the value must correspond to the expiration date of the emitter certificate.

identityTrustAnchorsPEM: |
    -----BEGIN CERTIFICATE-----
    contents of the certificate ca.crt
    -----END CERTIFICATE-----
  identity:
    issuer:
      crtExpiry: 2023-03-30T05:28:39Z
      tls:
        crtPEM: |
          -----BEGIN CERTIFICATE-----
          contents of the certificate issuer.crt
          -----END CERTIFICATE-----
        keyPEM: |
          -----BEGIN EC PRIVATE KEY-----
          contents of the certificate issuer-private.pem
          -----END EC PRIVATE KEY-----

4. Enable service auto-scaling by changing the value in the parameter elma365.global.autoscaling.enabled to true.
5. Execute the installation with the following command (pay attention to the parameter --set global.elma365-addons.enabled=true):

helm upgrade --install elma365-stack elma365/elma365-stack \
 -f values-elma365-stack.yaml --set global.elma365-addons.enabled=true \
 --timeout=30m --wait [-n namespace]

6. Add an annotation to the namespace with the ELMA365 application for automatic injection of Linkerd-proxy containers into ELMA365 services:

kubectl annotate namespace default linkerd.io/inject=enabled

7. Restart all services with the following command:

kubectl rollout restart deploy [-n namespace] && kubectl rollout restart ds [-n namespace]

Install NodeLocal DNS Cache (optional)

The installation of NodeLocal DNS Cache allows reducing the load on DNS queries in the Kubernetes cluster and improving the stability of DNS name resolution. This helps avoid DNAT rules, connection tracking, and connection limitation.

1. Get the IP address of the kube-dns service:

kubectl get svc kube-dns -n kube-system -o jsonpath={.spec.clusterIP}

2. In the file values-elma365-stack.yaml disable unused components by changing the value in the parameters global.kube-prometheus-stack.enabled, global.grafana.enabled, global.descheduler.enabled, global.linkerd2.enabled and global.audit.enabled to false, as their installation requires preliminary settings.
3. ВIn the parameters elma365-addons.node-local-dns specify the following:

• pillar_dns_domain: cluster domain;
• pillar_dns_server: kube-dns service IP address;
• pillar_local_dns: local IP address for NodeLocal DNS Cache.

4. Execute the installation with the following command (pay attention to the parameter --set global.elma365-addons.enabled=true):

helm upgrade --install elma365-stack elma365/elma365-stack \
 -f values-elma365-stack.yaml --set global.elma365-addons.enabled=true \
 --timeout=30m --wait [-n namespace]

Install Kyverno (optional)

Kyverno allows managing specific environment configurations independently of resource configurations, applying advanced configuration methods for its clusters, such as blocking or modifying API requests.

Policy for adding custom CA certificates to all containers

In some cases, it is necessary to trust custom CA certificates. Kyverno allows automatically mounting them into containers. The policy adds a volume containing the certificate to all containers labeled tier=elma365.

1. Createa ConfigMap сwith the root CA certificate.

kubectl create configmap elma365-onpremise-ca --from-file=/etc/ssl/certs/rootCA.pem  [-n namespace]

2. In the file values-elma365-stack.yaml enable Kyverno by changing the value in the parameter global.kyverno.enabled to true. Then disable unused components by changing the value for the add-on in the parameter global to false, as their installation requires preliminary settings.
3. In the parameters elma365-addons.kyverno specify the required namespace for the Kyverno service, for example, namespace: kyverno. Then enable the policy for adding certificates by changing the value in the parameter elma365-addons.kyverno.injectСerts.enabled to true, specifying the ConfigMap name with the root CA certificate. In the parameter  injectNamespace specify the list namespace of where the policy for adding certificates will be applied , . 
4. Create the namespace for the Kyverno service with the following command:

kubectl create namespace kyverno

5. Execute the installation with the following command (pay attention to the parameter --set global.elma365-addons.enabled=true:

helm upgrade --install elma365-stack elma365/elma365-stack \
-f values-elma365-stack.yaml --set global.elma365-addons.enabled=true \
--timeout=30m --wait [-n namespace]

6. Restart all services with the following command:

kubectl rollout restart deploy [-n namespace] && kubectl rollout restart ds [-n namespace]

Update ELMA365 version

1. Update the chart list in the repository:

helm repo update

2. Use the values-elma365-stack.yaml file saved at the installation step and then execute the command:

helm upgrade --install elma365-stack elma365/elma365-stack -f values-elma365-stack.yaml --timeout=30m --wait [-n namespace]

In case of changes to the connection strings when updating the application, restart all services with the command:

kubectl default rollout restart deploy [-n namespace] && kubectl default rollout restart ds [-n namespace]

Uninstall elma365 chart

To remove the ELMA365 package, view the list of installed releases, and then execute the deletion command:

helm list [-n namespace]
helm uninstall elma365-stack [-n namespace] 

Parameters of the elma365-stack chart

Was this helpful?

Thanks for your feedback!

Please specify why:

Recommendations did not help meArticle is hard to understandDidn`t answer my questionContent does not match the topicOther

How we can improve it?

YesNo

Please specify whyRecommendations did not help meArticle is hard to understandDidn`t answer my questionContent does not match the topicOther

Found a typo? Highlight the text, press ctrl + enter and notify us