Nutanix Ansible

Official Nutanix Ansible Collection

Requirements

This collection requires ansible-core>=2.16.0 and the Python dependencies listed in requirements.txt.

Red Hat Ansible Automation Platform customers should use an Execution Environment (EE) that includes this collection and its dependencies rather than installing packages directly with pip. See the Red Hat Ansible Automation Platform documentation for guidance on building and using Execution Environments, and install the collection from Red Hat Automation Hub.

Community / upstream users can install dependencies into a Python environment after installing the collection: pip install -r ~/.ansible/collections/ansible_collections/nutanix/ncp/requirements.txt

About

Nutanix ansible collection nutanix.ncp is the official Nutanix ansible collection to automate Nutanix Cloud Platform (ncp).

It is designed keeping simplicity as the core value. Hence it is 1. Easy to use 2. Easy to develop

Checkout this blog for getting started with nutanix ansible module.

NOTE: The latest version of the Nutanix Ansible collection is v2.5.0.

Introducing Nutanix Ansible Collection Version v2.5.0

We are excited to announce the release of Nutanix Ansible Collection v2.5.0 — a major update that brings powerful new features, enhancements, and critical bug fixes for automating your Nutanix infrastructure.

What's New in v2.5.0

• Built on v4 APIs/SDKs This release continues to expand coverage of the latest Nutanix v4 APIs and SDKs, providing improved performance, stability, and alignment with the newest platform capabilities.

• New Resource Support

• Network Functions (Networking): Create, Update and Delete network functions using v4 SDKs. #850
• Entity Groups (Flow Management): Create, update, delete, and list entity groups for microsegmentation using v4 SDKs. #851
• Security Policy Rules listing (Flow Management): List all network security policy rules by policy ExtID using v4 SDKs. #852
• IAM Entities (IAM): List and get IAM entities using v4 SDKs. #854

• Virtual Switches (Networking): CRUD operations, migrate from existing bridge, list and get virtual switches using v4 SDKs. #905

• Major Improvements

• Global scope and intratier rules (ntnx_security_rules_v2): Add functionality for global scope, specific intratier rules, and subnet/VPC references. #853
• Read timeout (All v4 modules): Add configurable read_timeout functionality to all v4 modules to avoid failures when Prism Central responds slowly. #882
• Service Account API key authentication (All): Support authentication via Service Account API keys (X-Ntnx-Api-Key header) alongside local and LDAP accounts. #888
• Proxy support (All v4 modules): Add HTTP/HTTPS proxy support via module parameters or environment variables, with authentication and precedence control. #900
• Python 3.12 CI/CD (Internal): Update CI/CD pipeline and dependencies to Python 3.12 for compatibility with Ansible Core 2.16 and modern Python packaging. #915
• Invalid group name characters (ntnx_prism_vm_inventory): Handle invalid characters in cluster-based group names in inventory plugins. #917
• Separate Base Module for v4 (Internal): Create a dedicated BaseModulev4 class to avoid unnecessary flags for v4-only parameters. #918
• Karbon deprecation notice (Karbon): Add deprecation message for Karbon modules as Karbon is not supported on PC 7.3+. #921
• Required permissions documentation (All modules): Document required permissions for Ansible service account used across all modules. #769
• Bug Fixes and Stability Improvements
• NoneType crash in inventory plugins when VM fields are explicitly None #939
• Unnecessary required fields for state: present in module ntnx_subnets_v2 #895
• Missing total_available_results in response in module ntnx_password_managers_info_v2 #902
• vSwitches spec issue in module ntnx_foundation #749

Upgrade now to take advantage of these powerful features and streamline your Nutanix automation workflows!

Important Notice

Upcoming Deprecation of Legacy Nutanix Ansible Modules. Starting with the Nutanix Ansible Collection release planned for Q4-CY2026, legacy modules which are based on v0.8,v1,v2 and v3 APIs will be deprecated and no longer supported. For more information, visit Legacy API Deprecation Announcement Legacy API Deprecation - FAQs Nutanix strongly encourages you to migrate your scripts and applications to the latest v2 version of the Nutanix Ansible modules, which are built on our v4 APIs/SDKs. By adopting the latest v2 version based on v4 APIs and SDKs, our users can leverage the enhanced capabilities and latest innovations from Nutanix. We understand that this transition may require some effort, and we are committed to supporting you throughout the process. Please refer to our documentation and support channels for guidance and assistance. Version Suffix: To easily distinguish resources and data sources specific to version 2.0.0 and later, they are marked with the *_v2 suffix.

Support

As Red Hat Ansible Certified Content, this collection is entitled to support through the Ansible Automation Platform (AAP) using the Create issue button on the top right corner. If a support case cannot be opened with Red Hat and the collection has been obtained either from Galaxy or GitHub, there may community help available on the Ansible Forum.

Update!! We now have a brand new developer-centric Support Program designed for organizations that require a deeper level of developer support to manage their Nutanix environment and build applications quickly and efficiently. As part of this new Advanced API/SDK Support Program, you will get access to trusted technical advisors who specialize in developer tools including Nutanix Ansible Collections and receive support for your unique development needs and custom integration queries. Visit our Support Portal - Premium Add-On Support Programs to learn more about this program.

