Install YugabyteDB Anywhere EARLY ACCESS

Use the following instructions to install YugabyteDB Anywhere (YBA) software. For guidance on which method to choose, see YBA Prerequisites.

Note: For higher availability, one or more additional YBA instances can be separately installed, and then configured later to serve as passive warm standby servers. See Enable High Availability for more information.

• Replicated
• Replicated - Airgapped
• Kubernetes
• OpenShift
• YBA Installer

Use YBA Installer to install YBA on a host. YBA Installer performs preflight checks to validate the workspace is ready to run YBA. YBA Installer also provides basic functionality for managing installations, including backup and restore of an installation, upgrading, basic licensing, and uninstalling the software.

Prerequisites

• Ensure your machine satisfies the minimum requirements.
• For production deployments, root privileges (or equivalent sudo access) are required for some YBA Installer commands. (You can use YBA Installer without root access, but this is not recommended for production; refer to Non-root installation.)

Download and configure YBA Installer

Download YBA Installer

Download and extract the YBA Installer by entering the following commands:

$ wget https://downloads.yugabyte.com/releases/2.17.3.0/yba_installer_full-2.17.3.0-b152-linux-x86_64.tar.gz
$ tar -xf yba_installer_full-2.17.3.0-b152-linux-x86_64.tar.gz
$ cd yba_installer_full-2.17.3.0-b152/

This bundle provides everything needed, except a license, to complete a fresh install of YBA:

• yba-ctl executable binary is used to perform all of the YBA Installer workflows.
• yba-ctl.yml.reference is a YAML reference for the available configuration options for both YBA Installer and YugabyteDB Anywhere.

To see a full list of commands, run the following command:

$ ./yba-ctl help

yba-ctl commands need to be run in the correct context; see Running yb-ctl commands.

Configure YBA Installer

Many YBA Installer commands require a configuration file, including preflight and install. When using these commands without a configuration file, you are prompted to continue using default values. For example:

$ sudo ./yba-ctl preflight

No config file found at '/opt/yba-ctl/yba-ctl.yml', creating it with default values now.
Do you want to proceed with the default config? [yes/NO]:

Respond with y or yes to create the configuration file using default configuration settings and continue the operation.

Respond with n or no to create the configuration file using default configuration settings and exit the command.

By default, YBA Installer installs YBA in /opt/yugabyte and creates a Linux user yugabyte to run YBA processes.

To change these and other default values, edit the yba-ctl.yml file, and then re-run the yba-ctl command. For a list of options, refer to Configuration options.

You can change some configuration options post-installation using the reconfigure command.

Install YBA using YBA Installer

Provide a license

YBA Installer requires a valid license before installing. To obtain a license, contact Yugabyte Support.

Provide the license to YBA Installer by running the license command as follows:

$ sudo ./yba-ctl license add -l /path/to/license

You can use this command to update to a new license if needed.

You can also provide a license when running the install command. Refer to Install the software.

Run preflight checks

Start by running the preflight checks to ensure that the expected ports are available, the hardware meets the minimum requirements, and so forth. The preflight check generates a report you can use to fix any issues before continuing with the installation.

$ sudo ./yba-ctl preflight

#  Check name             Status   Error
1  license                Critical stat /opt/yba-ctl/YBA.lic: no such file or directory
2  install does not exist Pass
3  validate-config        Pass
4  user                   Pass
5  cpu                    Pass
6  memory                 Pass
7  port                   Pass
8  python                 Pass
9  disk-availability      Pass
10 postgres               Pass

Some checks, such as CPU or memory, can be skipped, though this is not recommended for a production installation. Others, such as having a license and python installed, are hard requirements, and YugabyteDB Anywhere can't work until these checks pass. All checks should pass for a production installation.

If you are installing YBA for testing and evaluation and you want to skip a check that is failing, you can pass –skip_preflight <name>[,<name2>]. For example:

$ sudo ./yba-ctl preflight --skip_preflight cpu

Install the software

To perform an install, run the install command. Once started, an install can take several minutes to complete.

$ sudo ./yba-ctl install

You can also provide a license when running the install command by using the -l flag:

$ sudo ./yba-ctl install -l /path/to/license

               YBA Url |   Install Root |            yba-ctl config |              yba-ctl Logs |
  https://10.150.0.218 |  /opt/yugabyte |  /opt/yba-ctl/yba-ctl.yml |  /opt/yba-ctl/yba-ctl.log |

Services:
  Systemd service |       Version |  Port |                            Log File Locations |  Running Status |
         postgres |         10.23 |  5432 |          /opt/yugabyte/data/logs/postgres.log |         Running |
       prometheus |        2.42.0 |  9090 |  /opt/yugabyte/data/prometheus/prometheus.log |         Running |
      yb-platform |  2.19.0.0-b51 |   443 |       /opt/yugabyte/data/logs/application.log |         Running |
INFO[2023-04-24T23:19:59Z] Successfully installed YugabyteDB Anywhere!

The install command runs all preflight checks first, and then proceeds to do a full install, and then waits for YBA to start. After the install succeeds, you can immediately start using YBA.

Manage a YBA installation

Reconfigure

YBA Installer can be used to reconfigure an installed YBA instance.

To reconfigure an installation, edit the /opt/yba-ctl/yba-ctl.yml configuration file with your changes, and then run the command as follows:

$ sudo yba-ctl reconfigure

For a list of options, refer to Configuration options. Note that some settings can't be reconfigured, such as the install root, service username, or the PostgreSQL version.

