Installation

Daria Barysheva, Adelya Zvyagintseva

Collapse content Expand content

Contents

Online installation via a Docker Image
- Run with enhanced security parameters
Offline installation (available in the Enterprise Edition)
Check installation

Online installation via a Docker Image

NOTE

ADCM requires PostgreSQL, which you can configure as an external database or deploy as an embedded database using ADCM Installer. For more information on configuring PostgreSQL, see the Connection to an external database.
Starting with ADCM 2.5.0, the minimum required version of PostgreSQL is 14.
To see the full list of images, refer to the ADCM repository on Docker Hub.
ADCM has some mandatory persistent information stored in the /adcm/data directory inside a container. This means that you have to map a volume to that directory and provide backups for that volume.
If you plan to configure logging, log rotation, or HTTPS, mount the /opt/adcm directory from the host into the container (bind mount).

To install ADCM, perform the following steps:

Pull a Docker image from the Arenadata Docker Registry:

$ sudo docker pull hub.arenadata.io/adcm/adcm:<version>

where <version> is the desired ADCM image version in one of the following formats:

<major>.<minor>.<patch> — if you need a specific ADCM patch. For example, 2.0.0.
<major>.<minor> — if you need the last patch within the selected ADCM version. For example, 2.0.

IMPORTANT

latest was used for earlier versions of ADCM and is no longer supported starting from version 2.0.0.
Before ADCM 2.0.0, the following format was used for versioning: YYYY.MM.DD.HH.

Add and start a container based on that image:

NOTE

The command below creates and starts a container with ADCM on port 8000 and establishes a connection to an external database. All container data will be stored in the adcm-data named volume. For a description of the environment variables, see the table below.

$ sudo docker run \
    --name adcm \
    -p 8000:8000 \
    -v adcm-data:/adcm/data \
    -e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" \
    -e DB_PORT="<DATABASE_TCP_PORT>" \
    -e DB_USER="<DATABASE_USERNAME>" \
    -e DB_NAME="<DATABASE_NAME>" \
    -e DB_PASS="<DATABASE_USER_PASSWORD>" \
    -e DB_OPTIONS="<DATABASE_OPTIONS>" \
    hub.arenadata.io/adcm/adcm:<version>

If a bind mount is used and you need to run ADCM with SELinux enabled, you must specify the :Z option in the parameter containing the data directory name when creating and running the Docker container:

$ sudo docker run \
    --name adcm \
    -p 8000:8000 \
    -v /opt/adcm:/adcm/data:Z \
    hub.arenadata.io/adcm/adcm:<version>

NOTE

When using a bind mount (for example, the host directory /opt/adcm), make sure that the directory is created and owned by 10001:10001 before starting the container:

$ sudo mkdir -p /opt/adcm && sudo chown -R 10001:10001 /opt/adcm

Optionally, when you create and start a container, you can specify the environment variables listed below. Each variable is specified in the following format: -e <name>="<value>". For example:

$ sudo docker run \
    --name adcm \
    -p 8000:8000 \
    -v adcm-data:/adcm/data \
    -e LOG_LEVEL="INFO" \
    hub.arenadata.io/adcm/adcm:<version>

NOTE

Special environment variables, such as STATUS_LOG_LEVEL, ADCM_LOG_LEVEL, AUDIT_LOG_LEVEL, LDAP_LOG_LEVEL, BACKGROUND_TASKS_LOG_LEVEL, and TASK_RUNNER_LOG_LEVEL have higher priority than the LOG_LEVEL variable.

Environment variables

Name Description

DB_HOST

Name or IP address of the host where the database is deployed

DB_PORT

TCP port number that is used to connect to the database

DB_USER

Username that is used to connect to the database

DB_NAME

Database name

DB_PASS

Password that is used to connect to the database

DB_OPTIONS

Options for connecting to the database:

