https://github.com/lkummer/ansible-collection-homelab
https://github.com/lkummer/ansible-collection-homelab
Last synced: 9 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/lkummer/ansible-collection-homelab
- Owner: LKummer
- Created: 2022-06-13T14:28:28.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2023-12-16T22:35:55.000Z (over 2 years ago)
- Last Synced: 2025-10-10T09:46:38.296Z (9 months ago)
- Language: Python
- Size: 292 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Homelab Ansible Collection
Collection with roles and plugins for automating a virtualized homelab.
Roles:
- `lkummer.homelab.argo` configures ArgoCD.
- `lkummer.homelab.cert_manager` configures Cert Manager and a ClusterIssuer using Let's Encrypt and Cloudflare DNS.
- `lkummer.homelab.k3s` configures K3s.
- `lkummer.homelab.observability` configures Prometheus Operator, Grafana Agent, Grafana, Loki, Promtail, OpenTelemetry Operator, OpenTelemetry Collector and Tempo.
- `lkummer.homelab.helm` configures hosts for use with `kubernetes.core.helm` and `kubernetes.core.k8s` modules.
Inventory plugins:
- `lkummer.homelab.terraform_local` populates inventory from local Terraform state files.
- `lkummer.homelab.terraform_http` populates inventory from http Terraform state backend.
## Example
Included roles are designed to work together to configure a single host Kubernetes cluster with metric collection, log aggregation and continuous delivery.
```yaml
---
- name: Configure Kubernetes host
hosts: production
roles:
- role: lkummer.homelab.k3s
- role: lkummer.homelab.observability
vars:
observability_grafana_host: grafana.example.com
observability_grafana_user: admin
observability_grafana_password: admin
- role: lkummer.homelab.argo
vars:
argo_host: argo.example.com
argo_cert_manager_enabled: false
```
## Installation
Add the collection to the `requirements.yml` file at the root directory of your playbook.
```yaml
# Inside requirements.yml
---
collections:
- name: lkummer.homelab
type: git
source: https://github.com/LKummer/ansible-collection-homelab.git
version: 6.0.1
```
Install requirements from the file:
```
ansible-galaxy collection install --requirements requirements.yml
```
## Documentation
[Full documentation is available on the wiki](https://homelab.pages.houseofkummer.com/devops/wiki/).
The following instructions are for accessing less detailed documentation from the roles and plugins.
For role variable documentation, see:
```
ansible-doc --type role
```
For example:
```
ansible-doc --type role lkummer.homelab.k3s
```
For inventory plugin documentation, see:
```
ansible-doc --type inventory lkummer.homelab.terraform_local
```
## Development
Create a virtual environment:
```
python3 -m venv .venv
```
Activate the virtual environment:
```
source .venv/bin/activate
```
Install dependencies:
```
pip install -r requirements.txt
ansible-galaxy install -r requirements.yml
```
### Testing
`PM_API_TOKEN_ID` and `PM_API_TOKEN_SECRET` must be set.
Make sure the token id is of the form `user@pve!token` and contains your username, realm and token name.
Make sure the token has enough privileges for cloning VMs.
[For more information see this guide.](https://homelab.pages.houseofkummer.com/devops/wiki/how-to/proxmox-api-tokens/)
Set `ANSIBLE_HOST_KEY_CHECKING=0` to prevent Ansible from bugging you about SSH host key verification.
Each user facing role (`k3s`, `observability`, `argo`, `cert_manager`) has a Molecule test.
To run a test, first go to the directory of the role you want to test:
```
cd roles/observability
```
Then run Molecule with the following command:
```
molecule test
```
It is useful to run Molecule stages during role development, using the test as a machine and playbook for development.
To provision a machine for testing, run:
```
molecule create
```
To run the playbook of the role, run:
```
molecule converge
```
To run the test verification playbook, run:
```
molecule verify
```
To destroy infrastructure provisioned for the test, run:
```
molecule destroy
```
### Linting
Make sure to lint with both yamllint and ansible-lint before pushing.
To lint with `ansible-lint`, run:
```
ansible-lint --rules-dir rules
```