NetScaler ADC Collection

Description

The collection provides Ansible modules to configure and manage NetScaler ADC appliances. The modules are written using the NITRO API. The modules are idempotent and can be used to configure the NetScaler ADC appliances in a declarative manner.

Requirements

Ansible version compatibility

Tested with Ansible Core >=2.15 versions.

Python version compatibility

Tested with Python >=3.11

Installation

via Ansible-galaxy

The netscaler.adc collection can be installed with the Ansible Galaxy command-line tool:

ansible-galaxy collection install netscaler.adc

via Github (to have the latest updated which are yet to be released in ansible-galaxy)

ansible-galaxy collection install "git+https://github.com/netscaler/ansible-collection-netscaleradc.git" [--force]

--force option is required if you have already installed the collection via ansible-galaxy. This will overwrite the existing collection with the latest collection from github.

To verify the installation, run the following command:

ansible-galaxy collection list netscaler.adc

The above command should display the below output:

# /Users/netscaleruser/.ansible/collections/ansible_collections
Collection    Version
------------- -------
netscaler.adc 2.8.x

Usecases

The modules can be called by their Fully Qualified Collection Name (FQCN) such as netscaler.adc.lbvserver, or by their short name netscaler.adc if the collection is listed under the playbook's collections attribute:

Usecase by FQCN

---
- name: Sample lbvserver playbook
  hosts: demo_netscalers
  gather_facts: false
  tasks:
    - name: Configure lbvserver
      delegate_to: localhost
      netscaler.adc.lbvserver:
        nsip: "{{ nsip }}"
        nitro_user: "{{ nitro_user }}"
        nitro_pass: "{{ nitro_pass }}"
        nitro_protocol: "{{ nitro_protocol }}"
        validate_certs: false
        save_config: false
        state: present
        name: lb_dns_01
        servicetype: HTTP

Usecase by declaring collection

---
- name: Sample lbvserver playbook
  hosts: demo_netscalers
  gather_facts: false
  collections:
      - netscaler.adc
  tasks:
    - name: Configure lbvserver
      delegate_to: localhost
      lbvserver:
        nsip: "{{ nsip }}"
        nitro_user: "{{ nitro_user }}"
        nitro_pass: "{{ nitro_pass }}"
        nitro_protocol: "{{ nitro_protocol }}"
        validate_certs: false
        save_config: false
        name: lb_dns_01
        servicetype: HTTP

Usecase by netscaler.adc.module_default group

---
- name: Sample Playbook to use module_defaults to specify common arguments
  hosts: localhost
  gather_facts: false
  module_defaults:
    group/netscaler.adc.default_args:
      nsip: 10.10.10.10
      nitro_user: nsroot
      nitro_pass: verysecretpassword
      nitro_protocol: http
      validate_certs: false
      save_config: false
  tasks:
    - name: Sample Task | ipset
      delegate_to: localhost
      netscaler.adc.lbvserver:
        name: lb_dns_01
        servicetype: HTTP

NetScaler Console (ADM) as a Proxy Server

The collection supports configuring NetScaler Console as a proxy server. This is useful when you have multiple NetScaler ADC appliances and you want to manage them using a single NetScaler Console.

An example can be found in examples/netscaler_console_as_proxy_server.yaml.

Refer to the NetScaler ADM as an API proxy server for more details.

Examples and playbook anatomy

Refer to the sample_playboook and playbook_anatomy.md.

SSH Connection Plugin

The collection provides an SSH connection plugin (netscaler.adc.ssh_netscaler_adc) that enables direct SSH connectivity to NetScaler ADC devices for executing shell commands and CLI operations.

Prerequisites

• SSH key-based authentication must be configured
• SSH access to the NetScaler ADC device
• Private SSH key file available on the control machine

Inventory Configuration

Configure your inventory file with the required SSH parameters:

Example 1: Group-based inventory

[demo_netscaler1]
demo_netscalers

[demo_netscaler1:vars]
ansible_host=10.10.10.10
ansible_user=nsroot
ansible_ssh_private_key_file=~/.ssh/id_rsa
nitro_pass=YourPassword

Example 2: Inline inventory

[demo_netscalers]
netscaler_adc ansible_host=10.10.10.10 ansible_user=nsroot ansible_ssh_private_key_file=~/.ssh/id_rsa

Required inventory parameters:

• ansible_host - IP address or hostname of NetScaler ADC
• ansible_user - SSH username (typically nsroot)
• ansible_ssh_private_key_file - Path to SSH private key
• nitro_pass - Password for nscli commands (required when using CLI commands)

Playbook Structure for Shell Commands

To execute FreeBSD shell commands on the NetScaler appliance:

---
- name: Execute shell commands on NetScaler
  hosts: demo_netscalers
  connection: netscaler.adc.ssh_netscaler_adc
  remote_user: nsroot
  gather_facts: false

  vars:
    ansible_python_interpreter: /var/python/bin/python

  tasks:
    - name: List files in /var/tmp
      ansible.builtin.command: "ls -lhrt /var/tmp/"
      register: result
      changed_when: false

    - name: Display output
      ansible.builtin.debug:
        msg: "{{ result.stdout_lines }}"

Required settings for shell access:

• connection: netscaler.adc.ssh_netscaler_adc - Use the SSH connection plugin
• ansible_python_interpreter: /var/python/bin/python - Required for shell command execution
• gather_facts: false - Fact gathering is not supported

Playbook Structure for NetScaler CLI Commands

