Automating Nutanix Backup with Ansible

Last updated: March 4, 2026

---

Table of Contents

1. Why I Automated Nutanix Backups with Ansible

2. Nutanix Backup and Snapshot Concepts

3. Installing the nutanix.ncp Ansible Collection

4. Inventory and Credentials Setup

5. Taking VM Snapshots with Ansible

6. Working with Protection Domains via Prism Element API

7. Application-Consistent Snapshots with Pre/Post Tasks

8. Snapshot Retention and Cleanup

9. Backup Verification Playbook

10. Scheduling Playbooks with AAP or Cron

11. What Works Well and What Does Not

---

Why I Automated Nutanix Backups with Ansible

Nutanix's built-in protection domain scheduler is functional — you set a cron-like schedule in Prism Element and snapshots happen automatically. But this approach has limitations that matter for my home-lab projects:

• No pre/post hooks: I cannot quiesce a database or flush a write cache before the snapshot fires

• No external notification: I want a webhook or log entry that tells me backups succeeded or failed

• No conditional logic: I want to skip a backup if a particular service is actively running a migration

Ansible gives me full control: I write the backup flow as tasks, add pre/post database quiescing, log to a file, and run it on a schedule via cron or Ansible Automation Platform (AAP) if it's available.

---

Nutanix Backup and Snapshot Concepts

Before writing playbooks, it helps to understand the two distinct layers of backup in Nutanix:

VM Snapshots (Local)

A VM snapshot in Nutanix is a point-in-time copy of a VM's vDisks, stored locally on the same NDFS cluster. These use redirect-on-write copy-on-write semantics — reads from the snapshot point to original blocks, new writes go to new locations.

Local snapshots are:

• Fast to create and restore

• Limited by local cluster capacity

• Not a substitute for off-site backup

Protection Domains (Prism Element)

A Protection Domain (PD) is an older but still widely used mechanism managed at the Prism Element level. A PD:

• Contains one or more VMs (or consistency groups)

• Has a local snapshot schedule (how often snapshots run, how many to keep)

• Optionally has remote replication configured to replicate snapshots to a remote Nutanix cluster

Protection Policies and Nutanix DR (Prism Central)

The newer model, managed via Prism Central, uses:

• Protection Policies — define RPO (Recovery Point Objective), retention count, and optional replication targets

• Recovery Plans — define how applications fail over to a remote site

For my single-cluster home-lab, I work primarily with local VM snapshots and Protection Domains via the Prism Element API.

---

Installing the nutanix.ncp Ansible Collection

The official Nutanix Ansible collection is published on Ansible Galaxy:

ansible-galaxy collection install nutanix.ncp

Verify installation:

ansible-galaxy collection list | grep nutanix
# nutanix.ncp   1.9.0

Key modules relevant to backup:

Module	Purpose
nutanix.ncp.ntnx_vms_info	Query VM details (get UUID by name)
nutanix.ncp.ntnx_vm_snapshots	Create/delete VM snapshots (v4 API)
nutanix.ncp.ntnx_vm_snapshots_info	List existing snapshots
nutanix.ncp.ntnx_protection_rules	Manage PC protection rules

For direct Prism Element protection domain operations, the nutanix.ncp modules target the Prism Central (PC) API. For PE-level PD management, I use the uri module against the Prism Element REST API directly.

---

Inventory and Credentials Setup

Inventory File

# inventory/nutanix.ini
[nutanix_api]
prism_central ansible_host=192.168.1.50 ansible_connection=local

[nutanix_vms]
my-web-vm  ansible_host=192.168.1.101 ansible_user=ubuntu ansible_ssh_private_key_file=~/.ssh/id_rsa
my-db-vm   ansible_host=192.168.1.102 ansible_user=ubuntu ansible_ssh_private_key_file=~/.ssh/id_rsa

The ansible_connection=local for the Prism Central entry is intentional — the nutanix.ncp modules make API calls from the control node, not via SSH to Prism Central.

Vault-Encrypted Credentials File

# Create vault-encrypted credentials
ansible-vault create vars/nutanix_credentials.yml

Contents (vars/nutanix_credentials.yml):

