Best Practices Skill

Zscaler Terraform — Best Practices Skill

Diagnose-first guidance for how to structure, ship, and operate Terraform repositories that consume the Zscaler providers. This skill is provider-agnostic across the four Zscaler products — for resource-level catalog, auth, and lifecycle quirks of a specific provider, route to zpa-skill / zia-skill / ztc-skill / zcc-skill.

Scope: state organization, CI/CD shape, secret handling, testing strategy, module patterns, naming, versioning, anti-patterns. Things that don't belong in any single provider skill because they apply to all of them — and are different enough from generic Terraform to need Zscaler-specific guidance.

Response Contract

Every best-practices response must include:

1. Assumptions & version floor — Terraform/OpenTofu version, which Zscaler providers are in scope, runtime environment (local/CI/Cloud), team size, environment criticality.
2. Risk category addressed — one or more of: state organization, blast radius, secret exposure, CI drift, activation-in-CI gap, testing gap, compliance gap, module-boundary violation, version drift, anti-pattern.
3. Chosen approach & tradeoffs — what was chosen, what was traded off, why.
4. Validation plan — commands tailored to the change (fmt -check, validate, plan -out, trivy config, checkov, terraform test).
5. Rollback / recovery — for any state-mutating change: how to undo, what evidence to retain (especially for activation-bearing changes).

