### Constructing PostgreSQL URI for Snap Installation

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/variables.md

This example shows how to construct the database URI for MAAS when using a Snap installation of PostgreSQL. It utilizes Jinja2 templating to insert variable values.

```yaml
# DEB installation uses separate config file:
# /etc/maas/regiond.conf

# Snap installation requires database URI:
maas_postgres_uri: postgresql://{{ maas_postgres_user }}:{{ maas_postgres_password }}@{{ postgres_host }}/{{ maas_postgres_database }}
```

--------------------------------

### MAAS Multi-Region Inventory Setup

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/observability-and-advanced.md

Example inventory files for a multi-region MAAS deployment. This defines hosts for PostgreSQL, and MAAS region controllers across different regions.

```yaml
# hosts-region1.yaml
maas_postgres:
  hosts:
    db01.example.com:
    db02.example.com:
    db03.example.com:

maas_region_controller:
  hosts:
    region1.example.com:
    region2.example.com:

# hosts-region2.yaml
maas_region_controller:
  hosts:
    region2a.example.com:
    region2b.example.com:
    region2c.example.com:
```

--------------------------------

### Execute MAAS Restore Playbook (Inventory)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/playbooks.md

Restore a MAAS installation from a backup archive. This example assumes the backup file path is set per-host in the inventory. Specify the installation type (deb or snap).

```bash
ansible-playbook -i ./hosts \
  --extra-vars="maas_installation_type=deb" \
  ./restore.yaml
```

--------------------------------

### Install MAAS Rack Controller (Snap)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Installs the MAAS rack controller using snap. This is applicable when `maas_installation_type` is 'snap' and the host is not a region controller.

```bash
Condition: maas_installation_type == 'snap' and 'maas_region_controller' not in group_names

snap install maas --channel={{ maas_version }}/{{ maas_snap_channel }}
```

--------------------------------

### PostgreSQL Performance Tuning Examples

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/templates-and-configuration.md

Provides example memory configurations for PostgreSQL based on different system sizes and connection loads.

```yaml
# 16GB system, 100 connections
shared_buffers: 4GB
effective_cache_size: 12GB
work_mem: 16MB
maintenance_work_mem: 800MB

# 64GB system, 500 connections
shared_buffers: 16GB
effective_cache_size: 48GB
work_mem: 13MB
maintenance_work_mem: 3200MB

```

--------------------------------

### MAAS Installation Method Selection

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Selects the installation method for MAAS, either using snaps or debian packages. For snaps, it installs the specified version and channel. For debian, it adds the PPA and installs the region API, along with the chrony NTP service.

```yaml
If maas_installation_type == 'snap':
  snap install maas --channel={{ maas_version }}/{{ maas_snap_channel }}

If maas_installation_type == 'deb':
  apt-add-repository ppa:maas/{{ maas_version }}
  apt-get install maas-region-api
  chrony                    # NTP service
```

--------------------------------

### Ansible Playbook Execution Examples

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/playbooks.md

Examples demonstrate full deployment, HA component deployment, and region controller deployment using ansible-playbook with extra variables and tags.

```bash
# Full deployment
ansible-playbook -i ./hosts \
  --extra-vars="maas_version=3.2 \
    maas_postgres_password=example \
    maas_installation_type=deb \
    maas_url=http://example.com:5240/MAAS" \
  ./site.yaml
```

```bash
# Deploy only HA components
ansible-playbook -i ./hosts \
  --extra-vars="maas_version=3.2 maas_postgres_password=example \
    maas_installation_type=deb maas_url=http://example.com:5240/MAAS" \
  --tags maas_ha_postgres \
  ./site.yaml
```

```bash
# Deploy region controllers only
ansible-playbook -i ./hosts \
  --extra-vars="maas_version=3.2 maas_postgres_password=example \
    maas_installation_type=deb maas_url=http://example.com:5240/MAAS" \
  --tags maas_region_controller \
  ./site.yaml
```

--------------------------------

### Backup MAAS Installation

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/inventory-and-execution.md

Initiates a backup of the MAAS installation. Requires specifying the download path for the backup files and the installation type.

```bash
mkdir -p /tmp/maas-backups
ansible-playbook -i hosts.yaml \
  --extra-vars="\
    maas_backup_download_path=/tmp/maas-backups/ \
    maas_installation_type=deb" \
  backup.yaml
```

--------------------------------

### Install HAProxy Package

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-postgres.md

Installs the HAProxy package. The state is determined by the `maas_proxy_state` variable, defaulting to 'present' if the state is 'install'.

```yaml
haproxy:
  state: "{{ 'present' if maas_proxy_state | lower == 'install' else maas_proxy_state }}"
```

--------------------------------

### Install HAProxy Package

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Ensures the HAProxy package is installed on the system. This is a prerequisite for setting up the HAProxy reverse proxy.

```yaml
haproxy:
  state: present
```

--------------------------------

### MAAS Ansible Dependency Ordering Example

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/inventory-and-execution.md

Shows the implicit dependency order enforced by the site.yaml playbook. Roles are executed in a specific sequence to ensure proper setup.

```yaml
1. All hosts: validation + system update
2. maas_postgres hosts: install database
3. maas_corosync hosts: cluster comms
4. maas_pacemaker hosts: HA management
5. maas_postgres_proxy hosts: DB load balancing
6. maas_proxy hosts: region load balancing
7. maas_region_controller hosts: management
8. maas_rack_controller hosts: agents + observability
```