# vars/nutanix_credentials.yml (ansible-vault encrypted)
nutanix_host: "192.168.1.50"
nutanix_port: 9440
nutanix_username: "admin"
nutanix_password: "your-prism-central-password"
nutanix_validate_certs: false  # set true if you have valid certs

# Prism Element credentials (may differ from PC)
prism_element_host: "192.168.1.51"
prism_element_port: 9440
prism_element_username: "admin"
prism_element_password: "your-prism-element-password"

Reference in playbooks:

ansible-playbook backup.yml --vault-id @prompt -e @vars/nutanix_credentials.yml

---

Taking VM Snapshots with Ansible

The nutanix.ncp.ntnx_vm_snapshots module uses the v4 API introduced in Prism Central 2023.x and later.

Playbook: Create VM Snapshot

---
# playbooks/nutanix_vm_snapshot.yml
- name: Create VM snapshots on Nutanix
  hosts: nutanix_api
  gather_facts: false
  vars_files:
    - ../vars/nutanix_credentials.yml

  vars:
    snapshot_timestamp: "{{ lookup('pipe', 'date +%Y%m%d-%H%M%S') }}"
    vms_to_snapshot:
      - "my-web-vm"
      - "my-db-vm"

  tasks:
    - name: Get VM UUID by name
      nutanix.ncp.ntnx_vms_info:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_port: "{{ nutanix_port }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: "{{ nutanix_validate_certs }}"
        filter:
          name: "{{ item }}"
      loop: "{{ vms_to_snapshot }}"
      register: vm_info_results

    - name: Build VM UUID list
      set_fact:
        vm_uuid_map: >-
          {{
            vm_uuid_map | default({}) | combine(
              { item.item: item.response.entities[0].metadata.uuid }
            )
          }}
      loop: "{{ vm_info_results.results }}"
      when: item.response.entities | length > 0

    - name: Create snapshot for each VM
      nutanix.ncp.ntnx_vm_snapshots:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_port: "{{ nutanix_port }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: "{{ nutanix_validate_certs }}"
        state: present
        vm_uuid: "{{ vm_uuid_map[item] }}"
        name: "backup-{{ item }}-{{ snapshot_timestamp }}"
      loop: "{{ vms_to_snapshot }}"
      when: vm_uuid_map[item] is defined
      register: snapshot_results

    - name: Report snapshot results
      debug:
        msg: "Snapshot created for {{ item.item }}: {{ item.uuid | default('check Prism Central') }}"
      loop: "{{ snapshot_results.results }}"

Playbook: List Existing Snapshots

---
# playbooks/nutanix_list_snapshots.yml
- name: List VM snapshots
  hosts: nutanix_api
  gather_facts: false
  vars_files:
    - ../vars/nutanix_credentials.yml

  tasks:
    - name: List all snapshots for a VM
      nutanix.ncp.ntnx_vm_snapshots_info:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_port: "{{ nutanix_port }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: "{{ nutanix_validate_certs }}"
        vm_uuid: "{{ target_vm_uuid }}"
      register: snapshots

    - name: Print snapshot summary
      debug:
        msg: "{{ item.name }} | Created: {{ item.creation_time }}"
      loop: "{{ snapshots.response.entities }}"

---

Working with Protection Domains via Prism Element API

For protection domain management (more control over schedules and retain count), I use the Prism Element REST API v2 via Ansible's uri module, since the nutanix.ncp collection targets Prism Central.

Playbook: List Protection Domains

---
# playbooks/nutanix_list_pd.yml
- name: List Nutanix Protection Domains
  hosts: nutanix_api
  gather_facts: false
  vars_files:
    - ../vars/nutanix_credentials.yml

  tasks:
    - name: Get all protection domains from Prism Element
      uri:
        url: "https://{{ prism_element_host }}:{{ prism_element_port }}/api/nutanix/v2.0/protection_domains"
        method: GET
        user: "{{ prism_element_username }}"
        password: "{{ prism_element_password }}"
        force_basic_auth: true
        validate_certs: "{{ nutanix_validate_certs }}"
        return_content: true
        headers:
          Content-Type: "application/json"
      register: pd_list

    - name: Show protection domains
      debug:
        msg: "PD: {{ item.name }} | Active: {{ item.active }} | VMs: {{ item.vms | map(attribute='vm_name') | list }}"
      loop: "{{ pd_list.json.entities }}"