sslmode — flag that is used for establishing an SSL connection. Possible values:
- disable — only try a non-SSL connection.
- allow — first try a non-SSL connection. If that fails, try an SSL connection.
- prefer (default) — first try an SSL connection. If that fails, try a non-SSL connection.
- require — only try an SSL connection. If a root certificate authority (CA) file is present, verify the certificate in the same way as if verify-ca was specified.
- verify-ca — only try an SSL connection, and verify that the server certificate is issued by a trusted CA.
- verify-full — only try an SSL connection, and verify that the server certificate is issued by a trusted CA and that the requested server host name matches that in the certificate.
sslcert — specifies the file name of the client SSL certificate. This parameter is ignored if the connection is made without SSL.
sslkey — specifies the location for the secret key used for the client certificate. This parameter is ignored if the connection is made without SSL.
sslrootcert — specifies the name of a file containing SSL certificate authority certificate(s). If the file exists, the server certificate will be verified to be signed by one of these authorities. A special system value may be specified instead, in which case the system trusted CA roots will be loaded. The exact locations of these root certificates differ by SSL implementation and platform.

DEFAULT_ADCM_URL

URL of the host where the ADCM container is deployed. Use the following format: http://<IP>:8000/. If DEFAULT_ADCM_URL is not specified, you should set the URL manually in the ADCM’s URL field on the Settings page

LOG_LEVEL

Log level for all log types. Possible values:

DEBUG
INFO
WARNING
ERROR (default value)
CRITICAL

STATUS_LOG_LEVEL

Log level for status.log. Possible values:

DEBUG
INFO
WARNING
ERROR
CRITICAL

ADCM_LOG_LEVEL

Log level for adcm.log and adcm_debug.log. Possible values:

DEBUG
INFO
WARNING
ERROR
CRITICAL

AUDIT_LOG_LEVEL

Log level for audit.log. Possible values:

DEBUG
INFO (default value)
WARNING
ERROR
CRITICAL

LDAP_LOG_LEVEL

Log level for ldap.log. Possible values:

DEBUG
INFO
WARNING
ERROR
CRITICAL

BACKGROUND_TASKS_LOG_LEVEL

Log level for cron_task.log. Possible values:

DEBUG
INFO
WARNING
ERROR
CRITICAL

TASK_RUNNER_LOG_LEVEL

Log level for task_runner.err. Possible values:

DEBUG
INFO
WARNING
ERROR
CRITICAL

MAINTENANCE_MODE

Flag that enables maintenance mode for the ADCM container. In this mode, ADCM components are not started, enabling secret migration operations. Possible values:

0 — maintenance mode disabled (default);
1 — maintenance mode enabled.

CONSUL_URL

Consul server URL. Use the following format: http://<IP>:8500/

CONSUL_DATACENTER

Consul Datacenter. If the variable value is not specified, the value specified in Consul by default will be used

CONSUL_CACERT_FILE

Path to the certificate authority (CA) certificate file if encryption is enabled in Consul

CONSUL_CLIENT_CERT_FILE

Path to the client certificate file if encryption is enabled in Consul

CONSUL_CLIENT_KEY_FILE

Path to the client private key file if encryption is enabled in Consul

CONSUL_ACL_TOKEN_FILE

ACL (access control list) token for authentication in Consul (if ACLs are enabled in Consul). Optional variable

CONSUL_HEALTH_CHECK_INTERVAL

HTTP health check interval for the ADCM Backend Server. Optional variable. Default value — 30s

CONSUL_HEALTH_CHECK_TIMEOUT

Maximum response wait time for the ADCM Backend Server health check. Default value — 10s

CONSUL_HEALTH_CHECK_TTL

Time-to-Live (TTL) of the health check result for Celery Worker and tasks in Consul. Default value — 30s

CONSUL_DEREGISTER_CRITICAL_SERVICE_AFTER

Waiting time before removing a service from the Consul registry if its status remains critical. Optional variable. Default value — 5m

SCHEDULER_JOB_LAUNCH_POLL_INTERVAL

Polling interval for Job Scheduler to check the database for new jobs

SCHEDULER_JOB_MONITOR_POLL_INTERVAL

Monitoring (status polling) interval for active jobs by Job Scheduler

SCHEDULER_JOB_TERMINATION_POLL_INTERVAL

Check interval for jobs that need to be terminated

