Dev, Tests, Examples and Doc for Network Function

[george-ghawali]

Network Functions Modules Documentation

Overview

This PR introduces two new Ansible modules for managing Network Functions in Nutanix Prism Central. Network Functions enable service insertion capabilities, allowing traffic to be redirected through or mirrored to Network Function Virtual Machines (NFVM).
These modules use PC v4 APIs based SDKs.

---

Module 1: ntnx_network_functions_v2

Purpose

This module provides full CRUD (Create, Read, Update, Delete) operations for Network Functions in Nutanix Prism Central.

Version

• Version Added: 2.5.0

What It Does

1. Create Network Functions

• Creates a new network function with specified name, description, and NIC pair configuration
• Supports INLINE or VTAP traffic forwarding
• Configures high availability mode with ACTIVE_PASSIVE failover
• Defines failure handling behavior (FAIL_OPEN, FAIL_CLOSE)
• Configures data plane health check parameters for NFVM monitoring
• Returns the created network function details including its external ID

2. Update Network Functions

• Updates an existing network function using its external ID
• Can modify name, description, NIC pairs, failure handling, and health check config
• Supports idempotency - detects if no changes are needed
• Uses ETag for optimistic concurrency control

3. Delete Network Functions

• Deletes a network function by its external ID
• Waits for task completion by default

Key Features

• ✅ Check Mode Support: Preview changes without applying them
• ✅ Idempotency: Detects when no changes are needed
• ✅ Task Management: Supports waiting for task completion
• ✅ Error Handling: Comprehensive error messages and exception handling
• ✅ ETag Support: Uses ETags for safe concurrent updates
• ✅ High Availability: Supports ACTIVE_PASSIVE failover configuration
• ✅ Health Monitoring: Configurable data plane health checks

Options/Parameters

Conditional Requirements

State	Required Parameters
present	At least one of name OR ext_id must be provided
absent	ext_id is required

Parameters

1. state (str)

   • Operation to perform
   • Choices: present (create/update) or absent (delete)
   • Required: No (defaults from base module)

2. ext_id (str)

   • External ID of the network function
   • Required: When state=absent (delete operation)
   • Required: When state=present for update operation

3. name (str)

   • A user-friendly name for the network function (up to 128 characters)
   • Required in create operation

4. description (str)

   • An optional, longer text field (up to 1000 characters) to describe the network function's purpose
   • Required: No

5. nic_pairs (list of dict)

   • List of all NIC pairs part of this network function
   • Minimum 1, maximum 2 items
   • Required: No
   • Sub-options:
     • ingress_nic_reference (str): UUID of the virtual NIC where traffic enters the NFVM. Required: Yes
     • egress_nic_reference (str): UUID of the virtual NIC where traffic exits the NFVM. Required: No
     • vm_reference (str): UUID of the VM that hosts the ingress and egress NICs. Required: No
     • is_enabled (bool): Administrative state of the NIC pair. Required: No (default: true)

6. high_availability_mode (str)

   • HA configuration setting
   • Choices: ACTIVE_PASSIVE
   • Required: No

7. failure_handling (str)

   • Defines behavior when all NFVMs are unhealthy
   • Choices: FAIL_CLOSE, FAIL_OPEN, NO_ACTION
   • Required: No

8. traffic_forwarding_mode (str)

   • Specifies how traffic is delivered to the NFVM
   • Choices: INLINE, VTAP
   • Required: No

9. data_plane_health_check_config (dict)

   • Health check configuration for NFVMs
   • Required: No
   • Sub-options:
     • interval_secs (int): Time between health check probes (1-65535). Required: No (default: 5)
     • timeout_secs (int): Time before probe is considered failed (1-65535). Required: No (default: 1)
     • success_threshold (int): Consecutive successes to mark healthy (1-64). Required: No (default: 3)
     • failure_threshold (int): Consecutive failures to mark unhealthy (1-64). Required: No (default: 3)

