search string side menu

BRIX On-Premises > Other / Install BRIX stack

Install BRIX stack

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

  • elma365-stack: The full BRIX stack, including Helm packages elma365,elma365-dbs and elma365-addons.
  • elma365: The BRIX application package.
  • elma365-dbs: A set of databases and storage required for BRIX. You can also use your own databases such as PostgreSQL, MongoDB, Redis, RabbitMQ, and S3 storage by providing connection strings for values from the elma365 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. Read about creating databases in the Prepare external databases section.
  • elma365-addons: Add-ons for BRIX 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 BRIX using the elma365-stack chart

  1. Add the BRIX 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

  1. 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.
  1. If it is necessary to create a separate namespace, specify it in all installation commands.
  2. 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 BRIX 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 BRIX application

  1. If it is necessary to restore a dump before installing BRIX, you can use the elma365-backupper utility or run the elma365db.sh script from the BRIX chart.

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

  1. Execute the installation of the BRIX application with the following command:

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

  1. To create a dump, you can use the elma365db.sh script from the BRIX 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

  1. 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

  1. 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.
  2. 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-----

  1. Enable service auto-scaling by changing the value in the parameter elma365.global.autoscaling.enabled to true.
  2. 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]

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

kubectl annotate namespace default linkerd.io/inject=enabled

  1. 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}

  1. 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.
  2. В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.
  1. 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]

  1. 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.
  2. 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. 
  3. Create the namespace for the Kyverno service with the following command:

kubectl create namespace kyverno

  1. 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]

  1. Restart all services with the following command:

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

Update BRIX version

  1. Update the chart list in the repository:

helm repo update

  1. 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 BRIX chart

To remove the BRIX 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

 

Name

Description

Default value

Global parameters

global.elma365.enabled

Enable installation of BRIX application

true

global.elma365-dbs.enabled

Enable installation of databases

true

global.postgresql.enabled

Enable Postgres in database installation

true

global.mongodb.enabled

Enable MongoDB in database installation

true

global.redis.enabled

Enable Redis in database installation

true

global.rabbitmq.enabled

Enable Rabbitmq in database installation

true

global.minio.enabled

Enable MinIO for S3 storage in database installation

true

global.elasticsearch.enabled

Enable Elasticsearch in database installation (enabled for BRIX Bot)

false

global.elma365-addons.enabled

Enable installation of add-ons for BRIX

false

global.kube-prometheus-stack.enabled

Enable Prometheus in add-ons installation (create namespace monitoring before installation)

 

true

global.grafana.enabled

Enable Grafana in add-ons installation

true

global.linkerd2.enabled

Enable Linkerd in add-ons installation

true

global.descheduler.enabled

Enable Descheduler in add-ons installation (requires at least 3 nodes in the cluster)

false

global.node-local-dns.enabled

Enable NodeLocal DNS Cache in add-ons installation

true

global.audit.enabled

Enable Security Audit Service in add-ons installation

true

BRIX global parameters

elma365.global.host

Domain (FQDN) or IP address for system accessibility

example.ru

elma365.global.ingress.hostEnabled

Enabling host in Ingress (the value is taken from global.host)

false

elma365.global.ingress.onpremiseTls.enabled

Enabling HTTPS

false

elma365.global.ingress.onpremiseTls.secret

Name of the secret with certificates for HTTPS operation

"elma365-onpremise-tls"

elma365.global.ingress.onpremiseTls.enabledCA

Enabling the root CA certificate for HTTPS operation with a self-signed certificate

false

elma365.global.ingress.onpremiseTls.configCA

Name of the ConfigMap with the root CA certificate for HTTPS operation with a self-signed certificate

"elma365-onpremise-ca"

elma365.global.ingress.annotations

Annotations for Ingress

{"kubernetes.io/ingress.class": "nginx"}

elma365.global.autoscaling.enabled

Enabling service autoscaling

true

elma365.global.autoscaling.minReplicas

Minimum number of replicas

1

elma365.global.autoscaling.maxReplicas

Maximum number of replicas

9

elma365.global.dashboard.enabled

Enabling dashboards for Grafana

false

elma365.global.image.repository

Address for the registry

hub.elma365.tech

elma365.global.image.dockerRegistry

Address for the registry

" "

elma365.global.image.pullSecret

Secret with access rights to the private registry, must be created manually and encrypted in Base64

[yandexsecret]

Additional parameters

elma365.global.postgres.maxIdleConns

Maximum number of connections in the pool of idle connections

50

elma365.global.postgres.maxOpenConns

Maximum number of open connections from the pool

150

elma365.global.postgres.maxConnLife

Maximum connection lifetime from the pool

1m

elma365.global.postgres.poolMaxIdleConns

Maximum number of connections in the pool of idle connections

50

