Nutanix Ansible

Official nutanix ansible collection

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.2.0.

Introducing Nutanix Ansible Collection Version v2.2.0

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

What's New in v2.2.0

• Built on v4.1 APIs/SDKs
  This release is built on the latest Nutanix v4 APIs and SDKs, providing improved performance, stability, and alignment with the newest platform capabilities.

• New Resource Support

• Objects: Automate Nutanix Objects (S3-compatible storage) management for scalable storage use cases.

• Service Accounts: Manage service accounts and their associated roles and permissions directly through Ansible.

• Bug Fixes and Stability Improvements
  Multiple bugs have been resolved to improve the reliability and user experience across modules.

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

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 https://portal.nutanix.com/kb/13424 for more details.

Version compatibility

Ansible

This collection requires ansible-core>=2.16.0. This should be installed explicitly if ansible-core version is not installed previously or is below the specified version.

Python

This collection requires Python 3.10 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.

Examples:

1. Prism Central: https://github.com/nutanix/nutanix.ansible/tree/main/examples/

2. Foundation: https://github.com/nutanix/nutanix.ansible/tree/main/examples/foundation

3. Foundation Central: https://github.com/nutanix/nutanix.ansible/tree/main/examples/fc

4. Karbon: https://github.com/nutanix/nutanix.ansible/tree/main/examples/karbon

5. NDB: https://github.com/nutanix/nutanix.ansible/tree/main/examples/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 : https://galaxy.ansible.com/ui/repo/published/nutanix/ncp/

Installation:

ansible-galaxy collection install nutanix.ncp

Install requirements from repository if dependencies are missing in environment (Ref: https://github.com/nutanix/nutanix.ansible/issues/600):

pip install -r requirements.txt

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
• 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"}