Service management

YBA Installer provides basic service management, with start, stop, and restart commands. Each of these can be performed for all the services (platform, postgres, and prometheus), or any individual service.

$ sudo yba-ctl [start, stop, reconfigure]
$ sudo yba-ctl [start, stop, reconfigure] prometheus

In addition to the state changing operations, you can use the status command to show the status of all YugabyteDB Anywhere services, in addition to other information such as the log and configuration location, versions of each service, and the URL to access the YugabyteDB Anywhere UI.

$ sudo yba-ctl status

               YBA Url |   Install Root |            yba-ctl config |              yba-ctl Logs |
  https://10.150.0.218 |  /opt/yugabyte |  /opt/yba-ctl/yba-ctl.yml |  /opt/yba-ctl/yba-ctl.log |

Services:
  Systemd service |       Version |  Port |                            Log File Locations |  Running Status |
         postgres |         10.23 |  5432 |          /opt/yugabyte/data/logs/postgres.log |         Running |
       prometheus |        2.42.0 |  9090 |  /opt/yugabyte/data/prometheus/prometheus.log |         Running |
      yb-platform |  2.19.0.0-b59 |   443 |       /opt/yugabyte/data/logs/application.log |         Running |

Upgrade

To upgrade using YBA Installer, first download the version of YBA Installer corresponding to the version of YBA you want to upgrade to. See Download YBA Installer. Upgrade works similarly to the install workflow, by first running preflight checks to validate the system is in a good state. When ready to upgrade, run the upgrade command from the untarred directory of the target version of the YBA upgrade:

$ sudo ./yba-ctl upgrade

The upgrade takes a few minutes to complete. When finished, use the status command to verify that YBA has been upgraded to the target version.

Backup and restore

YBA Installer also provides utilities to take full backups of the YBA state (not YugabyteDB however) and later restore from them. This not only includes data seen in YBA for your universes, but also metrics stored in Prometheus.

To perform a backup, provide the full path to the directory where the backup will be generated. The createBackup command creates a timestamped tgz file for the backup. For example:

$ sudo yba-ctl createBackup ~/test_backup
$ ls test_backup/

backup_23-04-25-16-54.tgz  version_metadata_backup.json

To restore from the same backup, use the restoreBackup command:

$ sudo yba-ctl restoreBackup ~/test_backup/backup_23-04-25-16-64.tgz

Clean (uninstall)

To uninstall a YBA instance, YBA Installer also provides a clean command.

By default, clean removes the YugabyteDB Anywhere software, but keeps any data such as PostgreSQL or Prometheus information:

$ sudo yba-ctl clean

INFO[2023-04-24T23:58:13Z] Uninstalling yb-platform
INFO[2023-04-24T23:58:14Z] Uninstalling prometheus
INFO[2023-04-24T23:58:14Z] Uninstalling postgres

To delete all data, run clean with the –all flag as follows:

$ sudo yba-ctl clean -all

--all was specified. This will delete all data with no way to recover. Continue? [yes/NO]: y
INFO[2023-04-24T23:58:13Z] Uninstalling yb-platform
INFO[2023-04-24T23:58:14Z] Uninstalling prometheus
INFO[2023-04-24T23:58:14Z] Uninstalling postgres

Running yba-ctl commands

YBA Installer commands are run in the following contexts:

• local execution path using ./yba-ctl
• installed execution path using yba-ctl

This is because some commands require local execution context, while others require the context of the installed system.

The following commands must be run using the local execution path:

• install
• upgrade

The following commands must be run using the installed execution path:

• createBackup
• restoreBackup
• clean
• start, stop, restart, and status
• reconfigure

The help, license, and preflight commands can be run in either context.

If you don't use the correct execution path, yba-ctl fails with an error:

$ sudo ./yba-ctl createBackup ~/backup.tgz

FATAL[2023-04-25T00:14:57Z] createBackup must be run from the installed yba-ctl

Non-root installation

YBA Installer also supports a non-root installation, where sudo access is not required for any step of the installation. Note that this is not recommended for production use cases.

To facilitate a non-root install, YBA Installer will not create any additional users or set up services in systemd. The install will also be rooted in the home directory by default, instead of /opt, ensuring YBA Installer has write access to the base install directory. Instead of using systemd to manage services, basic cron jobs are used to start the services on bootup with basic management scripts used to restart the services after a crash.

To perform a non-root installation, run any of the preceding commands without root access. You can't switch between a root and non-root installation, and yba-ctl will return an error if sudo is not used when operating in a root installation.

Configuration options

YBA Installer configuration options

You can set the following YBA Installer configuration options.

YBA configuration options

You can configure the following YBA configuration options.

OAuth related settings are described in the following table. Only set these fields if you intend to use OIDC SSO for your YugabyteDB Anywhere installation (otherwise leave it empty).

Http and Https proxy settings are described in the following table.

Prometheus configuration options

Configure PostgreSQL

By default, YBA Installer provides a version of PostgreSQL. If you prefer, you can use your own version of PostgreSQL.

PostgreSQL configuration is divided into two different subsections:

• install - contains information on how YBA Installer should install PostgreSQL.
• useExisting - provides YBA Installer with information on how to connect to a PostgreSQL instance that you provision and manage separately.

These options are mutually exclusive, and can be turned on or off using the enabled option. Exactly one of these two sections must have enabled = true, while the other must have enabled = false.

Install options

useExisting options