SCHEDULER_JOB_INACTIVITY_THRESHOLD

Maximum inactivity time for a job before it is marked as stuck

SCHEDULER_JOB_EXECUTION_ENVIRONMENT

Job execution environment. Possible values:

LOCAL — for Local Executor;
CELERY — for Celery Worker.

SECRET_BACKEND

Type of secret storage. Specify VaultBackend to use Vault. If the variable is not set, file system storage is used

VAULT_URL

Vault server URL (for example, https://vault.example.com:8200)

VAULT_MOUNT_POINT

Mount point in Vault for storing ADCM secrets

VAULT_TOKEN_FILE

Path to the file containing the access token used for authentication in Vault

VAULT_NAMESPACE

Vault namespace. Used in the Enterprise version to isolate data and configuration

VAULT_CA_FILE

Path to the certificate authority (CA) certificate file for verifying TLS connections to Vault. If the variable is not set, but VAULT_CLIENT_CERT_FILE and VAULT_CLIENT_KEY_FILE are defined, TLS verification is disabled (verify=false)

VAULT_CLIENT_CERT_FILE

Path to the client certificate file when using TLS authentication in Vault

VAULT_CLIENT_KEY_FILE

Path to the client private key file when using TLS authentication in Vault

NOTE

The VAULT_* variables are used when working with Vault (SECRET_BACKEND="VaultBackend").

Run with enhanced security parameters

If your infrastructure requires an increased security level, use the advanced container startup command. In this configuration, the container’s file system is read-only, its capabilities are limited, and gaining extra privileges is prevented.

$ sudo docker run -d \
    --name adcm \
    --restart=always \
    -p 8000:8000 \
    -v adcm-data:/adcm/data \
    -e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" \
    -e DB_PORT="<DATABASE_TCP_PORT>" \
    -e DB_USER="<DATABASE_USERNAME>" \
    -e DB_NAME="<DATABASE_NAME>" \
    -e DB_PASS="<DATABASE_USER_PASSWORD>" \
    -e DB_OPTIONS="<DATABASE_OPTIONS>" \
    -e ANSIBLE_REMOTE_TMP="/tmp/.ansible/tmp" \
    --security-opt no-new-privileges:true \
    --cap-drop ALL \
    --read-only \
    --tmpfs /tmp:mode=1777,exec \
    --tmpfs /adcm/run/:uid=10001,gid=10001,mode=0770 \
    hub.arenadata.io/adcm/adcm:<version>

where:

-e ANSIBLE_REMOTE_TMP="/tmp/.ansible/tmp" — specifies the directory for Ansible temporary files on managed hosts;
--tmpfs /tmp:mode=1777,exec — mounts the container’s /tmp directory into RAM and allows file execution from this directory;
--read-only, --cap-drop ALL, --security-opt no-new-privileges:true — restrict container capabilities and reduce the risk of gaining extra privileges.

Offline installation (available in the Enterprise Edition)

If you use Enterprise Edition of the product, you can also try offline ADCM installation. It can be useful in situations without Internet access.

Offline ADCM installation includes the following steps:

Get an archive with the sh.xz extension that contains a special installation shell script from the Arenadata support team.
Create a directory on the host where ADCM should be deployed, and put the received archive into it.
Unpack the archive into the created directory using any of the available methods.

NOTE
Running the command can take some time. Please wait until it is completed.
Load the Docker image to the local storage using the received script:
```
$ sudo bash <script_name> unpack_adcm
```
where <script_name> is the full script name with the extension (for example, adcm_2.5.0.sh).

The example of a successful command execution result:
```
Loaded image: hub.arenadata.io/adcm/adcm:2.5.0
```

Create and start a new container based on the downloaded image. For data storage, you can use a named volume or a bind mount (for example, if you plan to configure logging, log rotation, or HTTPS):

IMPORTANT

The chosen data storage method must remain unchanged during future ADCM updates. Changing the storage method without prior backup and restore will cause data loss.

Named volume:

$ sudo docker run \
    --name adcm \
    -p 8000:8000 \
    -v adcm-data:/adcm/data \
    -e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" \
    -e DB_PORT="<DATABASE_TCP_PORT>" \
    -e DB_USER="<DATABASE_USERNAME>" \
    -e DB_NAME="<DATABASE_NAME>" \
    -e DB_PASS="<DATABASE_USER_PASSWORD>" \
    -e DB_OPTIONS="<DATABASE_OPTIONS>" \
    hub.arenadata.io/adcm/adcm:<version>

Bind mount:

NOTE

When using a bind mount (for example, the host directory /opt/adcm), make sure that the directory is created and owned by 10001:10001 before starting the container:

$ sudo mkdir -p /opt/adcm && sudo chown -R 10001:10001 /opt/adcm

$ sudo docker run \
    --name adcm \
    -p 8000:8000 \
    -v /opt/adcm:/adcm/data \
    -e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" \
    -e DB_PORT="<DATABASE_TCP_PORT>" \
    -e DB_USER="<DATABASE_USERNAME>" \
    -e DB_NAME="<DATABASE_NAME>" \
    -e DB_PASS="<DATABASE_USER_PASSWORD>" \
    -e DB_OPTIONS="<DATABASE_OPTIONS>" \
    hub.arenadata.io/adcm/adcm:<version>

Check installation

Check the Docker container status

To make sure that the Docker container adcm is successfully deployed, run the following command:

$ sudo docker container ls

The example of the command execution result is listed below. Make sure that the STATUS value is equal to Up.

CONTAINER ID        IMAGE                               COMMAND             CREATED             STATUS              PORTS                    NAMES
74b5628146e5        hub.arenadata.io/adcm/adcm:2.0   "/etc/startup.sh"   4 days ago          Up 21 minutes       0.0.0.0:8000->8000/tcp   adcm

Check the 8000 port availability

After ADCM is installed and started, its web interface should become available on the 8000 port of the deployed container.

For Ubuntu 22.04 LTS, first install the packages required for executing the netstat command:

$ sudo apt-get install net-tools

You can check the 8000 port availability using these commands:

The netstat command — to display information about port listening.

$ sudo netstat -ntpl | grep 8000

The example of the command execution result:

tcp6       0      0 :::8000                 :::*                    LISTEN                                             1514/docker-proxy-c

The curl command — to check the URL connection.

$ curl http://localhost:8000

The example of the command execution result:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Arenadata Cluster Manager</title>
  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" type="image/x-icon" href="assets/favicon.ico">
<link rel="stylesheet" href="styles.10db6328264e0907c52f.css"></head>
<body>
  <app-root></app-root>
<script src="runtime-es2015.7eb406ed18bf0258cd35.js" type="module"></script><script src="runtime-es5.7eb406ed18bf0258cd35.js" nomodule defer></script><script src="polyfills-es5.2e224d70daec4412d3c2.js" nomodule defer></script><script src="polyfills-es2015.37e0553ac06970d6a5b5.js" type="module"></script><script src="main-es2015.39851da0ebf9ed6fec45.js" type="module"></script><script src="main-es5.39851da0ebf9ed6fec45.js" nomodule defer></script></body>
</html>

Check the ADCM web-interface

To log in to ADCM, use the user with administrator rights that is created by default:

User: admin
Password: admin

Later you can change the password if necessary. To do this:

Open the user profile in the left navigation menu.
Enter the current password in the Current password field.
Fill in the New password field.
Confirm a new password in the Confirm password field.
Click Save.

Change the admin password

Set the ADCM URL

For successful communication between ADCM and product clusters deployed via ADCM, it is important to correctly define the external ADCM address. This address is used by cluster components for sending information about their state to ADCM. To specify the ADCM URL, use the environment variable DEFAULT_ADCM_URL when creating the ADCM container. If you did not specify that variable, you should manually install the URL in the ADCM web interface. To do this, follow the steps:

Select the Settings item in the left navigation menu.
Expand the Global Options node in the tree of configuration settings.

The Settings page
Enter the required value directly into the ADCM’s URL text field.
Click Save to apply changes.

Save the ADCM URL

Found a mistake? Seleсt text and press Ctrl+Enter to report it