07/15/2024 | News release | Distributed by Public on 07/15/2024 01:19
Zscaler Blog
Get the latest Zscaler blog updates in your inbox
SubscribeContents
Introducing Zscaler-Terraformer Tool
Terraform is designed to save a considerable amount of time once configuration files are created and deployed. However, it is challenging if you already have resources in your Zscaler Platform (ZPA and/or ZIA) and you want to convert the setup such as application segments, server groups, and 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 in the Zscaler official GitHubpage called Zscaler-Terraformer, which is designed to make the adoption of infrastructure-as-code (IaC) with Terraform easier and faster for even the most complex ZPA and or ZIA configurations into Terraform HCL (HashiCorp Configuration Language) compliant format.
This tool downloads your ZPA and/or ZIA configuration, including everything you have historically defined via the Zscaler UI or API, into Terraform-compliant configuration files with just a few commands.
What is the Zscaler Terraformer Tool?
Zscaler-Terraformer is a command line tool designed to facilitate the scalable import of existing ZPA and/or ZIA existing configurations into native Terraform HCL (HashiCorp Configuration Language) compliant format.
The tool requires your Zscaler API credentials from any 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 Helpportal for more information.
You can also visit the respective Terraform Provider registry page documentation for ZPAor ZIAwhich contains detailed instructions on how to authenticate using those credentials.
The tool allows for the import of individual resources or entire configuration sets with a single line of command, including optional flags to facilitate the exclusion of specific resources, which you may not want to manage via Terraform.
Once the tool finishes the import, it automatically generates the respective configuration files (.tf) for any of the resources currently supported in one of the official Zscaler Terraform providers, as well as the respective tfstatefile.
Why do I need the Zscaler-Terraformer?
Terraform itself provides the ability to import resources natively via the command terraform-importsince version ~0.7.0; however, there were a few limitations, which required a multi-step process to get started:
This functionality has evolved in Terraform version 1.5.0, with the introduction of config-driven mechanism, which provides benefits such as automatic code generation and bulk import via new top-level import block.
The main advantages of the Zscaler-Terraformer are:
It's important to note, that both Zscaler Terraform providers also support the importing process using the traditional Terraform import command.
Simplicity is key
Managing a tool like the Zscaler-Terraformer to support two distinct Terraform providers and 50+ different resources requires a high level of sophistication. Performing regular manual changes to the source code when updates are needed is not scalable.
To simplify the management of the tool from a development standpoint, we leverage HashiCorp's terraform-execCLI tool, which streamlines the process of generating both the .tffiles and the tfstateconfigurations. By using the terraform-exec CLI, we have direct access to the JSON schema for both the ZPA and ZIA Terraform providers.
This schema allows us to automatically map the fields from the Zscaler APIs to the necessary Terraform configuration fields. This automation significantly reduces the manual coding required, making the tool more efficient and easier to maintain.
Most API response fields align directly with the JSON schema, enabling us to automatically populate the .tf configuration files. When new adjustments are needed, the tool ensures minimal impact, thus simplifying the process of supporting new resources and adapting to changes in the providers.
This approach ensures that any updates to the Terraform providers are seamlessly integrated into our tool, as we dynamically fetch the updated schemas, minimizing the need for manual code changes. For managing the tfstatefile, our tool outputs the necessary terraform import commands for each resource. This approach simplifies future updates, as the import commands remain consistent even if there are changes to the Zscaler API or the Terraform provider.
This method ensures stability and reduces the need for continuous code revisions.
How to get started
Zscaler-Terraformer is available in the Zscaler official GitHubpage and it can be installed using "homebrew" on macOS, Chocolateypackage manager for Windows, or Linux by downloading the binary directly from our release pagein the GitHub repository and place on an executable path on the machine you will be executing the Zscaler-Terraformer tool.
To install the tool using homebrew, execute the command:
$ brew install zscaler/tap/zscaler-terraformer
Setting up the environment
Before we can use the Zscaler-Terraformer tool, or any of our Terraform Providers, you need to obtain the API credentials from the respective products ZPA and/or ZIA to interact programmatically with the platform. For more information on how to generate your API credentials visit the Zscaler Helpportal.
In this example, we'll go through the environment set up with the purpose of importing resources from a Zscaler Private Access (ZPA) environment; however, the process is the same if you intend to import resources from the Zscaler Internet Access (ZIA).
In this example, we are authenticating using environment variables.
export ZPA_CLIENT_ID="" export ZPA_CLIENT_SECRET="" export ZPA_CUSTOMER_ID="" export ZPA_CLOUD=""
Second, it's important to have a centralized directory where you will be executing the tool from. In this example, I am executing the tool from a directory called "demo".
$ zscaler-terraformer import --resources="zpa"
As previously mentioned, the tool also allows for the import of specific resources.
$ zscaler-terraformer import --resources="zpa_application_segment"
To provide users with a seamless experience, the resource names between the Zscaler-Terraformer tool and our terraform providers are consistent, which means that the same resource names are used in both the providers and the importing tool itself.
In certain instances, you may want to excludesome of the resources from the importing process, in which case the tool offers the optional flag --exclude, where you can specify which resources should not be imported. This is very useful, if your only interest is to manage specific resources within either ZPA or ZIA.
The tool automatically creates a specific directory called "zpa", where all generated configuration files will be stored. By default, Zscaler-terraformer initializes the directory by downloading the latest version of the provider, and creates the provider block itself.
Verifying the configuration
Once the import is complete, zscaler-terraformer will have generated the appropriate .tf files, as well as the tfstatefile. If everything works as expected, you can safely call the command terraform planto see if terraform can verify the consistency between the upstream configuration and the statefileitself.
Once the command terraform planis executed, you should see the message in the below image informing that no changes have been identified between the current state and the desired state.
If you want to see the complete list of supported resources, visit the READMEpage here.
Zscaler and Terraform use cases
Use case 1: Using Terraform instead of the Zscaler admin UI
Terraform automates the provisioning and deployment processes of your Zscaler tenants by building the requested state with API calls to the ZPA and ZIA API endpoints. Some of the key benefits of using Terraform and Zscaler together include:
Lowering the ZPA and ZIA infrastructure bus factor riskby defining and employing source files rather than relying on a sysadmin's memory.
Use case 2: Eliminating configuration drift
Over time, several different teams and administrators might edit ZPA and ZIA configuration policies, making it difficult to keep track of all the various configuration changes. By using Terraform as a single source of truth, any changes to your ZPA or ZIA infrastructure-whether intentional or by accident-are immediately detected based on Terraform's drift management capabilities.
This allows for:
A key consideration when using Terraform is that the state file acts as the source of truth for your most recent infrastructure configuration. Operators can use the necessary state files when making updates or changes by employing the Remote State Storagefeature from Terraform Cloud. This provides secure storage and access to your organization's state files, reducing the risk of misconfigurations or errors.
These types of changes are traditionally hard to identify, but Terraform can identify any undesired changes the next time it is executed.
For more information on the risks associated with configuration drift, read our article: Securing Infrastructure by Embedding Infrastructure as Code (IaC) into Developer Workflows.
Use case 3: Policy compliance and management
Terraform helps enforce policies covering which teams can provision and use certain types of resources. By leveraging ZPA or ZIA providers, organizations can govern and scale the Zscaler platform using automation.
Terraform enables Zscaler customers to more easily automate security, and ensure security is consistently incorporated into all aspects of the application environment when adopting IaC as part of their CI/CD pipelines. This approach reduces friction between development and security teams and provides rapid application deployment and better security posture.
For more information on what the ZPA and ZIA providers have to offer, visit the provider documentation on HashiCorp's Terraform site. To ask questions, post issues, or submit contributions to the ZPA/ZIA provider project, head over to the repositories on GitHub.
If you are a Zscaler customer looking to embark in your infrastructure as code journey, and want to adopt an as code approach with Terraform to manage your Zscaler zero trust environment, the Zscaler-Terraformer tool was designed to give you a head start.
For questions, comments or feature requests, please visit any of the respective GitHub repositories:
Additional Resources
By submitting the form, you are agreeing to our privacy policy.