Playbook: Trigger a Manual Snapshot of a Protection Domain

---
# playbooks/nutanix_pd_snapshot.yml
- name: Trigger manual PD snapshot
  hosts: nutanix_api
  gather_facts: false
  vars_files:
    - ../vars/nutanix_credentials.yml

  vars:
    protection_domain_name: "my-vms-pd"

  tasks:
    - name: Trigger manual snapshot for protection domain
      uri:
        url: "https://{{ prism_element_host }}:{{ prism_element_port }}/api/nutanix/v2.0/protection_domains/{{ protection_domain_name }}/oob_schedules"
        method: POST
        user: "{{ prism_element_username }}"
        password: "{{ prism_element_password }}"
        force_basic_auth: true
        validate_certs: "{{ nutanix_validate_certs }}"
        headers:
          Content-Type: "application/json"
        body_format: json
        body: {}
        status_code: [200, 201]
      register: snapshot_trigger

    - name: Confirm snapshot trigger
      debug:
        msg: "Snapshot triggered for PD '{{ protection_domain_name }}': {{ snapshot_trigger.status }}"

Playbook: Add a VM to a Protection Domain

---
# playbooks/nutanix_pd_add_vm.yml
- name: Add VM to Nutanix Protection Domain
  hosts: nutanix_api
  gather_facts: false
  vars_files:
    - ../vars/nutanix_credentials.yml

  vars:
    protection_domain_name: "my-vms-pd"
    vm_uuid_to_add: "{{ target_vm_uuid }}"  # pass via -e

  tasks:
    - name: Add VM UUID to protection domain
      uri:
        url: "https://{{ prism_element_host }}:{{ prism_element_port }}/api/nutanix/v2.0/protection_domains/{{ protection_domain_name }}/protect_vms"
        method: POST
        user: "{{ prism_element_username }}"
        password: "{{ prism_element_password }}"
        force_basic_auth: true
        validate_certs: "{{ nutanix_validate_certs }}"
        headers:
          Content-Type: "application/json"
        body_format: json
        body:
          uuids:
            - "{{ vm_uuid_to_add }}"
        status_code: [200, 201]
      register: add_result

    - name: Confirm
      debug:
        msg: "VM added to PD '{{ protection_domain_name }}': {{ add_result.status }}"

---

Application-Consistent Snapshots with Pre/Post Tasks

A crash-consistent snapshot is fine for stateless VMs. For database VMs, I want an application-consistent snapshot, which means:

1. Tell the database to flush its write buffers to disk

2. Take the snapshot

3. Resume normal database operation

Nutanix does not have a built-in VSS or quiescing mechanism for Linux VMs beyond the AHV agent (which handles only basic crash consistency). For PostgreSQL on Linux, I handle this manually in the playbook with a pre/post hook.

---
# playbooks/nutanix_db_consistent_snapshot.yml
- name: Application-consistent snapshot of DB VM
  hosts: my-db-vm
  gather_facts: false
  vars_files:
    - ../vars/nutanix_credentials.yml

  vars:
    db_vm_name: "my-db-vm"
    snapshot_timestamp: "{{ lookup('pipe', 'date +%Y%m%d-%H%M%S') }}"

  tasks:
    # ----- Pre-snapshot: quiesce PostgreSQL -----
    - name: Create PostgreSQL backup checkpoint
      become: true
      community.postgresql.postgresql_query:
        login_user: postgres
        db: appdb
        query: "CHECKPOINT;"
      register: checkpoint_result

    - name: Confirm checkpoint completed
      debug:
        msg: "PostgreSQL checkpoint result: {{ checkpoint_result }}"

    # ----- Take snapshot via API (delegate to localhost) -----
    - name: Get DB VM UUID
      delegate_to: localhost
      nutanix.ncp.ntnx_vms_info:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_port: "{{ nutanix_port }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: "{{ nutanix_validate_certs }}"
        filter:
          name: "{{ db_vm_name }}"
      register: db_vm_info

    - name: Create application-consistent snapshot
      delegate_to: localhost
      nutanix.ncp.ntnx_vm_snapshots:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_port: "{{ nutanix_port }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: "{{ nutanix_validate_certs }}"
        state: present
        vm_uuid: "{{ db_vm_info.response.entities[0].metadata.uuid }}"
        name: "app-consistent-{{ db_vm_name }}-{{ snapshot_timestamp }}"
      register: snap_result

    - name: Log snapshot creation
      delegate_to: localhost
      lineinfile:
        path: "/var/log/nutanix_backups.log"
        line: "{{ snapshot_timestamp }} | {{ db_vm_name }} | {{ snap_result.uuid | default('unknown') }} | SUCCESS"
        create: true
        mode: '0644'

    # ----- Post-snapshot: confirm database is healthy -----
    - name: Verify PostgreSQL is responding
      become: true
      community.postgresql.postgresql_query:
        login_user: postgres
        db: appdb
        query: "SELECT 1;"
      register: db_health

    - name: Confirm DB health post-snapshot
      debug:
        msg: "Database is healthy post-snapshot: {{ db_health.query_result }}"

