Skip to content

Commit

Permalink
Support installation of Itential artifacts using repository URL (ite…
Browse files Browse the repository at this point in the history
…ntial#87)

* Added functionality that allows the deployer to distribute bin/tar/whl files from a repository instead of from a file on the control node.

* Added a check to ensure that only one of iap_bin_file, iap_tar_file, or platform_download_url are defined.

* Added support for jfrog repository archive files.

* fixed ansible lint

* Removed reference to vault file

* Added explanation to readme and implemented recommended changes
  • Loading branch information
WadeCStern authored Oct 22, 2024
1 parent 1ecc55c commit e88ff21
Show file tree
Hide file tree
Showing 8 changed files with 244 additions and 85 deletions.
64 changes: 55 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -402,23 +402,41 @@ itential.deployer 1.0.0
The Deployer directory will be referred to as the `DEPLOYER-DIR` in this guide.
### Create the Files and Inventories Directories
### Create the Inventories Directory
The files and inventories directories should be sub-directories of the working directory. The files directory will contain the Itential binaries and artifacts. The inventories directory will contain the hosts files.
The `inventories` directory should be a sub-directory of the working directory. It will contain the hosts files.
```base
% cd <WORKING-DIR>
% mkdir files inventories
```bash
cd <WORKING-DIR>
mkdir inventories
```
### Determine Installation Artifacts Method
Choose one of the following installation methods based on your requirements:
1. **Manual Upload**: Manually download the required files onto the control node in a `files` directory. The deployer will move these artifact files to the target nodes.
2. **Repository Download**: Provide a repository download URL with either a username/password or an API key. The deployer will make an API request to download the files directly onto the target nodes.
### Manual Upload
#### Create the Files Directory
The `files` directory should be a sub-directory of the working directory. It will contain the Itential binaries and artifacts.
```bash
cd <WORKING-DIR>
mkdir files
```
### Download Installation Artifacts
#### Download Installation Artifacts
Download the IAP binary along with any desired IAP adapters (and, if applicable, the IAG binary) from the [Itential Nexus Repository] to local storage.
**&#9432; Note:**
If you are unsure which files should be downloaded for your environment, contact your Itential Professional Services representative.
### Copy Installation Artifacts into the Files Directory
#### Copy Installation Artifacts into the Files Directory
Next, copy the files downloaded in the previous step to the `files` subdirectory.
Expand All @@ -430,7 +448,7 @@ cp ~/Downloads/itential-premium_2023.1.1.linux.x86_64.bin .
cp ~/Downloads/automation_gateway-3.198.19+2023.1.0-py3-none-any.whl .
```
### Create a Symlink to the Files Directory
#### Create a Symlink to the Files Directory
Navigate to the playbooks directory in the Deployer directory and create a symlink to the files directory in the working directory.
Expand All @@ -439,6 +457,27 @@ cd <DEPLOYER-DIR>/playbooks
ln -s <WORKING-DIR>/files .
```
### Repository Download
#### Obtain the Download URL
You can obtain the download URL from either a **Sonatype Nexus Repository** or **JFrog**. Follow the steps below based on the repository type:
- **For Sonatype Nexus**: Navigate to the file you wish to use and locate the **Path** parameter. Copy the link provided in the **Path** field to obtain the download URL.
- **For JFrog**: Locate the file in the JFrog repository and copy the File URL.
This download method supports both the IAP (bin/tar) files and the IAG (whl) files.
#### Configure Repository Credentials
Depending on the repository you are using, you will need to provide the appropriate credentials:
- **For Nexus**: Set the `repository_username` and `repository_password` variables.
- **For JFrog**: Set the `repository_api_key` variable.
**&#9432; Note:**
To secure sensitive information like passwords or API keys, consider using Ansible Vault to encrypt these variables.
### Create the Inventory File
Using a text editor, create an inventory file that defines your deployment environment. To do this, assign your managed nodes to the relevant groups according to what components you would like to install on them. In the following example:
Expand Down Expand Up @@ -487,7 +526,14 @@ all:
hosts:
example1.host.com:
vars:
iap_bin_file: itential-premium_2023.1.1.linux.x86_64.bin
iap_archive_download_url: https://registry.aws.itential.com/repository/itential-premium/2023.2/2023.2.8/itential-premium_2023.2.8.linux.x86_64.tar.gzx
repository_username: user.name
repository_password: !vault |
$ANSIBLE_VAULT;1.1;AES123
12341234123412341234123412341234123412341234123412341234123412341234123412341234
12341234123412341234123412341234123412341234123412341234123412341234123412341234
12341234123412341234123412341241234123412341234123412341234123412341234123412341
1234123412341324
gateway:
hosts:
Expand Down
11 changes: 8 additions & 3 deletions docs/iag_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,14 @@ The variables in this section may be overridden in the inventory in the `gateway
| Variable | Group | Type | Description | Default Value | Required?
| :------- | :---- | :--- | :---------- | :------------ | :--------
| `iag_release` | `gateway` | Fixed-point | Designates which major release version of IAG to install. | N/A | Yes
| `iag_whl_file` | `gateway` | String | The name of the IAG wheel file to install. | N/A | Yes

Both the `iag_release` and `iag_whl_file` must be configured in the inventory.
| `iag_whl_file` | `gateway` | String | The name of the IAG wheel file to install. | N/A | Yes*
| `iag_archive_download_url` | `gateway` | String | The URL for the download of the iag whl file from a repository. | N/A | Yes*
| `repository_username` | `gateway` | String | The username for authentication of the repository from iag_archive_download_url. | N/A | No
| `repository_password` | `gateway` | String | The password for authentication of the repository from iag_archive_download_url. | N/A | No
| `repository_api_key` | `gateway` | String | The API for authentication of the repository from iag_archive_download_url. Can be used instead of username/password for authentication.| N/A | No

The `iag_release` and either `iag_whl_file` or `iag_archive_download_url` must be configured in the inventory.
When `iag_archive_download_url` is configured, the `repository_username`/`repository_password` or `repository_api_key` must be defined.

The following table lists the default variables located in `roles/gateway/defaults/main.yml`.

Expand Down
9 changes: 7 additions & 2 deletions docs/iap_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,12 +55,17 @@ The variables in this section may be overridden in the inventory in the `platfor
| :------- | :---- | :--- | :---------- | :------------ | :--------
| `iap_bin_file` | `platform` | String | The name of the IAP bin file. | N/A | Yes*
| `iap_tar_file` | `platform` | String | The name of the IAP tar file. | N/A | Yes*
| `iap_archive_download_url` | `platform` | String | The URL for the download of the bin/tar file from a repository. | N/A | Yes*
| `repository_username` | `platform` | String | The username for authentication of the repository from iap_archive_download_url. | N/A | No
| `repository_password` | `platform` | String | The password for authentication of the repository from iap_archive_download_url. | N/A | No
| `repository_api_key` | `platform` | String | The API for authentication of the repository from iap_archive_download_url. Can be used instead of username/password for authentication.| N/A | No
| `rabbit_svc_url` | `platform` | String | This variable defines the rabbit service url to use when connecting to an externally provided RabbitMQ cluster. It is intended to be used when the architecture demands that rabbit be hosted elsewhere such as when using AmazonMQ or if the demands of an organization require some other external rabbit solution, like a shared service. | N/A | No
| `redis_svc_url` | `platform` | String | This variable defines the redis service url to use when connecting to an externally provided redis cluster. It is intended to be used when the architecture demands that redis be hosted elsewhere such as when using Elasticache or if the demands of an organization require some other external redis solution, like a shared service. | N/A | No
| `mongobdb_svc_url_itential` | `platform` | String | This variable defines the mongodb connection string to use when connecting to the "itential" database. It is intended to be used when the architecture demands that mongo be hosted elsewhere such as when using Mongo Atlas or if the demands of an organization require some other external mongo solution, like a shared service. | N/A | No
| `mongobdb_svc_url_localaaa` | `platform` | String | This variable defines the mongodb connection string to use when connecting to the "LocalAAA" database. It is intended to be used when the architecture demands that mongo be hosted elsewhere such as when using Mongo Atlas or if the demands of an organization require some other external mongo solution, like a shared service. | N/A | No

Either `iap_bin_file` or `iap_tar_file` must be defined in the inventory, but not both.
Either `iap_bin_file`, `iap_tar_file`, or `iap_archive_download_url` must be defined in the inventory, but not both.
If `iap_archive_download_url` is defined, either `repository_api_key` or `repository_username` and `repository_password` should be defined.

The following table lists the default variables located in `roles/platform/defaults/main.yml`.

Expand Down Expand Up @@ -113,7 +118,7 @@ The following table lists the default variables located in `roles/platform_app_a

# Building the Inventory

To install and configure IAP, add a `platform` group and host(s) to your inventory and configure the `iap_release` and either `iap_bin_file` or `iap_tar_file`. The following inventory shows a basic IAP configuration with a single IAP node.
To install and configure IAP, add a `platform` group and host(s) to your inventory and configure the `iap_release` and either `iap_bin_file`, `iap_tar_file`, or `iap_archive_download_url`. The `iap_archive_download_url` supports Sonatype Nexus and JFrog Artifactory. It is recommended to use `repository_username` and `repository_password` for Nexus and `repository_api_key` for Artifactory. The following inventory shows a basic IAP configuration with a single IAP node.

## Example Inventory - Single IAP Node

Expand Down
50 changes: 40 additions & 10 deletions roles/gateway/tasks/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -140,19 +140,49 @@
path: "{{ iag_install_dir }}/venv/automation-gateway"
register: iag_installed

- name: Install Automation Gateway
when: not iag_installed.stat.exists
- name: Copy IAG archive from local
ansible.builtin.copy:
src: "{{ iag_whl_file }}"
dest: "{{ workingdir.path }}/{{ iag_whl_file | basename }}"
mode: '0644'
when:
- not iag_installed.stat.exists
- iag_whl_file is defined
- iag_archive_download_url is not defined

- name: Download IAG archive from repository
when:
- not iag_installed.stat.exists
- iag_archive_download_url is defined
- iag_whl_file is not defined
block:
- name: Copy IAG to host
ansible.builtin.copy:
src: "{{ iag_whl_file }}"
dest: "{{ workingdir.path }}/{{ iag_whl_file | basename }}"
- name: Download IAG archive from repository
ansible.builtin.get_url:
url: "{{ iag_archive_download_url }}"
dest: "{{ workingdir.path }}/"
mode: '0644'
# Sets the appropriate header based on the repository type:
# - For JFrog: Uses the "X-JFrog-Art-Api" header with the API key if "repository_api_key" is defined and "jfrog" is part of the download URL.
# - For Nexus: Uses a default header ("Accept: application/octet-stream") since Nexus doesn't support API key authentication.
headers: >-
{%- if repository_api_key is defined and iag_archive_download_url is search("jfrog") -%}
{"X-JFrog-Art-Api": "{{ repository_api_key }}", "Accept": "application/octet-stream"}
{%- else -%}
{"Accept": "application/octet-stream"}
{%- endif -%}
url_username: "{{ repository_username | default(omit) }}"
url_password: "{{ repository_password | default(omit) }}"
validate_certs: true
register: download_result

- name: Install IAG
ansible.builtin.pip:
name: "{{ workingdir.path }}/{{ iag_whl_file | basename }}"
virtualenv: "{{ iag_install_dir }}/venv"
- name: Set iag_whl_file destination from download
ansible.builtin.set_fact:
iag_whl_file: "{{ download_result.dest }}"

- name: Install IAG
ansible.builtin.pip:
name: "{{ workingdir.path }}/{{ iag_whl_file | basename }}"
virtualenv: "{{ iag_install_dir }}/venv"

- name: Set ownership/permissions and create properties.yml
when: not iag_installed.stat.exists
Expand Down
44 changes: 44 additions & 0 deletions roles/platform/tasks/download-platform-archive-from-repo.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Copyright (c) 2024, Itential, Inc
# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
---
- name: Download the IAP file from URL
ansible.builtin.get_url:
url: "{{ iap_archive_download_url }}"
dest: "{{ iap_install_dir }}/"
mode: '0755'
# Sets the appropriate header based on the repository type:
# - For JFrog: Uses the "X-JFrog-Art-Api" header with the API key if "repository_api_key" is defined and "jfrog" is part of the download URL.
# - For Nexus: Uses a default header ("Accept: application/octet-stream") since Nexus doesn't support API key authentication.
headers: >-
{%- if repository_api_key is defined and iap_archive_download_url is search("jfrog") -%}
{"X-JFrog-Art-Api": "{{ repository_api_key }}", "Accept": "application/octet-stream"}
{%- else -%}
{"Accept": "application/octet-stream"}
{%- endif -%}
url_username: "{{ repository_username | default(omit) }}"
url_password: "{{ repository_password | default(omit) }}"
validate_certs: true
register: download_result

- name: Extract downloaded filename from result
ansible.builtin.set_fact:
downloaded_file: "{{ download_result.dest | basename }}"

- name: Set iap_bin_file if the downloaded file is a bin file
ansible.builtin.set_fact:
iap_bin_file: "{{ downloaded_file }}"
when: downloaded_file.endswith('.bin')

- name: Set iap_tar_file if the downloaded file is a tar.gz file
ansible.builtin.set_fact:
iap_tar_file: "{{ downloaded_file }}"
when: downloaded_file.endswith('.tar.gz')

- name: Determine package name from the downloaded file
ansible.builtin.set_fact:
iap_package_name: >-
{%- if downloaded_file.endswith('.bin') -%}
{{ downloaded_file.split('.linux.x86_64.bin')[0] }}
{%- elif downloaded_file.endswith('.tar.gz') -%}
{{ downloaded_file.split('.linux.x86_64.tar.gz')[0] }}
{%- endif -%}
64 changes: 9 additions & 55 deletions roles/platform/tasks/install-platform.yml
Original file line number Diff line number Diff line change
@@ -1,61 +1,15 @@
# Copyright (c) 2024, Itential, Inc
# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
---
- name: Upload the IAP bin file using rsync
ansible.posix.synchronize:
src: "{{ iap_bin_file }}"
dest: "{{ iap_install_dir }}/{{ iap_bin_file }}"
rsync_opts:
- "--copy-links"
when:
- upload_using_rsync
- iap_bin_file is defined

- name: Upload the IAP tar file using rsync
ansible.posix.synchronize:
src: "{{ iap_tar_file }}"
dest: "{{ iap_install_dir }}/{{ iap_tar_file }}"
rsync_opts:
- "--copy-links"
when:
- upload_using_rsync
- iap_tar_file is defined

- name: Upload the IAP bin file using copy
ansible.builtin.copy:
src: "{{ iap_bin_file }}"
dest: "{{ iap_install_dir }}/{{ iap_bin_file }}"
mode: "0775"
force: false
when:
- not upload_using_rsync
- iap_bin_file is defined

- name: Upload the IAP tar file using copy
ansible.builtin.copy:
src: "{{ iap_tar_file }}"
dest: "{{ iap_install_dir }}/{{ iap_tar_file }}"
mode: "0775"
force: false
when:
- not upload_using_rsync
- iap_tar_file is defined

- name: Change bin file ownership, group and permissions
ansible.builtin.file:
path: "{{ iap_install_dir }}/{{ iap_bin_file }}"
owner: "{{ iap_user }}"
group: "{{ iap_group }}"
mode: "0755"
when: iap_bin_file is defined

- name: Change tar file ownership, group and permissions
ansible.builtin.file:
path: "{{ iap_install_dir }}/{{ iap_tar_file }}"
owner: "{{ iap_user }}"
group: "{{ iap_group }}"
mode: "0755"
when: iap_tar_file is defined
- name: Download archive files local
ansible.builtin.include_tasks:
file: upload-platform-archive-from-local.yml
when: iap_bin_file is defined or iap_tar_file is defined

- name: Download archive files repository
ansible.builtin.include_tasks:
file: download-platform-archive-from-repo.yml
when: iap_archive_download_url is defined

# Extract bin file contents
# -e Extract tar archive and exit
Expand Down
58 changes: 58 additions & 0 deletions roles/platform/tasks/upload-platform-archive-from-local.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Copyright (c) 2024, Itential, Inc
# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
---
- name: Upload the IAP bin file using rsync
ansible.posix.synchronize:
src: "{{ iap_bin_file }}"
dest: "{{ iap_install_dir }}/{{ iap_bin_file }}"
rsync_opts:
- "--copy-links"
when:
- upload_using_rsync
- iap_bin_file is defined

- name: Upload the IAP tar file using rsync
ansible.posix.synchronize:
src: "{{ iap_tar_file }}"
dest: "{{ iap_install_dir }}/{{ iap_tar_file }}"
rsync_opts:
- "--copy-links"
when:
- upload_using_rsync
- iap_tar_file is defined

- name: Upload the IAP bin file using copy
ansible.builtin.copy:
src: "{{ iap_bin_file }}"
dest: "{{ iap_install_dir }}/{{ iap_bin_file }}"
mode: "0775"
force: false
when:
- not upload_using_rsync
- iap_bin_file is defined

- name: Upload the IAP tar file using copy
ansible.builtin.copy:
src: "{{ iap_tar_file }}"
dest: "{{ iap_install_dir }}/{{ iap_tar_file }}"
mode: "0775"
force: false
when:
- not upload_using_rsync
- iap_tar_file is defined

- name: Change bin file ownership, group and permissions
ansible.builtin.file:
path: "{{ iap_install_dir }}/{{ iap_bin_file }}"
owner: "{{ iap_user }}"
group: "{{ iap_group }}"
mode: "0755"
when: iap_bin_file is defined

- name: Change tar file ownership, group and permissions
ansible.builtin.file:
path: "{{ iap_install_dir }}/{{ iap_tar_file }}"
owner: "{{ iap_user }}"
group: "{{ iap_group }}"
mode: "0755"
when: iap_tar_file is defined
Loading

0 comments on commit e88ff21

Please sign in to comment.