--------------------------------

### Install MAAS Rack Controller (DEB)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Installs the MAAS rack controller using apt-get. This requires the MAAS system user and group to be set up first. Applicable when `maas_installation_type` is 'deb'.

```bash
Condition: maas_installation_type == 'deb'

# Create MAAS system user/group
group: maas
user: maas (group: maas)

# Install package
apt-get install maas-rack-controller
```

--------------------------------

### MAAS SNAP Installation Defaults

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/variables.md

Default variables for installing MAAS using SNAP. Specifies the snap channel and the service names for region and rack controllers.

```yaml
maas_snap_channel: "stable"
maas_region_service: "snap.maas.maas.service"
maas_rack_service: "snap.maas.maas.service"
```

--------------------------------

### MAAS Installation Metrics Marker File

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Creates a marker file to indicate that the MAAS installation process is complete. This file is typically located at /var/lib/maas/ansible-install-done and has read/write permissions for the owner.

```yaml
Create Marker File: {{ maas_installmetric_file }}
  Path: /var/lib/maas/ansible-install-done
  Mode: 0644
```

--------------------------------

### Example STONITH Parameters for IPMI

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-postgres.md

Provides an example of the 'maas_pacemaker_stonith_params' dictionary for the 'ipmilan' STONITH driver. This includes IP address, login credentials, and connection type.

```yaml
maas_pacemaker_stonith_params:
  ipaddr: "192.168.1.10"
  login: "root"
  passwd: "password"
  lanplus: "true"
```

--------------------------------

### Install Corosync Package

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-postgres.md

Installs the Corosync package on the target system. Ensures the package manager cache is updated before installation.

```yaml
corosync:
  name: corosync
  state: present
  update_cache: true
```

--------------------------------

### Initialize MAAS Rack Controller (Snap)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Initializes the MAAS rack controller when installed via snap. This requires the MAAS URL and a secret. Applicable when `maas_installation_type` is 'snap' and the host is not a region controller.

```bash
Condition: maas_installation_type == 'snap' and 'maas_region_controller' not in group_names

maas init rack --maas-url={{ maas_url }} --secret={{ maas_rack_secret }}
```

--------------------------------

### Install Pacemaker Packages

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-postgres.md

Installs essential packages for Pacemaker, including the resource manager, command-line control tool, fencing agents, and the PostgreSQL resource agent.

```yaml
- pacemaker      # Resource management
- pcs            # Pacemaker command and control
- fence-agents   # STONITH (fencing) agents
- resource-agents-paf  # PostgreSQL OCF resource agent
```

--------------------------------

### YAML Inventory Example

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/inventory-and-execution.md

Defines hosts and their associated variables using the YAML inventory format. Recommended for its readability and support for complex structures.

```yaml
---
all:
  children:
    maas_pacemaker:
      children:
        maas_corosync:
          hosts:
            db01.example.com:
            db02.example.com:
            db03.example.com:
              maas_pacemaker_fencing_driver: ipmilan
              maas_pacemaker_stonith_params:
                ipaddr: "192.168.1.10"
                login: "root"
                passwd: "password"
                lanplus: "true"
              maas_pacemaker_self_address: "192.168.1.101"
    
    maas_postgres:
      hosts:
        db01.example.com:
          maas_postgres_ipv4: "192.168.1.20"
          maas_postgres_ipv6: "2001:db8::20"
        db02.example.com:
          maas_postgres_ipv4: "192.168.1.21"
          maas_postgres_ipv6: "2001:db8::21"
        db03.example.com:
          maas_postgres_ipv4: "192.168.1.22"
          maas_postgres_ipv6: "2001:db8::22"
    
    maas_postgres_proxy:
      hosts:
        region01.example.com:
        region02.example.com:
        region03.example.com:
    
    maas_region_controller:
      hosts:
        region01.example.com:
        region02.example.com:
        region03.example.com:
    
    maas_rack_controller:
      hosts:
        region01.example.com:
        rack01.example.com:
        rack02.example.com:
    
    maas_proxy:
      hosts:
        proxy01.example.com:

```

--------------------------------

### Pacemaker STONITH Parameters Example

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/variables.md

Example configuration for Pacemaker's STONITH (Shoot The Other Node In The Head) driver parameters, specifically for the 'ipmilan' driver. This is used for hardware-level fencing to ensure cluster stability.

```yaml
maas_pacemaker_stonith_params:
  ipaddr: "192.168.1.10"          # BMC IP address
  login: "root"                   # BMC user
  passwd: "password"              # BMC password
  lanplus: "true"                 # IPMI+
  privlvl: "ADMINISTRATOR"        # Privilege level
  action: "reboot"                # Fencing action
```

--------------------------------

### Start Postgres Service Handler

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/handlers-and-tasks-reference.md

Starts the PostgreSQL service with new configurations after a stop handler has executed. Ensures the service is enabled for auto-start on reboot.

```yaml
Name: Start Postgres Service To Load New Configuration
Condition: Always (executed after stop handler)
Effect: Start PostgreSQL with new configuration

Task Details:
  Module: ansible.builtin.systemd
  Service: postgresql@{{ maas_postgres_version_number }}-main.service
  Action: start
  Enabled: true (auto-start on reboot)
  Wait: true (no_block: false)
```

