ansible runner image build
Some checks failed
🐳 Build Ansible Act Runner Image / build (push) Failing after 55s
Some checks failed
🐳 Build Ansible Act Runner Image / build (push) Failing after 55s
This commit is contained in:
master of disaster
173
README.md
Normal file
173
README.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# ansible-runner
|
||||
|
||||
Centralized Ansible runner repository for the homelab. Contains the inventory,
|
||||
vault configuration, SSH credentials, and two reusable Gitea Actions workflows:
|
||||
one that builds the custom runner image, and one that executes Ansible playbooks
|
||||
from any role repository.
|
||||
|
||||
---
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
ansible-runner/
|
||||
├── docker/
|
||||
│ └── Dockerfile # Custom ansible-act-runner image
|
||||
├── inventory/
|
||||
│ └── raspberries.yaml # Ansible inventory
|
||||
├── .gitea/
|
||||
│ └── workflows/
|
||||
│ ├── build-image.yaml # Builds and pushes the runner image
|
||||
│ └── ansible-runner.yaml # Reusable workflow for all role repos
|
||||
└── example-caller-workflow.yaml # Example: how to call from another repo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflows
|
||||
|
||||
### `build-image.yaml` — Build the Ansible Act Runner Image
|
||||
|
||||
Triggers automatically when `docker/Dockerfile` changes on `main`, or manually
|
||||
via `workflow_dispatch` with an optional force-rebuild flag.
|
||||
|
||||
Runs on the `docker` label (directly on the runner host) to access the DinD
|
||||
sidecar that is configured in the OKD runner pod. Builds and pushes two tags:
|
||||
|
||||
- `gitea.mod.home/ansible/ansible-act-runner:latest`
|
||||
- `gitea.mod.home/ansible/ansible-act-runner:<short-sha>`
|
||||
|
||||
### `ansible-runner.yaml` — Reusable Ansible Playbook Runner
|
||||
|
||||
A `workflow_call` workflow that can be called from any role repository.
|
||||
Runs on the `ansible` label using the custom image, which has Node.js, Python,
|
||||
Ansible, and all required collections pre-installed.
|
||||
|
||||
**Inputs:**
|
||||
|
||||
| Input | Required | Default | Description |
|
||||
|-------|----------|---------|-------------|
|
||||
| `role_repo` | ✅ | — | Gitea repo of the role, e.g. `ansible/role-samba` |
|
||||
| `playbook_path` | ✅ | — | Path to playbook inside the role repo |
|
||||
| `inventory` | ❌ | `inventory/raspberries.yaml` | Inventory file relative to this repo |
|
||||
| `ansible_extra_args` | ❌ | `''` | Additional Ansible CLI arguments |
|
||||
|
||||
**Secrets passed through:**
|
||||
|
||||
| Secret | Description |
|
||||
|--------|-------------|
|
||||
| `TOKEN` | Gitea access token for checking out private repos |
|
||||
|
||||
---
|
||||
|
||||
## Calling from a Role Repository
|
||||
|
||||
Place a workflow file in `.gitea/workflows/` of your role repository:
|
||||
|
||||
```yaml
|
||||
name: 🚀 Deploy
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
uses: ansible/ansible-runner/.gitea/workflows/ansible-runner.yaml@main
|
||||
with:
|
||||
role_repo: ansible/role-samba
|
||||
playbook_path: playbooks/deploy.yml
|
||||
ansible_extra_args: '--tags install' # optional
|
||||
secrets:
|
||||
TOKEN: ${{ secrets.TOKEN }}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Required Secrets
|
||||
|
||||
All secrets are configured at the **Organization level** in Gitea
|
||||
(`ansible` org → Settings → Secrets) so they are available to all role
|
||||
repositories without duplication.
|
||||
|
||||
| Secret | Used in | Description |
|
||||
|--------|---------|-------------|
|
||||
| `SSHKEY_B64` | `ansible-runner.yaml` | Base64-encoded ED25519 private key for SSH access to managed hosts |
|
||||
| `ANSIBLE_VAULT_KEY` | `ansible-runner.yaml` | Ansible Vault password |
|
||||
| `TOKEN` | `ansible-runner.yaml` | Gitea access token (`repo` scope) for checking out role repos |
|
||||
| `REGISTRY_USER` | `build-image.yaml` | Gitea username for container registry login |
|
||||
| `REGISTRY_PASSWORD` | `build-image.yaml` | Gitea access token with `package:write` scope |
|
||||
| `TELEGRAM_BOT_TOKEN` | both | Telegram bot token for notifications |
|
||||
| `TELEGRAM_CHAT_ID` | both | Telegram chat ID for notifications |
|
||||
|
||||
### Creating the Gitea Access Token
|
||||
|
||||
In Gitea → User Settings → Applications → Generate Token:
|
||||
- For `TOKEN`: scopes `repo` (read/write)
|
||||
- For `GITEA_REGISTRY_PASSWORD`: scope `package` (read/write)
|
||||
|
||||
---
|
||||
|
||||
## OKD Runner Configuration
|
||||
|
||||
The act runner pod in the OKD cluster (`gitea-act-runner` namespace) runs with
|
||||
a DinD sidecar. The `build-image.yaml` workflow uses `runs-on: docker` to
|
||||
execute directly on the runner host where `DOCKER_HOST=tcp://localhost:2376`
|
||||
is available via the sidecar.
|
||||
|
||||
The `ansible-runner.yaml` workflow uses `runs-on: ansible` and spawns a
|
||||
container from the custom image. Node.js, Python, Ansible, and all collections
|
||||
are pre-installed — no runtime installation required.
|
||||
|
||||
### Runner Labels (configured in OKD ConfigMap)
|
||||
|
||||
The runner ConfigMap (`gitea-act-runner-config`) must have the following labels
|
||||
registered. Without the `docker` label, `build-image.yaml` will not be picked
|
||||
up by the runner.
|
||||
|
||||
```yaml
|
||||
# configmap.yaml — labels section
|
||||
runner:
|
||||
labels:
|
||||
- "docker:host" # required for build-image.yaml (runs-on: docker)
|
||||
- "ansible:host" # required for ansible-runner.yaml (runs-on: ansible)
|
||||
- "ubuntu-latest:docker://..."
|
||||
```
|
||||
|
||||
| Label | `runs-on` value | Purpose |
|
||||
|-------|----------------|---------|
|
||||
| `docker:host` | `docker` | Direct host execution with DinD sidecar — used for Docker builds |
|
||||
| `ansible:host` | `ansible` | Direct host execution — Ansible jobs via container image |
|
||||
| `ubuntu-latest` | `ubuntu-latest` | Container execution via DinD |
|
||||
|
||||
> **Note:** After changing the ConfigMap labels, the runner pod must re-register.
|
||||
> Delete the pod to force a restart: `kubectl delete pod -n gitea-act-runner -l app=gitea-act-runner`
|
||||
|
||||
---
|
||||
|
||||
## Bootstrap: First Image Build
|
||||
|
||||
No manual build from a laptop is required. The existing `gitea/act_runner:latest`
|
||||
pod already has a DinD sidecar and the `docker:host` label registered, so it can
|
||||
build and push the custom image itself.
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Create the repository in Gitea and push all files
|
||||
2. Set the required secrets in the `ansible` org (see above)
|
||||
3. Trigger the build manually via `workflow_dispatch` in Gitea Actions UI
|
||||
|
||||
The runner will build the image and push it to `gitea.mod.home/ansible/ansible-act-runner:latest`.
|
||||
All subsequent builds are triggered automatically when `docker/Dockerfile` changes on `main`.
|
||||
|
||||
---
|
||||
|
||||
## Roadmap
|
||||
|
||||
- [ ] TLS for Gitea registry via cert-manager (remove insecure flag)
|
||||
- [ ] Samba AD DC deployment playbook
|
||||
- [ ] Bind9 DNS backend playbook
|
||||
- [ ] Windows domain join playbook
|
||||
- [ ] Fluentbit → VictoriaLogs for Samba log shipping
|
||||
Reference in New Issue
Block a user