This repository provides Ansible modules for configuring Citrix ADC instances. It uses the NITRO REST API. All form factors of Citrix ADC are supported.
To learn more about Automation of Citrix ADC, check out the blog here.
- Module renaming
- Documentation
- List of implemented modules
- Pre-requisites
- Installation
- Usage
- Citrix ADC connection plugin
- What if there is no module for your configuration?
- Directory structure
- LICENSE
- COPYRIGHT
Note that as of this commit all modules were renamed to match the new Citrix product names.
See here for reference.
All modules which previously started with the netscaler_ prefix have been renamed to
to start with the citrix_adc_ prefix.
All new modules will follow this convention as well.
Until these changes are integrated into the Ansible distribution the Citrix ADC module names will differ depending on where they were installed from.
Extended documentation is hosted at readthedocs.
Currently the following modules are implemented
Included in the citrix.adc collection
- citrix_adc_appfw_confidfield - Configuration for configured confidential form fields resource
- citrix_adc_appfw_fieldtype - Configuration for application firewall form field type resource
- citrix_adc_appfw_global_bindings - Define global bindings for AppFW
- citrix_adc_appfw_htmlerrorpage - Configuration for configured confidential form fields resource
- citrix_adc_appfw_jsoncontenttype - Configuration for JSON content type resource
- citrix_adc_appfw_learningsettings - Configuration for learning settings resource
- citrix_adc_appfw_policy - Manage Citrix ADC Web Application Firewall policies
- citrix_adc_appfw_policylabel - Manage Citrix ADC Web Application Firewall policy labels
- citrix_adc_appfw_profile - Manage Citrix ADC Web Application Firewall profiles
- citrix_adc_appfw_settings - Manage Citrix ADC Web Application Firewall settings
- citrix_adc_appfw_signatures - Configuration for configured confidential form fields resource
- citrix_adc_appfw_wsdl - Configuration for configured confidential form fields resource
- citrix_adc_appfw_xmlcontenttype - Configuration for XML Content type resource
- citrix_adc_appfw_xmlerrorpage - Configuration for configured confidential form fields resource
- citrix_adc_appfw_xmlschema - Configuration for configured confidential form fields resource
- citrix_adc_cs_action - Manage content switching actions
- citrix_adc_cs_policy - Manage content switching policy
- citrix_adc_cs_vserver - Manage content switching vserver
- citrix_adc_dnsnsrec - Configuration for name server record resource
- citrix_adc_gslb_service - Manage gslb service entities in Citrix ADC
- citrix_adc_gslb_site - Manage gslb site entities in Citrix ADC
- citrix_adc_gslb_vserver - Configure gslb vserver entities in Citrix ADC
- citrix_adc_lb_monitor - Manage load balancing monitors
- citrix_adc_lb_vserver - Manage load balancing vserver configuration
- citrix_adc_nitro_info - Retrieve information from various NITRO API endpoints
- citrix_adc_nitro_request - Issue Nitro API requests to a Citrix ADC instance
- citrix_adc_nitro_resource - Create, update, delete resources on Citrix ADC
- citrix_adc_password_reset - Perform default password reset
- citrix_adc_save_config - Save Citrix ADC configuration
- citrix_adc_server - Manage server configuration
- citrix_adc_service - Manage service configuration in Citrix ADC
- citrix_adc_servicegroup - Manage service group configuration in Citrix ADC
- citrix_adc_ssl_certkey - Manage ssl certificate keys
- citrix_adc_sslcipher - Manage custom SSL ciphers
- citrix_adc_sslcipher_sslciphersuite_binding - Manage SSL cipher and SSL ciphersuite bindings
- citrix_adc_sslprofile_sslcipher_binding - Manage SSL profile and SSL cipher bindings
- citrix_adc_system_file - Upload systemfile to ADC
Included in the citrix.adm collection
- citrix_adm_application - Manage applications on Citrix ADM
- citrix_adm_dns_domain_entry - Manage Citrix ADM domain names
- citrix_adm_login - Login to a Citrix ADM instance
- citrix_adm_logout - Logout from a Citrix ADM instance
- citrix_adm_mpsgroup - Manage Citrix ADM user groups
- citrix_adm_mpsuser - Manage Citrix ADM users
- citrix_adm_ns_facts - Retrieve facts about Citrix ADM managed instances
- citrix_adm_poll_instances - Force the poll instances network function on the target Citrix ADM
- citrix_adm_rba_policy - Manage Citrix ADM rba policies
- citrix_adm_rba_role - Manage Citrix ADM rba roles
- citrix_adm_stylebook - Create or delete Citrix ADM stylebooks
- citrix_adm_tenant_facts - Retrieve facts about Citrix ADM tenants
The following NITRO API endpoints have their workflow dictionaries available
for use with the citrix_adc_nitro_resource module.
The workflows yaml file can be found here.
csvserver_rewritepolicy_binding, dnssoarec, lbgroup, lbgroup_lbvserver_binding, lbmetrictable, lbmetrictable_metric_binding, lbmonitor, lbmonitor_metric_binding, lbmonitor_sslcertkey_binding, lbprofile, lbroute, lbroute6, lbvserver, lbvserver_analyticsprofile_binding, lbvserver_appflowpolicy_binding, lbvserver_appfwpolicy_binding, lbvserver_appqoepolicy_binding, lbvserver_auditnslogpolicy_binding, lbvserver_auditsyslogpolicy_binding, lbvserver_authorizationpolicy_binding, lbvserver_cachepolicy_binding, lbvserver_capolicy_binding, lbvserver_cmppolicy_binding, lbvserver_contentinspectionpolicy_binding, lbvserver_csvserver_binding, lbvserver_dnspolicy64_binding, lbvserver_feopolicy_binding, lbvserver_filterpolicy_binding, lbvserver_pqpolicy_binding, lbvserver_responderpolicy_binding, lbvserver_rewritepolicy_binding, lbvserver_scpolicy_binding, lbvserver_service_binding, lbvserver_servicegroup_binding, lbvserver_servicegroupmember_binding, lbvserver_spilloverpolicy_binding, lbvserver_transformpolicy_binding, lbvserver_videooptimizationdetectionpolicy_binding, lbvserver_videooptimizationpacingpolicy_binding, nsacl, ntpparam, ntpserver, policypatset, policypatset_pattern_binding, rewriteaction, rewritepolicy, server, service, service_lbmonitor_binding, servicegroup, servicegroup_lbmonitor_binding, snmpmanager, spilloverpolicy, sslparameter, sslprofile, sslprofile_sslcipher_binding, sslvserver, sslvserver_sslcertkey_binding, systemuser, transformaction, transformpolicy, transformprofile
- NITRO Python SDK
- Ansible
- Python 2.7 or 3.x
Use of a python virtualenv during installation is recommended.
- Activate the virtualenv (
source bin/activate) - Install all dependencies by running
pip install -r requirements.test.txtfrom the project checkout.
- Install Ansible (
sudo pip install ansible) - Install NetScaler SDK (
pip install deps/nitro-python-1.0_kamet.tar.gz)
To install the available collections from the repository directly:
# ADC modules and connection plugin
ansible-galaxy collection install git+https://github.com/citrix/citrix-adc-ansible-modules.git#/ansible-collections/adc
# ADM modules
ansible-galaxy collection install git+https://github.com/citrix/citrix-adc-ansible-modules.git#/ansible-collections/admTo install the available collections from a local checkout of the repository:
# ADC modules and connection plugin
cd ansible-collections/adc
ansible-galaxy collection build
ansible-galaxy collection install citrix-adc-<semver>.tar.gz
# ADM modules
cd ansible-collections/adm
ansible-galaxy collection build
ansible-galaxy collection install citrix-adm-<semver>.tar.gzAll modules are intended to be run on the ansible control machine or a jumpserver with access to the Citrix ADC appliance.
To do this you need to use the local_action or the delegate_to options in your playbooks.
There are sample playbooks in the samples directory.
Detailed documentation for each module can be found in the htmldoc directory.
Documentation regarding the Citrix ADC appliance configuration in general can be found at the following link, http://docs.citrix.com/en-us/netscaler/11-1.html
Some input variables used by the Citrix ADC ansible modules contain sensitive data.
Most notably nitro_pass.
Other variables may also be considered security sensitive depending on the use case. For example a user may not want to expose backend service IPs since it gives an attacker insight into the network topology used.
In production environments it is recommended to keep the values of these variables encrypted until they are needed by the playbook. Ansible offers the ansible-vault utility which can be used to encrypt individual variables or entire files.
When the contents are needed the ansible-playbook command can take arguments which will point to the encrypted content
and decrypt it as needed.
For more information see the full documentation
By default the nitro_protocol parameter is set to http.
This leaves all NITRO API request and response data unencrypted and it is not recommended for production environments.
Set the nitro_protocol to https in order to have all NITRO API communication encrypted.
By default the Citrix ADC comes with a self signed TLS certificate.
If you intend to use https with this certificate you need to set the validate_certs parameter to false.
For production environments it is recommended to use trusted TLS certificate so that validate_certs
is set to true.
Please consult the Citrix ADC secure deployment guide where among other things the usage of trusted TLS certificates is documented.
There is also the ability to proxy module NITRO calls through a Citrix ADM to a target ADC.
In order to do that you need a NITRO Python SDK that has the MAS proxy calls capability and also follow these 2 steps.
- First acquire a nitro authentication token with the use of the
netscaler_nitro_requestmas_loginoperation. - Next all subsequent module invocations should have the
mas_proxy_calloption set totrue, replace thenitro_userandnitro_passauthentication options with thenitro_auth_tokenacquired from the previous step and finally include theinstance_ipoption to instruct MAS to which citrix ADC to proxy the calls.
A sample playbook is provided in the samples directory. mas_proxied_server.yaml
There is the option for citrix_adm modules to be executed targetting the ADM service instead of an on prem ADM.
This mode of execution relies on first getting a nitro_auth_token by logging in the ADM service and using this
token for all subsequent module calls.
Also the option is_cloud: true must be set as well as having the adm_ip: adm.cloud.com.
Examples can be found in this folder.
The Citrix ADC connection plugin allows the use of standard Ansible modules, such as shell and fetch, with Citrix ADC.
The connection plugin is included in the citrix.adc collection.
In order for a standard Ansible module to work properly with the Citrix ADC connection plugin the following conditions must hold true.
- Modify the playbook so that it uses the connection plugin (
connection: ssh_citrix_adc). - Citrix ADC does not have the python interpreter path defined, so one should pass this path when defining the host group (
ansible_python_interpreter: /var/python/bin/python). - The plugin works only with ssh key based authentication. The remote Citrix ADC must have the public ssh key of the controlling machine in their authorized_keys file (
/flash/nsconfig/ssh/authorized_keys). - In the local ansible.cfg file make sure the following lines exist:
[defaults]
host_key_checking = False
[ssh_connection]
scp_if_ssh = True
You can find usage samples in this folder.
With the connection plugin and the shell ansible module it is posssible to run nscli commands
as show in the example below.
tasks:
- name: Run nscli command
shell: "nscli -s -U :nsroot:{{nitro_pass}} show ns ip"
no_log: TrueIn order to not expose the actual nsroot password the following rules must be observed
-
Do not hardcode the password in the command string.
Use a variable which is retrieved from a secure storage.
-
For the task that contains the password set the task option
no_log: TrueThis will hide log output from the specified task including the password.
There are some conflicting configuration options when using a standard Ansible module with a Citrix ADC specific module in the same playbook.
To have such a playbook execute correctly the following solutions are proposed.
- Have a single playbook with multiple plays ( sample ).
- Have a single play configured for standard Ansible modules and define the neeeded overrides in the Citrix ADC specific tasks ( sample ).
- Have a single play configured for Citrix ADC specific modules and define the needed overrides for the generic Ansible tasks ( sample ).
When there is no module that covers the ADC configuration you want to apply there are a few options that will allow you to still apply the configuration through an ansible playbook.
This a module that is a thin wrapper around the NITRO REST API. It provides a number of operations which it then translates into HTTP requests and provides the resulting NITRO API response in a well defined return value.
You can find examples of using the module in this folder
The citrix_adc_nitro_resource module can be used to create, update and delete
NITRO objects.
It has the same base parameters as the other modules for connecting to the ADC.
Its most important attributes are the workflow parameter which determines
the execution of the module with respect to how the NITRO object will be created, updated
or deleted and the resource parameter which contains the actual attributes
for the NITRO resource.
The workflows dictionaries published so far can be found here.
Examples can be found in this folder.
Extended documentation can be found here.
If an endpoint cannot be found in the existing workflows file please open an issue so that we can investigate if this endpoint is covered by the existing workflows and publish its dictionary.
As a last resort the user can user the shell Ansible module
along with the Citrix ADC connection plugin to issue nscli commands
to the target ADC.
This provides the least feedback but it is useful for one off configuration steps or when nothing else is applicable.
Examples can be found in this folder
-
ansible-modules.Contains all the ansible modules available. These are the files that must be installed on an ansible control node in order for the functionality to be present -
ansible-plugins.Contains all the ansible plugins available. -
tests.Contains the test suite for the modules. It requires some extra dependencies than the plain modules in order to run. -
samples.Contains some sample playbooks that combine more than one modules together to achieve a desired configuration. Examples of the modules' usage are also contained in the EXAMPLES section of the modules themselves. -
htmldoc.Contains the html documentation for each module. -
utils.Contains utilities mainly used for the authoring of the modules and are not relevant to the end user. -
documentation_fragments.Contains the Citrix ADC specific documentation files for ansible. -
run_tests.py. Top level script to run all the tests.
GPL V3 See LICENSE
COPYRIGHT 2017 CITRIX Systems Inc
Pull requests and issues are welcome.