Install the JFrog Platform Using Ansible

JFrog’s Ansible Collection includes several Ansible roles for JFrog JFrog Artifactory, Xray, JFrog Distribution, and PostgreSQL (optional) that allow you to...

JFrog’s Ansible Collection includes several Ansible roles for JFrog Artifactory, JFrog Xray, JFrog Distribution, and PostgreSQL (optional) that allow you to install the latest JFrog Platform in many different configurations — from simple single server installations to redundant and highly available setups — this collection provides the flexibility for any architecture.

In addition, the Ansible Collection includes optional roles for a PostgreSQL database and NGINX, which also allows you to add those components (refer to the example inventory and playbook files that are included in the Collection and that address most of the popular use cases).

Set up Ansible and the JFrog Ansible Collection

There are several ways to install Ansible depending on your system; Ansible uses SSH to connect to hosts, so the best practice is to set up SSH key pairs and place the public key on the hosts (refer to the Ansible documentation for information on how to set this up). Some cloud providers also make this easier by setting up the SSH keys for you.

The JFrog Ansible Platform Collection consists of the following:

ansible_collections directory: This directory contains the Ansible Collection package with the Ansible roles for the following products:
- Artifactory
- Xray
- Distribution
examples directory: This directory contains example playbooks for various architectures

System Requirements for Ansible Installation

Before installing the JFrog Ansible Collection, refer to System Requirements for information on supported platforms, supported browsers, required ports and other requirements.

📘
Note
Each JFrog product must be installed on a separate box.

📘
Note
When installing the JFrog Platform, you must run the installation as a root user or provide sudo access to a non-root user.

You can install the JFrog Ansible Collection on the following operating systems.

Ubuntu LTS versions (20.4/22.04)
RHEL 8.x, 9.x
Debian 10.x/11.x

From 10.11.x collection and above if you use fully qualified collection name (FQCN), run the following command to install collection dependencies.

ansible-galaxy collection install community.postgresql community.general ansible.posix

JFrog Platform Ansible Installation Steps

The following installation installs the JFrog Platform as single product (single node) installations and not as clusters/HA.

Install the Ansible Collection from the Ansible Galaxy.
```
ansible-galaxy collection install jfrog.platform
```

Verify that you reference the Ansible Collection in your playbook when using these roles.

---
- hosts: artifactory_servers
      collections:
        - jfrog.platform
      roles:
        - artifactory

📘
Note
Ansible uses SSH to connect to hosts. Verify that your SSH private key is on your client and that the public keys are installed on your Ansible hosts.

Create an inventory file: Use one of the examples from the examples directory to construct an inventory file (hosts.yml) with the host addresses and variables.
Next, create your playbook: Use one of the examples from the examples directory to construct a playbook using the JFrog Ansible roles. These roles will be applied to your inventory and provision software.
Execute the following command to provision the JFrog software with Ansible.
```
ansible-playbook -vv platform.yml -i hosts.ini
```

Generate master and join keys for the Ansible Installation

If you do not provide these keys, they will be set to the defaults in the groupvars/all/vars.yaml file under each role. For production deployments, you may want to generate your master and join keys and to apply them to all the nodes using the following command.

MASTER_KEY_VALUE=$(openssl rand -hex 32)
JOIN_KEY_VALUE=$(openssl rand -hex 32)
ansible-playbook -vv platform.yml -i hosts.ini --extra-vars "master_key=$MASTER_KEY_VALUE join_key=$JOIN_KEY_VALUE"

📘
Note
Remember to save the generated master and join keys for future upgrades.

Override the system.yaml file in Ansible installations

By default, the flag <product>_systemyaml_override is set to false, which means that any changes you do to override/edit the existing yaml will not be applied.

Set the flag to true, for example artifactory_systemyaml_override: true, you can override the existing configurations for the product, in this case Artifactory.

Use Ansible Vault to encrypt vars

Some vars you may want to keep secret. You may put these vars into a separate file and encrypt them using the Ansible Vault.

Run the following command.

ansible-vault encrypt secret-vars.yml --vault-password-file ~/.vault_pass.txt

Then in your playbook include the secret vars file.

- hosts: artifactory_servers
  vars_files:
    - ./vars/secret-vars.yml
    - ./vars/vars.yml
  roles:
    - artifactory

Use an External Database with the Ansible Installation

Set the value of the postgres_enabled field to false (which means that you are not going to use the Postgres role that is bundled with the collection) in group_vars/all/vars.yml.

Follow the steps below to create an external database and then change the corresponding product values in group_vars/all/vars.yml.

The following example shows a sample configuration for the Artifactory database connection details.

postgres_enabled: false

artifactory_db_type: postgresql
artifactory_db_driver: org.postgresql.Driver
artifactory_db_name: <external_db_name>
artifactory_db_user: <external_db_user>
artifactory_db_password: <external_db_pasword>
artifactory_db_url: jdbc:postgresql://<external_db_host>:5432/{{ artifactory_db_name }}