--------------------------------

### MAAS Initialization (Snap)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Initializes the MAAS region controller when installed via snap. The 'type' parameter should be 'region+rack' if rack controllers are present, otherwise 'region'. This command should only be run once per deployment.

```bash
Command: maas init {{ type }} --maas-url={{ maas_url }} --database-uri {{ maas_postgres_uri }}
  type: 'region+rack' (if maas_rack_controller in groups)
         'region' (otherwise)
  
Throttle: 1 (only one region per deployment initializes)
```

--------------------------------

### Execute MAAS Backup Playbook

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/playbooks.md

This playbook creates a compressed archive of MAAS configuration and database state. Specify the download path and installation type (deb or snap) using extra variables.

```bash
mkdir -p /tmp/maas_backups
ansible-playbook -i ./hosts \
  --extra-vars="maas_backup_download_path=/tmp/maas_backups/ \
    maas_installation_type=deb" \
  ./backup.yaml
```

--------------------------------

### Start HA Clusters Metrics Agent

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/handlers-and-tasks-reference.md

Installs and restarts the HA clusters metrics exporter service, which exposes cluster metrics on port 9664. This handler is conditional on observability being enabled.

```yaml
Name: Start HA clusters metrics agent
Condition: Observability enabled (o11y_enable=true)
Effect: Install and start cluster metrics exporter

Task Details:
  Module: ansible.builtin.systemd
  Service: ha_cluster_exporter
  Enabled: true (auto-start)
  State: restarted
  Daemon Reload: true
```

--------------------------------

### Execute MAAS Restore Playbook (Per-Host Variable)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/playbooks.md

Restore a MAAS installation from a backup archive, specifying the backup file path directly as an extra variable for a specific host. Specify the installation type (deb or snap).

```bash
ansible-playbook -i ./hosts \
  --extra-vars="maas_installation_type=deb" \
  --limit "host1" \
  -e "maas_backup_file=/path/to/backup-host1.tar.gz" \
  ./restore.yaml
```

--------------------------------

### MAAS DEB Installation Defaults

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/variables.md

Default variables for installing MAAS using the DEB package manager. Specifies the package name, snap channel (if applicable), installation state, and service names for region and rack controllers.

```yaml
maas_package_name: "maas-region-api"
maas_snap_channel: "stable"
maas_deb_state: "present"
maas_region_service: "maas-regiond.service"
maas_rack_service: "maas-rackd.service"
```

--------------------------------

### Restore MAAS Installation from Backup

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/inventory-and-execution.md

Restores a MAAS installation from a backup. This can be done by setting `maas_backup_file` in the inventory for each host or specifying it per-host using `--limit` and `--extra-vars`.

```bash
# Set maas_backup_file in inventory for each host, then:
ansible-playbook -i hosts.yaml \
  --extra-vars="maas_installation_type=deb" \
  restore.yaml

# Or specify per-host:
ansible-playbook -i hosts.yaml \
  --limit "region01.example.com" \
  --extra-vars="\
    maas_installation_type=deb \
    maas_backup_file=/tmp/maas-backups/backup-region01-20240115.tar.gz" \
  restore.yaml
```

--------------------------------

### Create MAAS Admin User with SSH Key

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/playbooks.md

Use this playbook to create a new MAAS administrator account. This example includes importing an SSH key from Launchpad using the `lp:username` format.

```bash
ansible-playbook -i ./hosts \
  --extra-vars="user_name=newuser \
    user_pwd=newpwd \
    user_email=user@email.com \
    user_ssh=lp:launchpad_id" \
  ./createadmin.yaml
```

--------------------------------

### Registered Variables for PostgreSQL Installation

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-postgres.md

Details the registered variables available after the PostgreSQL installation task, primarily indicating whether the installation process resulted in changes.

```yaml
postgres_installed:
  description: Result of postgres apt install
  type: object
  attributes:
    changed: boolean - True if new installation
```

--------------------------------

### MAAS Backup with Ansible

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/README.md

Perform a backup of the MAAS installation using Ansible. Specify the download path for the backup archive.

```bash
# Backup
ansible-playbook -i ./hosts.yaml \
  --extra-vars="maas_backup_download_path=/tmp/" \
  ./backup.yaml
```

--------------------------------

### View MAAS Snap Logs

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/troubleshooting-and-operations.md

Access the logs for the MAAS snap installation to diagnose issues.

```bash
sudo snap logs maas
```

--------------------------------

### MAAS Admin User Creation

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Creates an administrative user for MAAS with specified username, password, and email. Optionally, SSH keys can be imported. This command runs only if it's not a new snap installation or if snap installation was skipped, and it executes only once across all region controllers.

```bash
Command: maas createadmin \
  --username={{ admin_username }} \
  --password={{ admin_password }} \
  --email={{ admin_email }} \
  --ssh-import={{ admin_id if defined else '' }}

Execution:
  - Only if this is not a new snap installation, or if snap installation skipped
  - Run Once: true (across all region controllers)
```

--------------------------------

### Pacemaker Usage Example with Explicit Flush

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/handlers-and-tasks-reference.md

This example demonstrates an explicit flush after configuring SSH for Pacemaker. It ensures the SSH service restarts before proceeding with cluster authentication.

