{"id":20900374,"url":"https://github.com/lkummer/homelab-tutorial-infrastructure","last_synced_at":"2026-03-19T18:01:59.372Z","repository":{"id":209759361,"uuid":"622966101","full_name":"LKummer/homelab-tutorial-infrastructure","owner":"LKummer","description":null,"archived":false,"fork":false,"pushed_at":"2024-01-27T20:55:00.000Z","size":30,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-19T13:15:20.440Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LKummer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-03T12:30:38.000Z","updated_at":"2023-07-18T02:40:00.000Z","dependencies_parsed_at":"2024-11-19T04:18:23.037Z","dependency_job_id":null,"html_url":"https://github.com/LKummer/homelab-tutorial-infrastructure","commit_stats":null,"previous_names":["lkummer/homelab-tutorial-infrastructure"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LKummer%2Fhomelab-tutorial-infrastructure","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LKummer%2Fhomelab-tutorial-infrastructure/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LKummer%2Fhomelab-tutorial-infrastructure/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LKummer%2Fhomelab-tutorial-infrastructure/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LKummer","download_url":"https://codeload.github.com/LKummer/homelab-tutorial-infrastructure/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243285620,"owners_count":20266849,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-18T11:19:14.079Z","updated_at":"2025-12-25T15:43:31.013Z","avatar_url":"https://github.com/LKummer.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Homelab Tutorial Infrastructure\n\nThis repository contains example infrastructure code for my homelab infrastructure framework.\n[It is accompanied by a step-by-step tutorial.](https://lkummer.github.io/homelab-wiki/tutorial/part-1-preparation/)\n\nThis repository creates a Proxmox VM and sets up:\n\n* Single node Kubernetes cluster with K3s.\n* Cert Manager and ClusterIssuer for issuing certificates using ACME DNS01 challenge.\n* Observability stack with Grafana, OpenTelemetry Collector, Prometheus, Loki, Tempo and operators for managing them.\n* ArgoCD as CD solution.\n\n**Make this repository private when cloning.**\nTerraform plans and state may leak secrets.\n\nRelated guides:\n\n* [How to deploy this repository with GitLab CI](https://lkummer.github.io/homelab-wiki/how-to/gitlab-automation/)\n* [How to configure Proxmox credentials](https://lkummer.github.io/homelab-wiki/how-to/proxmox-api-tokens/)\n* [How to configure GitLab managed Terraform state](https://lkummer.github.io/homelab-wiki/how-to/gitlab-managed-state/)\n* [How to build the Proxmox template](https://lkummer.github.io/homelab-wiki/how-to/packer-template/)\n\n# Quickstart\n\nThis is a *very* short version of the tutorial, with many details missing.\n[Make sure to follow the tutorial if you need more than just the commands to bring it up.](https://lkummer.github.io/homelab-wiki/tutorial/part-1-preparation/)\n\nThis guide assumes you have the Packer template already built.\nIf not, [see this guide for instructions](https://lkummer.github.io/homelab-wiki/how-to/packer-template/).\n\n## Configuring credentials\n\nConfigure Proxmox credentials [(see guide for more information)](https://lkummer.github.io/homelab-wiki/how-to/proxmox-api-tokens/#managing-credentials-when-working).\n\nThere are 2 options for managing Terraform state:\n\n1. Use local Terraform state\n2. Use GitLab managed Terraform state\n\n### Using local Terraform state\n\nRun the following commands to modify the repository to use local Terraform state:\n\n```\nsed 's/terraform_http/terraform_local/' -i playbook/inventory/tutorial.yaml\necho tfstate_path: ../terraform/terraform.tfstate \u003e\u003e playbook/inventory/tutorial.yaml\nsed '/backend \"http\"/d' -i terraform/main.tf\n```\n\n### Using GitLab managed Terraform state\n\n[See how-to guide for preparing your environment.](https://lkummer.github.io/homelab-wiki/how-to/gitlab-managed-state/#preparing-local-environment)\n\n## Cloning a VM with Terraform\n\nHead into the `terraform` folder, and initialize Terraform:\n\n```\nterraform init\n```\n\nOnce Terraform is initialized, apply the module to clone a VM:\n\n```\nterraform apply\n```\n\nMake sure the plan looks about right, and type `yes` to confirm it.\n\n## Configuring the VM with Ansible\n\nHead into the `playbook` folder, and install the Galaxy dependencies:\n\n```\nansible-galaxy collection install --requirements requirements.yaml\n```\n\n**Make sure to install Galaxy dependencies whenever switching between projects.**\nGalaxy dependencies are managed globally and mixing collection versions between projects may be destructive.\n\nConfigure the VM by running the playbook:\n\n```\nansible-playbook --inventory=inventory main.yaml\n```\n\nYou should now have a Kubernetes cluster up and running, with an observability stack and CD solution.\n\n# Development Guide\n\n## Terraform initialization\n\nGo to `terraform` directory:\n\n```\ncd terraform\n```\n\nInitialize Terraform:\n\n```\nterraform init\n```\n\n## Terraform linting\n\nFormat and validate the Terraform module:\n(still in `terraform` directory)\n\n```\nterraform fmt\nterraform validate\n```\n\n## Provision with Terraform\n\nApply the Terraform module:\n(still in `terraform` directory)\n\n```\nterraform apply\n```\n\nReview and confirm the plan.\n\n## Installing Ansible dependencies\n\nGo to the playbook directory:\n\n```\ncd playbook\n```\n\nCreate a virtual environment:\n\n```\npython3 -m venv .venv\n```\n\nActivate the virtual environment:\n\n```\nsource .venv/bin/activate\n```\n\nInstall dependencies:\n\n```\npip install -r requirements.txt\nansible-galaxy install -r requirements.yml\n```\n\n## Playbook linting\n\nLint the Ansible playbook:\n(still in `playbook` directory)\n\n```\nansible-lint main.yaml\n```\n\n## Configure with Ansible\n\nRun the playbook:\n(still in `playbook` directory)\n\n```\nansible-playbook --inventory=inventory main.yaml\n```\n\n# CI Variables\n\nCI variables required for the pipeline:\n\n* `PM_API_TOKEN_ID` ID of the form `user@pve!token`\n* `PM_API_TOKEN_SECRET` secret of the ID stored in `PM_API_TOKEN_ID`\n* `SSH_PRIVATE_KEY_FILE` (file) (protected) private key in OpenSSH format, **make sure it ends with an empty line**\n* `SSH_PUBLIC_KEY` (protected) public key of the key stored in `SSH_PRIVATE_KEY_FILE`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flkummer%2Fhomelab-tutorial-infrastructure","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flkummer%2Fhomelab-tutorial-infrastructure","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flkummer%2Fhomelab-tutorial-infrastructure/lists"}