To execute NetScaler CLI commands using nscli:

---
- name: Execute NetScaler CLI commands
  hosts: demo_netscalers
  connection: netscaler.adc.ssh_netscaler_adc
  remote_user: nsroot
  gather_facts: false

  vars:
    ansible_python_interpreter: /var/python/bin/python
    nscli_command: "show ns version"

  tasks:
    - name: Run NetScaler CLI command
      ansible.builtin.command: "nscli -s -U :nsroot:{{ nitro_pass }} {{ nscli_command }}"
      register: cli_result
      changed_when: false

    - name: Display CLI output
      ansible.builtin.debug:
        msg: "{{ cli_result.stdout_lines }}"

CLI command format:

• Use nscli -s -U :nsroot:{{ nitro_pass }} <command> to execute NetScaler CLI commands
• The -s flag runs in non-interactive mode
• The -U :nsroot:{{ nitro_pass }} provides authentication credentials
• Replace <command> with any valid NetScaler CLI command (e.g., show ns ip, show lb vserver)

Running the Playbook

ansible-playbook playbook.yaml -i inventory.ini

Add -vvvv for verbose debugging output if needed:

ansible-playbook playbook.yaml -i inventory.ini -vvvv

Additional Examples

For more complete examples and use cases, refer to the SSH connections examples directory.

Authentication

Authenticate to NetScaler via username and password

Every module in the collection requires the user to authenticate to the NetScaler ADC appliance. To authenticate, provide the nsip, nitro_user and nitro_pass parameters directly or set them using environment variables NETSCALER_NSIP, NETSCALER_NITRO_USER and NETSCALER_NITRO_PASS.

Refer to the playbook_anatomy.md and sessionid_based_authentication_via_login_logout.yaml example playbook.

login module requires username and password parameters to be passed. If you do not wish to pass the username and password, refer below.

You can use the below curl command to generate the token. The token can be passed to other modules using the nitro_auth_token parameter. The nitro_auth_token parameter can also be passed as environment variable NETSCALER_NITRO_AUTH_TOKEN. The token is valid for 60 minutes.

The below command also uses jq to parse the JSON output and store the sessionid in the NETSCALER_NITRO_AUTH_TOKEN environment variable, so that it can be used by other modules.

Note: Change the NETSCALER_NSIP, NETSCALER_NITRO_USER and NETSCALER_NITRO_PASS. Install jq util if not already installed.

export NETSCALER_NITRO_AUTH_TOKEN=$(curl -X POST -H "Content-Type:application/json" --insecure --silent https://NETSCALER_NSIP/nitro/v1/config/login -d '{"login":{"username":"NETSCALER_NITRO_USER", "password":"NETSCALER_NITRO_PASS"}}' | jq .sessionid)
echo $echo $NETSCALER_NITRO_AUTH_TOKEN

Migration Tool

The collection includes a migration tool to help convert existing Ansible playbooks from the legacy citrix.adc collection to the new netscaler.adc collection format. This tool simplifies the transition from legacy automation to the updated collection.

Features

• Module Mapping: Automatically converts citrix.adc modules to netscaler.adc modules
• NITRO Request Conversion: Transforms citrix_adc_nitro_request tasks to specific resource modules
• State Conversion: Maps legacy operations (add, update, delete) to appropriate state values
• Credential Preservation: Maintains authentication parameters and playbook structure
• YAML Structure Preservation: Keeps task names, variables, and organization intact

Usage

# Basic conversion
python3 migrationtool/convert_yaml.py -i legacy_playbook.yaml -o migrated_playbook.yaml

# With verbose output
python3 migrationtool/convert_yaml.py -i legacy_playbook.yaml -o migrated_playbook.yaml -v

Example Conversion

Before (Legacy citrix.adc):

- name: Configure LB vserver
  citrix_adc_nitro_request:
    nsip: "{{ nsip }}"
    nitro_user: "{{ nitro_user }}"
    nitro_pass: "{{ nitro_pass }}"
    operation: add
    resource: lbvserver
    name: my_lb_vserver
    attributes:
      servicetype: HTTP
      ipv46: 10.10.10.10
      port: 80

After (New netscaler.adc):

- name: Configure LB vserver
  netscaler.adc.lbvserver:
    nsip: "{{ nsip }}"
    nitro_user: "{{ nitro_user }}"
    nitro_pass: "{{ nitro_pass }}"
    state: present
    name: my_lb_vserver
    servicetype: HTTP
    ipv46: 10.10.10.10
    port: 80

For detailed migration tool documentation, usage examples, and troubleshooting, refer to the Migration Tool README.

Invocation

The credentials of the netscaler can be provided either in the playbook by hardcoding or defining in a inventory.ini file.

Execution command when hosts are declared in playbook:

ansible-playbook playbook.yaml [--verbose]

Execution command hosts are declared in an inventory file:

ansible-playbook playbook.yaml -i inventory.ini [--verbose]

Testing

The collection is tested using Github Actions. To know more about testing, please refer the link to know more.

Contributing

For external contributions, refer the guidelines.

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, we strongly encourage engaging with the NetScaler and Ansible community. You can contribute to the collection or seek assistance via the NetScaler's Official GitHub Repository or connect with other Ansible users on the Ansible Forum.

For feature requests: https://github.com/netscaler/ansible-collection-netscaleradc/discussions

Release Notes

Please refer to the link for the release notes.

License Information

The collection uses MIT license. You can refer the link to view license information.