Citrix has developed a custom Terraform provider for automating Citrix ADC deployments and configurations. Using Terraform, you can custom configure your ADCs for different use-cases such as Load Balancing, SSL, Content Switching, GSLB, WAF etc.
For users new to terraform provider for Citrix ADC, check out the installation steps and getting started with configuring adc.
For deploying Citrix ADC in Public Cloud - AWS and Azure, check out cloud scripts in github repo terraform-cloud-scripts.
Learn more about Citrix ADC Automation here
Important note: The provider will not commit the config changes to Citrix ADC's persistent store.
- Why Terraform for Citrix ADC ?
- Navigating Repository
- Installating Terraform and Citrix ADC Provider
- Get Started on using terraform to configure Citrix ADC
- Generic nitro_resource
- Usage Guidelines
Terraform is an open-source infrastructure as code software tool that provides a consistent CLI workflow to manage hundreds of cloud services.Terraform codifies cloud APIs into declarative configuration files. Terraform can be used to deploy and configure ADC. Configuring Citrix ADC through Terraform provides multiple benefits.
- Infrastucture as Code approach to ADC -You can store the ADC configs in scm tools like GitHub and version and track it like just other code repositories you have.
- Declarative Approach to ADC automation - Users just need to defined the target state of ADC. ADC terraform resources will make the appropriate API calls to achieve the target state.
- ADC resources files in Terraform are human friendly and easy to understand.
- Abstract away the complexity associated with Citrix ADC internals architecture.
- Detect the configuration drifts on ADC through Terraform easily.
To run the terraform-citrixadc-provider you need to have the hashicorp terraform executable installed in your system.
You can download it from this page.
- citrixadc folder - Contains all the ADC resources library that we support through Terraform. These resource libraries will internally call NITRO APIS to configure target ADC.
- examples folder - Contain the examples for users to use various ADC resources e.g simple_lb folder contains the resources.tf that illustrates how citrixadc_lbvserver resource can be used to create a Load Balancing vserver on target ADC. Similarly , different folders contains examples on defining different resources. Users are expected to review these examples and define their desired ADC configurations.
- docs folder - https://github.com/citrix/terraform-provider-citrixadc/tree/master/docs/resources - contains the documentation of all resources confgirations supported through Terraform. Refer this to understand the different arguments, values that a particular resource takes.
First step is to install Terraform CLI. Refer the https://learn.hashicorp.com/tutorials/terraform/install-cli for installing Terraform CLI.
Terraform provider for Citrix ADC is not available through terrform.registry.io as of now. Hence users have to install the provider manually.
-
Download the citrix adc terraform binary in your local machine where you have terraform installed from the Releases section of the github repo.Untar the files and you can find the binary file terraform-provider-ctxadc.
-
Edit .terraformrc for the base directory of plugins:
plugin_cache_dir = "/home/user/.terraform.d/plugins"
- Copy terrafom-provider-citrixadc binary in appropriate location -
$plugin_cache_dir/<platform>/terraform-provider-citrixadc. e.g./home/user/.terraform.d/plugins/linux_amd64/terraform-provider-citrixadc
-
Download the citrix adc terraform binary in your local machine where you have terraform installed from the Releases section of the github repo.Untar the files and you can find the binary file terraform-provider-ctxadc.
-
Create a following directory in your local machine and save the citrix adc terraform binary. e.g. in Ubuntu machine. Note that the directory structure has to be same as below, you can edit the version -0.12.43 to the citrix adc version you downloaded.
mkdir -p /home/user/.terraform.d/plugins/registry.terraform.io/citrix/citrixadc/0.12.43/linux_amd64/
- Copy the terraform-provider-citrixadc to the above created folder as shown below
cp terraform-provider-citrixadc /home/user/.terraform.d/plugins/registry.terraform.io/citrix/citrixadc/0.12.43/linux_amd64/
In order to familiarize with citrix adc configuration through terraform, lets get started with basic configuration of setting up server in ADC through Terraform.
Before we configure, clone the github repository in your local machine as follows:
git clone https://github.com/citrix/terraform-provider-citrixadc/
Step-1 : Now navigate to examples folder as below. Here you can find many ready to use examples for you to get started:
cd terraform-provider-citrixadc/examples/
Lets configure a simple server in citrix ADC.
cd terraform-provider-citrixadc/examples/simple_server/
Step-2 : Provider.tf contains the details of the target Citrix ADC.Edit the simple_server/provider.tf as follows and add details of your target adc.
For terraform version > 13.0 edit the provider.tf as follows
terraform {
required_providers {
citrixadc = {
source = "citrix/citrixadc"
}
}
}
provider "citrixadc" {
endpoint = "http://10.1.1.3:80"
username = "UsernameOfYourADC"
password = "PasswordOfYourADC"
}
For terraform version < 13.0, edit the provider.tf as follows
provider "citrixadc" {
endpoint = "http://10.1.1.3:80"
username = "UsernameOfYourADC"
password = "PasswordOfYourADC"
}
Step-3 : Resources.tf contains the desired state of the resources that you want to manage through terraform.Here we want to create simple server. Edit the simple_server/resources.tf with your configuration values - name,ipaddress as below.
resource "citrixadc_server" "test_server" {
name = "test_server"
ipaddress = "192.168.2.2"
}
Step-4 : Once the provider.tf and resources.tf is edited and saved with the desired values in the simple_server folder, you are good to run terraform and configure ADC.Initialize the terraform by running terraform-init inside the simple_server folder as follow:
terraform-provider-citrixadc/examples/simple_server$ terraform init
You should see following output if terraform was able to successfully find citrix adc provider and initialize it -
Step-5 : Now run the terraform-plan command. This will fetch the true state of your target ADC and will show you the changes/additions it need to make to achieve the desired configuration given in resources.tf. As we see below, terraform plans to add a new resource :
terraform-provider-citrixadc/examples/simple_server$ terraform plan
Step-6 : If the above plan looks good, then go ahead and run terraform-apply to apply the configurations. Type yes, when prompted.**
terraform-provider-citrixadc/examples/simple_server$ terraform apply
As you see above, terraform successfully created server with name test_server3 and given ipaddress on your target ADC. You can validate it by going to ADC GUI, and navigating to Traffic Management -> Load Balancing -> Servers.
Similary repeat steps 1-6 for different resource configurations on Citrix ADC. Also refer to general guidelines on configuring ADC
The provider contains a generic NITRO API resource.
Its intention is to encapsulate multiple NTIRO API endpoints in a single resource so that it is more convenient to manage and add API endpoints under the management of the Terraform network.
There are some limitations to this resource's use so make sure to read it in the resource documentation.
Provider.tf contains the information on target ADC where you want to apply configuration.
provider "citrixadc" {
username = "${var.ns_user}"
password = "${var.ns_password}"
endpoint = "http://10.71.136.250/"
}
We can use a https URL and accept the untrusted authority certificate on the Citrix ADC by specifying insecure_skip_verify = true
To use https without the need to set insecure_skip_verify = true follow this guide on
how to replace the default TLS certificate with one from a trusted Certifcate Authority.
Use of https is preferred. Using http will result in all provider configuration variables as well as resource variables
to be transmitted in cleartext. Anyone observing the HTTP data stream will be able to parse sensitive values such as the provider password.
Avoid storing provider credentials in the local state by using a backend that supports encryption. The hasicorp vault provider is also recommended for storing sensitive data.
The following arguments are supported.
username- This is the user name to access to Citrix ADC. Defaults tonsrootunless environment variableNS_LOGINhas been setpassword- This is the password to access to Citrix ADC. Defaults tonsrootunless environment variableNS_PASSWORDhas been setendpoint- (Required) Nitro API endpoint in the formhttp://<NS_IP>/orhttp://<NS_IP>:<PORT>/. Can be specified in environment variableNS_URLinsecure_skip_verify- (Optional, true/false) Whether to accept the untrusted certificate on the Citrix ADC when the Citrix ADC endpoint ishttpsproxied_ns- (Optional, NSIP) The target Citrix ADC NSIP for MAS proxied calls. When this option is defined,username,passwordandendpointmust refer to the MAS proxy.
The username, password and endpoint can be provided in environment variables NS_LOGIN, NS_PASSWORD and NS_URL.
Resources.tf contains the desired state of the resources that you want on target ADC. E.g. For creating a Load Balancing vserver in ADC following resource.tf contains the desired configs of lbvserver
citrixadc_lbvserver
resource "citrixadc_lbvserver" "foo" {
name = "sample_lb"
ipv46 = "10.71.136.150"
port = 443
servicetype = "SSL"
lbmethod = "ROUNDROBIN"
persistencetype = "COOKIEINSERT"
sslcertkey = "${citrixadc_sslcertkey.foo.certkey}"
sslprofile = "ns_default_ssl_profile_secure_frontend"
}
In order to understand the arguments, possible values, and other arguments available for a given resource, refer the NITRO API documentation https://developer-docs.citrix.com/projects/netscaler-nitro-api/en/12.0/configuration/load-balancing/lbvserver/lbvserver/ and the Terraform documentation such as https://github.com/citrix/terraform-provider-citrixadc/blob/master/docs/resources/lbvserver.md .
**Note that the attribute state is not synced with the remote object.
If the state of the lb vserver is out of sync with the terraform configuration you will need to manually taint the resource and apply the configuration again.
**
The subfolders in the example folder contains examples of different ADC configurations through terraform. Refer to simple_lb example to understand below structure and usage.
resources.tfdescribes the actual NetScaler config objects to be created. The attributes of these resources are either hard coded or looked up from input variables interraform.tfvarsvariables.tfdescribes the input variables to the terraform config. These can have defaultsprovider.tfis used to specify the username, password and endpoint of the NetScaler. Alternatively, you can set the NS_URL, NS_LOGIN and NS_PASSWORD environment variables.terraform.tfvarshas the variable inputs specified invariables.tf
Modify the terraform.tfvars and provider.tf to suit your own NetScaler deployment. Use terraform plan and terraform apply to configure the NetScaler.
Modify the set of backend services and use terraform plan and terraform apply to verify the changes
The provider will not commit the config changes to Citrix ADC's persistent store. To do this, run the shell script ns_commit.sh:
export NS_URL=http://<host>:<port>/
export NS_LOGIN=nsroot
export NS_PASSWORD=nsroot
./ns_commit.sh
To ensure that the config is saved on every run, we can use something like terraform apply && ns_commit.sh
Examples can be found in the examples directory.
| ADC Use Case | Configuration Examples |
|---|---|
| Load Balancing | lbvserver lbvserver_cmppolicy_binding lbvserver_filterpolicy_binding lbvserver_responderpolicy_binding lbvserver_rewritepolicy_binding lbvserver_service_binding lbvserver_transformpolicy_binding simple_lb simple_server |
| Content Switching | csvserver csvserver_cmppolicy_binding csvserver_cspolicy_binding csvserver_filterpolicy_binding csvserver_lbvserver_binding csvserver_responderpolicy_binding csvserver_rewritepolicy_binding csvserver_transformpolicy_binding content_switch_ssl_lb_mon |
| Responder/Rewrite Policies | csvserver_responderpolicy_binding lbvserver_responderpolicy_binding responder csvserver_rewritepolicy_binding lbvserver_rewritepolicy_binding rewrite |
| SSL | content_switch_ssl_lb_mon ssl_lb_monitors sslaction sslcipher ssldhparam sslparameter sslpolicy sslprofile sslprofile_sslcipher_binding sslvserver sslvserver_sslcertkey_binding sslvserver_sslpolicy_binding |
| Global Load Server Balancing (GSLB) | gslb gslbservice_lbmonbindings |
| Web Application Firewall (WAF) | appfwfieldtype appfwjsoncontenttype appfwpolicy appfwpolicylabel appfwprofile appfwprofile_denyurl_binding appfwprofile_starturl_binding appfwjsonerrorpage appfwprofile_fileuploadtype_binding appfwxmlschema appfwhtmlerrorpage appfwprofile_contenttype_binding appfwlearningsettings appfwglobal_appfwpolicy_binding appfwsettings appfwprofile_excluderescontenttype_binding appfwprofile_sqlinjection_binding appfwurlencodedformcontenttype appfwxmlcontenttype appfwxmlerrorpage appfwprofile_csrftag_binding appfwconfidfield appfwprofile_xmlwsiurl_binding appfwprofile_cookieconsistency_binding appfwprofile_jsoncmdurl_binding appfwprofile_xmldosurl_binding appfwprofile_xmlxss_binding appfwprofile_jsondosurl_binding appfwprofile_fieldformat_binding appfwprofile_cmdinjection_binding appfwprofile_creditcardnumber_binding appfwpolicylabel_appfwpolicy_binding appfwprofile_jsonsqlurl_binding appfwsignatures appfwprofile_xmlsqlinjection_binding appfwglobal_auditnslogpolicy_binding appfwprofile_crosssitescripting_binding appfwmultipartformcontenttype appfwprofile_fieldconsistency_binding appfwprofile_jsonxssurl_binding appfwglobal_auditsyslogpolicy_binding appfwprofile_safeobject_binding appfwwsdl appfwprofile_xmlattachmenturl_binding appfwprofile_xmlvalidationurl_binding appfwprofile_logexpression_binding appfwprofile_trustedlearningclients_binding |
| Core ADC features | cluster clusterL3 installer interface ipset linkset netprofile network nsacl nsconfig nsfeature nshttprofile nsip nsip6 nsparam nsrpcnode nstcpprofile password_resetter pinger rebooter route routerdynamicrouting saveconfig systemfile systemgroup systemuser |
| Pool Licensing | nscapacity_cico nscapacity_pooled nscapacity_vcpu nslicenseserver nslicense |
| SSL VPN | vpnglobal_auditsyslogpolicy_binding vpnglobal_authenticationcertpolicy_binding vpnglobal_authenticationldappolicy_binding vpnglobal_authenticationlocalpolicy_binding vpnglobal_authenticationnegotiatepolicy_binding vpnglobal_authenticationradiuspolicy_binding vpnglobal_authenticationsamlpolicy_binding vpnglobal_authenticationtacacspolicy_binding vpnglobal_domain_binding vpnglobal_intranetip_binding vpnglobal_intranetip6_binding vpnglobal_sharefileserver_binding vpnglobal_sslcertkey_binding vpnglobal_staserver_binding vpnglobal_vpnclientlessaccesspolicy_binding vpnglobal_vpneula_binding vpnglobal_vpnintranetapplication_binding vpnglobal_vpnnexthopserver_binding vpnglobal_vpnportaltheme_binding vpnglobal_vpnsessionpolicy_binding vpnglobal_vpntrafficpolicy_binding vpnglobal_vpnurl_binding vpnglobal_vpnurlpolicy_binding vpnintranetapplication vpnnexthopserver vpnparameter vpnpcoipprofile vpnpcoipvserverprofile vpnportaltheme vpnsamlssoprofile vpnsessionaction vpnsessionpolicy vpntrafficaction vpntrafficpolicy vpnurl vpnurlaction vpnurlpolicy vpnvserver_aaapreauthenticationpolicy_binding vpnvserver_analyticsprofile_binding vpnvserver_appcontroller_binding vpnvserver_appflowpolicy_binding vpnvserver_auditnslogpolicy_binding vpnvserver_auditsyslogpolicy_binding vpnvserver_authenticationcertpolicy_binding vpnvserver_authenticationdfapolicy_binding vpnvserver_authenticationldappolicy_binding vpnvserver_authenticationlocalpolicy_binding vpnvserver_authenticationloginschemapolicy_binding vpnvserver_authenticationnegotiatepolicy_binding vpnvserver_authenticationoauthidppolicy_binding vpnvserver_authenticationradiuspolicy_binding vpnvserver_authenticationsamlidppolicy_binding vpnvserver_authenticationsamlpolicy_binding vpnvserver_authenticationtacacspolicy_binding vpnvserver_authenticationwebauthpolicy_binding vpnvserver_cachepolicy_binding vpnvserver_cspolicy_binding vpnvserver_feopolicy_binding vpnvserver_icapolicy_binding vpnvserver_intranetip_binding vpnvserver_intranetip6_binding vpnvserver_responderpolicy_binding vpnvserver_rewritepolicy_binding vpnvserver_sharefileserver_binding vpnvserver_staserver_binding vpnvserver_vpnclientlessaccesspolicy_binding vpnvserver_vpneula_binding vpnvserver_vpnintranetapplication_binding vpnvserver_vpnnexthopserver_binding vpnvserver_vpnportaltheme_binding vpnvserver_vpnsessionpolicy_binding vpnvserver_vpntrafficpolicy_binding vpnvserver_vpnurl_binding vpnvserver_vpnurlpolicy_binding |
| Authentication | authenticationvserver_authenticationcertpolicy_binding authenticationvserver_rewritepolicy_binding authenticationcertaction authenticationcitrixauthaction authenticationldapaction authenticationvserver_authenticationldappolicy_binding authenticationsamlidppolicy authenticationoauthaction authenticationvserver_vpnportaltheme_binding authenticationvserver_authenticationwebauthpolicy_binding authenticationldappolicy authenticationvserver_auditsyslogpolicy_binding authenticationvserver_authenticationoauthidppolicy_binding authenticationvserver_cachepolicy_binding authenticationcertpolicy authenticationauthnprofile authenticationsamlidpprofile authenticationnegotiatepolicy authenticationtacacsaction authenticationvserver authenticationvserver_authenticationnegotiatepolicy_binding authenticationlocalpolicy authenticationvserver_auditnslogpolicy_binding authenticationnoauthaction authenticationldappolicy_systemglobal_binding authenticationvserver_authenticationsamlpolicy_binding authenticationnegotiateaction authenticationvserver_authenticationtacacspolicy_binding authenticationtacacspolicy authenticationvserver_authenticationlocalpolicy_binding authenticationpushservice authenticationwebauthaction authenticationcaptchaaction authenticationvserver_authenticationpolicy_binding authenticationradiuspolicy authenticationvserver_tmsessionpolicy_binding authenticationradiusaction authenticationloginschemapolicy authenticationwebauthpolicy authenticationvserver_cspolicy_binding authenticationstorefrontauthaction authenticationvserver_responderpolicy_binding authenticationvserver_authenticationsamlidppolicy_binding authenticationemailaction authenticationdfapolicy authenticationsamlpolicy authenticationloginschema authenticationoauthidpprofile authenticationepaaction authenticationvserver_authenticationloginschemapolicy_binding authenticationpolicylabel_authenticationpolicy_binding authenticationdfaaction authenticationpolicylabel authenticationsamlaction authenticationvserver_authenticationradiuspolicy_binding authenticationoauthidppolicy authenticationpolicy |
| BOT | botprofile_captcha_binding botpolicylabel botprofile botprofile_tps_binding botprofile_trapinsertionurl_binding botprofile_logexpression_binding botprofile_whitelist_binding botpolicylabel_botpolicy_binding botsettings botprofile_ratelimit_binding botsignature botprofile_ipreputation_binding botglobal_botpolicy_binding botpolicy botprofile_blacklist_binding |
| Basic | locationparameter radiusnode servicegroup_lbmonitor_binding service_lbmonitor_binding servicegroup_servicegroupmember_binding servicegroup service_dospolicy_binding extendedmemoryparam service location server |
| NS | nsconsoleloginprompt nsdiameter nsassignment nsspparams nstrafficdomain_vlan_binding nstimer nsratecontrol nsservicepath_nsservicefunction_binding nsicapprofile nshmackey nslimitidentifier nsacl6 nspartition_vxlan_binding nsdhcpparams nshttpparam nspbr6 nslicenseserver nspartition_bridgegroup_binding nssimpleacl6 nspartition nsacl nsxmlnamespace nstcpbufparam nstrafficdomain_bridgegroup_binding nsappflowcollector nshttpprofile nssimpleacl nsservicepath nspartition_vlan_binding nsservicefunction nsencryptionkey nsvpxparam nslicenseparameters nsvariable nstrafficdomain nstcpparam nstrafficdomain_vxlan_binding |
| Network | ptp netbridge_iptunnel_binding mapdomain_mapbmr_binding ip6tunnel netbridge_vlan_binding bridgetable mapdomain bridgegroup_vlan_binding nat64param bridgegroup rsskeytype netprofile_natrule_binding iptunnelparam appalgparam vxlanvlanmap_vxlan_binding bridgegroup_nsip6_binding mapbmr vridparam arpparam vrid bridgegroup_nsip_binding vrid6 vxlan_nsip6_binding mapbmr_bmrv4network_binding mapdmr vxlan fis netprofile_srcportset_binding rnatparam l4param netbridge |
Terraform is useful for maintaining desired state for a set of resources. It is less useful for tasks such as network configuration which don't change. Network configuration is like using a provisioner inside Terraform. The directory examples/remote-exec show examples of how Terraform can use ssh to accomplish these one-time tasks.
- You have (some) experience with Terraform, the different provisioners and providers that come out of the box, its configuration files, tfstate files, etc.
- You are comfortable with the Go language and its code organization.
- Install
terraformfrom https://www.terraform.io/downloads.html - Check out this code:
git clone https://<> - Build this code using
make build - Binary can be found at
$GOPATH/bin/terraform-provider-citrixadc