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

| Item | Value | |---|---| | Hypervisor | AHV (KVM-based) | | Management | Prism Central (multi-cluster), Prism Element (per-cluster) | | APIs | v3 (mature), v4 (modern, OpenAPI) | | Ecosystem | NCM Self-Service (Calm), Flow Networking, Files, Objects |

See also: Ansible AWS: Complete Guide to Cloud Automation (2026)

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"

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.

See also: Ansible Become: Privilege Escalation with sudo, su & runas (Complete Guide)

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.

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

See also: Ansible check_mode: Dry Run & Test Playbooks Without Making Changes

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.

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.