```yaml
# Update configuration
- name: Configure SSH for pacemaker
  ansible.builtin.template: ...
  notify: "Restart sshd"

# Wait for SSH to restart before proceeding
- name: "Flush handlers"
  ansible.builtin.meta: flush_handlers

# SSH now ready for cluster auth
- name: "Auth cluster"
  ansible.builtin.shell: pcs host auth {{ hosts }}
```

--------------------------------

### INI Inventory Example

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/inventory-and-execution.md

Defines hosts and groups using the INI inventory format. A simpler format suitable for less complex environments.

```ini
[maas_corosync]
db01.example.com
db02.example.com
db03.example.com

[maas_pacemaker:children]
maas_corosync

[maas_postgres]
db01.example.com
db02.example.com
db03.example.com

[maas_postgres_proxy]
region01.example.com
region02.example.com
region03.example.com

[maas_region_controller]
region01.example.com
region02.example.com
region03.example.com

[maas_rack_controller]
region01.example.com
rack01.example.com
rack02.example.com

[maas_proxy]
proxy01.example.com

```

--------------------------------

### Tune PostgreSQL Database Settings

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/troubleshooting-and-operations.md

Commands to check current PostgreSQL settings and examples of parameters to adjust in postgresql.conf for performance tuning.

```bash
# Check current settings
sudo -u postgres psql -c "SHOW shared_buffers; SHOW max_connections;"
```

```ini
# Adjust in postgresql.conf
shared_buffers = 8GB  # 25% of RAM
effective_cache_size = 24GB  # 75% of RAM
work_mem = 100MB
```

--------------------------------

### Start Postgres Metrics Agent Handler

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/handlers-and-tasks-reference.md

Starts or restarts the postgres_exporter service when observability is enabled. Ensures the service is enabled for auto-start and reloads the daemon.

```yaml
Name: Start Postgres metrics agent
Condition: Observability enabled (o11y_enable=true)
Effect: Start/restart postgres_exporter

Task Details:
  Module: ansible.builtin.systemd
  Service: postgres_exporter
  Enabled: true (auto-start)
  State: restarted
  Daemon Reload: true
```

--------------------------------

### Ansible Playbook Execution Example

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/README.md

This is a shell command to execute an Ansible playbook. It specifies the inventory file, the playbook to run, and passes extra variables for configuration.

```bash
ansible-playbook -i hosts.yaml site.yaml \
  --extra-vars="maas_version=3.2"
```

--------------------------------

### Full MAAS Deployment with Ansible

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/README.md

Execute a full MAAS deployment using Ansible. Ensure MAAS version, PostgreSQL password, installation type, and MAAS URL are correctly set.

```bash
# Full deployment
ansible-playbook -i ./hosts.yaml \
  --extra-vars="maas_version=3.2 \
    maas_postgres_password=secret \
    maas_installation_type=deb \
    maas_url=http://example.com:5240/MAAS" \
  ./site.yaml
```

--------------------------------

### Upgrade MAAS Rack Controller (DEB)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Installs the latest version of the MAAS rack controller package using apt-get. This command updates the package list before installing.

```bash
apt-get update
apt-get install --upgrade maas-rack-controller
```

--------------------------------

### MAAS Package Detection (SNAP)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Detects if MAAS is installed when using SNAP packages.

```yaml
For SNAP:
  maas_installed = 'maas' in snap list output
```

--------------------------------

### Check MAAS Region Configuration (DEB)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/troubleshooting-and-operations.md

Inspect the MAAS region controller configuration file to verify database connection details on DEB installations.

```bash
sudo cat /etc/maas/regiond.conf
```

--------------------------------

### Upgrade Existing MAAS Installation

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/inventory-and-execution.md

Upgrade an existing MAAS deployment to a newer version. The playbook automatically detects the existing installation, runs the upgrade process, and handles database migrations.

```bash
ansible-playbook -i hosts.yaml \
  --extra-vars="maas_version=3.3" \
  site.yaml
```

--------------------------------

### Create New Admin User in MAAS

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/README.md

Use this playbook to create a new administrator user for an existing MAAS installation. Ensure the target host is configured in `./hosts` and provide user credentials and an optional SSH public key.

```bash
ansible-playbook -i ./hosts --extra-vars="user_name=newuser user_pwd=newpwd user_email=user@email.com user_ssh=lp:id" ./createadmin.yaml
```

--------------------------------

### MAAS Restore with Ansible

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/README.md

Restore a MAAS installation from a backup archive using Ansible. Provide the path to the backup file.

```bash
# Restore
ansible-playbook -i ./hosts.yaml \
  --extra-vars="maas_backup_file=/tmp/backup.tar.gz" \
  ./restore.yaml
```

--------------------------------

### MAAS Initialization (DEB)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Initializes the MAAS region controller when installed via debian packages. This command prompts for administrative credentials and SSH key import. Ensure the RBAC URL and candid agent file are correctly configured.

```bash
Command: maas init --rbac-url={{ maas_rbac_url }} --candid-agent-file={{ maas_candid_auth_file }}
  
Interactive Prompts:
  Username: "{{ admin_username }}" (default: admin)
  Password: "{{ admin_password }}" (default: admin)
  Again (confirm): "{{ admin_password }}"
  Email: "{{ admin_email }}" (default: admin@email.com)
  Import SSH keys: "{{ admin_id }}" (optional: lp:id or gh:id)
```