elma365.global.postgres.poolMaxOpenConns

Maximum number of open connections from the pool

150

elma365.global.postgres.poolConnMaxLifetime

Maximum connection lifetime from the pool

5m

elma365.global.maxGrpcMessageSize

Maximum response size

8388608

elma365.global.maxGrpcBackoffDelay

Maximum delay between attempts to establish a GRPC connection

2s

elma365.global.activeDeadlineSeconds

Number of seconds allocated for the entire Job execution

3000

elma365.global.curlCreateCompanyMaxTime

Number of seconds allocated for Job company creation

1800

elma365.global.curlMigrationsMaxTime

Number of seconds allocated for Job migration

3000

General parameters

elma365.debug

Enable platform debugging mode

false

elma365.bootstrapCompany.email

Administrator's email

admin@mail.com

elma365.bootstrapCompany.password

Administrator's password

test

elma365.bootstrapCompany.locale

System language installed, possible options: en-US, sk-SK, ru-RU

ru-RU

elma365.language.default

System language installed, possible options: en-US, sk-SK, ru-RU

ru-RU

Connection strings for connecting to databases

elma365.db.psqlUrl

PostgreSQL DB connection string

"db.psqlUrl: 'postgres:// postgres:pgpassword@ postgres.default.svc.cluster. local:5432/elma365?sslmode=disable"

elma365.db.psqlSecret

Secret name with the PostgreSQL database connection string encrypted in Base64 (key PSQL_URL)

" "

elma365.db.roPsqlUrl

PostgreSQL database connection string for read-only access

" "

elma365.db.roPsqlSecret

Secret name with the PostgreSQL database connection string for read-only access encrypted in Base64 (key RO_POSTGRES_URL)

" "

elma365.db.mongoUrl

MongoDB database connection string for the application

"mongodb://elma365:mongopassword@ mongo.default.svc.cluster.local: 27017/elma365?ssl=false&replicaSet= rs0&readPreference= secondaryPreferred"

elma365.db.mongoSecret

Secret name with the MongoDB database connection string for the application encrypted in Base64 (key MONGO_URL)

" "

elma365.db.vahterMongoUrl

MongoDB database connection string for the authorization server

"mongodb://elma365:mongopassword@ mongo.default.svc.cluster.local: 27017/elma365?ssl=false&replicaSet= rs0&readPreference= secondaryPreferred"

elma365.db.vahterMongoSecret

Secret name with the MongoDB database connection string for the authorization server

" "

elma365.db.redisUrl

Redis connection string

"redis://redis.default.svc.cluster.local:6379/0"

elma365.db.redisSecret

Secret name with the Redis connection string encrypted in Base64 (key REDIS_URL)

" "

elma365.db.amqpUrl

RabbitMQ connection string

"amqp://elma365:rmqpassword@ rabbitmq.default.svc. cluster.local:5672/elma365"

elma365.db.amqpSecret

Secret name with the RabbitMQ connection string encrypted in Base64 (key AMQP_URL)

" "

elma365.db.s3.method

Request method

PUT

elma365.db.s3.accesskeyid

Username

PZSF73JG72Ksd955JKU1HIA

elma365.db.s3.secretaccesskey

Password for the user

aFDkj28Jbs2JKbnvJH678MNwiz88zKjsuNBHHs

elma365.db.s3.bucket

List of buckets

 

s3elma365

elma365.db.s3.backend.address

S3 address

example.ru

elma365.db.s3.backend.region

Region

us-east-1

elma365.db.s3.ssl.enabled

Enable SSL

"false"

elma365.db.s3Secret

Secret name with the connection to the S3 file storage encrypted in Base64

 # (keys S3_BACKEND_ADDRESS, S3_REGION, S3_KEY, S3_SECRET, S3_BUCKET, S3_SSL_ENABLED, S3_UPLOAD_METHOD)

" "

Settings for connecting to SMTP mailing server

elma365.mailer.smtp.host

SMTP server addres

" "

elma365.mailer.smtp.port

SMTP server port

" "

elma365.mailer.smtp.from

 

Sender’s email address

" "

elma365.mailer.smtp.user

User for authentication on the SMTP server

" "

elma365.mailer.smtp.password

Password for authentication on the SMTP server

" "

elma365.mailer.smtp.needTLS

Whether encryption is used

false

Global parameters of the Security Audit service

elma365-addons.audit.global.psql_url

PostgreSQL connection string

"postgresql://postgres:pgpassword@ postgres.default.svc.cluster. local:5432/audit?sslmode=disable"

elma365-addons.audit.image.repository

Address for registry

hub.elma365.tech

elma365-addons.audit.image.pullSecret

Secret with access rights to the private registry, must be created manually and encrypted in Base64

[yandexsecret]
bi-elma365.html install-kubernetes.html