📘
Note
You can also modify other JFrog products database configuration to set up an external PostgreSQL database in the same file.

Create the PostgreSQL Database for the Ansible Installation

📘
Note
For information about supported versions of PostgreSQL, see Artifactory PostgreSQL Support.

Use the following commands to create an Artifactory user and database with appropriate permissions. Modify the relevant values to match your specific environment.

Creating an Artifactory User and Database

CREATE USER artifactory WITH PASSWORD 'password';
CREATE DATABASE artifactory WITH OWNER=artifactory ENCODING='UTF8';
GRANT ALL PRIVILEGES ON DATABASE artifactory TO artifactory;

Once you verify that the script is correct, run the script to create the database and proceed with the database configuration.

📘
Note
We recommend providing Artifactory with full privileges on the database.

Configure Artifactory to use PostgreSQL in an Ansible Installation

When you configure Artifactory to use PostgreSQL, all the artifact information is stored in PostgreSQL while the artifact binary data is stored in the file system (under $JFROG_HOME/artifactory/var/data/artifactory/filestore).

📘
Note
While it is possible to store BLOBs inside PostgreSQL we do not recommend it. This is important because the PostgreSQL driver does not support streaming BLOBs with unknown length to the database. Therefore, Artifactory temporarily saves deployed files to the filesystem and only then saves the BLOB to the database.

Configure Artifactory to Use PostgreSQL Single Node in Ansible

Stop the Artifactory service.

Edit the database connection details in the system.yaml configuration file as follows.

shared:
  database:
    type: postgresql
    driver: org.postgresql.Driver
    url: jdbc:postgresql://<your db url, for example: localhost:5432>/artifactory
    username: artifactory
    password: password

Start the Artifactory service.

Configure Artifactory HA to Use PostgreSQL Database in HA in Ansible

Stop the Artifactory service.
Edit the system.yaml file to update the following values.

📘
Note
Because Artifactory uses multiple drivers and you need to configure the connection strings for these separately.
1. The url field under the shared database section in the following format.
```
jdbc:postgresql://<PostgreSQL Database 1 URL>,..., <PostgreSQL Database N URL>/artifactory?targetServerType=primary
```
2. The urlfield under the metadatadatabase section in the following format.
```
jdbc:postgresql://<PostgreSQL Database 1 URL>,..., <PostgreSQL Database N URL>/artifactory?target_session_attrs=read-write"
```

The following sample shows an example system.yaml file configuration.

systemYaml:
 shared:
   logging:
   ...
   database:
     type: postgresql
     url: "jdbc:postgresql://17.21.0.2:5432,17.21.0.3:5432/artifactory?targetServerType=primary"
     driver: org.postgresql.Driver
     username: "artifactory"
     password: "password"
 artifactory:
   Database:
 ...
 frontend:
 ...
 access:
 ...
 metadata:
   database:
     type: postgresql
     url: "jdbc:postgresql://17.21.0.2:5432,17.21.0.3:5432/artifactory?target_session_attrs=read-write"
     driver: org.postgresql.Driver
     username: "artifactory"
     password: "password"
...

Start the Artifactory service.

Enable TLS Encryption in Ansible Installation

To enable Transport Layer Security (TLS) encryption for PostgreSQL, set the sslmode property to verify-full in the JDBC connector URL.

For example, in the $JFROG_HOME/artifactory/var/etc/system.yaml file:

shared:
  database:
    ...
    url:jdbc:postgresql://mypostgress.mydomain.com:5432/artifactory?ssl=true&sslfactory=org.postgresql.ssl.jdbc4.LibPQFactory&sslmode=verify-  
    full&sslrootcert=/tmp/server.crt
...

📘
Note
If you are using old certificates or have an AWS RDS instance that was created before July 2020, you will not have Subject Alternative Name (SAN) enabled. To resolve this issue, you will need to generate a new certificate with SAN.

High Availability (HA) Ansible Installation

By default, the Ansible Platform Collection is installed in a single node configuration. Currently, HA is supported for Artifactory and not the other products.

To enable HA for Artifactory, set the following as true in roles/artifactory/defaults/main.yml inside the Ansible Platform Collection.

artifactory_ha_enabled: true

You can also enable HA by setting extra-vars by running the following command if you are doing a fresh installation.

ansible-playbook -vv platform.yml -i hosts.ini --extra-vars "artifactory_ha_enabled=true"

You can enable HA for an existing single node installation by running the following command.

ansible-playbook -vv platform.yml -i hosts.ini --extra-vars "artifactory_ha_enabled=true artifactory_systemyaml_override=true"

⚠️
Warning
By default, Ansible tries to manage all of the machines referenced in a play in parallel and starts all Artifactory nodes in parallel, which is not supported and causes the installation to fail. To avoid such a scenario, add the following serial mode logic in your playbook when you install or upgrade Artifactory in HA mode.
- hosts: artifactory_servers
  serial:
    - 1
    - 100%
  roles:
    - role: artifactory
      when: artifactory_enabled | bool

