Ansible on Nutanix AHV Automation Complete Guide

Nutanix AHV is the native KVM-based hypervisor in the Nutanix Cloud Platform (NCI). It's managed through Prism Central (multi-cluster) and Prism Element (per-cluster). Ansible automates AHV via the official nutanix.ncp collection, which targets Prism Central v3 and v4 APIs and covers VMs, categories, projects, images, subnets, and NCM Self-Service (formerly Calm) blueprints. This is the master Ansible guide for Nutanix AHV.

Nutanix release facts

Prerequisites and install

Nutanix automation runs from a control node against Prism Central — you install nothing on the AHV hosts. On the control node:

ansible-galaxy collection install nutanix.ncp
pip install requests

Use ansible-core 2.15 or newer, and pin the collection in requirements.yml so runs are reproducible:

collections:
  - name: nutanix.ncp
    version: ">=2.0.0"

See also: AAP 2.7 Patch Release June 17, 2026: Metrics Backup, 18 CVE Fixes, FIPS Receptor, and Bug Fixes

v3 and v4 APIs

Prism Central exposes two API generations: the mature v3 API and the newer OpenAPI-based v4 API. The nutanix.ncp collection covers both. The widely available modules used in this guide (ntnx_vms, ntnx_images, and friends) target v3; where your Prism Central version supports v4, the collection also ships v4 modules that follow the same task patterns. Pick one generation per playbook and stay consistent.

Authentication

Every module authenticates to Prism Central with the same connection variables. Keep them in group_vars, encrypt the password with Ansible Vault, and use a scoped service account rather than admin:

# group_vars/nutanix.yml
nutanix_host: pc.lab.example.com      # Prism Central FQDN or VIP
nutanix_username: svc-ansible
nutanix_password: "{{ vault_nutanix_password }}"
nutanix_port: 9440
validate_certs: false                 # set true in production with a valid PC certificate

> To avoid repeating the connection details on every task, define them once as variables (as above) or with module_defaults.

See also: AAP 2.7: Removing Direct API Access — Migration Guide and aap-detect-direct-component-access Tool

Create a VM

- name: Create AHV VM via Prism Central
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Provision VM
      nutanix.ncp.ntnx_vms:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: false
        state: present
        name: app-01
        cluster:
          name: PROD-CLUSTER
        memory_gb: 8
        vcpus: 4
        cores_per_vcpu: 1
        networks:
          - is_connected: true
            subnet:
              name: vlan100
        disks:
          - type: DISK
            size_gb: 80
            bus: SCSI
        boot_config:
          boot_type: UEFI
          boot_order:
            - DISK
            - CDROM
            - NETWORK
        guest_customization:
          type: cloud_init
          script_path: ./cloud-init/app-01.yaml

Query and delete VMs

Use the info module to look up VMs — for reporting, or to grab a VM's UUID and IP — and state: absent to decommission one:

- name: Query and remove a VM
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Find VMs by name
      nutanix.ncp.ntnx_vms_info:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: false
        filter:
          vm_name: app-01
      register: vms

    - name: Show the matching VMs (name, UUID, IPs)
      ansible.builtin.debug:
        var: vms.response

    - name: Delete a VM by its UUID
      nutanix.ncp.ntnx_vms:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: false
        state: absent
        vm_uuid: "{{ target_vm_uuid }}"

Creating with state: present keyed on a stable name is idempotent — re-running reports no change. Deletion needs the VM's uuid, which the info module returns in each VM's metadata.

See also: AAP 2.7 Upgrade Path: RPM Installer Removed, Containerized-Only, and the Mandatory 2.6 Stepping Stone

Categories and projects

- name: Tag VM with categories
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Apply categories
      nutanix.ncp.ntnx_vms:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: false
        state: present
        name: app-01
        categories:
          Environment:
            - Production
          AppType:
            - Web

Image upload

- name: Upload image to Prism Central
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Upload Ubuntu 24.04 cloud image
      nutanix.ncp.ntnx_images:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: false
        state: present
        name: ubuntu-24.04-server-cloudimg
        image_type: DISK_IMAGE
        source_uri: "https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-amd64.img"
        clusters:
          - name: PROD-CLUSTER

Run a Calm blueprint

- name: Launch a NCM Self-Service blueprint
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Launch blueprint
      nutanix.ncp.ntnx_blueprints:
        nutanix_host: "{{ nutanix_host }}"
        nutanix_username: "{{ nutanix_username }}"
        nutanix_password: "{{ nutanix_password }}"
        validate_certs: false
        state: present
        name: bp-three-tier-web
        project:
          name: WebApps

Best practices

• Manage Nutanix at the Prism Central layer, never per-Prism Element, for multi-cluster consistency.
• Tag everything with categories; use them in Flow security policies and Self-Service entitlements.
• Use API keys / service accounts with role-based access; avoid admin.
• Pin to v4 API where supported; fall back to v3 for older modules. The collection abstracts this transparently.

FAQ

Q. Which collection automates Nutanix? The official nutanix.ncp collection — install it with ansible-galaxy collection install nutanix.ncp. It targets Prism Central, not individual AHV hosts.

Q. Do I point Ansible at Prism Central or Prism Element? Prism Central. Managing at that layer gives you one control point across every registered cluster; the modules run on the control node and call the Prism Central REST API on port 9440.

Q. v3 or v4 API — which should I use? Use the v3 modules shown here for the widest compatibility. If your Prism Central version supports the v4 API, the collection's v4 modules follow the same patterns — just pick one generation per playbook and stay consistent.

Q. How do I keep credentials out of playbooks? Put the connection variables in group_vars, encrypt the password with Ansible Vault, and use a scoped service account instead of admin.

Q. Is VM creation idempotent? Yes — creating with state: present keyed on a stable VM name converges, so re-running reports no change. Deletion uses the VM's uuid returned by the info module.

Related Articles

• automate Proxmox VE with Ansible
• configure Ansible for VMware vSphere
• build dynamic inventories from your platform API
• encrypt credentials with Ansible Vault
• how Ansible inventory works

Conclusion

Nutanix AHV + nutanix.ncp gives you a clean Ansible interface to the entire Nutanix Cloud Platform — VMs, images, categories, projects, subnets, and NCM Self-Service blueprints — all through Prism Central. Standardize on a Prism Central service account in Vault, tag everything with categories, key VM creation on stable names for idempotency, and you can manage Nutanix HCI declaratively and at scale.