Customers not taking advantage of the Advanced API/SDK Support Program will continue to receive the support through our standard, community-supported model. This community model also provides support for contributions to the open-source Nutanix Ansible Collections repository.Visit Nutanix Portal KB for more details.

Version compatibility

Ansible

This collection requires ansible-core>=2.16.0. Red Hat Ansible Automation Platform customers should obtain ansible-core through an Execution Environment (EE) rather than installing it directly with pip. Community users should ensure their environment has the required version installed.

Python

This collection requires Python 3.12 or greater

Releases

SDK-PC-PE Compatibility

Notes:

1. Static routes module (ntnx_static_routes) is supported for PC versions >= pc.2022.1

2. Adding cluster references in projects module (ntnx_projects) is supported for PC versions >= pc.2022.1

3. For Users and User Groups modules (ntnx_users and ntnx_user_groups), adding Identity Provider (IdP) & Organizational Unit (OU) based users/groups are supported for PC versions >= pc.2022.1

4. ntnx_security_rules - The apptier option in target group has been removed. New option called apptiers has been added to support multi tier policy.

5. Currently NDB based modules are supported and tested against postgres based databases.

6. Karbon (NKE) modules are deprecated — Prism Central versions later than 7.3 no longer support Karbon. Karbon modules (ntnx_karbon_clusters, ntnx_karbon_clusters_node_pools, ntnx_karbon_registries, ntnx_karbon_clusters_info, ntnx_karbon_registries_info) will not be supported on PC versions later than 7.3 and will be removed in a future release.

Examples:

1. Prism Central

2. Foundation

3. Foundation Central

4. Karbon

5. NDB

Installing the collection

Prerequisite

Ansible should be pre-installed. If not, please follow official ansible install guide .

Installation can be done as per usage using below methods:

1. Install from Ansible Galaxy Portal:

Published at : Ansible Galaxy

Installation:

ansible-galaxy collection install nutanix.ncp

Red Hat Ansible Automation Platform customers should use an Execution Environment (EE) that bundles this collection and its dependencies instead of pip-installing them directly. See the Red Hat Ansible Automation Platform documentation for building and using EEs, and install the collection from Red Hat Automation Hub.

Community / upstream users — install requirements if dependencies are missing in your environment (Ref: GitHub Issue):

pip install -r requirements.txt

This collection requires ansible-core>=2.16.0.

2. Build and install from code:

For Developers, please follow this install guide for setting up dev environment.

1. Clone the GitHub repository to a local directory

git clone https://github.com/nutanix/nutanix.ansible.git

2. Git checkout release version

git checkout <release_version> -b <release_version>

3. Install requirements

pip install -r requirements.txt

3. Build the collection

ansible-galaxy collection build

4. Install the collection

ansible-galaxy collection install nutanix-ncp-<version>.tar.gz

Note Add --force option for rebuilding or reinstalling to overwrite existing data

Using this collection

You can either call modules by their Fully Qualified Collection Namespace (FQCN), such as nutanix.ncp.ntnx_vms, or you can call modules by their short name if you list the nutanix.ncp collection in the playbook's collections: keyword

For example, the playbook for iaas.yml is as follows:

---
- name: IaaS Provisioning
  hosts: localhost
  gather_facts: false
  collections:
    - nutanix.ncp
  module_defaults:
    group/nutanix.ncp.ntnx:
      nutanix_host: <pc_ip>
      nutanix_username: <user>
      nutanix_password: <pass>
      validate_certs: true
  tasks:
    - include_role:
        name: external_subnet
    - include_role:
        name: vpc
    - include_role:
        name: overlay_subnet
    - include_role:
        name: vm
    - include_role:
        name: fip

To run this playbook, use ansible-playbook command as follows:

ansible-playbook <playbook_name>
ansible-playbook examples/iaas/iaas.yml

Included Content

Note: v1 are based on legacy APIs (v0.8,v1,v2 and v3 APIs) and v2 are based on prism central v4 APIs.

Resources

Data Sources

Inventory Plugins

Module documentation and examples

ansible-doc nutanix.ncp.<module_name>

How to contribute

We glady welcome contributions from the community. From updating the documentation to adding more functions for Ansible, all ideas are welcome. Thank you in advance for all of your issues, pull requests, and comments!

• Contributing Guide
• Contributing Guide for v4 modules — for modules built on Nutanix v4 APIs/SDKs (recommended for all new contributions)
• Code of Conduct

Testing

Integration Testing for Nutanix Ansible Modules

To conduct integration tests for a specific Ansible module such as the ntnx_vms module, the following step-by-step procedures can be followed:

Prerequisites

• Ensure you are in the installed collection directory where the module is located. For example: /Users/mac.user1/.ansible/collections/ansible_collections/nutanix/ncp

Setting up Variables

1. Navigate to the tests/integration/targets directory within the collection.

2. Define the necessary variables within the feature-specific var files, such as tests/integration/targets/prepare_env/vars/main.yml, tests/integration/targets/prepare_foundation_env/vars/main.yml,tests/integration/targets/prepare_ndb_env/tasks/prepare_env.yml, etc.