By default, all nodes are installed as primary nodes, which means that all nodes in the high availability cluster can perform tasks such as replication, garbage collection, backups, exporting, and importing. Every node in the cluster can serve any of the mentioned tasks and if any node goes down, the different nodes in the cluster will be able to perform these tasks instead. By default, when adding a new node (member) to the cluster, it will be able to perform cluster-wide tasks without user intervention.

The "taskAffinity": "any" attribute is set by default, on all the nodes in the cluster, when installing an Artifactory version 7.17.4 and above and is configured under the Nodes section in the Artifactory Configuration YAML. To remove this functionality from a node, set "taskAffinity": "none". For more information, see Cloud-Native High Availability.

Build the Ansible Collection Archive

Go to the ansible_collections/jfrog/installers directory.
Update the galaxy.yml meta file as needed. Update the version.
Build the archive (this requires Ansible 2.9+).
```
ansible-galaxy collection build
```

Set SSL Certificate and Key for Nginx for the Ansible Installation

Set artifactory_nginx_ssl_enabled as true in roles/artifactory/defaults/main.yml inside the Ansible Platform Collection. This enables Artifactory to use the artifactory_nginx_ssl role.

Configure the following role variables in the artifactory_nginx_ssl role.

server_name: The server name. For example, artifactory.54.105.51.178.xip.io.
certificate: The SSL certificate
certificate_key: The SSL private key.
nginx_worker_processes: The worker_processes configuration for Nginx. Default is 1.
artifactory_docker_registry_subdomain: Whether to add a redirect directive to the Nginx configuration for the use of docker subdomains.

Configure mTLS in Artifactory with NGINX

To enable mTLS (Mutual TLS) authentication in Artifactory through NGINX, follow these steps:

Step: 1 - NGINX Changes

Navigate to the main.yml file located at:

platform/products/ansible/ansible_collections/jfrog/platform/roles/artifactory_nginx_ssl/defaults/main.yml

To set up a CA certificate, find the parameter mtls_ca_certificate_install in the main.yml file and change its value from false to true.

To create a CA certificate, run the following command:

openssl req -new -x509 -nodes -days 365 -subj '/CN=my-ca' -keyout ca.key -out ca.crt

📘
Note
CA certificates in mTLS verify the authenticity and trustworthiness of client and server certificates, ensuring secure and mutual authentication.

Place the ca.crt and ca.key files into the same directory as your main.yml file.
In the main.yml file, add the following parameters to update the generated certificates:
```
mtls_ca_certificate_crt: |
mtls_ca_certificate_key: |
```

Step: 2 - Arifactory Changes

Navigate to the main.yml file located at:

platform/products/ansible/ansible_collections/jfrog/platform/roles/artifactory/defaults/main.yml

Under the artifactory_access_config_patch section, add the following configuration:

security:
  authentication:
    mtls:
      enabled: true                  
      extraction-regex: (.*)

In the same main.yml, update the following flags:
```
artifactory_nginx_ssl_enabled: true
artifactory_nginx_enabled: false
```
For more information, see Set up mTLS Verification and Certificate Termination on the Reverse Proxy.
Follow these steps to validate the client:
1. Generate a new server key with the following command:
```
openssl genrsa -out server.key 2048
```
2. Use the server key to create a Certificate Signing Request (CSR) with the following command:
```
openssl req -new -key server.key -subj '/CN=localhost' -out server.csr
```
3. Use the CA certificates created in Step 1 to generate the server certificate with the following command:
```
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -days 365 -out server.crt
```
To test the mTLS setup, use a tool like curl with the following command:
```
curl -u <username>:<password> "http://<artifactory-url>/artifactory/api/system/ping" --cert server.crt --key server.key -k
```
Replace the placeholders:

<username>: Your Artifactory username.

<password>: Your Artifactory password.

<artifactory-url>: The URL of your Artifactory instance.

This command should establish a connection using the configured mTLS, ensuring proper communication with Artifactory.

Upgrading JFrog Platform for the Ansible Collection

The JFrog Artifactory and JFrog Xray roles support software upgrades using Ansible Collection.

⚠️
Before You Proceed
To ensure you can restore your JFrog Platform and database in case you encounter any issues during the upgrade process, we strongly recommend you make sure your system and database backups are up to date.

All JFrog product roles support software updates. To use a role to perform a software update only, use the _<product>_upgrade_only_ variable and specify the version. See the following example.

- hosts: artifactory_servers
vars:
artifactory_version: "{{ lookup('env', 'artifactory_version_upgrade') }}"
artifactory_upgrade_only: true
roles:
- artifactory
- hosts: xray_servers
vars:
xray_version: "{{ lookup('env', 'xray_version_upgrade') }}"
xray_upgrade_only: true
roles:
- xray

Updated 1 day ago