Skip to content

Commit 9cfc10a

Browse files
Copilotvitabaks
Copilot
and
vitabaks
authored
Describe the README for each ansible role (#1217)
The current goal is to document the purpose of each role and list all available variables. In future iterations, we plan to improve and expand the documentation for each role in more detail. Co-authored-by: Vitaliy Kukharik <[email protected]>
1 parent bd402e3 commit 9cfc10a

File tree

45 files changed

+1486
-286
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+1486
-286
lines changed

‎automation/roles/add_repository/README.md‎

Lines changed: 4 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Ansible Role: add_repository
22

3-
This role manages repository configuration for PostgreSQL and other packages on both Debian/Ubuntu and RedHat/CentOS systems. It handles the installation and configuration of various repositories including PostgreSQL PGDG repository, EPEL repository, and extension repositories like TimescaleDB and Citus.
3+
This role manages repository configuration for PostgreSQL and other packages. It handles the installation and configuration of various repositories including PostgreSQL PGDG repository, EPEL repository, and extension repositories like TimescaleDB and Citus.
44

55
## Description
66

@@ -37,13 +37,12 @@ The `add_repository` role is responsible for:
3737

3838
| Variable | Default | Description |
3939
|----------|---------|-------------|
40-
| `enable_timescale` | `false` | Enable TimescaleDB repository |
41-
| `enable_timescaledb` | `false` | Enable TimescaleDB repository (alternative name) |
40+
| `enable_timescale` / `enable_timescaledb` | `false` | Enable TimescaleDB repository |
4241
| `enable_citus` | `false` | Enable Citus repository |
4342

4443
## Repository Definitions
4544

46-
### APT Repository Format (Debian/Ubuntu)
45+
### APT Repository Format
4746

4847
```yaml
4948
apt_repository:
@@ -56,7 +55,7 @@ apt_repository:
5655
enabled: true # Whether repository is enabled (default: true)
5756
```
5857
59-
### YUM Repository Format (RedHat/CentOS)
58+
### YUM Repository Format
6059
6160
```yaml
6261
yum_repository:
@@ -68,86 +67,7 @@ yum_repository:
6867
enabled: true # Optional (default: true)
6968
```
7069
71-
## Usage Examples
72-
73-
### Basic PostgreSQL Repository Setup
74-
75-
```yaml
76-
install_postgresql_repo: true
77-
install_postgresql_repo_extras: true # Enables pgdg-rhel<version>-extras for HAProxy, etc.
78-
install_epel_repo: true
79-
```
80-
81-
### Custom Repository Configuration
82-
83-
```yaml
84-
# For Debian/Ubuntu
85-
apt_repository:
86-
- name: "custom-repo"
87-
uris: "https://apt.example.com"
88-
signed_by: "https://apt.example.com/gpg"
89-
suites: "{{ ansible_distribution_release }}"
90-
components: ["main"]
91-
92-
# For RedHat/CentOS
93-
yum_repository:
94-
- name: "custom-repo"
95-
description: "Custom Repository"
96-
baseurl: "https://yum.example.com/repo"
97-
gpgkey: "https://yum.example.com/gpg"
98-
```
99-
100-
### Extension Repositories
101-
102-
```yaml
103-
# Enable TimescaleDB repository
104-
enable_timescale: true
105-
106-
# Enable Citus repository (PostgreSQL 11+ only)
107-
enable_citus: true
108-
postgresql_version: 15
109-
```
110-
11170
## Dependencies
11271
11372
This role depends on:
11473
- `vitabaks.autobase.common` - Provides common variables and configurations
115-
116-
## Platform Support
117-
118-
### Supported Operating Systems
119-
120-
- **Debian/Ubuntu**: Uses `deb822_repository` for modern repository management
121-
- **RedHat/CentOS/AlmaLinux/Oracle Linux**: Uses `yum_repository` and `dnf config-manager`
122-
123-
### Supported Architectures
124-
125-
- **x86_64/amd64**: Full support for all repositories
126-
- **arm64**: Limited support (TimescaleDB and Citus have x86_64-only repositories)
127-
128-
## Special Features
129-
130-
### Automatic PowerTools/CodeReady Builder Enablement
131-
132-
The role automatically enables additional repositories based on the distribution:
133-
134-
- **AlmaLinux/Rocky 8**: PowerTools repository
135-
- **RHEL 9+/AlmaLinux/Rocky**: CodeReady Linux Builder (crb) repository
136-
- **Oracle Linux 8+**: CodeReady Builder repository
137-
138-
### PostgreSQL Debuginfo Repository
139-
140-
When PostgreSQL debuginfo packages are requested, the role:
141-
1. Enables existing debuginfo repositories in pgdg-redhat-all.repo
142-
2. Creates new debuginfo repository entries if they don't exist
143-
3. Disables GPG checking for debuginfo packages
144-
145-
## Tags
146-
147-
Available tags for selective execution:
148-
- `add_repo`: General repository addition
149-
- `install_postgresql_repo`: PostgreSQL repository installation
150-
- `install_epel_repo`: EPEL repository installation
151-
- `timescaledb`, `timescale`: TimescaleDB repository
152-
- `citus`: Citus repository
153-
- `debuginfo`: PostgreSQL debuginfo repository

‎automation/roles/authorized_keys/README.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,37 @@
11
# Ansible Role: authorized_keys
2+
3+
Adds SSH public keys to ~/.ssh/authorized_keys of the remote user detected via `whoami`.
4+
5+
## Description
6+
- Detects target user with `whoami` on the managed host.
7+
- Ensures ~/.ssh and authorized_keys exist with secure permissions.
8+
- Idempotent: adds keys without duplicates or removing other keys.
9+
10+
## Role Variables
11+
12+
| Variable | Type | Default | Description |
13+
|-------------------|---------------|------------|-------------|
14+
| ssh_public_keys | string or list| undefined | Public key(s) to add. Accepts a list of key lines or a single string; if string, keys may be separated by newlines or commas. Extra quotes are stripped. If undefined/empty, the role does nothing. |
15+
16+
Note: The target user is the actual SSH user (resolved via `whoami`) and cannot be overridden by a variable.
17+
18+
## Examples
19+
20+
List of keys:
21+
```yaml
22+
ssh_public_keys:
23+
- "ssh-ed25519 AAAAC3... user1@example"
24+
- "ssh-rsa AAAAB3... user2@example"
25+
```
26+
27+
Single string (newline-separated):
28+
```yaml
29+
ssh_public_keys: |
30+
ssh-ed25519 AAAAC3... user1@example
31+
ssh-rsa AAAAB3... user2@example
32+
```
33+
34+
## Dependencies
35+
36+
This role depends on:
37+
- `vitabaks.autobase.common` - Provides common variables and configurations

‎automation/roles/bind_address/README.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,10 @@ This role automatically detects and sets the available private IPv4 address for
55
#### How it works
66

77
- Finds the first available private IPv4 address on the host (excluding the docker0 interface, if present).
8-
- Sets this address as the Ansible fact bind_address using set_fact.
9-
- If bind_address is already defined in inventory or variables, it will not be executed.
8+
- Sets this address as the Ansible fact `bind_address` using `set_fact`.
9+
- If `bind_address` is already defined in inventory or variables, it will not be executed.
10+
- If no suitable private IP is found, the role fails with a clear message.
11+
12+
#### Recommendation
13+
14+
If a host has multiple IP addresses (e.g., multiple interfaces/VLANs), explicitly set `bind_address` in inventory for each host instead of relying on auto-detection.

‎automation/roles/cloud_resources/README.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,113 @@
11
# Ansible Role: cloud_resources
2+
3+
Provision the PostgreSQL cluster infrastructure in public clouds (AWS, GCP, Azure, DigitalOcean, Hetzner). The role can:
4+
- Create/delete servers (count, size, image, region)
5+
- Configure private networking/VPC/VNet and firewalls/Security Groups
6+
- Optionally create Load Balancers (AWS NLB/CLB, GCP TCP Proxy, Azure LB, DO LB, Hetzner LB)
7+
- Optionally create object storage for backups (S3/GCS/Azure Blob/Spaces/Hetzner Object Storage)
8+
- Generate in-memory inventory (postgres_cluster, master/replica, etcd_cluster/consul_instances).
9+
10+
## Requirements
11+
- Collections on control host:
12+
- amazon.aws, community.aws
13+
- google.cloud
14+
- azure.azcollection
15+
- community.digitalocean
16+
- hetzner.hcloud
17+
- Credentials via environment variables:
18+
- AWS: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
19+
- GCP: `GCP_SERVICE_ACCOUNT_CONTENTS` (JSON or base64)
20+
- Azure: `AZURE_SUBSCRIPTION_ID`, `AZURE_CLIENT_ID`, `AZURE_SECRET`, `AZURE_TENANT`
21+
- DigitalOcean: `DO_API_TOKEN`
22+
- Hetzner: `HCLOUD_API_TOKEN`
23+
24+
## Variables
25+
26+
| Variable | Type | Default | Description |
27+
|---------|------|---------|-------------|
28+
| cloud_provider | string | "" | Specifies the Cloud provider for server creation. Available options: 'aws', 'gcp', 'azure', 'digitalocean', 'hetzner' |
29+
| state | string | present | present to create, absent to delete |
30+
| server_count | int | 3 | Number of servers in the cluster |
31+
| server_name | string | {{ patroni_cluster_name }}-pgnode | Will be automatically named with suffixes 01, 02, 03, etc. |
32+
| server_type | string | "" | Instance/VM size (required) |
33+
| server_image | string | "" | OS image. For Azure, use variables 'azure_vm_image_offer', 'azure_vm_image_publisher', 'azure_vm_image_sku', 'azure_vm_image_version' instead of 'server_image' variable |
34+
| server_location | string | "" | Region/zone (required) |
35+
| server_network | string | "" | Existing network/subnet/VPC. If provided, the server will be added to this network (needs to be created beforehand) |
36+
| server_spot | bool | false | Spot/preemptible where supported. Applicable for AWS, GCP, Azure |
37+
| server_public_ip | bool | true | Assign public IPs to servers |
38+
| volume_type | string | "" | Data disk type. Defaults: 'gp3' for AWS, 'pd-ssd' for GCP, 'StandardSSD_LRS' for Azure |
39+
| volume_size | int | 100 | Data disk size (GB) |
40+
| system_volume_type | string | "" | System disk type. Defaults: 'gp3' for AWS, 'pd-ssd' for GCP, 'StandardSSD_LRS' for Azure |
41+
| system_volume_size | int | 100 | System disk size (GB) |
42+
| ssh_key_name | string | "" | Name of the SSH key to be added to the server. Note: If not provided, all cloud available SSH keys will be added (applicable to DigitalOcean, Hetzner) |
43+
| ssh_key_content | string | "" | If provided, the public key content will be added to the cloud (directly to the server for GCP) |
44+
| cloud_firewall | bool | true | Manage firewall/Security Groups |
45+
| ssh_public_access | bool | true | Allow public ssh access (required for deployment from the public network). Applicable if server_public_ip is set to true |
46+
| ssh_public_allowed_ips | string | "" | Comma-separated CIDRs for SSH (empty = 0.0.0.0/0,::/0) |
47+
| netdata_public_access | bool | true | Allow public Netdata (if 'netdata_install' is 'true') |
48+
| netdata_public_allowed_ips | string | "" | Comma-separated CIDRs for Netdata |
49+
| database_public_access | bool | false | Allow public DB access |
50+
| database_public_allowed_ips | string | "" | Comma-separated CIDRs for DB |
51+
| cloud_load_balancer | bool | true | Create a cloud Load Balancer |
52+
| aws_load_balancer_type | string | nlb | 'nlb' = Network Load Balancer; 'clb' = Classic Load Balancer (previous generation) |
53+
| aws_s3_bucket_create | bool | true | Create S3 bucket (if 'pgbackrest_install' or 'wal_g_install' is 'true') |
54+
| aws_s3_bucket_name | string | {{ patroni_cluster_name }}-backup | Bucket name |
55+
| aws_s3_bucket_region | string | {{ server_location }} | Bucket region |
56+
| aws_s3_bucket_object_lock_enabled | bool | false | Enable S3 Object Lock |
57+
| aws_s3_bucket_encryption | string | AES256 | Server-side encryption ("AES256","aws:kms") |
58+
| aws_s3_bucket_block_public_acls | bool | true | BlockPublicAcls |
59+
| aws_s3_bucket_ignore_public_acls | bool | true | IgnorePublicAcls |
60+
| aws_s3_bucket_absent | bool | false | Allow delete bucket on state=absent |
61+
| gcp_bucket_create | bool | true | Create GCS bucket (if 'pgbackrest_install' or 'wal_g_install' is 'true') |
62+
| gcp_bucket_name | string | {{ patroni_cluster_name }}-backup | Storage bucket name |
63+
| gcp_bucket_storage_class | string | MULTI_REGIONAL | Storage bucket class |
64+
| gcp_bucket_default_object_acl | string | projectPrivate | Default object ACL |
65+
| gcp_bucket_absent | bool | false | Allow delete bucket on state=absent |
66+
| azure_blob_storage_create | bool | true | Create Azure Blob container (if 'pgbackrest_install' or 'wal_g_install' is 'true') |
67+
| azure_blob_storage_name | string | {{ patroni_cluster_name }}-backup | Name of a blob container within the storage account |
68+
| azure_blob_storage_blob_type | string | block | Type of blob object. Values include: block, page |
69+
| azure_blob_storage_account_name | string | {{ patroni_cluster_name }} | Storage account name. Must be between 3 and 24 characters in length and use numbers and lower-case letters only |
70+
| azure_blob_storage_account_type | string | Standard_RAGRS | Type of storage account. Values include: Standard_LRS, Standard_GRS, Standard_RAGRS, Standard_ZRS, Standard_RAGZRS, Standard_GZRS, Premium_LRS, Premium_ZRS |
71+
| azure_blob_storage_account_kind | string | BlobStorage | The kind of storage. Values include: Storage, StorageV2, BlobStorage, BlockBlobStorage, FileStorage |
72+
| azure_blob_storage_account_access_tier | string | Hot | The access tier for this storage account. Required when kind=BlobStorage |
73+
| azure_blob_storage_account_public_network_access | string | Enabled | Allow public network access to Storage Account to create Blob Storage container |
74+
| azure_blob_storage_account_allow_blob_public_access | bool | false | Allow anonymous blob access |
75+
| azure_blob_storage_absent | bool | false | Allow delete Azure Blob Storage on state=absent |
76+
| digital_ocean_spaces_create | bool | true | Create Spaces bucket (if 'pgbackrest_install' or 'wal_g_install' is 'true') |
77+
| digital_ocean_spaces_name | string | {{ patroni_cluster_name }}-backup | Spaces name |
78+
| digital_ocean_spaces_region | string | nyc3 | Spaces region |
79+
| digital_ocean_spaces_absent | bool | false | Allow delete Spaces on state=absent |
80+
| hetzner_object_storage_create | bool | true | Create Hetzner Object Storage (if 'pgbackrest_install' or 'wal_g_install' is 'true') |
81+
| hetzner_object_storage_name | string | {{ patroni_cluster_name }}-backup | Bucket name |
82+
| hetzner_object_storage_region | string | {{ server_location }} | Region |
83+
| hetzner_object_storage_endpoint | string | https://{{ hetzner_object_storage_region }}.your-objectstorage.com | S3 endpoint |
84+
| hetzner_object_storage_access_key | string | "" | Object Storage ACCESS KEY (required) |
85+
| hetzner_object_storage_secret_key | string | "" | Object Storage SECRET KEY (required) |
86+
| hetzner_object_storage_absent | bool | false | Allow delete Object Storage on state=absent |
87+
88+
### Provider-specific (optional) variables referenced in tasks
89+
90+
| Variable | Provider | Default/Notes |
91+
|----------|----------|---------------|
92+
| aws_ec2_spot_instance | AWS | Fallback for server_spot |
93+
| gcp_project | GCP | Fallbacks to projectNumber from credentials |
94+
| gcp_compute_instance_preemptible | GCP | Fallback for server_spot |
95+
| gcp_compute_health_check_interval_sec, gcp_compute_health_check_check_timeout_sec, gcp_compute_health_check_unhealthy_threshold, gcp_compute_health_check_healthy_threshold | GCP | Interval/timeout/threshold tuning |
96+
| gcp_compute_backend_service_timeout_sec, gcp_compute_backend_service_log_enable | GCP | LB Backend timeouts/logging |
97+
| digital_ocean_vpc_name | DO | Custom VPC name if creating one |
98+
| digital_ocean_load_balancer_size | DO | default('lb-medium') if server_location in ['ams2', 'nyc2', 'sfo1'] |
99+
| digital_ocean_load_balancer_size_unit | DO | default(3) if server_location not in ['ams2', 'nyc2', 'sfo1'] |
100+
| digital_ocean_load_balancer_port, digital_ocean_load_balancer_target_port | DO | LB port, default: pgbouncer_listen_port |
101+
| azure_resource_group | Azure | Resource group name |
102+
| azure_virtual_network, azure_subnet | Azure | VNet/Subnet names, default: postgres-cluster-network/postgres-cluster-subnet |
103+
| azure_virtual_network_prefix, azure_subnet_prefix | Azure | CIDRs, default: '10.0.0.0/16'/'10.0.1.0/24' |
104+
| azure_admin_username | Azure | Default: azureadmin |
105+
| azure_vm_image_offer, azure_vm_image_publisher, azure_vm_image_sku, azure_vm_image_version | Azure | Image reference |
106+
| hetzner_load_balancer_type | Hetzner | Default: lb21 |
107+
| hcloud_network_name | Hetzner | Network name if creating, default('postgres-cluster-network-' + target_network_zone) |
108+
| hcloud_network_ip_range, hcloud_subnetwork_ip_range | Hetzner | CIDRs, default: '10.0.0.0/16'/'10.0.1.0/24' |
109+
110+
## Dependencies
111+
112+
This role depends on:
113+
- `vitabaks.autobase.common` - Provides common variables and configurations

‎automation/roles/confd/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,15 @@
11
# Ansible Role: confd
2+
3+
Installs and configures [confd](https://github.com/kelseyhightower/confd) to render HAProxy configuration templates from a distributed configuration store (DCS) such as etcd (used by Patroni / PostgreSQL cluster).
4+
5+
## Variables
6+
7+
| Variable | Default | Description |
8+
|----------|---------|-------------|
9+
| confd_package_repo | `https://github.com/kelseyhightower/confd/releases/download/v0.16.0/confd-0.16.0-linux-{{ confd_architecture_map[ansible_architecture] }}` | URL to download confd binary (used when installation_method=packages). |
10+
| confd_etcd_tls_dir | /etc/confd/tls/etcd | Destination for etcd TLS certs used by confd. |
11+
12+
## Dependencies
13+
14+
This role depends on:
15+
- `vitabaks.autobase.common` - Provides common variables and configurations

0 commit comments

Comments
 (0)