Terraform is a tremendous time-saver once you have your configuration files in place, but what do you do if you already have resources in your Zscaler Platform (ZPA and/or ZIA) and now you want to convert your setup such as application segments, server groups, access policies from ZPA or ZIA Cloud Firewall rules into Terraform configuration files?
Today we are excited to share a new open-source tool available on GitHub now to make the migration of even the most complex ZPA and or ZIA configurations into Terraform simple and fast.
The tool is called Zscaler-Terraformer and it downloads your ZPA and/or ZIA set up, meaning everything you’ve defined via the Zscaler UI and API, into Terraform-compliant configuration files with just a few commands.
Zscaler-Terraformer is a command line tool that can be invoked with your Zscaler API credentials from either one of the products you want to manage via Terraform. If you want more information on how to create your API credentials in ZPA or ZIA visit the Zscaler Help portal for more information. You can also visit the Terraform registry documentation, which contains detailed instructions on how to authenticate using those credentials.
The tool can create configuration files for any of the resources currently available in one of the official Zscaler Terraform providers.
Let’s assume, you’re migrating your ZPA configuration to Terraform and you want to import either your entire configuration or only individual resources. You simply need to call zscaler-terraformer with your API credentials, and the name of the provider or the name of the specific resource.
Importing ZPA Resources via Zscaler-Terraformer Tool
This command will import the entire ZPA configuration
This command will import all ZPA segment group, including all associated resources.
Importing ZIA Resources via Zscaler-Terraformer Tool
This command will import the entire ZIA configuration
This command will import all ZIA Cloud Firewall Rules, including all associated resources.
Which Resources Are Supported?
Currently, Zscaler-Terraformer support every resource type that you can manage via one of the official Terraform Providers. To see the full list of supported resources, visit the project GitHub repository.
We are looking for feedback and any issues you might encounter while getting up and running with Zscaler-Terraformer tool. Please open any issues against the GitHub repository. The tool is open-source, so if you want to get involved, feel free open an issue or make a pull request.
- Zscaler Terraformer GitHub Repository
- Terraform Tutorial | Importing Existing ZPA Resources to Terraform
- Community Slack Channel
In this video, we’ll explore
0:00:04;00 – 0:00:25;10 – Introduction
0:00:25;11 – 0:01:21;14 – Pre-Requisites
0:01:21;15 – 0:01:55;00 – Zscaler Terraformer Installation
0:01:55;02 – 0:02:41;20 – Native Terraform Import Command limitations
0:02:41;21 - 0:03:08;01 – Zscaler Terraformer Help
0:03:48;29 – 0:03:48;28 – Generate Terraform Configuration
0:03:49;06 – 0:04:19;12 – Zscaler Terraformer – ZPA Demo
0:04:19;18 – 0:04:56;17 – Zscaler Terraformer – ZIA Demo
0:04:56;19 – 0:05:53;02 – Summary
Hi, my name is William Guilherme, and I am a Solutions Architect at Zscaler with the Technology Alliances Team.
In this video, I am happy to introduce a new utility tool called Zscaler Terraformer, which is designed to expedite the import of your existing ZPA and ZIA resources to HashiCorp Configuration Language (HCL) in a matter of minutes instead of hours.
Before you proceed it is important to have all the necessary pre-requisites in place. You can also visit our Zenith Community and watch our pre-requisites video in the ZPA Terraform video series, by clicking in the link description below.
Because the Zscaler Terraformer tool, needs to authenticate to the Zscaler platform:
- The first pre-requisite is that you must have an administrator account in either ZPA and/or ZIA
- Second, you must create an API Key which is required as part of the authentication process.
- Next, the Zscaler Terraformer tool can be installed via the Homebrew package manager in MacOS or Linux; however, an exe option is also available for download in case in need to execute the tool in a Windows system.
- It is also important that you ensure your system have Terraform 0.13 or above installed as well as bash interpreter to execute to tool.
To install the Zscaler-Terraformer tool you only need to run a couple commands in your terminal on MacOS or Linux system.
If you are on MacOS or Linux and have the Homebrew package manager installed, you can run the command:
- brew tap zscaler/tap and then
- brew install zscaler/tap/zscaler-terraformer
- You can also install the tool using the –cask flag.
- Both options will result in the successful installation of the tool.
Although not covered in this video, the traditional way of importing resources into Terraform have some limitations that can make the migration process daunting and time consuming.
If you want to see the process in detail, I suggest visiting the Terraform Tutorial | Importing Existing ZPA Resources to Terraform linked in the description below, where we walk through the step by step on how to use the Terraform import command in the context of ZPA.
For sake of this video, we will cover only a few of the limitations.
First, the import command only generates the Terraform Statefile and it does not generate the HCL code itself or the actual resource blocks.
That means, that once the Terraform import command is executed it is up to the administrator to ensure that the actual HCL code is put together.
Zscaler Terraformer – Help
If you want to see the several available flag commands provided by the Zscaler-Terraformer tool, you can type zscaler-terraformer -h or simply zscaler-terraformer.
Remember that in order to use the tool, you must be authenticated using one of the multiple authentication methods described in the first part of this video with the respective API credentials of each product (ZPA and/or ZIA).
As mentioned in the beginning of this video, the Zscaler-Terraformer tool, is an open-source utility, designed to support the fast migration of ZPA and ZIA resources into native HCL language.
You only need a single line of command that will generate the configuration blocks and produce the HCL configuration resources.
For example: the flag --resources allow you to specify either the name of a single resource to be imported, or if you’d like to import all supported resources into your HCL configuration, you only need to specify the resources flag followed by the provider name in between double quotes such as for example “zpa”
In this demo, we are importing all our configuration from a ZPA tenant; however, it is also possible to import individual resource types if desired.
In this example, we are using the –resources flag followed by the provider name “zpa”. The process may take a few minutes depending on the number of resources being imported.
Once the import process is concluded, notice that the zscaler-terraformer tool creates a specific with the name of the provider containing individual files per resource type.
In this next demo, we are importing all our configuration resources from a ZIA tenant. Notice that just like the ZPA resource import process, it is also possible to import individual ZIA resource types if desired.
For sake of this demo, we are importing all resources by using the resources flag followed by the provider name “zia”
The zscaler-terraformer tool will create a specific folder with the name of the provider containing individual file per ZIA resource type.
In summary, to get started with the Zscaler-Terraformer tool:
- You must ensure you have the necessary pre-requisites in place as described at the beginning of this video.
- The tool requires authentication to the respective Zscaler products ZPA and or ZIA, either via static credentials or environment variables.
- The installation is currently only available via Homebrew package manager. The use of the tool in Windows systems, requires the manual download of the exe file.
- The tool automatically creates the state file as well as the HCL files. There is no need to manually reconfigure the HCL files once the import is concluded.
- The tool automatically initializes the repository by always downloading the latest provider binary.
- Finally, you can utilize the tool, to import configuration from any of the supported ZPA and/or ZIA clouds.