Note: For Karbon and FC tests, use the PC vars exclusively, as these features rely on pc setup. Not all variables are mandatory; define only the required variables for the particular feature to be tested.

1. Run the test setup playbook for the specific feature you intend to test to create entities in setup:
   • For PC, NDB, and Foundation tests, execute the relevant commands: bash ansible-playbook prepare_env/tasks/prepare_env.yml ansible-playbook prepare_ndb_env/tasks/prepare_env.yml ansible-playbook prepare_foundation_env/tasks/prepare_foundation_env.yml

Running Integration Tests

1. Conduct integration tests for all modules using: bash ansible-test integration

2. To perform integration tests for a specific module: bash ansible-test integration module_test_name Replace module_test_name with test directory name under tests/integration/targets.

Cleanup

1. After completing the integration tests, perform a cleanup specific to the tested feature:
   • For PC tests, execute the command: bash ansible-playbook prepare_env/tasks/clean_up.yml
   • For Foundation tests, execute the command: bash ansible-playbook prepare_foundation_env/tasks/clean_up.yml

By following these steps, you can perform comprehensive integration testing for the specified Ansible module and ensure a clean testing environment afterward. Define only the necessary variables for the specific feature you intend to test.

Examples

Playbook for IaaS provisioning on Nutanix

Refer to examples/iaas for full implementation

---
- name: IaaS Provisioning
  hosts: localhost
  gather_facts: false
  collections:
    - nutanix.ncp
  vars:
      nutanix_host: <pc_ip>
      nutanix_username: <user>
      nutanix_password: <pass>
      validate_certs: true
  tasks:
    - name: Inputs for external subnets task
      include_tasks: external_subnet.yml
      with_items:
        - { name: Ext-Nat, vlan_id: 102, ip: 10.44.3.192, prefix: 27, gip: 10.44.3.193, sip: 10.44.3.198, eip: 10.44.3.207, eNat: True }

    - name: Inputs for vpcs task
      include_tasks: vpc.yml
      with_items:
      - { name: Prod, subnet_name: Ext-Nat}
      - { name: Dev, subnet_name: Ext-Nat}

    - name: Inputs for overlay subnets
      include_tasks: overlay_subnet.yml
      with_items:
        - { name: Prod-SubnetA, vpc_name: Prod , nip: 10.1.1.0, prefix: 24, gip: 10.1.1.1, sip: 10.1.1.2, eip: 10.1.1.5,
            domain_name: "calm.nutanix.com", dns_servers : ["8.8.8.8","8.8.8.4"], domain_search: ["calm.nutanix.com","eng.nutanix.com"] }
        - { name: Prod-SubnetB, vpc_name: Prod , nip: 10.1.2.0, prefix: 24, gip: 10.1.2.1, sip: 10.1.2.2, eip: 10.1.2.5,
            domain_name: "calm.nutanix.com", dns_servers : ["8.8.8.8","8.8.8.4"], domain_search: ["calm.nutanix.com","eng.nutanix.com"] }
        - { name: Dev-SubnetA, vpc_name:  Dev , nip: 10.1.1.0, prefix: 24, gip: 10.1.1.1, sip: 10.1.1.2, eip: 10.1.1.5,
            domain_name: "calm.nutanix.com", dns_servers : ["8.8.8.8","8.8.8.4"], domain_search: ["calm.nutanix.com","eng.nutanix.com"] }
        - { name: Dev-SubnetB, vpc_name:  Dev , nip: 10.1.2.0, prefix: 24, gip: 10.1.2.1, sip: 10.1.2.2, eip: 10.1.2.5,
            domain_name: "calm.nutanix.com", dns_servers : ["8.8.8.8","8.8.8.4"], domain_search: ["calm.nutanix.com","eng.nutanix.com"] }

    - name: Inputs for vm task
      include_tasks: vm.yml
      with_items:
       - {name: "Prod-Wordpress-App", desc: "Prod-Wordpress-App", is_connected: True , subnet_name: Prod-SubnetA, image_name: "wordpress-appserver", private_ip: ""}
       - {name: "Prod-Wordpress-DB", desc: "Prod-Wordpress-DB", is_connected: True , subnet_name: Prod-SubnetB, image_name: "wordpress-db", private_ip: 10.1.2.5}
       - {name: "Dev-Wordpress-App", desc: "Dev-Wordpress-App", is_connected: True , subnet_name: Dev-SubnetA, image_name: "wordpress-appserver", private_ip: ""}
       - {name: "Dev-Wordpress-DB", desc: "Dev-Wordpress-DB", is_connected: True , subnet_name: Dev-SubnetB, image_name: "wordpress-db",private_ip: 10.1.2.5}

    - name: Inputs for Floating IP task
      include_tasks: fip.yml
      with_items:
        - {vm_name: "Prod-Wordpress-App"}
        - {vm_name: "Dev-Wordpress-App"}

Changelog

See the full list of changes in the CHANGELOG.rst or CHANGELOG.md.

License

GNU General Public License v3.0 or later

See LICENSE to see the full text.