---

Snapshot Retention and Cleanup

Without a cleanup policy, snapshots accumulate and consume NDFS capacity. My retention policy: keep the last 7 daily snapshots for each VM.

---
# playbooks/nutanix_snapshot_cleanup.yml
- name: Clean up old VM snapshots
  hosts: nutanix_api
  gather_facts: false
  vars_files:
    - ../vars/nutanix_credentials.yml

  vars:
    retention_days: 7
    vms_to_manage:
      - name: "my-web-vm"
        vm_uuid: "{{ web_vm_uuid }}"
      - name: "my-db-vm"
        vm_uuid: "{{ db_vm_uuid }}"

  tasks:
    - name: List snapshots for each VM
      nutanix.ncp.ntnx_vm_snapshots_info:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_port: "{{ nutanix_port }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: "{{ nutanix_validate_certs }}"
        vm_uuid: "{{ item.vm_uuid }}"
      loop: "{{ vms_to_manage }}"
      register: all_snapshots

    - name: Identify snapshots older than retention period
      set_fact:
        stale_snapshots: >-
          {{
            stale_snapshots | default([]) +
            (item.response.entities
              | selectattr('creation_time', 'defined')
              | sort(attribute='creation_time')
              | list)[:-retention_days]
          }}
      loop: "{{ all_snapshots.results }}"
      when: item.response.entities | length > retention_days

    - name: Delete stale snapshots
      nutanix.ncp.ntnx_vm_snapshots:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_port: "{{ nutanix_port }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: "{{ nutanix_validate_certs }}"
        state: absent
        snapshot_uuid: "{{ item.uuid }}"
      loop: "{{ stale_snapshots | default([]) }}"
      register: deleted

    - name: Report deleted snapshots
      debug:
        msg: "Deleted snapshot {{ item.item.name }} ({{ item.item.uuid }})"
      loop: "{{ deleted.results | default([]) }}"

---

Backup Verification Playbook

Creating a snapshot is not the same as verifying the data is recoverable. For critical VMs, I run a periodic verification by restoring a snapshot to a temporary VM and checking that the data is present.

---
# playbooks/nutanix_backup_verify.yml
- name: Verify last VM snapshot by restore test
  hosts: nutanix_api
  gather_facts: false
  vars_files:
    - ../vars/nutanix_credentials.yml

  vars:
    source_vm_name: "my-db-vm"
    test_restore_vm_name: "verify-restore-{{ lookup('pipe', 'date +%Y%m%d') }}"

  tasks:
    - name: Get latest snapshot UUID for source VM
      nutanix.ncp.ntnx_vm_snapshots_info:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_port: "{{ nutanix_port }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: "{{ nutanix_validate_certs }}"
        vm_uuid: "{{ source_vm_uuid }}"
      register: snap_list

    - name: Extract most recent snapshot
      set_fact:
        latest_snapshot: >-
          {{
            snap_list.response.entities
            | sort(attribute='creation_time', reverse=true)
            | first
          }}

    - name: Show selected snapshot
      debug:
        msg: "Will restore: {{ latest_snapshot.name }} ({{ latest_snapshot.uuid }})"

    - name: Clone VM from snapshot
      nutanix.ncp.ntnx_vms:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_port: "{{ nutanix_port }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: "{{ nutanix_validate_certs }}"
        state: present
        name: "{{ test_restore_vm_name }}"
        clone_vm:
          vm_snapshot_uuid: "{{ latest_snapshot.uuid }}"
      register: cloned_vm

    - name: Wait for cloned VM to power on
      pause:
        seconds: 60

    # ---- Delegate verification to the cloned VM ----
    - name: Verify PostgreSQL data on restored VM
      delegate_to: "{{ cloned_vm.ip_address }}"
      community.postgresql.postgresql_query:
        login_user: postgres
        db: appdb
        query: "SELECT COUNT(*) FROM users;"
      register: verify_result
      retries: 5
      delay: 15
      until: verify_result is not failed

    - name: Log verification result
      lineinfile:
        path: "/var/log/nutanix_backups.log"
        line: "{{ lookup('pipe', 'date +%Y%m%d-%H%M%S') }} | VERIFY | {{ source_vm_name }} | {{ latest_snapshot.name }} | rows={{ verify_result.query_result[0].count }}"
        create: true

    - name: Delete test restore VM
      nutanix.ncp.ntnx_vms:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_port: "{{ nutanix_port }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: "{{ nutanix_validate_certs }}"
        state: absent
        vm_uuid: "{{ cloned_vm.vm_uuid }}"

