tudattr/ansible
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Added README.md for roles

Browse Source 
Signed-off-by: Tuan-Dat Tran <tuan-dat.tran@tudattr.dev>
This commit is contained in:
Tuan-Dat Tran
2025-07-27 16:40:46 +02:00
parent 2b759cc2ab
commit 2882abfc0b
9 changed files with 479 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
roles/common/README.md Normal file
View File

@@ -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/).

85
roles/docker_host/README.md Normal file
View File

@@ -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.

39
roles/k3s_agent/README.md Normal file
View File

@@ -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
```

50
roles/k3s_loadbalancer/README.md Normal file
View File

@@ -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"
```

49
roles/k3s_server/README.md Normal file
View File

@@ -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"
```

39
roles/k3s_storage/README.md Normal file
View File

@@ -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"
```

44
roles/kubernetes_argocd/README.md Normal file
View File

@@ -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"
```

66
roles/proxmox/README.md Normal file
View File

@@ -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"
```

58
roles/reverse_proxy/README.md Normal file
View File

@@ -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"
```