platform-config

Public Ansible configuration for platform hosts, services, and safe example inventories.

platform-config configures already-provisioned hosts with Ansible. It contains public playbooks, roles, examples, helper scripts, and documentation for production-oriented operating system and service configuration.

The repository is one part of a split platform project. Template building, infrastructure provisioning, system configuration, Kubernetes bastion tooling, documentation, and shared helper tools live in separate repositories so each layer can evolve independently. Site-specific and personal configuration stays outside this public repository.

Scope

This repository owns public Ansible code: playbooks, roles, examples, helper scripts, and documentation.

It configures already-provisioned hosts. It does not create VMs, build Proxmox templates, manage OpenTofu state, or store secrets.

Only safe examples belong here. Real inventories, host variables, access policies, CA certificates, and non-secret environment-specific configuration belong in ../platform-private/config/; real kubeconfigs, tokens, passwords, private keys, and other secrets belong outside Git.

Working plans, test plans, incident notes, and environment-specific operational notes belong in ../platform-plans/config/plans/, not in this public repo.

Requirements

• Podman for the development/tooling container.
• Git and Make for local setup and helper targets.
• Ansible and lint tooling installed inside Containerfile.dev from requirements-dev.txt and requirements.yml.
• The vendor/platform-k8s-bastion submodule for default bastion runtime input.
• SSH access, host keys, private inventory, and secret files for real runs.

Quick Start

Clone submodules and build the local development container:

git submodule update --init --recursive
make deps
make help

Open an interactive toolbox shell when you need to run Ansible or lint tooling without installing those dependencies on the host:

make shell

For real runs, source the matching private environment file and run a helper script. homelab is one example environment name; use the environment name from your private configuration layout.

source ../platform-private/config/homelab.ansible.env
./scripts/run-homelab.sh

The helper scripts also accept explicit inventory overrides when needed.

For the full environment bring-up order, SSH key handoff, secrets layout, and service smoke commands, see Operator runbook.

Common Commands

make help
make syntax ENV=dev
make check ENV=dev
make lint
make yamllint
make verify
make smoke-k8s-bastion ENV=dev

Most Make targets accept ENV, PLAYBOOK, LIMIT, and EXTRA_ARGS. Real runs require the matching private environment file and inventory.

Platform Project

Typical workflow:

platform-template-builder
 -> platform-infra
 -> platform-config
 -> platform-k8s-bastion
platform-tools provides optional shared helper commands.
platform-docs documents the design and operations across all repositories.

Documentation

• Private workflow
• Operator runbook
• Kubernetes bastion
• Kubernetes bastion smoke test
• Registry
• Migrations
• Maintenance playbooks
• Rebuild
• Inventories
• Roles
• Development
• Platform workflow

License

This project is licensed under the MIT License. See LICENSE for details.