112 lines
4.6 KiB
Markdown
112 lines
4.6 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```yaml
|
||
cilium_enabled: true
|
||
cilium_profile: k3d
|
||
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 selects the shared values from
|
||
`deployments/cilium/values/common.yaml` and the profile from
|
||
`deployments/cilium/values/profiles/{{ cilium_profile }}.yaml`. Supported
|
||
profiles are `k3d` and `flatcar-k3s`. It refuses to proceed if a kube-proxy
|
||
DaemonSet is present, 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.
|
||
|
||
Use `cilium_profile: flatcar-k3s` for a dedicated VM deployment. Review the
|
||
profile's routing assumptions and provide a stable control-plane API address.
|
||
The dedicated VM profile defaults to Geneve tunneling. Native routing should
|
||
only be selected when the VM network routes the pod CIDR between nodes.
|
||
|
||
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:
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
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.
|