feat: add ansible execution environment for playbooks

This creates an ansible based container that has ansible-runner as the
executor inside which can then be loaded with playbooks and roles so
that we can have a consistent way to configure different parts of the
system or react to events in the system and execute a series of steps.
To provide a consistent way to configure the overall system and react to
events in the system. Some areas where this might be useful is for
OpenStack Helm has a bootstrap bash script that executes on deployment.
This is a big hardcoded blob and will be easier to be configurable via
ansible.

Author: cardoe

.ansible-lint

@@ -0,0 +1,4 @@
+---
+
+exclude_paths:
+  - ansible/.venv/

.github/workflows/containers.yaml

@@ -7,12 +7,14 @@ on:
     branches:
       - main
     paths:
+      - "ansible/**"
       - "containers/**"
       - ".github/workflows/containers.yaml"
       - "python/**"
   pull_request:
     types: [opened, synchronize, reopened, closed]
     paths:
+      - "ansible/**"
       - "containers/**"
       - ".github/workflows/containers.yaml"
       - "python/**"
@@ -123,6 +125,7 @@ jobs:
         container:
           - name: ironic-nautobot-client
           - name: nova-flavors
+          - name: ansible
 
     steps:
       - name: setup docker buildx
@@ -182,6 +185,7 @@ jobs:
           - dnsmasq
           - ironic-nautobot-client
           - nova-flavors
+          - ansible
 
     steps:
       - name: clean up PR container

.pre-commit-config.yaml

@@ -48,6 +48,15 @@ repos:
       - id: ruff
         args: [--fix]
       - id: ruff-format
+  - repo: https://github.com/ansible/ansible-lint
+    rev: v25.1.2
+    hooks:
+      - id: ansible-lint
+        entry: "sh -c 'cd ansible && python3 -m ansiblelint -v --force-color'"
+        additional_dependencies:
+          - ansible
+          - jmespath
+        files: '^ansible/.*$'
   - repo: https://github.com/python-poetry/poetry
     rev: '1.7.1'
     hooks:

ansible/playbooks/debug.yaml

@@ -0,0 +1,20 @@
+---
+# Copyright (c) 2025 Rackspace Technology, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+- name: Debug
+  hosts: localhost
+
+  roles:
+    - role: debug

ansible/requirements.txt

@@ -0,0 +1,5 @@
+ansible-core==2.18.4
+ansible-runner==2.4.0
+openstacksdk==4.3.0
+pynautobot==2.6.1
+jmespath==1.0.1

ansible/requirements.yml

@@ -0,0 +1,7 @@
+collections:
+  - name: community.general
+    version: "==10.5.0"
+  - name: openstack.cloud
+    version: "==2.4.1"
+  - name: networktocode.nautobot
+    version: "==5.6.0"

ansible/roles/debug/tasks/main.yml

@@ -0,0 +1,18 @@
+---
+# Copyright (c) 2025 Rackspace Technology, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+- name: Debug
+  ansible.builtin.debug:
+    msg: debug

containers/ansible/Dockerfile.ansible

@@ -0,0 +1,29 @@
+FROM python:3.12-slim
+
+ENV PIP_NO_CACHE_DIR=off \
+    PIP_DISABLE_PIP_VERSION_CHECK=on \
+    PIP_DEFAULT_TIMEOUT=100
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+      git \
+    && apt-get autoremove -y \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN --mount=type=cache,target=/root/.cache/pip pip install dumb-init==1.2.5
+
+COPY ansible/requirements.txt ansible/requirements.yml ./
+
+RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt
+RUN --mount=type=cache,target=/root/.cache/pip ansible-galaxy collection install -r requirements.yml
+
+RUN useradd -m -d /runner -s /bin/bash runner
+WORKDIR /runner
+USER runner
+
+COPY ansible/playbooks/ /runner/project/
+COPY ansible/roles/ /runner/project/roles/
+
+ENTRYPOINT ["dumb-init"]
+CMD ["ansible-runner"]

docs/component-ansible.md

@@ -0,0 +1,28 @@
+# Ansible
+
+Ansible is used to configure different parts of the overall system
+in a consistent manner. To this effect a container is produced with
+playbooks, roles and collections pre-installed and it can be run by
+providing system configuration to it.
+
+## Execution Environment
+
+Ansible is executed within a container which is build within this repo.
+The configuration and the source are contained within the
+[`ansible/`][ansible-src] directory.
+
+## Configuration
+
+The execution environment within the container is [ansible-runner][ansible-runner].
+An inventory directory is necessary to be provided which would be part
+of your system deployment data.
+
+## Sample Execution
+
+```bash
+docker run --rm -it ghcr.io/rackerlabs/understack/ansible:latest -- \
+  ansible-runner run /runner --playbook debug.yaml
+```
+
+[ansible-src]: <https://github.com/rackerlabs/understack/tree/main/ansible>
+[ansible-runner]: <https://ansible.readthedocs.io/projects/runner/en/stable/intro/>

mkdocs.yml

@@ -116,6 +116,7 @@ nav:
         - component-networking-neutron.md
       - component-argo-workflows.md
       - component-understack-workflows.md
+      - component-ansible.md
   - 'Deployment Guide':
     - deploy-guide/index.md
     - Quick Start: deploy-guide/gitops-install.md