Install a Multi-Node Air-Gapped Deployment

This chapter presents instructions on deploying Autonomous Identity in a multi-node air-gapped or offline target machine that has no external Internet connectivity. ForgeRock provides a deployer script that pulls a Docker container image from ForgeRock's Google Cloud Registry (gcr.io) repository. The image contains the microservices, analytics, and backend databases needed for the system.

The air-gap installation is similar to that of the multi-node deployment with Internet connectivity, except that the image and deployer script must be stored on a portable media, such as USB drive or drive, and copied to the air-gapped target environment.

The deployment depends on how the network is configured. You could have a Docker cluster with multiple Spark nodes and/or Cassandra nodes. The key is to determine the IP addresses of each node.

Figure 11: A multi-node air-gap deployment.

Let's deploy Autonomous Identity on a single-node target on CentOS 7. The following are prequisites:

Operating System. The target machine requires CentOS 7. The deployer machine can use any operating system as long as Docker is installed. For this guide, we use CentOS 7 as its base operating system.
Memory Requirements. Make sure you have enough free disk space on the deployer machine before running the deployer.sh commands. We recommend at least a 40GB/partition with 14GB used and 27GB free after running the commands.
Default Shell. The default shell for the autoid user must be bash.
Subnet Requirements. We recommend deploying your multinode instances within the same subnet. Ports must be open for the installation to succeed. Each instance should be able to communicate to the other instances.
Important
If any hosts used for the Docker cluster (docker-managers, docker-workers) have an IP address in the range of 10.0.x.x/16, they will conflict with the Swarm network. As a result, the services in the cluster will not connect to the Cassandra database or Elasticsearch backend.
The Docker cluster hosts must be in a subnet that provides IP addresses 10.10.1.x or higher.
Deployment Requirements. Autonomous Identity provides a Docker image that creates a deployer.sh script. The script downloads additional images necessary for the installation. To download the deployment images, you must first obtain a registry key to log into the ForgeRock Google Cloud Registry (gcr.io). The registry key is only available to ForgeRock Autonomous Identity customers. For specific instructions on obtaining the registry key, see How To Configure Service Credentials (Push Auth, Docker) in Backstage.
Filesystem Requirements. Autonomous Identity requires a shared filesystem accessible from the Spark master, Spark worker, and analytics hosts. The shared filesystem should be mounted at the same mount directory on all of those hosts. If the mount directory for the shared filesystem is different from the default, /data, update the /autoid-config/vars.yml file to point to the correct directories:
```
analytics_data_dir: /data
analytics_conf_dif: /data/conf
```
Architecture Requirements. Make sure that the analytics server is on the same node as the Spark master.

Set Up the Deployer Machine

Set up the deployer on an Internet-connect machine.

The install assumes that you have CentOS 7 as your operating system. Check your CentOS 7 version.
```
$ sudo cat /etc/centos-release
```
Set the user for the target machine to a username of your choice. For example, autoid.
```
$ sudo adduser autoid
```
Set the password for the user you created in the previous step.
```
$ sudo passwd autoid
```

Configure the user for passwordless sudo.

$ echo "autoid  ALL=(ALL)  NOPASSWD:ALL" | sudo tee /etc/sudoers.d/autoid

Add administrator privileges to the user.
```
$ sudo usermod -aG wheel autoid
```
Change to the user account.
```
$ su - autoid
```
Install yum-utils package on the deployer machine. yum-utils is a utilities manager for the Yum RPM package repository. The repository compresses software packages for Linux distributions.
```
$ sudo yum install -y yum-utils
```
Create the installation directory. Note that you can use any install directory for your system as long as your run the deployer.sh script from there. Also, the disk volume where you have the install directory must have at least 8GB free space for the installation.
```
$ mkdir ~/autoid-config
```

Install Docker on the Deployer Machine

On the target machine, set up the Docker-CE repository.

$ sudo yum-config-manager \
     --add-repo https://download.docker.com/linux/centos/docker-ce.repo

