Automating Nutanix with Ansible: Foundations, Playbooks, and Best Practices

Introduction

Start by proving that your Ansible control node can authenticate to Prism Central and read AHV VM inventory. This guide uses nutanix.ncp.ntnx_vms_info_v2, which calls the v4 API. It does not create a VM. Provisioning belongs in a separate, version-matched exercise after connectivity, permissions, and input references have been verified.

My Personal Repository on GitHub

Nutanix Repository on GitHub

Step 1: Prerequisites

The examples below use the nutanix.ncp 2.5.0 release as a documented baseline, reviewed September 4, 2026. Check the release’s compatibility table against your actual AOS and Prism Central versions before installing it; older clusters may require a different collection and different examples.

• Use a Linux control node or another Ansible-supported UNIX-like environment. Windows users need a suitable WSL environment rather than native Windows PowerShell for these shell commands.
• Provide Python 3.12 or later, pip, and venv support. Nutanix lists ansible-core 2.16 or later for this collection; also check the Python support and compatibility of the Ansible version you choose.
• The 2.5.0 release table lists AOS 7.5/7.5.1 and Prism Central pc7.5/pc7.5.1 or later. This is a release-specific baseline, not a blanket statement that every newer combination is validated.
• Use the Prism Central endpoint for this AHV VM information module, an account permitted to view the intended VMs, network access to its API, and a valid certificate trusted by the controller’s Python environment.

In a new project folder on the control node, create an isolated Python environment. The commands below assume python3.12 is installed; use the path to your approved compatible interpreter if different. The engine constraint is a minimum, not a full tested dependency lock—record and approve the resolved versions before production use.

python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install "ansible-core>=2.16"
ansible --version

Step 2: Install the Nutanix Ansible Collection

Keep this collection inside the project next to the playbook. Then install the Python dependencies shipped with that exact release into the same active virtual environment. Do not skip the SDK dependencies.

ansible-galaxy collection install nutanix.ncp:2.5.0 -p ./collections
python -m pip install -r ./collections/ansible_collections/nutanix/ncp/requirements.txt

Verify the locally installed collection and review its module help. Keep inventory.yml, nutanix_credentials.yml, and read_vms.yml in this same project folder.

ansible-galaxy collection list -p ./collections nutanix.ncp
ANSIBLE_COLLECTIONS_PATH=./collections ansible-doc nutanix.ncp.ntnx_vms_info_v2

Step 3: Define Your Inventory

Create inventory.yml:

all:
  hosts:
    localhost:
      ansible_connection: local
      ansible_python_interpreter: "{{ ansible_playbook_python }}"

This inventory runs the API task on the control node; it does not SSH to a CVM, host, or VM. The interpreter setting keeps the task in the same Python environment as ansible-playbook, where you installed the Nutanix SDKs.

Step 4: Store Your Credentials

Create the credential file with ansible-vault create nutanix_credentials.yml, then put the following variable names in the editor it opens. Replace placeholders there, not in shell arguments. Use an account limited to the required inventory access rather than assuming a built-in administrator account.

nutanix_pc_hostname: "prism-central.example.com"
nutanix_pc_port: "9440"
nutanix_username: "REPLACE_WITH_APPROVED_ACCOUNT"
nutanix_password: "REPLACE_INSIDE_VAULT_EDITOR"

Save and close the Vault editor so the file is encrypted. For later changes, use the command below. Secure your editor’s temporary/backup files, keep the Vault password separate, and never commit plaintext credentials or print them while debugging. Vault protects stored data; it does not make secret-bearing logs safe.

ansible-vault edit nutanix_credentials.yml

Step 5: Write a Read-Only First Playbook

Create read_vms.yml. This uses the documented VM information module, passes credentials explicitly, keeps certificate validation enabled, and requests at most one VM record. no_log: true suppresses this task’s result from ordinary Ansible output; the final message confirms completion without printing inventory or credentials.

- name: Verify read-only access to Prism Central AHV inventory
  hosts: localhost
  gather_facts: false
  vars_files:
    - nutanix_credentials.yml

  tasks:
    - name: Read at most one AHV VM record
      nutanix.ncp.ntnx_vms_info_v2:
        nutanix_host: "{{ nutanix_pc_hostname }}"
        nutanix_port: "{{ nutanix_pc_port }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: true
        limit: 1
      no_log: true

    - name: Confirm the read completed
      ansible.builtin.debug:
        msg: "Prism Central inventory query completed. No VM was created or changed."

Step 6: Run the Playbook

ansible-playbook -i inventory.yml read_vms.yml --syntax-check --ask-vault-pass

# Only after syntax and compatibility checks pass, run the read-only API query:
ansible-playbook -i inventory.yml read_vms.yml --ask-vault-pass

Enter the Vault password when prompted. A syntax check does not prove API access. On the real run, expect no infrastructure changes; a successful query may return no visible VMs because the inventory is empty or the account is scoped. If it fails, check hostname/DNS, API reachability, SDK versions, account permissions, and the certificate’s hostname and trust chain. Fix trust for the Python environment instead of changing validate_certs to false. Do not disable log protection on a shared runner to expose a secret-bearing error.

Summary

You now have a sequence for preparing a version-matched Ansible environment, protecting stored credentials, checking syntax, and making a first read-only Prism Central request. A successful inventory query is the starting point—not proof that a deployment playbook or every cluster combination is ready for production.

Before adding VM creation, review the installed provisioning module’s exact schema and permissions, validate cluster/subnet/image references, and test lifecycle and rollback behavior in a lab. The references below are the sources for this revised starter.

• Nutanix collection 2.5.0 requirements and compatibility
• Nutanix: ntnx_vms_info_v2 module
• Nutanix: connection and certificate options
• Nutanix: information-query options
• Ansible: installing project-local collections
• Ansible: encrypting and editing Vault files