--------------------------------

### Check MAAS Database Connectivity (DEB)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/troubleshooting-and-operations.md

Access the MAAS database shell and run a simple query to verify connectivity to the MAAS database on DEB installations.

```bash
sudo maas dbshell
  >>> SELECT 1;  # If works, DB is up
```

--------------------------------

### Selective MAAS Deployment with Tags

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/inventory-and-execution.md

Deploy specific roles or components of MAAS using tags. This allows for targeted installations, such as only the PostgreSQL tier or region controllers.

```bash
# Deploy only PostgreSQL tier
ansible-playbook -i hosts.yaml \
  --tags maas_postgres \
  site.yaml
```

```bash
# Deploy only region controllers
ansible-playbook -i hosts.yaml \
  --tags maas_region_controller \
  site.yaml
```

```bash
# Deploy HA clustering (Corosync + Pacemaker)
ansible-playbook -i hosts.yaml \
  --tags maas_ha_postgres \
  site.yaml
```

```bash
# Deploy only firewall rules
ansible-playbook -i hosts.yaml \
  --tags maas_firewall \
  site.yaml
```

--------------------------------

### Start Grafana Agent Handler

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/handlers-and-tasks-reference.md

Installs and restarts the Grafana Agent service. This handler is conditional on 'o11y_enable=true' and is triggered by Grafana Agent installation, configuration updates, or integration setup. It exposes metrics on port 12345 and potentially others depending on integrations.

```yaml
Name: Start grafana agent
Condition: Observability enabled (o11y_enable=true)
Effect: Install and start Grafana Agent

Task Details:
  Module: ansible.builtin.systemd
  Service: telemetry
  Enabled: true (auto-start)
  State: restarted
  Daemon Reload: true
```

--------------------------------

### Observability Agent Configuration Variables

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/variables.md

Variables for configuring the observability agent, including its installation directory, directories to create, the package source URL, and the roles where the agent should be enabled.

```yaml
o11y_grafana_agent_dir: "/opt/grafana-agent"
o11y_grafana_agent_dirs: -

grafana_agent_pkg: -

o11y_enabled_roles: ['maas_postgres', 'maas_region_controller', 'maas_rack_controller', 'maas_pacemaker']
```

--------------------------------

### Execute MAAS Teardown Playbook

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/playbooks.md

Use this playbook to completely remove a MAAS installation and revert the system to a clean state. Ensure data backups are performed before execution as this is a destructive operation.

```bash
ansible-playbook -i ./hosts ./teardown.yaml
```

--------------------------------

### Host Variables for INI Inventory

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/inventory-and-execution.md

Example of defining host-specific variables for a host when using the INI inventory format. These variables are placed in `host_vars/<hostname>.yml`.

```yaml
maas_pacemaker_fencing_driver: ipmilan
maas_pacemaker_stonith_params:
  ipaddr: "192.168.1.10"
  login: "root"
  passwd: "password"
maas_pacemaker_self_address: "192.168.1.101"

```

--------------------------------

### Deploy HA MAAS 3.2 with Observability

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/inventory-and-execution.md

Deploys a High Availability MAAS 3.2 instance with observability features enabled. Requires specifying MAAS version, database password, installation type, MAAS URL, and observability endpoints.

```bash
ansible-playbook -i hosts.yaml \
  --extra-vars="\
    maas_version=3.2 \
    maas_postgres_password='secure_db_password' \
    maas_installation_type=deb \
    maas_url=http://proxy01.example.com:5240/MAAS \
    maas_ha_postgres_enabled=true \
    maas_postgres_floating_ip=192.168.1.50 \
    maas_postgres_floating_ip_prefix_len=24 \
    o11y_enable=true \
    o11y_prometheus_url=http://prometheus.example.com:9090/api/v1/write \
    o11y_loki_url=http://loki.example.com:3100/loki/api/v1/push \
    enable_tls=true \
    generate_tls_cred=true" \
  site.yaml
```

--------------------------------

### View MAAS Region Service Logs (DEB)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/troubleshooting-and-operations.md

Retrieve the last 50 lines of logs for the MAAS region controller service to diagnose startup issues on DEB installations.

```bash
sudo journalctl -u maas-regiond.service -n 50
```

--------------------------------

### Discover Available STONITH Drivers

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/variables.md

Commands to list installed STONITH drivers and retrieve metadata for a specific driver. This is useful for identifying compatible fencing hardware and understanding their configuration options.

```bash
stonith_admin --list-installed
```

```bash
stonith_admin --metadata --agent <driver>
```

--------------------------------

### Configure Pacemaker Shell Script Template

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/templates-and-configuration.md

Shell script template to configure Pacemaker cluster resources, including PostgreSQL, floating IP, constraints, and STONITH. Generated on the first node during Pacemaker installation.

