From c6202264dd9fe38d0471a089b642ab650375c6d3 Mon Sep 17 00:00:00 2001 From: haseeb Date: Thu, 13 Nov 2025 16:36:29 +0530 Subject: [PATCH] usage of ansible container in local --- docs/component-ansible.md | 14 ++ docs/operator-guide/ansible-local-usage.md | 162 +++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 177 insertions(+) create mode 100644 docs/operator-guide/ansible-local-usage.md diff --git a/docs/component-ansible.md b/docs/component-ansible.md index 55cbf6ac8..14e6203da 100644 --- a/docs/component-ansible.md +++ b/docs/component-ansible.md @@ -28,5 +28,19 @@ docker run --rm -it ghcr.io/rackerlabs/understack/ansible:latest -- \ ansible-runner run /runner --playbook debug.yaml ``` +## Local Development + +For local development and testing, see the [Ansible Container Local Usage Guide][local-usage-guide] for detailed instructions on: + +- Running playbooks locally with Docker +- Volume mount configurations +- Environment-specific inventory setup +- Debugging and troubleshooting + +## Operational Playbooks (undercloud-rackspace Repository) + +Ongoing operational playbooks that are not part of the initial Understack setup are maintained in a separate [repository](https://github.com/RSS-Engineering/undercloud-rackspace/tree/main/ansible) and can be executed via Argo Workflows using the [ansible-run workflow template](https://github.com/rackerlabs/understack/blob/main/workflows/argo-events/workflowtemplates/ansible-run.yaml). + [ansible-src]: [ansible-runner]: +[local-usage-guide]: diff --git a/docs/operator-guide/ansible-local-usage.md b/docs/operator-guide/ansible-local-usage.md new file mode 100644 index 000000000..1c06aab9b --- /dev/null +++ b/docs/operator-guide/ansible-local-usage.md @@ -0,0 +1,162 @@ +# Running Ansible Playbooks Locally with Docker + +This guide explains how to run Understack Ansible playbooks locally +using the containerized Ansible environment. + +## TL;DR + +Quick start with local playbook development: + +```bash +docker run --rm -it \ + -v $(pwd)/ansible:/runner/project \ + -v $(pwd)/ansible/roles:/runner/project/roles \ + -v $(pwd)/ansible/vars:/runner/project/vars \ + -v /path/to/environment-specific/inventory:/runner/inventory \ + -e NAUTOBOT_URL=https://nautobot.example.com \ + -e NAUTOBOT_TOKEN=your_token_here \ + -e env=dev + -e EXTRA_VARS='{"password":"secret","token":"abc123","username":"user"}' + -w /runner \ + ghcr.io/rackerlabs/understack/ansible:latest \ + ansible-runner run /runner --playbook your-playbook.yaml +``` + +**Note:** Replace `/path/to/environment-name/inventory` with your actual environment inventory path, for example: + +- Dev: `/path/to/undercloud-deploy/{environment-name}/inventory` + +For OpenStack playbooks, add these environment variables: + +```bash + -e OS_USERNAME=admin \ + -e OS_PASSWORD=your_password \ + -e OS_PROJECT_NAME=admin \ + -e OS_AUTH_URL=https://keystone.example.com/v3 \ + -e OS_USER_DOMAIN_NAME=Default \ + -e OS_PROJECT_DOMAIN_NAME=Default \ + -e OS_DEFAULT_DOMAIN=default \ +``` + +## Container Overview + +The Ansible container (`ghcr.io/rackerlabs/understack/ansible`) is built from `containers/ansible/Dockerfile` + +The container uses `ansible-runner` as its default command and expects playbooks to be located in `/runner/project/`. + +## Interactive Shell for Debugging + +Drop into a bash shell to explore or debug: + +```bash +docker run --rm -it \ + -v $(pwd)/ansible:/runner/project \ + -v $(pwd)/ansible/roles:/runner/project/roles \ + -v $(pwd)/ansible/vars:/runner/project/vars \ + -v /path/to/undercloud-deploy/bravo-uc-iad3-dev/inventory:/runner/inventory \ + -e NAUTOBOT_URL=https://nautobot.example.com \ + -e NAUTOBOT_TOKEN=your_token \ + -w /runner \ + ghcr.io/rackerlabs/understack/ansible:latest \ + bash +``` + +Once inside, you can run playbooks manually: + +```bash +ansible-runner run /runner --playbook your-playbook.yaml +``` + +## Volume Mounts Explained + +| Host Path | Container Path | Purpose | +|-----------|---------------|---------| +| `$(pwd)/ansible` | `/runner/project` | Main playbook directory | +| `$(pwd)/ansible/roles` | `/runner/project/roles` | Ansible roles | +| `$(pwd)/ansible/vars` | `/runner/project/vars` | Variable files | +| `/path/to/environment/inventory` | `/runner/inventory` | Environment-specific inventory files | + +**Important:** The inventory directory is environment-specific and should be mounted from your deployment directory structure. +The inventory is assembled from multiple files: + +- Environment inventory: `undercloud-deploy/ansible/inventory/{environment}.yaml` +- Hosts file: `undercloud-deploy/{environment}/inventory/hosts.yaml` +- Group vars: `undercloud-deploy/{environment}/inventory/group_vars/*.yaml` + +**For local development convenience**, you can copy all inventory files into a single directory and mount that: + +```bash +# Create a local inventory directory +mkdir -p /tmp/my-inventory + +# Copy all inventory files +cp /path/to/undercloud-deploy/ansible/inventory/uc-iad3-dev.yaml /tmp/my-inventory/ +cp /path/to/undercloud-deploy/bravo-uc-iad3-dev/inventory/hosts.yaml /tmp/my-inventory/ +cp -r /path/to/undercloud-deploy/bravo-uc-iad3-dev/inventory/group_vars /tmp/my-inventory/ + +# Mount the consolidated directory +-v /tmp/my-inventory:/runner/inventory +``` + +Example environment paths: + +- Dev: `/path/to/undercloud-deploy/bravo-uc-iad3-dev/inventory` +- Staging: `/path/to/undercloud-deploy/charlie-uc-iad3-staging/inventory` + +## Using Different Container Tags + +### Latest Release + +```bash +ghcr.io/rackerlabs/understack/ansible:latest +``` + +### Specific PR (for testing) + +```bash +ghcr.io/rackerlabs/understack/ansible:pr-862 +``` + +## Troubleshooting + +### Check Container Contents + +```bash +docker run --rm -it ghcr.io/rackerlabs/understack/ansible:latest bash +ls -la /runner/project/ +``` + +### View Ansible Version + +```bash +docker run --rm -it ghcr.io/rackerlabs/understack/ansible:latest \ + ansible --version +``` + +### Test OpenStack Connectivity + +```bash +docker run --rm -it \ + -e OS_USERNAME=admin \ + -e OS_PASSWORD=your_password \ + -e OS_PROJECT_NAME=admin \ + -e OS_AUTH_URL=https://keystone.example.com/v3 \ + -e OS_USER_DOMAIN_NAME=Default \ + -e OS_PROJECT_DOMAIN_NAME=Default \ + ghcr.io/rackerlabs/understack/ansible:latest \ + bash -c "openstack --version && openstack token issue" +``` + +## Building the Container Locally + +To build the container from source: + +```bash +docker build -f containers/ansible/Dockerfile -t understack-ansible:local . +``` + +Then use your local image: + +```bash +docker run --rm -it understack-ansible:local ansible-runner run /runner --playbook your-playbook.yaml +``` diff --git a/mkdocs.yml b/mkdocs.yml index f06e88383..90efe9b9c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -174,6 +174,7 @@ nav: - operator-guide/nautobot.md - operator-guide/troubleshooting-osh.md - operator-guide/logging.md + - operator-guide/ansible-local-usage.md - 'Hardware': - operator-guide/device-types.md - operator-guide/flavors.md