From 2882abfc0b891100bda846ca386c25cd558d2e4a Mon Sep 17 00:00:00 2001 From: Tuan-Dat Tran Date: Sun, 27 Jul 2025 16:40:46 +0200 Subject: [PATCH] Added README.md for roles Signed-off-by: Tuan-Dat Tran --- roles/common/README.md | 49 ++++++++++++++++++ roles/docker_host/README.md | 85 +++++++++++++++++++++++++++++++ roles/k3s_agent/README.md | 39 ++++++++++++++ roles/k3s_loadbalancer/README.md | 50 ++++++++++++++++++ roles/k3s_server/README.md | 49 ++++++++++++++++++ roles/k3s_storage/README.md | 39 ++++++++++++++ roles/kubernetes_argocd/README.md | 44 ++++++++++++++++ roles/proxmox/README.md | 66 ++++++++++++++++++++++++ roles/reverse_proxy/README.md | 58 +++++++++++++++++++++ 9 files changed, 479 insertions(+) create mode 100644 roles/common/README.md create mode 100644 roles/docker_host/README.md create mode 100644 roles/k3s_agent/README.md create mode 100644 roles/k3s_loadbalancer/README.md create mode 100644 roles/k3s_server/README.md create mode 100644 roles/k3s_storage/README.md create mode 100644 roles/kubernetes_argocd/README.md create mode 100644 roles/proxmox/README.md create mode 100644 roles/reverse_proxy/README.md diff --git a/roles/common/README.md b/roles/common/README.md new file mode 100644 index 0000000..98be0e9 --- /dev/null +++ b/roles/common/README.md @@ -0,0 +1,49 @@ +# Ansible Role: common + +This role configures a baseline set of common configurations for Debian-based systems. + +## Requirements + +None. + +## Role Variables + +Available variables are listed below, along with default values (see `vars/main.yml`): + +```yaml +# The hostname to configure. +hostname: "new-host" + +# A list of extra packages to install. +extra_packages: + - "htop" + - "ncdu" + - "stow" + - "unzip" +``` + +## Dependencies + +None. + +## Example Playbook + +Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too: + +```yaml +- hosts: servers + roles: + - role: common + hostname: "my-new-host" + extra_packages: + - "vim" + - "curl" +``` + +## License + +MIT + +## Author Information + +This role was created in 2025 by [TuDatTr](https://codeberg.org/tudattr/). diff --git a/roles/docker_host/README.md b/roles/docker_host/README.md new file mode 100644 index 0000000..2b6967b --- /dev/null +++ b/roles/docker_host/README.md @@ -0,0 +1,85 @@ +# Ansible Role: Docker Host + +This role sets up a Docker host, installs Docker, and configures it according to the provided variables. It also handles user and group management, directory setup, and deployment of Docker Compose services. + +## Role Variables + +### General + +- `docker_host_package_common_dependencies`: A list of common packages to be installed on the host. + - Default: `nfs-common`, `firmware-misc-nonfree`, `linux-image-amd64` +- `apt_lock_files`: A list of apt lock files to check. +- `arch`: The architecture of the host. + - Default: `arm64` if `ansible_architecture` is `aarch64`, otherwise `amd64`. + +### Docker + +- `docker.url`: The URL for the Docker repository. + - Default: `https://download.docker.com/linux` +- `docker.apt_release_channel`: The Docker apt release channel. + - Default: `stable` +- `docker.directories.local`: The local directory for Docker data. + - Default: `/opt/local` +- `docker.directories.config`: The directory for Docker configurations. + - Default: `/opt/config` +- `docker.directories.compose`: The directory for Docker Compose files. + - Default: `/opt/compose` + +### Keycloak + +- `keycloak_config`: A dictionary containing the Keycloak configuration. See `templates/keycloak/realm.json.j2` for more details. + +### Services + +- `services`: A list of dictionaries, where each dictionary represents a Docker Compose service. See `templates/compose.yaml.j2` for more details. + +## Tasks + +The role performs the following tasks: + +1. **Setup VM**: + - Includes `non-free` and `non-free-firmware` components in the apt sources. + - Installs common packages. + - Removes cloud kernel packages. + - Reboots the host. +2. **Install Docker**: + - Uninstalls old Docker versions. + - Installs dependencies for using repositories over HTTPS. + - Adds the Docker apt key and repository. + - Installs Docker Engine, containerd, and Docker Compose. +3. **Setup user and group for Docker**: + - Ensures the `docker` group exists. + - Adds the `ansible_user_id` to the `docker` group. + - Reboots the host. +4. **Setup directory structure for Docker**: + - Creates necessary directories for Docker and media. + - Sets ownership of the directories. + - Mounts NFS shares. +5. **Deploy configs**: + - Sets up Keycloak realms if the host is a Keycloak host. +6. **Deploy Docker Compose**: + - Copies the Docker Compose file to the target host. +7. **Publish metrics**: + - Copies the `daemon.json` file to `/etc/docker/daemon.json` to enable metrics. + +## Handlers + +- `Restart docker`: Restarts the Docker service. +- `Restart compose`: Restarts the Docker Compose services. +- `Restart host`: Reboots the host. + +## Usage + +To use this role, include it in your playbook and set the required variables. + +```yaml +- hosts: docker_hosts + roles: + - role: docker_host + vars: + # Your variables here +``` + +## License + +This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details. diff --git a/roles/k3s_agent/README.md b/roles/k3s_agent/README.md new file mode 100644 index 0000000..ee4df69 --- /dev/null +++ b/roles/k3s_agent/README.md @@ -0,0 +1,39 @@ +# K3s Agent Ansible Role + +This Ansible role installs and configures a K3s agent on a node. + +## Role Variables + +- `k3s.loadbalancer.default_port`: The port for the K3s load balancer. Defaults to `6443`. +- `k3s_token`: The token for joining the K3s cluster. This is a required variable. +- `hostvars['k3s-loadbalancer'].ansible_default_ipv4.address`: The IP address of the K3s load balancer. This is a required variable. + +## Tasks + +The main tasks are in `tasks/main.yml` and `tasks/installation.yml`. + +- **`installation.yml`**: + - Installs `qemu-guest-agent`. + - Checks if K3s is already installed. + - Downloads the K3s installation script to `/tmp/k3s_install.sh`. + - Installs K3s as an agent, connecting to the master. + +## Handlers + +The main handlers are in `handlers/main.yml`. + +- **`Restart k3s`**: Restarts the `k3s` service. + +## Usage + +Here is an example of how to use this role in a playbook: + +```yaml +--- +- hosts: k3s_agents + roles: + - role: k3s_agent + vars: + k3s_token: "your_k3s_token" + k3s.loadbalancer.default_port: 6443 +``` diff --git a/roles/k3s_loadbalancer/README.md b/roles/k3s_loadbalancer/README.md new file mode 100644 index 0000000..7b676d6 --- /dev/null +++ b/roles/k3s_loadbalancer/README.md @@ -0,0 +1,50 @@ +# K3s Loadbalancer Ansible Role + +This Ansible role configures a load balancer for a K3s cluster using Nginx. + +## Role Variables + +- `k3s_loadbalancer_nginx_config_path`: The path to the Nginx configuration file. Defaults to `/etc/nginx/nginx.conf`. +- `domain`: The domain name to use for the load balancer. Defaults to `{{ internal_domain }}`. +- `k3s.loadbalancer.default_port`: The default port for the K3s API server. Defaults to `6443`. +- `k3s_server_ips`: A list of IP addresses for the K3s server nodes. This variable is not defined in the role, so you must provide it. +- `netcup_api_key`: Your Netcup API key. +- `netcup_api_password`: Your Netcup API password. +- `netcup_customer_id`: Your Netcup customer ID. + +## Tasks + +The role performs the following tasks: + +- **Installation:** + - Updates the `apt` cache. + - Installs `qemu-guest-agent`. + - Installs `nginx-full`. +- **Configuration:** + - Templates the Nginx configuration file with dynamic upstreams for the K3s servers. + - Enables and starts the Nginx service. +- **DNS Setup:** + - Sets up a DNS A record for the load balancer using the `community.general.netcup_dns` module. + +## Handlers + +- `Restart nginx`: Restarts the Nginx service when the configuration file is changed. + +## Example Usage + +Here is an example of how to use this role in a playbook: + +```yaml +- hosts: k3s_loadbalancer + roles: + - role: k3s_loadbalancer + vars: + k3s_server_ips: + - 192.168.1.10 + - 192.168.1.11 + - 192.168.1.12 + netcup_api_key: "your_api_key" + netcup_api_password: "your_api_password" + netcup_customer_id: "your_customer_id" + internal_domain: "example.com" +``` diff --git a/roles/k3s_server/README.md b/roles/k3s_server/README.md new file mode 100644 index 0000000..ff959af --- /dev/null +++ b/roles/k3s_server/README.md @@ -0,0 +1,49 @@ +# K3s Server Ansible Role + +This Ansible role installs and configures a K3s server cluster. + +## Role Variables + +- `k3s_primary_server_ip`: The IP address of the primary K3s server. +- `k3s_server_name`: The server name for the K3s cluster. +- `k3s_cluster_name`: The name for the K3s cluster in the kubeconfig. +- `k3s_user_name`: The user name for the K3s cluster in the kubeconfig. +- `k3s_context_name`: The context name for the K3s cluster in the kubeconfig. +- `k3s_server_token_vault_file`: The path to the Ansible Vault file containing the K3s token. Default is `../vars/group_vars/k3s/secrets_token.yml`. + +## Tasks + +The main tasks are: + +1. **Install dependencies**: Installs `qemu-guest-agent`. +2. **Primary Server Installation**: + - Downloads the K3s installation script. + - Installs the K3s server on the primary node with a TLS SAN. +3. **Pull Token**: + - Retrieves the K3s token from the primary server. + - Stores the token in an Ansible Vault encrypted file. +4. **Secondary Server Installation**: + - Installs K3s on the secondary servers, joining them to the cluster using the token from the vault. +5. **Create Kubeconfig**: + - Slurps the `k3s.yaml` from the primary server. + - Creates a kubeconfig file on the local machine for accessing the cluster. + +## Handlers + +- `Restart k3s`: Restarts the K3s service. + +## Usage + +Here is an example of how to use this role in a playbook: + +```yaml +- hosts: k3s_servers + roles: + - role: k3s_server + vars: + k3s_primary_server_ip: "192.168.1.100" + k3s_server_name: "k3s.example.com" + k3s_cluster_name: "my-k3s-cluster" + k3s_user_name: "my-k3s-user" + k3s_context_name: "my-k3s-context" +``` diff --git a/roles/k3s_storage/README.md b/roles/k3s_storage/README.md new file mode 100644 index 0000000..06d6ccf --- /dev/null +++ b/roles/k3s_storage/README.md @@ -0,0 +1,39 @@ +# k3s_storage Ansible Role + +This role installs and configures a k3s node with storage-specific taints and labels. + +## Role Variables + +- `k3s.loadbalancer.default_port`: The port of the k3s loadbalancer. Defaults to `6443`. +- `k3s_token`: The token to join the k3s cluster. This is a required variable. +- `hostvars['k3s-loadbalancer'].ansible_default_ipv4.address`: The IP address of the k3s loadbalancer. This is discovered automatically from the host with the name `k3s-loadbalancer`. + +## Tasks + +The main task includes the following files: + +- `requirements.yml`: + - Updates and upgrades system packages. + - Installs `open-iscsi` and `nfs-common`. + - Starts and enables the `open-iscsi` service. +- `installation.yml`: + - Downloads the k3s installation script. + - Installs k3s on the node with the following configurations: + - Taint: `storage=true:NoExecute` + - Label: `longhorn=true` + +## Handlers + +- `Restart k3s`: Restarts the k3s service. + +## Usage + +Here is an example of how to use this role in a playbook: + +```yaml +- hosts: k3s_storage_nodes + roles: + - role: k3s_storage + vars: + k3s_token: "your_k3s_token" +``` diff --git a/roles/kubernetes_argocd/README.md b/roles/kubernetes_argocd/README.md new file mode 100644 index 0000000..1dc124c --- /dev/null +++ b/roles/kubernetes_argocd/README.md @@ -0,0 +1,44 @@ +# Ansible Role: ArgoCD + +This role installs and configures ArgoCD in a Kubernetes cluster. + +## Role Variables + +Available variables are listed below, along with default values (see `defaults/main.yml`): + +| Variable | Default | Description | +|---|---|---| +| `argocd_version` | `stable` | The version of ArgoCD to install. | +| `argocd_namespace` | `argocd` | The namespace where ArgoCD will be installed. | +| `argocd_repo` | `https://raw.githubusercontent.com/argoproj/argo-cd/refs/tags/{{ argocd_version }}/manifests/ha/install.yaml` | The URL to the ArgoCD installation manifests. | +| `argocd_git_repository` | `https://github.com/argocd/argocd` | The Git repository URL for ArgoCD to use. | +| `argocd_git_username` | `user` | The username for the Git repository. | +| `argocd_git_pat` | `token` | The personal access token for the Git repository. | + +## Tasks + +The following tasks are performed by this role: + +- **Install ArgoCD**: Creates the ArgoCD namespace and applies the installation manifests. +- **Apply ArgoCD Ingress**: Applies an Ingress resource for the ArgoCD server. **Note:** The template file `ingress.yml.j2` is missing from the role. +- **Apply ArgoCD CM**: Applies a ConfigMap with command parameters for ArgoCD. +- **Apply ArgoCD repository**: Creates a Secret with Git repository credentials. +- **Apply ArgoCD Root Application**: Creates a root Application resource for ArgoCD. + +## Handlers + +There are no handlers in this role. + +## Usage + +Here is an example of how to use this role in a playbook: + +```yaml +- hosts: kubernetes + roles: + - role: kubernetes_argocd + vars: + argocd_git_repository: "https://github.com/my-org/my-repo.git" + argocd_git_username: "my-user" + argocd_git_pat: "my-token" +``` diff --git a/roles/proxmox/README.md b/roles/proxmox/README.md new file mode 100644 index 0000000..53d02de --- /dev/null +++ b/roles/proxmox/README.md @@ -0,0 +1,66 @@ +# Proxmox Ansible Role + +This role facilitates the management of Proxmox VE resources, including virtual machines (VMs) and LXC containers. It automates the setup of Proxmox nodes and the creation, configuration, and destruction of guests. + +## Requirements + +- `community.general.proxmox_vm_info` +- `community.general.proxmox_kvm` + +## Role Variables + +| Variable | Description | Default Value | +|---|---|---| +| `proxmox_author` | The author of the Proxmox resources. | `tuan-dat.tran@tudattr.dev` | +| `proxmox_creator` | The creator of the Proxmox resources. | `ansible` | +| `proxmox_storage` | The Proxmox storage to use. | `proxmox` | +| `proxmox_vault_file` | The path to the vault file for storing secrets. | `../vars/group_vars/proxmox/secrets_vm.yml` | +| `proxmox_secrets_prefix` | The prefix for secrets stored in the vault. | `secrets_vm` | +| `proxmox_cloud_init_images` | A dictionary of cloud-init images to download. | `{ 'debian': { 'name': 'debian-12-genericcloud-amd64.qcow2', 'url': '...' }, 'ubuntu': { 'name': 'noble-server-cloudimg-amd64.img', 'url': '...' } }` | +| `proxmox_dirs` | A dictionary of directories used by the role. | `{ 'isos': '/opt/proxmox/template/iso/' }` | +| `proxmox_tags` | A list of tags to apply to the Proxmox resources. | `['{{ proxmox_creator }}']` | +| `proxmox_node_dependencies` | A list of dependencies to install on the Proxmox node. | `['nmap']` | +| `proxmox_localhost_dependencies` | A list of dependencies to install on the localhost. | `[]` | +| `vms` | A list of VMs to create. | `[{ 'name': 'test-vm', 'vmid': 1000, ... }]` | +| `lxcs` | A list of LXC containers to create. | `[{ 'name': 'test-lxc', 'vmid': 2000, ... }]` | + +## Handlers + +- `Reboot Node`: Reboots the Proxmox node. This is triggered when the GRUB configuration or VFIO modules are changed. + +## Tasks + +The role includes the following main tasks: + +- `00_setup_machines.yml`: Prepares the localhost and Proxmox nodes by installing dependencies and configuring hardware acceleration. +- `10_create_secrets.yml`: Creates a vault file and generates secrets for the VMs. +- `40_prepare_vm_creation.yml`: Downloads cloud-init images required for VM creation. +- `50_create_vms.yml`: Creates VMs based on the `vms` variable. +- `60_create_containers.yml`: Creates LXC containers based on the `lxcs` variable. + +## Usage + +Here is an example of how to use this role in a playbook: + +```yaml +- hosts: proxmox + roles: + - role: proxmox + vars: + proxmox_api_user: "root@pam" + proxmox_api_token_id: "your-token-id" + proxmox_api_token_secret: "your-token-secret" + proxmox_api_host: "your-proxmox-host" + vms: + - name: my-vm + vmid: 1001 + node: proxmox + cores: 4 + memory: 8192 + disk_size: 50 + boot_image: debian-12-genericcloud-amd64.img + ciuser: myuser + sshkeys: "your-ssh-key" + net: + net0: "virtio=BC:24:11:7E:2B:A1,bridge=vmbr0" +``` diff --git a/roles/reverse_proxy/README.md b/roles/reverse_proxy/README.md new file mode 100644 index 0000000..9bbe2b8 --- /dev/null +++ b/roles/reverse_proxy/README.md @@ -0,0 +1,58 @@ +# Ansible Role: Reverse Proxy + +This role installs and configures Caddy as a reverse proxy. + +## Role Variables + +### `defaults/main.yml` + +- `caddy_binary_url`: The URL to download the Caddy binary. +- `caddy_binary_path`: The path to install the Caddy binary. +- `caddy_user`: The user to run Caddy as. +- `caddy_group`: The group to run Caddy as. +- `caddy_config_path`: The path to the Caddy configuration file. +- `caddy_log_path`: The path to the Caddy log file. +- `caddy_systemd_service_path`: The path to the Caddy systemd service file. +- `caddy_systemd_service_name`: The name of the Caddy systemd service. +- `caddy_version`: The version of Caddy to install. +- `xcaddy_version`: The version of xcaddy to install. +- `go_version`: The version of Go to install. +- `go_download_url`: The URL to download Go from. +- `go_install_dir`: The directory to install Go to. +- `caddy_custom_plugins`: A list of custom plugins to install with Caddy. +- `netcup_customer_id`: Your Netcup customer ID. +- `netcup_api_key`: Your Netcup API key. +- `netcup_api_password`: Your Netcup API password. + +### `vars/main.yml` + +- `caddy_email`: The email address to use for Let's Encrypt. +- `caddy_domains`: A list of domains to configure for the reverse proxy. + +## Handlers + +- `restart caddy`: Restarts the Caddy service. + +## Tasks + +### `main.yml` + +- `00_go_install.yml`: Installs Go. +- `10_caddy_install.yml`: Installs Caddy. +- `20_xcaddy_install.yml`: Installs xcaddy. +- `30_custom_caddy.yml`: Builds a custom Caddy binary with plugins. +- `50_netcup_dns.yml`: Configures Netcup DNS for Caddy. +- `80_configure.yml`: Configures Caddy. + +## Usage + +```yaml +- hosts: servers + roles: + - role: reverse_proxy + vars: + caddy_email: "user@example.com" + caddy_domains: + - domain: "example.com" + proxy: "http://localhost:8080" +```