zscaler-terraform-skills

Zscaler Terraform Skills

A bundle of agent skills that teach AI coding assistants (Claude Code, Cursor, Copilot, Gemini CLI, OpenCode, Codex, …) how to design and write correct Terraform HCL for the Zscaler providers. Five skills ship in this bundle:

Skill	Scope
zpa-skill	Zscaler Private Access (zscaler/zpa) — resource catalog, OneAPI / legacy / GOV / microtenant auth, policy rules, troubleshooting.
zia-skill	Zscaler Internet Access (zscaler/zia) — resource catalog, rule ordering, activation lifecycle, troubleshooting.
ztc-skill	Zscaler Zero Trust Cloud (zscaler/ztc, formerly Cloud Branch Connector) — resource catalog, cloud-orchestrated objects, activation.
zcc-skill	Zscaler Client Connector (zscaler/zcc) — resource catalog, singleton / existing-only patterns, env-var trap.
best-practices-skill	Cross-cutting engineering discipline for any Zscaler-Terraform repo — state, CI/CD with the activation step, secrets, testing, modules, naming, anti-patterns.

The four provider skills cover provider correctness (what attributes does this resource take, how does auth work, how do you avoid known API quirks). The best-practices skill covers engineering discipline (how do you structure the repo, how do you split state, how do you wire CI/CD, how do you handle secrets and testing). Install the provider skills you use plus the best-practices skill — they're designed to compose.

What this is not. This repo does not help you develop the providers themselves (Go code, Plugin SDK, acceptance tests). It is for end users writing HCL that consumes the published zscaler/* providers. The canonical schema source for every zpa_*, zia_*, ztc_*, and zcc_* resource is the official Terraform Registry: https://registry.terraform.io/providers/zscaler.

What these skills provide

Provider correctness (zpa, zia, ztc, zcc)

• Resource catalog per provider with minimum-viable HCL grounded in the live Registry
• OneAPI vs legacy v3 vs GOV authentication patterns; multi-cloud vanity-domain handling
• Microtenant scoping (microtenant_id) for the ZPA resources that actually accept it
• Policy-rule operand structures (ZPA access policy, ZIA URL filtering, ZTC firewall) — the parts that aren't obvious from the schema
• Activation lifecycle: which products require it (ZIA, ZTC) and which don't (ZPA, ZCC)
• Known API quirks distilled from real customer support cases

Engineering discipline (best-practices)

• State organization for multi-microtenant, multi-team Zscaler estates
• The Zscaler activation step in CI pipelines (frequently forgotten by base LLMs)
• Secret handling: OneAPI rotation, the ZSCALER_* vs <product>_* env-var trap, write-only / ephemeral variables (Terraform 1.11+)
• Module patterns sized to Zscaler API granularity, not generic AWS-shaped boilerplate
• Naming, variables, outputs, and 30+ documented anti-patterns specific to Zscaler resource graphs

Testing strategy

• Three-layer test pyramid: unit.tftest.hcl (plan-only, no creds) → mock.tftest.hcl (mock_provider, Terraform 1.7+) → integration.tftest.hcl (sandbox tenant only)
• When to use terraform test vs Terratest for Zscaler workloads
• Sandbox-tenant guardrails — never run integration tests against production credentials

CI/CD workflows

• GitHub Actions templates that include the activation step
• OIDC against Zidentity (preferred) vs long-lived OneAPI client secrets
• Drift detection, scheduled plans, PR-test/apply-on-merge gates with terraform validate + terraform plan -out

Security & secrets

• OneAPI client rotation strategy and per-environment scoping (sandbox vs production tenants)
• Write-only / ephemeral variables for client_secret handling (Terraform 1.11+)
• The provider env-var trap that silently authenticates against the wrong namespace

Quick reference