```bash
#!/bin/bash
# Configures:
# 1. PostgreSQL resource (pgsql-ha)
# 2. Floating IP resource ({{ maas_postgres_floating_ip }})
# 3. Resource constraints and ordering
# 4. STONITH (fencing) configuration

# Execution:
#   pcs cluster cib {{ maas_pacemaker_tmp_cib }}
#   # Edit CIB file with resources
#   pcs cluster push cib {{ maas_pacemaker_tmp_cib }}

# Key Resources Configured:

## PostgreSQL Resource
resource primitive pgsql-ha ocf:heartbeat:pgsql \
  params \
    pgctl="/usr/lib/postgresql/{{ version }}/bin/pg_ctl" \
    pgdata="/var/lib/postgresql/{{ version }}/main" \
    stop_escalate_in_sec="300" \
    masterScore="1000"

## Floating IP Resource
resource primitive floating-ip ocf:heartbeat:IPaddr2 \
  params \
    ip="{{ maas_postgres_floating_ip }}" \
    cidr_netmask="{{ maas_postgres_floating_ip_prefix_len }}"

## Constraints
colocation add floating-ip-with-pgsql floating-ip with pgsql-ha
order add fencing-then-pgsql Mandatory: stonith-cleanup-pgsql then pgsql-ha

```

--------------------------------

### Register MAAS Rack Controller (DEB)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Registers the MAAS rack controller with the region controller when installed via deb. This requires the MAAS URL and a secret. Applicable when `maas_installation_type` is 'deb'.

```bash
Condition: maas_installation_type == 'deb'

maas-rack register --url={{ maas_url }} --secret={{ maas_rack_secret }}
```

--------------------------------

### Configure RBAC with Launchpad/GitHub OAuth

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/observability-and-advanced.md

Enable RBAC (Role-Based Access Control) using Launchpad or GitHub OAuth for authentication. This requires specifying the RBAC URL and a candid-auth certificate file.

```bash
ansible-playbook site.yaml \
  --extra-vars="maas_rbac_url=https://rbac.internal/ \
    maas_candid_auth_file=/etc/maas/candid-auth.pem"
```

--------------------------------

### Enable TLS with Existing Certificates

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/observability-and-advanced.md

For production environments, enable TLS using pre-existing certificate files. Ensure the certificate and key paths are correctly specified.

```bash
# Copy certificates to hosts first, then:
ansible-playbook site.yaml \
  --extra-vars="enable_tls=true \
    generate_tls_cred=false \
    tls_key_path=/etc/ssl/private/maas.key \
    tls_cert_path=/etc/ssl/certs/maas.crt"
```

--------------------------------

### Update MAAS Region Controller (Snap)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Refreshes the MAAS snap installation to a specified channel. This is used for updating MAAS installations managed via snap.

```bash
# Snap channel refresh
snap refresh maas --channel={{ maas_version }}/{{ maas_snap_channel }}
```

--------------------------------

### Configure MAAS Observability

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Sets up MAAS observability integration with Prometheus and Loki. This command configures the proxy to send metrics to the specified URLs.

```bash
maas config-proxy set {{ o11y_prometheus_url }}
  --loki-url {{ o11y_loki_url }}
```

--------------------------------

### Full Stack MAAS Deployment

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/inventory-and-execution.md

Deploy a complete MAAS infrastructure from scratch. This command deploys all necessary components and requires several extra variables for configuration.

```bash
ansible-playbook -i hosts.yaml \
  --extra-vars="maas_url=http://example.com:5240/MAAS \
    maas_version=3.2 \
    maas_postgres_password=secret \
    maas_installation_type=deb" \
  site.yaml
```

--------------------------------

### Start HA Clusters Metrics Agent

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-postgres.md

Handler to start or restart the HA clusters metrics agent, ensuring it is enabled and that systemd's daemon configuration is reloaded.

```yaml
Name: Start HA clusters metrics agent
  systemd:
    name: ha_cluster_exporter
    enabled: true
    state: restarted
    daemon-reload: true
```

--------------------------------

### Update MAAS Region Controller (DEB)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Updates an existing MAAS installation to the latest version using APT. Ensure MAAS is already installed and the execution condition is met.

```bash
# APT update with latest version
apt-get update
apt-get install --upgrade maas-region-api
```

--------------------------------

### Re-create MAAS Backup

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/troubleshooting-and-operations.md

Execute the backup playbook with specific host and download path variables to ensure a correct backup is created.

```bash
ansible-playbook -i hosts.yaml \
  --limit "source_host" \
  --extra-vars="maas_backup_download_path=/tmp/" \
  backup.yaml
```

--------------------------------

### Ensure Pacemaker Service is Started

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/handlers-and-tasks-reference.md

Ensures the Pacemaker resource management service is started. Note that Pacemaker is intentionally not set to auto-start on reboot to allow for manual investigation before rejoining a cluster.

```yaml
Name: Ensure Pacemaker is started
Condition: Always
Effect: Start Pacemaker resource management service

Task Details:
  Module: ansible.builtin.systemd
  Service: pacemaker.service
  State: started
  Enabled: false   ← Note: NOT auto-start on reboot
  Wait: true (no_block: false)
```

--------------------------------

### MAAS Deployment with Observability Enabled

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/README.md

Deploy MAAS with observability features enabled. Configure the Prometheus URL for metrics collection.

```bash
# Deploy with observability
ansible-playbook -i ./hosts.yaml \
  --extra-vars="maas_version=3.2 ... \
    o11y_enable=true \
    o11y_prometheus_url=http://prometheus:9090/api/v1/write" \
  ./site.yaml
```

--------------------------------

### Check MAAS Snap Service Status

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/troubleshooting-and-operations.md

Verify the status of the MAAS snap installation by checking its information and services.

```bash
snap info maas
snap services maas
```

--------------------------------