Never recommend terraform state rm against any Zscaler resource (orphans the API object — see provider skills' troubleshooting).

For ZIA and ZTC, never propose a design that applies two states against the same tenant concurrently, or that activates once per state. The tenant has a single write lock and a single activation queue regardless of how state is split — see Concurrency Is a Tenant Property.

Workflow

1. Capture context (fields below).
2. Diagnose discipline gap(s) using the routing table.
3. Load only the matching reference file(s).
4. Propose the change with risk controls (tests, approvals, rollback).
5. Cross-link the relevant provider skill(s) for resource-level details.
6. Validate before finalizing.
7. Emit the Response Contract.

Capture Context — Fields to Confirm

Diagnose Before You Generate

Cross-Cutting Principles (Compressed)

These apply to every Zscaler-Terraform repo regardless of which provider you use. Detailed playbooks live in the references; this section is the fast-path.

Never store credentials in code or state

• ❌ client_secret, password, api_key, private_key in .tfvars checked into git.
• ❌ client_secret in a Terraform variable on Terraform < 1.11 (it ends up in state, even with sensitive = true).
• ✅ Source from env vars in CI (ZSCALER_CLIENT_SECRET, ZSCALER_PRIVATE_KEY, ZIA_API_KEY, etc.).
• ✅ On Terraform 1.11+, use write_only arguments (*_wo) to keep credentials out of state entirely.
• ✅ Prefer OIDC federation (GitHub Actions → Zidentity) over long-lived static keys when available.

See Security & Compliance.

Never terraform state rm a Zscaler resource

The API object stays orphaned. Use terraform apply -target= (selective destroy) or removed blocks (Terraform 1.7+) instead. See each provider skill's troubleshooting for product-specific recovery.

Activation is a pipeline stage, not an afterthought (ZIA & ZTC)

• ❌ Apply ZIA/ZTC resources without <product>_activation_status in the same state.
• ❌ Manual console activation in production CI flows (no audit trail, race-prone).
• ✅ Include zia_activation_status / ztc_activation_status as a depends_on resource at the bottom of the same state.
• ✅ For multi-stage pipelines, the activation stage is its own job that depends on the apply stage's success — never re-run plan inside the apply job.
• ZPA & ZCC have no activation step — changes take effect on apply.

See CI/CD: Activation as a Pipeline Stage.

One state per blast-radius boundary, not per provider

• ❌ All ZPA + ZIA + ZTC + ZCC in one state file (any change blocks every team's plans).
• ❌ One state per microtenant if there are 100 of them (lockfile fan-out, no CI parallelism).
• ✅ Split state on policy ownership boundary: who reviews and approves changes to this set of resources? That's a state.
• ✅ Common starter shape: per-product, per-environment, per-microtenant-cohort.

See State Management.

Use for_each over count for any list of named Zscaler objects

count over a list reshuffles every address when an item is removed from the middle — meaning a single removed app segment can churn every downstream zpa_application_segment resource. Use for_each = toset(...) or for_each = map. The only safe count is the boolean count = condition ? 1 : 0 toggle for an optional resource.

Pin runtime, providers, and the lockfile

• required_version = "~> 1.9" (or your floor).
• version = "~> 4.0" for zscaler/zpa, zscaler/zia, zscaler/ztc; version = "~> 0.1" for the not-yet-1.0 zscaler/zcc.
• Commit .terraform.lock.hcl. Updates are a separate PR from feature work.

Test before you ship — even if "test" means a sandbox tenant

• ✅ Static analysis (fmt -check, validate, tflint) on every PR — free, instant.
• ✅ terraform plan against a non-prod tenant on every PR.
• ✅ terraform test (Terraform 1.6+) for input-validation coverage.
• ⚠️ Mock providers (1.7+) help with input shape but cannot validate Zscaler API behavior — pair with sandbox-tenant integration on merge to main.
• ✅ Tag any test-created resources for cleanup; have a sweeper job.

See Testing & Validation.

Module Hierarchy (when you decide to build modules)

The module boundary is purpose, not product.

❌ Do not bundle unrelated zia_* and zpa_* resources in one module — different lifecycles, different activation rules, different tenants likely. ✅ Do declare two providers in one module when a single feature spans both products. zia_forwarding_control_zpa_gateway (IP Source Anchoring) is defined by the external_id of a ZPA server group and application segment, which only the ZPA provider can supply — that module needs zia and zpa in required_providers.

✅ Modules are reusable; root configs are not. Reusable modules never declare provider blocks — the root composes them.

Detailed patterns: Module Patterns.

Reference Files

Progressive disclosure — essentials in this skill router, depth on demand.

Operational discipline:

• State Management — backends, per-tenant / per-microtenant state organization, never-state rm rationale, multi-team isolation, cross-state references.
• CI/CD for Zscaler — GitHub Actions / GitLab CI / Atlantis templates with the activation step, OIDC against Zidentity, plan-artifact discipline, secret handling, per-microtenant CI parallelism.
• Security & Compliance — secrets out of state (write_only / ephemeral on 1.11+), Trivy/Checkov/tflint, custom OPA policies, audit-trail pattern, SOC2 / ISO 27001 / PCI / FedRAMP mappings.
• Testing & Validation — terraform test (1.6+), mock_provider (1.7+) limits, sandbox-tenant integration with cleanup, acceptance-criteria-by-risk-tier table.

Code shape:

• Module Patterns — required files, boundaries, composition, nested modules, examples directory, cross-state composition.
• Coding Practices — count vs for_each vs dynamic, locals, validation, dependency management, provider-block hygiene.
• Naming Conventions — Terraform addresses, Zscaler portal names, variables, outputs, locals, files, modules, cross-provider consistency.
• Variables and Outputs — typing, optional(), validation blocks, sensitive handling, output design, Zscaler-flavored variable templates.

Process discipline:

• Versioning — Terraform / provider pins, lockfile discipline, module SemVer, moved {}, OneAPI migration.
• Anti-Patterns — quick-index table of every footgun + detail on the non-obvious ones.
• Import and Brownfield — zscaler-terraformer for existing ZIA/ZPA tenants, per-resource imports, removed {} instead of state rm, write-only-value limits.

Cross-cutting peer equivalence:

• Cross-Product Equivalents — side-by-side tables across zpa / zia / ztc / zcc for auth, activation, microtenancy, version pins, rule-style rules, data-source-only objects, and cross-product composition recipes (ZIA → ZPA gateway, ZCC → ZIA tunnel, ZTC → ZIA location). Load this when the prompt mentions more than one product, when the user asks "what's the equivalent of X in Y", or when you catch yourself about to default to ZPA / OneAPI / S3.

Fast lookup:

• Quick Reference — DO/DON'T cheat sheet across all four Zscaler providers.

Cross-References

Provider-specific guidance lives in the per-product skills. When the answer needs a resource attribute or auth field, route there:

• zpa-skill — Zscaler Private Access resource catalog, OneAPI / legacy / GOV / microtenant auth, policy rule semantics.
• zia-skill — Zscaler Internet Access resource catalog, rule ordering, activation lifecycle.
• ztc-skill — Zscaler Zero Trust Cloud resource catalog, cloud-orchestrated objects, activation lifecycle.
• zcc-skill — Zscaler Client Connector resource catalog, singleton / existing-only patterns.

What This Skill Will Not Do

• Generate provider-specific HCL with attribute names — route to the relevant provider skill.
• Cover provider development (Plugin SDK schema, expand/flatten, acceptance tests) — out of scope.
• Recommend a state-file split for a repo whose blast-radius / approval boundaries you haven't described — ask first.