ansible

Multiple Ansible images with different kind of tools ready for K8s interactions.

Pulling the images

docker pull ghcr.io/specsnl/ansible:latest
docker pull ghcr.io/specsnl/ansible/k8s:latest

Tools

• ansible: Ansible with ansible-lint, yamllint and molecule, plus sops, docker (CLI), git, jq, ssh, rsync, sshpass, pass and uv.
• ansible/k8s: everything above, plus kubectl, kubectx, kubens and helm.

Task commands

Available Task commands:

* build:                        Build both ansible and k8s images
* lint:                         Apply a Dockerfile linter (https://github.com/hadolint/hadolint)
* shell:                        Interactive shell with Ansible
* build:ansible:                Build the ansible image
* build:k8s:                    Build the k8s image
* deps:audit:                   Audit the locked dependencies for known vulnerabilities (OSV)
* deps:update:                  Update uv.lock (update all dependencies to their latest allowed versions)
* deps:upgrade:                 Update pyproject.toml (upgrade dependencies past their bounds and rewrite them)
* scripts:check-versions:       Check kubctl and kubectx versions

Dependencies

Python dependencies are managed with uv: pyproject.toml holds the constraints and uv.lock pins the resolved versions. SemVer packages are capped at their current major, while CalVer tooling (ansible-lint, yamllint) only gets a lower bound.

• task deps:update — refresh uv.lock to the newest versions within the current constraints.
• task deps:upgrade — rewrite the constraints in pyproject.toml to move past their current bounds (uv.lock is updated along with them).
• task deps:audit — check the locked versions against the OSV database for known vulnerabilities.

Some dependencies only exist for a collection the image doesn't bundle (e.g. upcloud-api for upcloud.cloud). Install such collections via the project's own requirements.yml.

Misc

Workdir: /workspace

Environment variables:

SSH_PRIVATE_KEY: If this env variable is set, the key is loaded into an ssh-agent and the variable is unset before the command runs, so the key never touches the disk.

Example:

SSH_PRIVATE_KEY="op://Vault/Item/private key?ssh-format=openssh" \
op run -- docker run --rm --tty --env SSH_PRIVATE_KEY ghcr.io/specsnl/ansible:latest ssh-add -l

KUBECONFIG_OVERRIDE (k8s image only): If this env variable is set, it will put the contents of the variable in a (new) file at $HOME/.kube/config-override. The path of the new file is then set as the value of KUBECONFIG-env.

Example:

docker run --rm --tty --env KUBECONFIG_OVERRIDE="`kind get kubeconfig --internal`" \
ghcr.io/specsnl/ansible/k8s:latest kubectl get nodes

Quote:

kind is a tool for running local Kubernetes clusters using Docker container "nodes".

For more info see: https://github.com/kubernetes-sigs/kind

SOPS_AGE_KEY: The age key sops uses to decrypt, e.g. for group_vars/*.sops.yml files loaded by the bundled community.sops collection (enable its vars plugin via vars_plugins_enabled in ansible.cfg).

Example:

SOPS_AGE_KEY="op://Vault/Item/age key" \
op run -- docker run --rm --tty --env SOPS_AGE_KEY --volume $(pwd):/workspace ghcr.io/specsnl/ansible:latest \
ansible-playbook playbook.yml

Entrypoint hooks: docker-entrypoint.sh sources every /etc/docker-entrypoint.d/*.sh before running the command, so variables they export reach it. Derived images can add their own hooks there (the k8s image uses this for KUBECONFIG_OVERRIDE).