10. metadata (dict)

    • Standard resource metadata
    • Required: No
    • Sub-options:
      • owner_reference_id (str): UUID of the resource owner. Required: No
      • owner_user_name (str): Username of the owner. Required: No
      • project_reference_id (str): UUID of the associated project. Required: No
      • project_name (str): Name of the associated project. Required: No
      • category_ids (list of str): List of category UUIDs. Required: No

Common Parameters (from fragments)

• nutanix_host: Prism Central IP address
• nutanix_username: Username for authentication
• nutanix_password: Password for authentication
• validate_certs: Whether to validate SSL certificates
• wait: Whether to wait for task completion (default: True)
• timeout: Task timeout in seconds

Return Values

1. response (dict)

   • Network function details if wait is True
   • Task details if wait is False
   • Always returned

2. changed (bool)

   • Indicates whether the task resulted in any changes
   • Always returned

3. ext_id (str)

   • The network function external ID
   • Always returned

4. task_ext_id (str)

   • The task external ID (for async operations)
   • Returned when task is created

5. error (str)

   • Error information if task execution failed
   • Always returned

6. failed (bool)

   • Indicates if the task execution failed
   • Returned when failed

7. msg (str)

   • Message if any occurred (errors, idempotency, or check mode messages)
   • Returned when there's an error or in check mode

Use Cases

1. Create Network Function with INLINE Traffic Forwarding Mode and ACTIVE_PASSIVE HA

- name: Create network function with INLINE traffic forwarding mode and ACTIVE_PASSIVE HA
  nutanix.ncp.ntnx_network_functions_v2:
    state: present
    nutanix_host: "{{ ip }}"
    validate_certs: false
    nutanix_username: "{{ username }}"
    nutanix_password: "{{ password }}"
    name: "my-network-function"
    description: "Network function for traffic inspection"
    high_availability_mode: ACTIVE_PASSIVE
    failure_handling: FAIL_OPEN
    traffic_forwarding_mode: INLINE
    nic_pairs:
      - ingress_nic_reference: "a3265671-de53-41be-af9b-f06241b95356"
        egress_nic_reference: "b4376782-ef64-52cf-bg0c-g17352ca6467"
        vm_reference: "c5487893-fg75-63dg-ch1d-h28463db7578"
        is_enabled: true
      - ingress_nic_reference: "d6598904-gh86-74eh-di2e-i39574ec8689"
        egress_nic_reference: "e7609015-hi97-85fi-ej3f-j40685fd979a"
        vm_reference: "f8710126-ij08-96gj-fk4g-k51796ge080b"
        is_enabled: true
    data_plane_health_check_config:
      interval_secs: 5
      timeout_secs: 1
      success_threshold: 3
      failure_threshold: 3

2. Create Network Function with VTAP Traffic Forwarding Mode and ACTIVE_PASSIVE HA

- name: Create network function with VTAP traffic forwarding mode and ACTIVE_PASSIVE HA
  nutanix.ncp.ntnx_network_functions_v2:
    state: present
    nutanix_host: "{{ ip }}"
    validate_certs: false
    nutanix_username: "{{ username }}"
    nutanix_password: "{{ password }}"
    name: "vtap-network-function"
    description: "Network function for VTAP traffic forwarding mode and ACTIVE_PASSIVE HA"
    high_availability_mode: ACTIVE_PASSIVE
    traffic_forwarding_mode: VTAP
    nic_pairs:
      - ingress_nic_reference: "a3265671-de53-41be-af9b-f06241b95356"
        is_enabled: true
        vm_reference: "c5487893-fg75-63dg-ch1d-h28463db7578"
      - ingress_nic_reference: "d6598904-gh86-74eh-di2e-i39574ec8689"
        vm_reference: "f8710126-ij08-96gj-fk4g-k51796ge080b"
        is_enabled: true

3. Update Network Function