### MAAS Package Detection (DEB)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-controllers.md

Detects if MAAS is installed when using DEB packages, checking against Ansible facts.

```yaml
For DEB:
  maas_installed = {{ maas_package_name }} in ansible_facts.packages
```

--------------------------------

### Schedule Daily MAAS Backups

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/observability-and-advanced.md

Schedule daily MAAS backups using cron and Ansible. Ensure the backup playbook path and download path are correctly specified.

```bash
# Schedule daily backups
0 2 * * * ansible-playbook -i /path/to/hosts.yaml \
  --extra-vars="maas_backup_download_path=/backups/" \
  /path/to/backup.yaml
```

--------------------------------

### PostgreSQL Tmpfiles.d Configuration Template

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/templates-and-configuration.md

Systemd tmpfiles.d configuration template to ensure PostgreSQL runtime directories exist when Pacemaker brings up the resource. Survives reboots.

```yaml
# Creates temporary runtime directories for PostgreSQL managed by Pacemaker
# Survives across reboots (not in /tmp)

d   /var/run/postgresql              0755  postgres  postgres  -
d   /var/run/postgresql/{{ version }}       0755  postgres  postgres  -

```

--------------------------------

### Clone MAAS Ansible Playbook Repository

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/README.md

Use this command to clone the MAAS-ansible-playbook repository from GitHub. Ensure you have Git installed.

```bash
git clone git@github.com:canonical/maas-ansible-playbook
```

--------------------------------

### Verify Required Variables for MAAS Deployment

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/troubleshooting-and-operations.md

Use this command to ensure all necessary variables are provided when deploying MAAS. Required variables include maas_url, maas_version, maas_postgres_password, and maas_installation_type.

```bash
# Verify all required variables are provided:
ansible-playbook site.yaml \
  --extra-vars="maas_url=http://... \
    maas_version=3.2 \
    maas_postgres_password=secret \
    maas_installation_type=deb"
```

--------------------------------

### PostgreSQL Replication Query Example

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/README.md

This is an SQL query to check replication status in PostgreSQL. It selects all columns from the pg_stat_replication view.

```sql
SELECT * FROM pg_stat_replication;
```

--------------------------------

### Check for Port Conflicts

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/troubleshooting-and-operations.md

Identify if port 5240 is already in use by another process, which can prevent MAAS services from starting.

```bash
sudo netstat -tlnp | grep 5240
```

--------------------------------

### Create Additional Admin Users

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/observability-and-advanced.md

Use this playbook to create additional administrative users in MAAS. Specify the username, password, email, and optionally a Launchpad username for SSH key association.

```bash
# Create additional admin users
ansible-playbook createadmin.yaml \
  --extra-vars="user_name=ops_user \
    user_pwd=secure_password \
    user_email=ops@example.com \
    user_ssh=lp:launchpad_username"
```

--------------------------------

### Ensure Pacemaker Service is Started

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/roles-postgres.md

Handler to ensure the Pacemaker service is running and enabled. Note that it is set to manual restart on reboot.

```yaml
Name: Ensure Pacemaker is started
  systemd:
    name: pacemaker.service
    state: started
    enabled: false  # Manual restart on reboot
    no_block: false
```

--------------------------------

### Complete MAAS Teardown

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/inventory-and-execution.md

Performs a complete teardown of the MAAS installation, removing all components and packages. It is crucial to back up data before executing this command.

```bash
ansible-playbook -i hosts.yaml teardown.yaml
```

--------------------------------

### Monitor MAAS Cluster and PostgreSQL Replication

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/troubleshooting-and-operations.md

Real-time monitoring commands for HAProxy, cluster status, and PostgreSQL replication lag and slot status.

```bash
sudo crm_mon -A  # Auto-update
```

```sql
-- Check standby lag
SELECT client_addr, write_lag, flush_lag, replay_lag FROM pg_stat_replication;
```

```sql
-- Check replication slot status
SELECT slot_name, slot_type, active, restart_lsn FROM pg_replication_slots;
```

```bash
# Backend health
echo "show stat" | sudo socat - /run/haproxy/admin.sock
```

```bash
# Real-time updates
watch -n 1 'echo "show stat" | sudo socat - /run/haproxy/admin.sock'
```

--------------------------------

### Dynamic Memory Calculation for PostgreSQL

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/templates-and-configuration.md

Illustrates how memory parameters for PostgreSQL are dynamically calculated based on system memory and connection counts.

```python
shared_buffers = system_memory / 4
effective_cache_size = system_memory * 0.75
work_mem = system_memory / max_connections / 10
maintenance_work_mem = system_memory / 20

```

--------------------------------

### Project Structure

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/overview.md

Illustrates the directory and file organization of the MAAS Ansible Playbook project.

```yaml
maas-ansible-playbook/
├── site.yaml                    # Main deployment playbook
├── teardown.yaml               # Complete infrastructure teardown
├── backup.yaml                 # Database and configuration backup
├── restore.yaml                # Restore from backup
├── createadmin.yaml            # Create new admin user
├── alertrules.yaml             # Export observability alert rules
├── hosts.yaml                  # Example inventory file
├── roles/                       # Ansible roles
│   ├── common/                  # Shared tasks (TLS, backup, restore, vault, firewall)
│   ├── maas_postgres/           # PostgreSQL database setup (single/HA)
│   ├── maas_corosync/           # Corosync clustering for HA quorum
│   ├── maas_pacemaker/          # Pacemaker HA resource management
│   ├── maas_postgres_proxy/     # HAProxy for HA PostgreSQL
│   ├── maas_region_controller/  # MAAS region controller installation
│   ├── maas_rack_controller/    # MAAS rack controller installation
│   ├── maas_proxy/              # HAProxy for region controller HA
│   ├── maas_firewall/           # Firewall rules (iptables)
│   └── o11y_agent/              # Observability/monitoring agent (Grafana)

```