---

Scheduling Playbooks with AAP or Cron

Option 1: Cron on the Control Node

For a home-lab with no AAP, a simple cron job works fine:

# /etc/cron.d/nutanix-backup
# Daily snapshot at 02:00
0 2 * * * ansible-user /usr/bin/ansible-playbook \
    /opt/ansible/playbooks/nutanix_db_consistent_snapshot.yml \
    --vault-password-file /etc/ansible/.vault_pass \
    -e @/opt/ansible/vars/nutanix_credentials.yml \
    >> /var/log/nutanix_backup_cron.log 2>&1

# Weekly snapshot cleanup at 03:00 on Sunday
0 3 * * 0 ansible-user /usr/bin/ansible-playbook \
    /opt/ansible/playbooks/nutanix_snapshot_cleanup.yml \
    --vault-password-file /etc/ansible/.vault_pass \
    -e @/opt/ansible/vars/nutanix_credentials.yml \
    >> /var/log/nutanix_cleanup_cron.log 2>&1

Option 2: Ansible Automation Platform Job Templates

If you have AAP available, configure:

1. Project: Point to the Git repo containing your playbooks

2. Credential: Machine credential (vault password) and custom credential for Nutanix API

3. Job Template per playbook: nutanix-daily-snapshot, nutanix-weekly-cleanup, nutanix-backup-verify

4. Schedule: Set the recurrence within the job template (daily at 02:00, weekly cleanup, etc.)

This gives you full visibility into job run history, output logs, and failure notifications without managing cron manually.

---

What Works Well and What Does Not

What Works Well

• nutanix.ncp collection is well-maintained: The collection modules are idiomatic Ansible — good changed state tracking, consistent return values

• PE REST API is straightforward: For protection domain operations that lack a dedicated collection module, the raw REST API via uri is reliable and well-documented

• Vault integration: Standard Ansible Vault keeps Prism Central credentials out of plaintext files

• Pre/post snapshot hooks: The flexibility to quiesce applications before snapping is the main reason I chose Ansible over built-in Nutanix scheduler

What Does Not Work Well (or Needs Workarounds)

• The ntnx_vm_snapshots module requires Prism Central 2023.x+ (v4 API): Older PC versions need the Prism Element v2 API directly via uri

• Finding the right JSON path for VM IPs after snapshot restore: The response structure from ntnx_vms after a clone-from-snapshot operation changed between collection versions — always inspect actual output with debug: var=result first

• Snapshot restore to a new VM with networking: After cloning from snapshot, the VM comes up with the same network config as the original. If you're verifying on the same network segment, there will be a MAC/IP conflict unless you modify the clone's NIC config before powering it on

• The nutanix_validate_certs: false requirement for CE: Community Edition ships with a self-signed cert. In production, invest time in proper certificate management to avoid habitualizing the insecure flag

---

Next Steps

This completes the Nutanix 101 series. For further reading:

• Nutanix AHV Administration Guide — official reference for AHV operations

• Nutanix.ncp Ansible Collection on Galaxy — module reference and examples

• calm-dsl on GitHub — Blueprint DSL source and documentation

Go back to Nutanix 101 series index.