Install the latest version of the Docker CE, the command-line interface, and containerd.io, a containerized website.
```
$ sudo yum install -y docker-ce docker-ce-cli containerd.io
```

Set Up SSH on the Deployer

While SSH is not necessary to connect the deployer to the target node as the machines are isolated from one another. You still need SSH on the deployer so that it can communicate with itself.

On the deployer machine, run ssh-keygen to generate an RSA keypair, and then click Enter. You can use the default filename. Enter a password for protecting your private key.
```
$ ssh-keygen -t rsa -C "autoid"
```
The public and private rsa key pair is stored in home-directory/.ssh/id_rsa and home-directory/.ssh/id_rsa.pub.
Copy the SSH key to the autoid-config directory.
```
 $ cp ~/.ssh/id_rsa ~/autoid-config
```
Change the privileges to the file.
```
$ chmod 400 ~/autoid-config/id_rsa
```

Prepare the Tar File

Run the following steps on an Internet-connect host machine:

On the deployer machine, change to the installation directory.
```
$ cd ~/autoid-config/
```
Log in to the ForgeRock Google Cloud Registry (gcr.io) using the registry key. The registry key is only available to ForgeRock Autonomous Identity customers. For specific instructions on obtaining the registry key, see How To Configure Service Credentials (Push Auth, Docker) in Backstage.
```
$ docker login -u _json_key -p "$(cat autoid_registry_key.json)" https://gcr.io/forgerock-autoid
```
Run the create-template command to generate the deployer.sh script wrapper. Note that the command sets the configuration directory on the target node to /config. Note that the --user parameter eliminates the need to use sudo while editing the hosts file and other configuration files.
```
$ docker run --user=`id -u` -v ~/autoid-config:/config -it gcr.io/forgerock-autoid/deployer:2020.6.4 create-template
```
Make the script executable.
```
$ chmod +x deployer.sh
```
Download the Docker images. This step downloads software dependencies needed for the deployment and places them in the autoid-packages directory.
```
$ sudo ./deployer.sh download-images
```
Create a tar file containing all of the Autonomous Identity binaries.
```
$ tar czf deployer.sh autoid-packages.tgz autoid-packages/*
```
Copy the autoid-packages.tgz to a USB drive or portable hard drive.

Install from the Air-Gap Target

Before you begin, make sure you have CentOS 7 installed on your air-gapped target machine.

Create the ~/autoid-config directory if you haven't already.
```
$ mkdir ~/autoid-config
```

Unpack the tar file.

$ tar xf autoid-packages.tgz -C ~/autoid-config

On the air-gap host node, copy the SSH key to the ~/autoid-config directory.
```
 $ cp ~/.ssh/id_rsa ~/autoid-config
```
Change the privileges to the file.
```
$ chmod 400 ~/autoid-config/id_rsa
```
Change to the configuration directory.
```
$ cd ~/autoid-config
```
Install Docker.
```
$ sudo ./deployer.sh install-docker
```
Log out and back in.
Change to the configuration directory.
```
$ cd ~/autoid-config
```
Import the deployer image.
```
$ ./deployer.sh import-deployer
```
Create the configuration template using he create-template command. This command creates a configuration file, ansible.cfg.
```
$ ./deployer.sh create-template
```
Open a text editor and edit the ansible.cfg to set up the remote user and SSH private key file location on the target node. Make sure that the remote_user exists on the target node and that the deployer machine can ssh to the target node as the user specified in the id_rsa file.
```
[defaults]
host_key_checking = False
remote_user = autoid
private_key_file = id_rsa
```

Open a text editor and enter the IP addresses of the target machines in the ~/autoid-config/hosts file. Make sure the ports are open. The following is an example of the ~/autoid-config/hosts file:

[docker-managers]
10.10.15.240

[docker-workers]
10.10.15.201

[docker:children]
docker-managers
docker-workers

[cassandra-seeds]
10.10.15.212