--------------------------------

### Check PostgreSQL Connection Details

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/troubleshooting-and-operations.md

Verify PostgreSQL version, user existence, and pg_hba.conf settings to diagnose connection refused errors. These commands are run on the database host.

```bash
# On database host:
sudo -u postgres psql -c "SELECT version();"
```

```bash
# Verify user exists:
sudo -u postgres psql -c "\du"
```

```bash
# Check pg_hba.conf:
sudo cat /etc/postgresql/14/main/pg_hba.conf | grep maas
```

--------------------------------

### Define a Custom Handler

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/handlers-and-tasks-reference.md

Define a custom handler in the `handlers/main.yaml` file of a role. This example shows how to restart a systemd service named 'custom.service'.

```yaml
# roles/custom_role/handlers/main.yaml
---
- name: "Custom Handler"
  ansible.builtin.systemd:
    name: custom.service
    state: restarted
```

--------------------------------

### Enable TLS with Existing Certificates

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/variables.md

Use this snippet to enable TLS for MAAS and specify paths to your existing private key and certificate files. This is suitable for production environments with pre-managed certificates.

```yaml
# Example: use existing certificates
ansible-playbook site.yaml \
  --extra-vars="enable_tls=true \
    generate_tls_cred=false \
    tls_key_path=/etc/ssl/private/custom.pem \
    tls_cert_path=/etc/ssl/crt/custom.crt"
```

--------------------------------

### PostgreSQL Server Configuration Template (postgresql.conf.j2)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/templates-and-configuration.md

Generates the main PostgreSQL server configuration file, optimizing settings for MAAS. Includes dynamic memory calculations and HA-specific replication settings.

```yaml
Connection Settings:
  listen_addresses: '*'
  port: 5432
  max_connections: {{ maas_postgres_max_connections | default(200) }}

Memory Configuration (system-dependent):
  shared_buffers: {{ ansible_memtotal_mb // 4 }}MB
  effective_cache_size: {{ (ansible_memtotal_mb * 0.75) | int }}MB
  work_mem: {{ (ansible_memtotal_mb // max_connections) | int }}MB
  maintenance_work_mem: {{ (ansible_memtotal_mb // 20) | int }}MB

Write-Ahead Logging:
  wal_level: {{ maas_postgres_wal_level | default('replica') }}
  max_wal_senders: {{ maas_postgres_max_wal_senders | default(10) }}
  wal_keep_size: {{ maas_postgres_wal_keep_size | default(1024) }}MB

Logging:
  logging_collector: on
  log_directory: 'pg_log'
  log_filename: 'postgresql-%Y-%m-%d_%H%M%S.log'
  log_statement: 'all'
  log_duration: on

Replication (HA only):
  {% if maas_ha_postgres_enabled %}
  synchronous_commit: {{ maas_postgres_synchronous_commit | default('off') }}
  synchronous_standby_names: {{ maas_postgres_sync_standby_names | default("'*'") }}
  {% endif %}

Recovery (Standby only):
  {% if maas_ha_postgres_enabled and inventory_hostname != groups['maas_postgres'][0] %}
  primary_conninfo: 'host={{ primary_host }} user={{ maas_postgres_replication_user }} password={{ maas_postgres_replication_password }}'
  restore_command: ...
  {% endif %}

```

--------------------------------

### Check MAAS Region Service Status (DEB)

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/troubleshooting-and-operations.md

Use this command to check the current status of the MAAS region controller service on DEB installations.

```bash
sudo systemctl status maas-regiond.service
```

--------------------------------

### MAAS PostgreSQL Inventory Group Example

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/README.md

This is a YAML structure defining the 'maas_postgres' inventory group for Ansible. It specifies the hosts that will act as PostgreSQL instances.

```yaml
maas_postgres:
  hosts:
    db01.example.com:
```

--------------------------------

### View and Test STONITH Fencing Configuration

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/troubleshooting-and-operations.md

List configured STONITH (fencing) devices and test a specific fencing device. This is crucial for verifying that failed nodes can be properly isolated.

```bash
# List configured stonith devices:
sudo pcs stonith config

# Test fencing device:
sudo pcs stonith fence {{ node_name }}

# Check IPMI connectivity (ipmilan driver):
sudo ipmitool -I lanplus -U {{ ipmi_user }} -P {{ ipmi_pass }} -H {{ ipmi_host }} power status
```

--------------------------------

### Start Grafana Agent Service

Source: https://github.com/canonical/maas-ansible-playbook/blob/main/_autodocs/observability-and-advanced.md

Configures and restarts the Grafana Agent service using systemd. Ensure the 'telemetry' service is correctly named and enabled.

```yaml
Name: Start grafana agent
  systemd:
    name: telemetry
    enabled: true
    state: restarted
    daemon-reload: true
```