Skip to content

Commit cf251c8

Browse files
cardoecardoe
authored
Merge pull request #1397 from rackerlabs/run-ansible-local
docs: usage of ansible container in local
2 parents 53c3911 + c620226 commit cf251c8

File tree

3 files changed

+177
-0
lines changed

3 files changed

+177
-0
lines changed

‎docs/component-ansible.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,5 +28,19 @@ docker run --rm -it ghcr.io/rackerlabs/understack/ansible:latest -- \
2828
ansible-runner run /runner --playbook debug.yaml
2929
```
3030

31+
## Local Development
32+
33+
For local development and testing, see the [Ansible Container Local Usage Guide][local-usage-guide] for detailed instructions on:
34+
35+
- Running playbooks locally with Docker
36+
- Volume mount configurations
37+
- Environment-specific inventory setup
38+
- Debugging and troubleshooting
39+
40+
## Operational Playbooks (undercloud-rackspace Repository)
41+
42+
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).
43+
3144
[ansible-src]: <https://github.com/rackerlabs/understack/tree/main/ansible>
3245
[ansible-runner]: <https://ansible.readthedocs.io/projects/runner/en/stable/intro/>
46+
[local-usage-guide]: <operator-guide/ansible-local-usage.md>

‎docs/operator-guide/ansible-local-usage.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Running Ansible Playbooks Locally with Docker
2+
3+
This guide explains how to run Understack Ansible playbooks locally
4+
using the containerized Ansible environment.
5+
6+
## TL;DR
7+
8+
Quick start with local playbook development:
9+
10+
```bash
11+
docker run --rm -it \
12+
-v $(pwd)/ansible:/runner/project \
13+
-v $(pwd)/ansible/roles:/runner/project/roles \
14+
-v $(pwd)/ansible/vars:/runner/project/vars \
15+
-v /path/to/environment-specific/inventory:/runner/inventory \
16+
-e NAUTOBOT_URL=https://nautobot.example.com \
17+
-e NAUTOBOT_TOKEN=your_token_here \
18+
-e env=dev
19+
-e EXTRA_VARS='{"password":"secret","token":"abc123","username":"user"}'
20+
-w /runner \
21+
ghcr.io/rackerlabs/understack/ansible:latest \
22+
ansible-runner run /runner --playbook your-playbook.yaml
23+
```
24+
25+
**Note:** Replace `/path/to/environment-name/inventory` with your actual environment inventory path, for example:
26+
27+
- Dev: `/path/to/undercloud-deploy/{environment-name}/inventory`
28+
29+
For OpenStack playbooks, add these environment variables:
30+
31+
```bash
32+
-e OS_USERNAME=admin \
33+
-e OS_PASSWORD=your_password \
34+
-e OS_PROJECT_NAME=admin \
35+
-e OS_AUTH_URL=https://keystone.example.com/v3 \
36+
-e OS_USER_DOMAIN_NAME=Default \
37+
-e OS_PROJECT_DOMAIN_NAME=Default \
38+
-e OS_DEFAULT_DOMAIN=default \
39+
```
40+
41+
## Container Overview
42+
43+
The Ansible container (`ghcr.io/rackerlabs/understack/ansible`) is built from `containers/ansible/Dockerfile`
44+
45+
The container uses `ansible-runner` as its default command and expects playbooks to be located in `/runner/project/`.
46+
47+
## Interactive Shell for Debugging
48+
49+
Drop into a bash shell to explore or debug:
50+
51+
```bash
52+
docker run --rm -it \
53+
-v $(pwd)/ansible:/runner/project \
54+
-v $(pwd)/ansible/roles:/runner/project/roles \
55+
-v $(pwd)/ansible/vars:/runner/project/vars \
56+
-v /path/to/undercloud-deploy/bravo-uc-iad3-dev/inventory:/runner/inventory \
57+
-e NAUTOBOT_URL=https://nautobot.example.com \
58+
-e NAUTOBOT_TOKEN=your_token \
59+
-w /runner \
60+
ghcr.io/rackerlabs/understack/ansible:latest \
61+
bash
62+
```
63+
64+
Once inside, you can run playbooks manually:
65+
66+
```bash
67+
ansible-runner run /runner --playbook your-playbook.yaml
68+
```
69+
70+
## Volume Mounts Explained
71+
72+
| Host Path | Container Path | Purpose |
73+
|-----------|---------------|---------|
74+
| `$(pwd)/ansible` | `/runner/project` | Main playbook directory |
75+
| `$(pwd)/ansible/roles` | `/runner/project/roles` | Ansible roles |
76+
| `$(pwd)/ansible/vars` | `/runner/project/vars` | Variable files |
77+
| `/path/to/environment/inventory` | `/runner/inventory` | Environment-specific inventory files |
78+
79+
**Important:** The inventory directory is environment-specific and should be mounted from your deployment directory structure.
80+
The inventory is assembled from multiple files:
81+
82+
- Environment inventory: `undercloud-deploy/ansible/inventory/{environment}.yaml`
83+
- Hosts file: `undercloud-deploy/{environment}/inventory/hosts.yaml`
84+
- Group vars: `undercloud-deploy/{environment}/inventory/group_vars/*.yaml`
85+
86+
**For local development convenience**, you can copy all inventory files into a single directory and mount that:
87+
88+
```bash
89+
# Create a local inventory directory
90+
mkdir -p /tmp/my-inventory
91+
92+
# Copy all inventory files
93+
cp /path/to/undercloud-deploy/ansible/inventory/uc-iad3-dev.yaml /tmp/my-inventory/
94+
cp /path/to/undercloud-deploy/bravo-uc-iad3-dev/inventory/hosts.yaml /tmp/my-inventory/
95+
cp -r /path/to/undercloud-deploy/bravo-uc-iad3-dev/inventory/group_vars /tmp/my-inventory/
96+
97+
# Mount the consolidated directory
98+
-v /tmp/my-inventory:/runner/inventory
99+
```
100+
101+
Example environment paths:
102+
103+
- Dev: `/path/to/undercloud-deploy/bravo-uc-iad3-dev/inventory`
104+
- Staging: `/path/to/undercloud-deploy/charlie-uc-iad3-staging/inventory`
105+
106+
## Using Different Container Tags
107+
108+
### Latest Release
109+
110+
```bash
111+
ghcr.io/rackerlabs/understack/ansible:latest
112+
```
113+
114+
### Specific PR (for testing)
115+
116+
```bash
117+
ghcr.io/rackerlabs/understack/ansible:pr-862
118+
```
119+
120+
## Troubleshooting
121+
122+
### Check Container Contents
123+
124+
```bash
125+
docker run --rm -it ghcr.io/rackerlabs/understack/ansible:latest bash
126+
ls -la /runner/project/
127+
```
128+
129+
### View Ansible Version
130+
131+
```bash
132+
docker run --rm -it ghcr.io/rackerlabs/understack/ansible:latest \
133+
ansible --version
134+
```
135+
136+
### Test OpenStack Connectivity
137+
138+
```bash
139+
docker run --rm -it \
140+
-e OS_USERNAME=admin \
141+
-e OS_PASSWORD=your_password \
142+
-e OS_PROJECT_NAME=admin \
143+
-e OS_AUTH_URL=https://keystone.example.com/v3 \
144+
-e OS_USER_DOMAIN_NAME=Default \
145+
-e OS_PROJECT_DOMAIN_NAME=Default \
146+
ghcr.io/rackerlabs/understack/ansible:latest \
147+
bash -c "openstack --version && openstack token issue"
148+
```
149+
150+
## Building the Container Locally
151+
152+
To build the container from source:
153+
154+
```bash
155+
docker build -f containers/ansible/Dockerfile -t understack-ansible:local .
156+
```
157+
158+
Then use your local image:
159+
160+
```bash
161+
docker run --rm -it understack-ansible:local ansible-runner run /runner --playbook your-playbook.yaml
162+
```

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,7 @@ nav:
174174
- operator-guide/nautobot.md
175175
- operator-guide/troubleshooting-osh.md
176176
- operator-guide/logging.md
177+
- operator-guide/ansible-local-usage.md
177178
- 'Hardware':
178179
- operator-guide/device-types.md
179180
- operator-guide/flavors.md

0 commit comments

Comments
 (0)