kubernetes-security-baseline-lab/ansible/README.md

Ansible bootstrap paths

The repository has two separate Ansible paths:

• bootstrap-k3s.yml configures a production-style Flatcar K3s server.
• bootstrap-flatcar-k3d.yml configures the dedicated Flatcar k3d test host, bootstraps ArgoCD, and optionally installs Cilium.

The Flatcar k3d path is idempotent and keeps the standard profile as the default. Cilium is enabled only when the inventory explicitly sets cilium_enabled: true and selects a kube-proxy-free cluster configuration.

Flatcar does not include Python in the immutable host OS. The role therefore uses Ansible raw tasks for host operations and ansible.posix.synchronize for repository and kubeconfig transfer. Install the collection before use:

ansible-galaxy collection install -r ansible/requirements.yml

Flatcar k3d bootstrap

Copy the example inventory and replace the host, SSH key, and optional API endpoint values:

cp ansible/inventory.flatcar-k3d.example.yml ansible/inventory.flatcar-k3d.yml
ansible-playbook \
  -i ansible/inventory.flatcar-k3d.yml \
  ansible/bootstrap-flatcar-k3d.yml

The playbook installs pinned k3d, kubectl, and Helm binaries, starts Docker, creates the k3d cluster, writes the core user's kubeconfig, fetches a copy into the local artifacts/ directory, merges that config into the operator's default ~/.kube/config, selects the new context as current, installs ArgoCD from a pinned official manifest, and applies the GitOps root Application from deployments/argocd/. The merge preserves existing contexts and the playbook verifies the selected context before continuing.

Set kubeconfig_import_enabled: false when the fetched artifact should not change the operator's default kubeconfig.

By default the playbook copies the current repository from the Ansible controller to the host. For a private repository, set bootstrap_repo_url, bootstrap_repo_ref, and provide bootstrap_repo_ssh_private_key through Ansible Vault. The private key task is marked no_log and is removed after the checkout.

When k3d exports its kubeconfig, it may use 0.0.0.0 as the API server host. Ansible rewrites that host to kubeconfig_server_host, which defaults to the Flatcar host address, while preserving the dynamically assigned API port. The rewritten endpoint is verified before the config is merged into the default kubeconfig.

For the optional Cilium path, set these variables in the inventory:

cilium_enabled: true
k3d_config_source: "{{ playbook_dir }}/../local-quickstart/k3d-cilium-cluster-config.yaml"
cilium_k8s_service_host: 192.168.60.252
cilium_k8s_service_port: 0

The Cilium role refuses to proceed if a kube-proxy DaemonSet is present. It derives the dynamically published k3d API port from the new cluster's kubeconfig, passes the API endpoint explicitly to Helm, and waits for the Cilium DaemonSet.

The playbook does not create Slack or Discord credentials. Those will be added through a separate opt-in Ansible secret toggle so ordinary bootstrap remains credential-free.

If CoreDNS cannot resolve external names from a nested Docker network, set k3d_dns_servers to DNS servers reachable from the Flatcar host. Ansible creates the supported K3s coredns-custom ConfigMap and restarts CoreDNS so ArgoCD can resolve the Git server and Falcosidekick can resolve its webhook.

Validate the playbook before connecting to a host:

ANSIBLE_LOCAL_TEMP=/tmp/k8s-baseline-ansible-tmp \
  ansible-playbook --syntax-check \
  -i ansible/inventory.flatcar-k3d.example.yml \
  ansible/bootstrap-flatcar-k3d.yml

Production-style K3s bootstrap

The existing production-style path applies a host baseline and installs a pinned K3s server. It is intentionally separate from the local k3d path so the portfolio can run without cloud credentials.

cp inventory.example.yml inventory.yml
# Replace the Terraform public IP and local SSH key path.
ansible-playbook -i inventory.yml bootstrap-k3s.yml

Before production use, review the pinned K3s version and extend the playbook for your organization’s OS baseline, firewall model, HA topology, and secret management. RKE2 can replace K3s here if the target environment requires it.