[cassandra-workers]
10.10.15.94

[spark-master]
10.10.15.212

[spark-workers]
10.10.15.94

[analytics]
10.10.15.212

An air-gap deployment has no external IP addresses, but you may still need to define a mapping if your internal IP address differs from an external IP, say in a virtual air-gapped configuration.
If the IP addresses are the same, you can skip this step.
On the target machine, add the private_ip_address_mapping property in the /inventory/vars.yml file. Make sure the values are within double quotes. The key should not be in double quotes and should have two spaces preceding the IP address.
```
private_ip_address_mapping:
  34.70.190.144:  "10.128.0.34"
```
Edit other properties in the ~/autoid-config/vars.yml file, specific to your deployment, such as the following:
- Domain name. For information, see Customize the Domain and Namespace.
- UI Theme. Autonomous Identity provides a dark theme mode for its UI. Set the enable_dark_theme to true to enable it.
- Session Duration. The default session duration is set to 30 minutes. You can alter this value by editing the jwt_expiry property to a time value in minutes of your choice.
- SSO. Autonomous Identity provides a single sign-on (SSO) feature that you can configure with an OIDC IdP provider. For information, see Set Up Single Sign-On.
The default Autonomous Identity URL will be: https://autoid-ui.forgerock.com. To customize your domain name and target environment, see Customize the Domain and Namespace.

Set the Autonomous Identity passwords, located at ~/autoid-config/vault.yml.

Note

Do not include special characters & or $ in vault.yml passwords as it will result in a failed deployer process.

configuration_service_vault:
  basic_auth_password: Welcome123

openldap_vault:
  openldap_password: Welcome123

cassandra_vault:
  cassandra_password: Welcome123
  cassandra_admin_password: Welcome123

Encrypt the vault file that stores the Autonomous Identity passwords, located at ~/autoid-config/vault.yml. The encrypted passwords will be saved to /config/.autoid_vault_password. The /config/ mount is internal to the deployer container.
```
$ ./deployer.sh encrypt-vault
```
Run the deployment.
```
$ ./deployer.sh run
```

Access the Dashboard

You can now access the Autonomous Identity console UI.

Open a browser, and point it to https://autoid-ui.forgerock.com/ (or your customized URL: https://myid-ui.abc.com).
Log in as a test user: bob.rodgers@forgerock.com. Enter the password: Welcome123.

Check Apache Cassandra

On the target node, check the status of Apache Cassandra.

$ /opt/autoid/apache-cassandra-3.11.2/bin/nodetool status

An example output is as follows:

Datacenter: datacenter1
=======================
Status=Up/Down
|/ State=Normal/Leaving/Joining/Moving
-- Address Load Tokens Owns (effective) Host ID Rack
UN 34.70.190.144 1.33 MiB 256 100.0% a10a91a4-96e83dd-85a2-4f90d19224d9 rack1

Check Apache Spark

SSH to the target node and open Spark dashboard using the bundled text-mode web browser
```
$ elinks http://localhost:8080
```
You should see Spark Master status as ALIVE and worker(s) with State ALIVE

Access Self-Service

The self-service feature lets Autonomous Identity users change their own passwords.

Open a browser and point it to: https://autoid-selfservice.forgerock.com/.

Run the Analytics

If the previous steps all check out successfully, you can start an analytics pipeline run, where association rules, confidence scores, predications, and recommendations are determined. Autonomous Identity provides a small demo data set that lets you run the analytics pipeline on. Note for production runs, prepare your company's dataset as outlined in Data Preparation.

SSH to the target node.
Check that the analytics service is running.
```
$ docker ps | grep analytics
```
If the previous step returns blank, start the analytics. For more information, see Data Preparation.
```
$ docker start analytics
```
Once you have verified that the analytics service has started, you can run the analytics commands. For more information, see Run the Analytics Pipeline.

If your analytics pipeline run completes successfully, you have finished your Autonomous Identity installation.