Introducing Zscaler Terraformer Tool

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 GitHub page 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 Help portal for more information.

You can also visit the respective Terraform Provider registry page documentation for ZPA or ZIA which 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 tfstate file.

Why do I need the Zscaler-Terraformer?

Terraform itself provides the ability to import resources natively via the command terraform-import since version ~0.7.0; however, there were a few limitations, which required a multi-step process to get started:

• Resources could only be imported one at a time
• The resource blocks had to be manually written
• Once the resource was imported some attributes had to be cleaned up such as Computed attributes

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 designed to be compatible with both Zscaler Terraform Providers for ZPA and ZIA
• It’s capable of importing a single or multiple resources using a single command line
• It automatically generates the (.tf) files by removing any attribute considered computed, so that you as the developer don’t have to worry about performing manual cleanups
• It allows for the exclusion of specific resources during bulk import by using a specific --exclude flag

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-exec CLI tool, which streamlines the process of generating both the .tf files and the tfstate configurations. 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 tfstate file, 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 GitHub page and it can be installed using "homebrew" on macOS, Chocolatey package manager for Windows, or Linux by downloading the binary directly from our release page in 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 Help portal.

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="<client_id>"
export ZPA_CLIENT_SECRET="<client_secret>"
export ZPA_CUSTOMER_ID="<customer_id>"
export ZPA_CLOUD="<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 exclude some 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 tfstate file. If everything works as expected, you can safely call the command terraform plan to see if terraform can verify the consistency between the upstream configuration and the statefile itself. 

Once the command terraform plan is 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 README page 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:

• Reducing maintenance by making the ZPA and ZIA configuration more predictable and deterministic based on the state file configuration
• Minimizing ZPA/ZIA management overhead when onboarding new applications or enforcing new security policies

Lowering the ZPA and ZIA infrastructure bus factor risk by 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:

• Reduced need to analyze audit logs to find any changed configuration
• Improved security in case unauthorized configuration changes are detected

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 Storage feature 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.

• ITSM: Ticket-based review processes are a bottleneck that can slow down development. Instead, you can use an integration workflow such as the one described in our guide: Zscaler Private Access and HashiCorp Terraform with ServiceNow Approval Workflow Deployment.
   
• Workspace management: If your organization leverages the ZIA Terraform provider to configure the Cloud Firewall module managed by the security team, you can restrict them to their specific workspace so that they cannot configure other features or resources not associated with their function. The same applies if your organization is leveraging the ZPA Terraform provider—you can set specific teams to perform changes to an application segment while other teams can create or change access policies.

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

• Zscaler-Terraformer GitHub Repository
• Zscaler-Terraformer Demo
• Terraform Provider for Zscaler Private Access (ZPA)
• Terraform Provider for Zscaler Internet Access (ZIA)
• Terraform Providers Project on GitHub