- name: Update network function
  nutanix.ncp.ntnx_network_functions_v2:
    state: present
    nutanix_host: "{{ ip }}"
    validate_certs: false
    nutanix_username: "{{ username }}"
    nutanix_password: "{{ password }}"
    ext_id: "a3265671-de53-41be-af9b-f06241b95356"
    name: "updated-network-function"
    description: "Updated description"
    failure_handling: FAIL_CLOSE
    high_availability_mode: ACTIVE_PASSIVE
    traffic_forwarding_mode: INLINE
    nic_pairs:
      - ingress_nic_reference: "0c0068b3-6caf-415b-a055-0a727bc5f963"
        egress_nic_reference: "3f325e81-916c-45d4-ba3f-c1dbfb205399"
        vm_reference: "657ab599-4819-4d49-46e0-b726bb785422"
        is_enabled: true
      - ingress_nic_reference: "d813fcad-d32c-4469-98bc-028c9ac148e1"
        egress_nic_reference: "5349fd3b-e71a-462c-a59f-63b62d45b4de"
        vm_reference: "2180291c-aeb0-47cc-466f-7f37a1b98086"
        is_enabled: true
    data_plane_health_check_config:
      interval_secs: 5
      timeout_secs: 1
      success_threshold: 3
      failure_threshold: 3

4. Delete Network Function

- name: Delete network function
  nutanix.ncp.ntnx_network_functions_v2:
    state: absent
    nutanix_host: "{{ ip }}"
    nutanix_username: "{{ username }}"
    nutanix_password: "{{ password }}"
    validate_certs: false
    ext_id: "a3265671-de53-41be-af9b-f06241b95356"

---

Module 2: ntnx_network_functions_info_v2

Purpose

This module provides read-only operations to fetch information about Network Functions in Nutanix Prism Central.

Version

• Version Added: 2.5.0

What It Does

1. Get Single Network Function

• Fetches detailed information about a specific network function using its external ID
• Returns complete network function configuration including NIC pairs and health status

2. List All Network Functions

• Retrieves a list of all network functions in Prism Central
• Supports pagination with limit parameter
• Supports filtering using filter expressions
• Returns total count of available network functions

Key Features

• ✅ Flexible Querying: Get single or multiple network functions
• ✅ Filtering Support: Filter by any attribute using filter expressions
• ✅ Pagination: Limit results for better performance
• ✅ Metadata: Returns total available results count
• ✅ Read-Only: Safe to use without making changes
• ✅ Health Status: Returns data plane health status for each NIC pair

Options/Parameters

Parameters (All Optional)

1. ext_id (str)

   • External ID to fetch specific network function info
   • If provided: Returns single network function
   • If not provided: Returns list of network functions
   • Mutually exclusive with filter
   • Required: No

2. filter (str)

   • A URL query parameter that allows clients to filter a collection of resources
   • The expression specified with $filter is evaluated for each resource in the collection, and only items where the expression evaluates to true are included in the response
   • Expression must conform to the OData V4.01 URL conventions
   • Mutually exclusive with ext_id
   • Required: No
   • Filterable fields: extId, name
   • Examples:
     • extId eq '887fddf0-b125-4da3-8110-b82bdbd21da2'
     • name eq 'samplenf'

3. limit (int)

   • A URL query parameter that specifies the total number of records returned in the result set
   • Range: 1 to 100
   • Default: 50
   • Any number out of this range will lead to a validation error
   • Required: No

4. page (int)

   • A URL query parameter that specifies the page number of the result set
   • Must be a positive integer between 0 and the maximum number of pages available
   • Default: 0
   • Any number out of this range might lead to no results
   • Required: No

5. orderby (str)

   • A URL query parameter that allows clients to specify the sort criteria for the returned list of objects
   • Resources can be sorted in ascending order using asc or descending order using desc
   • If asc or desc are not specified, the resources will be sorted in ascending order by default
   • Required: No
   • Orderable fields: name
   • Example: name desc

Common Parameters (from fragments)

• nutanix_host: Prism Central IP address
• nutanix_username: Username for authentication
• nutanix_password: Password for authentication
• validate_certs: Whether to validate SSL certificates

Return Values

