Skip to content

Updated readme with playbooks and roles #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
WadeCStern merged 1 commit into from
May 1, 2025
Merged

Updated readme with playbooks and roles #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
250 changes: 135 additions & 115 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ information.
## Connection Variables

Playbooks in this collection need to connect to some combination of:
- **Host Machines** (via SSH), or
- **Ansible Hosts** (via SSH), or
- The **Itential Platform Service** (via API).
- The **IAG Service** (via API).

Expand Down Expand Up @@ -39,29 +39,32 @@ To connect to the IAG API, provide
Variables can be:
- Defined in an **inventory file (hosts file)**.
- Passed via the command line using `--extra-vars` or `-e`.
- Encoded using ansible vault and provided by either of the above methods.

Example:
`ansible-playbook playbook.yml -i hosts.yaml --extra-vars 'platform_auth_token=<token>'`

# Tools

1. [Get Platform Token](#get-platform-token)
2. [Restart Adapter](#restart-adapter)
2. [Restart Adapters](#restart-adapters)
3. [Metrics](#metrics)
4. [Adjusting Adapters' log level](#adjusting-adapters'-log-level)
5. [Starting/Stopping Workersics](#starting/stopping-workers)
6. [Mongo Dump](#mongo-dump)
7. [Create Adapter](#create-adapter)
8. [App Adapter Version](#app-adapter-version)
9. [Sync IAG Custom Script Schema](#sync-iag-custom-script-schema)
10. [Dependencies Version](#dependencies-version)
11. [Switch Active Profile](#switch-active-profile)
12. [Job and Task Worker Status](#job-and-task-worker-status)
13. [RBAC Settings](#rbac-settings)
14. [IAG Refresh Custom Script](#iag-refresh-custom-script)
15. [Restart Platform](#restart-platform)
16. [Restart IAG](#restart-iag)
17. [Admin All Roles](#admin-all-roles)
4. [Adjusting Adapters' Log Level](#adjusting-adapters-log-level)
5. [Starting/Stopping Workers](#startingstopping-workers)
6. [Sync IAG Custom Script Schema](#sync-iag-custom-script-schema)
7. [Dependencies Version](#dependencies-version)
8. [Job and Task Worker Status](#job-and-task-worker-status)
9. [RBAC Settings](#rbac-settings)
10. [IAG Refresh Custom Scripts](#iag-refresh-custom-scripts)
11. [Restart Platform](#restart-platform)
12. [Restart IAG](#restart-iag)
13. [IAG Fakenos](#iag-fakenos)
14. [MongoDB Change Password](#mongodb-change-password)
15. [Redis Change Password](#redis-change-password)
16. [Sentinel Change Password](#sentinel-change-password)
17. [Step Down Mongo Primary](#step-down-mongo-primary)
18. [Step Down Redis Primary](#step-down-redis-primary)


## Get Platform Token
This tool will fetch a platform session token and display it to the screen.
Expand All @@ -70,26 +73,26 @@ This playbook requries Platform API access.
### Example
`ansible-playbook playbooks/get_platform_token.yml -i hosts.yaml --extra-vars 'platform_username=<some-user> platform_password=<some-password>'`

## Restart Adapter
## Restart Adapters
This tool will restart a list of provided adapter names after fetching an IAP
session token. This playbook requries Platform API access.

### Required Variables

| NAME | DESCRIPTION |
|-------------------|---------------------------------------------------|
| adapters | String(one adapter) or Comma separated list of adapter names to restart |
| adapters | Comma separated list of adapter names to restart |

### Example
`ansible-playbook playbooks/restart_adapters.yml -i hosts.yaml --extra-vars 'iap_username=<some-user> iap_password=<some-password> adapters=<comma-separated-list-of-adapter-names>'`
`ansible-playbook playbooks/restart_adapters.yml -i hosts.yaml adapters=<comma-separated-list-of-adapter-names>'`

## Metrics
This tool will show the quantity of workflows, templates, MOP templates,
analytic templates, JSTs, JSON forms, forms, jobs and automations in IAP.
This playbook requries Platform API access.

### Example
`ansible-playbook playbooks/metrics.yml -i hosts.yaml --extra-vars 'iap_username=<some-user> iap_password=<some-password>'`
`ansible-playbook playbooks/metrics.yml -i hosts.yaml`

## Adjusting Adapters' log level
This tool will adjust the log level of the adapters in IAP. Available options are
Expand All @@ -100,9 +103,10 @@ This tool will adjust the log level of the adapters in IAP. Available options ar
| NAME | DESCRIPTION |
|--------------|-----------------------------------------------------------------|
| log_level | The log level to be set (error, warn, info, debug, trace, spam) |
| adapters | Comma separated list of adapters to update |

### Example
`ansible-playbook playbooks/adapters_log_level.yml -i hosts.yaml --extra-vars 'iap_username=<some-user> iap_password=<some-password> log_level=error'`
`ansible-playbook playbooks/adapters_log_level.yml -i hosts.yaml --extra-vars log_level=error'`

## Starting/Stopping Workers
These playbooks will start or stop **task workers** and/or **job workers** (supported in Platform 2023.1 and later).
Expand All @@ -116,58 +120,7 @@ Each action has its own playbook:
- `stop_job_worker.yml`

### Example Usage
`ansible-playbook start_task_worker.yml -i hosts.yaml --extra-vars 'platform_username=<user> platform_password=<password>'`


## Mongo Dump
This tool will dump single or all collections from a given mongo database.
This playbook requries Host Machine access.

### Required Variables

| NAME | DESCRIPTION |
|----------------|--------------------------------------------------------------------------|
| db | The database containing collections to be dumped |
| mongo_auth_db | The database to perform authentication on |
| mongo_username | MongoDB username |
| mongo_password | MongoDB user's password |
| collection | Optional. If not defined, all collections in the database will be dumped |

### Example
`ansible-playbook playbooks/mongo_dump.yml -i hosts.yaml --extra-vars 'db=itential collection=workflows'`

## Create Adapter
This tool will create the adapter and starts it.
This playbook requries Platform API access.

### Required Variables

| NAME | DESCRIPTION |
|-------------------------|---------------------------------------------------------------------------------------------|
| adapter_properties_file | Name of the JSON file where the adapter properties are stored. |

### Example
`ansible-playbook playbooks/create_adapter.yml -i hosts --extra-vars 'adapter_properties_file="<file_path>" iap_username=<some-user> iap_password=<some-password>'`

## App Adapter Version
This tool will show the the version of applications and adapters in the IAP. User can specify the applications/adapters of which they want to see the version. The users also have the option to view the versions of all applications and adapters.
This playbook requries Platform API access.

### Required Variables

| NAME | DESCRIPTION |
|-------------------|---------------------------------------------------------------------------------------------|
| adapter_app_names | Names of applications and adapters, separated by comma. If no names are provided, will return versions of all applications and adapters.|

### Example
The following command returns the version of local_aaa adapter and AGManager application:

`ansible-playbook playbooks/app_adapter_version.yml -i hosts --extra-vars 'adapter_app_names="local_aaa, AGManager" iap_username=<some-username> iap_password=<some-password>'`

The following command returns the version of all applications and adapters.

`ansible-playbook playbooks/app_adapter_version.yml -i hosts --extra-vars 'adapter_app_names="" iap_username=<some-username> iap_password=<some-password>'`

`ansible-playbook start_task_worker.yml -i hosts.yaml`

## Sync IAG Custom Script Schema
This tool will grab the JSON schema(decorations) of the custom script from the first IAG host in the `gateway` group and applies it to the custom script across other IAG hosts in the `gateway` group.
Expand All @@ -184,11 +137,10 @@ This playbook requries IAG API access.
### Example
`ansible-playbook sync_iag_script_schema.yml -i hosts --extra-vars 'script_name=hello.py'`


## Dependencies Version
This tool will return the version of redis, rabbitmq, mongobd, IAP components, and IAG components. More information about the dependencies can be found in [this](https://docs.itential.com/docs/itential-dependencies-consolidated) page. The rabbitmq server, redis server, IAP server and IAG server
should be under their respective group in the hosts file.
This playbook requries Host Machine access.
This playbook requries ansible host access.

### Required Variables

Expand All @@ -205,42 +157,12 @@ This playbook requries Host Machine access.
### Example
`ansible-playbook playbooks/dependencies_version.yml -i hosts --extra-vars 'component=all'`

## Switch Active Profile
This tool will switch the active profile to the profile specified. After the active profile is switched, it restarts the IAP. This playbook requries Host Machine and Platform API access.

### Required Variables

| NAME | DESCRIPTION |
|--------------|-------------------------------------------------|
| id | The id of the profile. |

### Example
`ansible-playbook playbooks/app_adapter_version.yml -i hosts --extra-vars 'id=<profile-id> iap_username=<some-username> iap_password=<some-password>'`

Running the playbook by providing ssh key file from command line

`ansible-playbook playbooks/app_adapter_version.yml -i hosts --extra-vars 'id=<profile-id> iap_username=<some-username> iap_password=<some-password>' --private-key <key_file_name>`

Running the playbook by providing ssh username and password from command line

`ansible-playbook playbooks/app_adapter_version.yml -i hosts --extra-vars 'id=<profile-id> iap_username=<some-username> iap_password=<some-password>' -u <ssh_username> --ask-pass <password>`


## Job and Task Worker Status
This tool will return the status of job worker and task worker of IAP.
This playbook requries Platform API access.

### Required Variables

| NAME | DESCRIPTION |
|-------------------|---------------------------------------------------------------------------------------------|
| iap_port | The port that the IAP is running on. |
| iap_protocol | The HTTP/HTTPS protocol that is being used by IAP |
| iap_username | The application user's name |
| iap_password | The application user's password |

### Example
`ansible-playbook playbooks/job_worker_status.yml -i hosts --extra-vars 'iap_username=<some-username> iap_password=<some-password>`
`ansible-playbook playbooks/job_worker_status.yml -i hosts`

## RBAC Settings
This playbook retrieves **RBAC (Role-Based Access Control)** settings for one or more users in the Platform. It gathers authorization accounts and roles from the Platform API, processes the data, and displays the assigned roles for the specified users.
Expand All @@ -257,8 +179,7 @@ This playbook requries Platform API access.
### Example Usage

Get RBAC settings for multiple users using username/password:
`ansible-playbook rbac_settings.yml -i hosts.yaml --extra-vars 'platform_username=<user> platform_password=<password> users=["user1","user2"]'`

`ansible-playbook rbac_settings.yml -i hosts.yaml --extra-vars users=["user1","user2"]'`

## IAG Refresh Custom Script
This tool will refresh the custom scripts cache in IAG. Furthermore, it also restarts the AGManager application and the IAG adapters in the IAP so that the updated scripts can be accessed from the IAP. The IAP hostnames should be under `platform` group and the IAG hostnames should be under the `gateway` group inside the host file.
Expand All @@ -269,16 +190,16 @@ This playbook requries Platform API and IAG API access.

## Restart Itential Platform
This tool will perform a safe restart the Itential Platform. It turns off task and job workers then waits until there are no
in progress jobs before restarting the Platform. The playbook requires Host Machine and Platform API access.
in progress jobs before restarting the Platform. The playbook requires ansible host and Platform API access.

### Example
Running playbook when password/key file is defined in the hosts file

`ansible-playbook playbooks/restart_iap.yml -i hosts`
`ansible-playbook playbooks/restart_platform.yml -i hosts`

## Restart IAG
This tool will restart the IAG.
This playbook requries Host Machine access.
This playbook requries ansible host access.

### Example
Running playbook when password/key file is defined in the hosts file
Expand All @@ -293,10 +214,109 @@ Running playbook by providing username and password from command-line

`ansible-playbook playbooks/restart_iag.yml -i hosts -u <ssh_username> --ask-pass <password>`

## IAG Fakenos
This tool will install and start fakenos which will create mock devices on an IAG host.
The playbook requires ansible host access.

## Admin All Roles
This tool will add all available roles to the admin user.
This playbook requries Platform API access.
### Required Variables

| NAME | DESCRIPTION |
|------------------|-----------------------------------------------------------------|
| fakenos_devices | Object containing the device type. Each device type needs vendor, platform, and count |


### Example Inventory variable

```
fakenos_devices:
cisco_ios:
vendor: cisco
platform: ios
count: 5
juniper_junos:
vendor: junipernetworks
platform: junos
count: 5
```

### Example

Running playbook when fakenos_devices is defined in the inventory file

`ansible-playbook rbac_settings.yml -i hosts.yaml`

## Mongodb Change Password
This tool will update the password for the 'itential' user in the mongo database.
It also updates the platform configuration and restarts the platform.
The playbook requires ansible host access for mongo and platform.

| NAME | DESCRIPTION |
|------------------|-----------------------------------------------------------------|
| mongo_admin_password | the password for the 'admin' user in the mongo database |
| mongo_new_password | The new password for the itential user |

### Example
`ansible-playbook playbooks/admin_all_roles.yml -i hosts.yaml --extra-vars 'iap_username=<some-user>' --vault-password-file .password`
`ansible-playbook mongodb_change_password.yml -i hosts.yaml --extra-vars "mongo_admin_password=password mongo_new_password=newpassword"`

## Redis Change Password
This tool will update the password for the 'itential' user in the Redis configuration file.
It also updates the platform configuration and restarts the platform.
The playbook requires ansible host access for redis and platform.

| NAME | DESCRIPTION |
|------------------|-----------------------------------------------------------------|
| redis_new_password | The new password for the itential user |

### Example
`ansible-playbook redis_change_password.yml -i hosts.yaml --extra-vars "redis_new_password=newpassword"`

## Sentinel Change Password
This tool will update the password for the 'sentineluser' user in the Redis and Sentinel configuration files.
It also updates the platform configuration and restarts the platform.
The playbook requires ansible host access for redis and platform.

| NAME | DESCRIPTION |
|------------------|-----------------------------------------------------------------|
| sentinel_new_password | The new password for the sentineluser user |

### Example
`ansible-playbook sentinel_change_password.yml -i hosts.yaml --extra-vars "sentinel_new_password=newpassword"`

## Step Down Mongo Primary
This tool forces a mongo re-election for a new Mongo Primary.
The playbook requires ansible host access for mongodb.

| NAME | DESCRIPTION |
|------------------|-----------------------------------------------------------------|
| mongo_admin_password | The password for the admin user in the mongodb |

### Example
`ansible-playbook stepdown_mongo_primary.yml -i hosts.yaml --extra-vars "mongo_admin_password=password"`

## Step Down Redis Primary
This tool forces a redis re-election for a new Redis Primary.
The playbook requires ansible host access for redis

| NAME | DESCRIPTION |
|------------------|-----------------------------------------------------------------|
| redis_password | The password for the admin user in redis |

### Example
`ansible-playbook stepdown_redis_primary.yml -i hosts.yaml --extra-vars "redis_password=password"`

# Roles

## Auth Token
This role retrieves and stores the auth token from the platform API. It is used in playbooks that need
to make many api requests so that ansible doesn't have to re-authenticate each time it wants to make a request.
This role requires platform API access

## Restart Adapters
This role makes an API call to restart all of the adapters from the 'adapter_names' list.
It requires platform API access

## Restart Platform
This role contains the logic to do a safe restart of the platform. It includes a handler that can be
used when the role is imported. This role does not contain a main task file, so to run it the restart.yml
task file or the handler must be explicitly called.
This role requires platform API access
1 change: 1 addition & 0 deletions galaxy.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ readme: README.md
authors:
- Steven Schattenberg <steven.schattenberg@itential.com>
- Ranjitha Parameshwaraiah <ranjitha.parameshwaraiah@itential.com>
- Wade Stern <wade.stern@itential.com>


### OPTIONAL but strongly recommended
Expand Down