1. response (dict or list)

   • Single network function info if ext_id is provided
   • List of network functions if ext_id is not provided
   • Always returned

2. changed (bool)

   • Always False (read-only operation)
   • Always returned

3. total_available_results (int)

   • Total number of available network functions in PC
   • Returned when listing all network functions

4. ext_id (str)

   • The external ID of the network function that was fetched
   • Returned when fetching a specific network function

5. error (str)

   • Error information if task execution failed
   • Always returned

6. msg (str)

   • Message if any error occurred
   • Returned when there's an error

Use Cases

1. List All Network Functions

- name: List all network functions
  nutanix.ncp.ntnx_network_functions_info_v2:
    nutanix_host: "{{ ip }}"
    nutanix_username: "{{ username }}"
    nutanix_password: "{{ password }}"
    validate_certs: false
  register: result

2. List Network Functions with Filter

- name: List network functions with filter
  nutanix.ncp.ntnx_network_functions_info_v2:
    nutanix_host: "{{ ip }}"
    nutanix_username: "{{ username }}"
    nutanix_password: "{{ password }}"
    validate_certs: false
    filter: "name eq 'my-network-function'"
  register: result

3. List Network Functions with Limit

- name: List network functions with limit
  nutanix.ncp.ntnx_network_functions_info_v2:
    nutanix_host: "{{ ip }}"
    nutanix_username: "{{ username }}"
    nutanix_password: "{{ password }}"
    validate_certs: false
    limit: 1
  register: result

4. Get Details of a Specific Network Function

- name: Get details of a specific network function
  nutanix.ncp.ntnx_network_functions_info_v2:
    nutanix_host: "{{ ip }}"
    nutanix_username: "{{ username }}"
    nutanix_password: "{{ password }}"
    validate_certs: false
    ext_id: "a3265671-de53-41be-af9b-f06241b95356"
  register: result

Infrastructure Components

API Client Function

• get_network_function_api_instance(module): Returns NetworkFunctionsApi instance from ntnx_networking_py_client SDK

Helper Functions

• get_network_function(module, api_instance, ext_id): Fetches network function by external ID with error handling

Constants

• NETWORK_FUNCTION: Constant value "Networking:config:network-function" for task entity type

---

Files Changed

File	Description
plugins/modules/ntnx_network_functions_v2.py	Main CRUD module for network functions
plugins/modules/ntnx_network_functions_info_v2.py	Info module for fetching network functions
plugins/module_utils/v4/network/api_client.py	Added get_network_function_api_instance()
plugins/module_utils/v4/network/helpers.py	Added get_network_function() helper
plugins/module_utils/v4/constants.py	Added NETWORK_FUNCTION constant
meta/runtime.yml	Added modules to action groups
examples/networks_v2/network_functions_v2.yml	Example playbook
tests/integration/targets/ntnx_network_functions_v2/	Integration tests

---

Testing

Comprehensive integration tests are included covering:

• Create operations with INLINE and VTAP modes
• Create operations with ACTIVE_PASSIVE HA configuration
• Update operations with idempotency checks
• Delete operations
• Info operations (list, filter, limit, get by ext_id)
• Error handling scenarios (wrong ext_id, missing parameters)
• Check mode operations
• Data plane health check configuration
• NIC pair configuration with multiple VMs

---

Examples

See examples/networks_v2/network_functions_v2.yml for complete usage examples demonstrating:

• Creating network functions with INLINE mode
• Creating network functions with VTAP mode
• Updating network functions
• Listing network functions
• Filtering network functions
• Getting network functions by ID
• Deleting network functions

---

Notes

• Both modules use PC v4 APIs based SDKs (ntnx_networking_py_client)
• Network functions require VMs with special "Network Function NIC" type
• VMs must have NICs configured with INGRESS and EGRESS network function types
• Advanced networking must be enabled on the subnet for network function support
• The modules support check mode for safe testing
• Update operation is idempotent where applicable
• Error handling includes detailed error messages
• ETag support ensures safe concurrent operations
• Health check monitors NFVM availability for automatic failover