Zpa Skill

Zscaler Private Access (ZPA) Skill

Diagnose-first guidance for end users writing Terraform HCL that consumes the zscaler/zpa provider. This skill does not cover provider Go code (Plugin SDK schema, expand/flatten, acceptance tests).

Canonical source of truth for resource/data-source schemas: https://registry.terraform.io/providers/zscaler/zpa/latest/docs.

Response Contract

Every ZPA HCL response must include:

1. Assumptions & version floor — zscaler/zpa provider version (~> 4.0 minimum for OneAPI), Terraform/OpenTofu version, auth mode (ASK if not stated — provider supports both OneAPI and legacy v3 as first-class options), ZPA customer ID, cloud target (only set if non-default), microtenant scope (yes/no + which microtenant_id). State assumptions explicitly if the user did not provide them.
2. Risk category addressed — one or more of: auth misconfiguration, resource catalog mismatch, policy operand misuse, dependency / detach order, microtenant scoping, drift, secret exposure.
3. Chosen approach & tradeoffs — what was chosen, what was traded off (e.g. data-source lookup vs hardcoded ID), why.
4. Validation plan — exact commands: terraform fmt -check, terraform validate, terraform plan -out=tfplan, optional terraform show -json tfplan | jq to inspect operand JSON before apply.
5. Rollback notes — for any policy-rule or segment-group change: how to undo (re-apply previous HCL, terraform state rm not safe for ZPA — see Troubleshooting), what evidence to keep (debug log capture).

Never recommend terraform apply against a production ZPA tenant without a reviewed plan artifact and a microtenant scope check.

Workflow

1. Capture context (see fields below).
2. Diagnose intent using the routing table.
3. Load only the matching reference file(s). Do not preload depth the task does not need.
4. Propose HCL grounded in the canonical examples from references/resource-catalog.md — never invent attribute names.
5. Validate with the commands tailored to risk tier.
6. Emit the Response Contract.

Capture Context — Fields to Confirm

Diagnose Before You Generate

Provider Block — Pick One

The provider supports two auth paths. Pick based on whether the tenant has been migrated to Zidentity. Do not default — confirm with the user.

Authoring rule (do not summarise): when emitting an OneAPI provider block, reproduce the env-var comment list verbatim — including ZSCALER_CLOUD with its optional annotation. Users need to discover that ZSCALER_CLOUD exists as a supported (but optional) parameter for OneAPI; condensing it to # ZSCALER_CLIENT_ID, ZSCALER_CLIENT_SECRET, ZSCALER_VANITY_DOMAIN, ZPA_CUSTOMER_ID hides that fact.

OneAPI (Zidentity tenants)

terraform {
  required_version = "~> 1.9"
  required_providers {
    zpa = {
      source  = "zscaler/zpa"
      version = "~> 4.0"
    }
  }
}

provider "zpa" {
  # In CI, set these env vars instead of hardcoding. The first four are required,
  # the fifth is optional and only used to target a non-production Zidentity environment.
  #   ZSCALER_CLIENT_ID       (required)
  #   ZSCALER_CLIENT_SECRET   (required; or ZSCALER_PRIVATE_KEY)
  #   ZSCALER_VANITY_DOMAIN   (required)
  #   ZPA_CUSTOMER_ID         (required)
  #   ZSCALER_CLOUD           (optional — only set for non-prod, e.g. "beta")
}

Legacy v3 (pre-Zidentity tenants, or FedRAMP below v4.4.6)

provider "zpa" {
  use_legacy_client = true
  # Env vars:
  #   ZPA_CLIENT_ID, ZPA_CLIENT_SECRET, ZPA_CUSTOMER_ID
  #   ZPA_CLOUD               ← REQUIRED only when not PRODUCTION: BETA | ZPATWO | GOV | GOVUS | PREVIEW
  #   ZSCALER_USE_LEGACY_CLIENT=true
}

❌ Do not set zscaler_cloud = "PRODUCTION" on OneAPI — PRODUCTION is a legacy zpa_cloud value. On OneAPI, omit zscaler_cloud entirely for production tenants.

For private-key auth and microtenant scoping, see Auth & Providers.

Resource Hierarchy

Standard composition flow: Application Server → Server Group ← Segment Group ← Application Segment → referenced by Policy Rule. See Resource Catalog: Composition Recipes.

Naming Conventions

• Use descriptive names: resource "zpa_application_segment" "crm_app", not ... "this".
• Reserve "this" for genuine singletons (e.g. a single zpa_microtenant_controller).
• Prefix variables with context: zpa_segment_group_id, not id.
• Standard files: main.tf, variables.tf, outputs.tf, versions.tf, providers.tf.

Block Ordering

Resource blocks: count/for_each first → required arguments → optional arguments → nested blocks → lifecycle. Variable blocks: description → type → default → validation → nullable → sensitive.

Policy Rules — Quick Rules

• Always look up policy_set_id via data "zpa_policy_type" — never hardcode.
• Always prefer data sources (data.zpa_application_segment.x.id) over literal IDs.
• conditions is an ordered list of OR-groups combined by the rule-level operator. Inside each conditions block, multiple operands are combined by that block's operator.
• operands.object_type is a closed enum (APP, APP_GROUP, SCIM, SCIM_GROUP, SAML, IDP, POSTURE, TRUSTED_NETWORK, CLIENT_TYPE, PLATFORM, COUNTRY_CODE, MACHINE_GRP, …).
• lhs / rhs semantics depend on object_type. For SCIM_GROUP, lhs = idp_id, rhs = scim_group_id. For APP, lhs = "id", rhs = application_segment_id. Get this wrong → 400 INVALID_INPUT.

Full mapping in Policy Rules: Operand Reference.

Microtenants — When to Worry

If the customer's tenant uses microtenants, every resource and every data source call must pass the same microtenant_id. Mixing scopes silently breaks Read (returns 404 → Terraform recreates the resource). See Troubleshooting: Microtenant 404.

resource "zpa_application_segment" "crm" {
  name           = "CRM"
  microtenant_id = var.zpa_microtenant_id  # propagate consistently
  # ...
}

If the user does not mention microtenants, assume parent tenant and state that assumption in the Response Contract.

Data-Source-Only Objects

ZPA exposes 70 resources and 70 data sources, but ~30 of those data sources have no matching resource because the underlying object is provisioned by another system (IdP, posture vendor, ZPA console, cloud orchestration). Common data-source-only objects:

Always check the official Terraform Registry before assuming there's a matching resource:

• Resources index: https://registry.terraform.io/providers/zscaler/zpa/latest/docs
• Specific resource: https://registry.terraform.io/providers/zscaler/zpa/latest/docs/resources/<name_without_zpa_prefix>
• Specific data source: https://registry.terraform.io/providers/zscaler/zpa/latest/docs/data-sources/<name_without_zpa_prefix>

If only the data-source page exists for an object, it's read-only.

❌ Do not propose resource "zpa_idp_controller" — IdPs are configured in the ZPA admin console, not by Terraform. ✅ Use data "zpa_idp_controller" { name = "Okta" } to look one up for use in policy operands.

Credential Hygiene

• ❌ Never put client_secret, private_key, or customer_id in .tfvars checked into git.
• ❌ Never echo credentials in CI job logs.
• ❌ Do not mix ZSCALER_* and ZPA_* env vars in the same job — the provider picks one path based on use_legacy_client and silently ignores the other namespace. (ZPA_CUSTOMER_ID is the exception — it is required for both modes.)
• ✅ Use env vars matching your auth path:
  • OneAPI: ZSCALER_CLIENT_ID, ZSCALER_CLIENT_SECRET (or ZSCALER_PRIVATE_KEY), ZSCALER_VANITY_DOMAIN, ZPA_CUSTOMER_ID, optionally ZSCALER_CLOUD for non-prod.
  • Legacy: ZPA_CLIENT_ID, ZPA_CLIENT_SECRET, ZPA_CUSTOMER_ID, ZSCALER_USE_LEGACY_CLIENT=true, plus ZPA_CLOUD for non-PRODUCTION clouds.
• ✅ Source from your secret store (Vault, AWS Secrets Manager, GH Actions secrets) and inject as env at job start.
• ✅ Mark any HCL variable that holds these sensitive = true even though it's display-only — it prevents accidental terraform output / log leakage.

State files contain identifiers (segment IDs, server IDs) but not the OneAPI client secret, since auth is config-only and not persisted. Still, treat state as sensitive — restrict S3/GCS bucket access.

Reference Files

Progressive disclosure — essentials here, depth on demand:

• Auth & Providers — provider config, OneAPI vs legacy, env vars, GOV cloud, microtenant config, credential hygiene.
• Resource Catalog — minimum-viable HCL per resource, composition recipes, data-source lookups.
• Policy Rules — policy type map, operand reference, condition composition, ordering, common 400 errors.
• Troubleshooting — drift causes, detach-before-delete, microtenant 404, debug logging.
• Recent Provider Changes — auto-mined from the upstream provider CHANGELOG; lists user-facing additions and breaking changes from the last several releases.

Cross-cutting engineering discipline (state organization, microtenant blast radius, CI/CD, secret handling, testing strategy, modules, naming, versioning) lives in the sibling best-practices-skill — load it whenever the question is about how to structure or operate a Zscaler-Terraform repo rather than how to call a specific zpa_* resource.

Authoring Rule — Grounding for Uncatalogued Resources

The reference catalog ships canonical HCL for the most-used zpa_* resources, but ZPA exposes 70 resources and 70 data sources. When asked about an object not in Resource Catalog:

1. Fetch the official Registry page first before generating any HCL:
   • Resource: https://registry.terraform.io/providers/zscaler/zpa/latest/docs/resources/<name_without_zpa_prefix>
   • Data source: https://registry.terraform.io/providers/zscaler/zpa/latest/docs/data-sources/<name_without_zpa_prefix>
2. Ground every attribute name in that fetched page.
3. State the Registry URL you used in the Response Contract Assumptions section.

❌ Never invent attribute names. ✅ If the Registry page does not exist for a zpa_<name>, the resource does not exist — say so explicitly.

What This Skill Will Not Do

• Generate HCL with attribute names not documented on the official Terraform Registry page for that resource.
• Recommend terraform state rm for ZPA resources (orphans the API object, see Troubleshooting).
• Cover provider development (Plugin SDK schema, expand/flatten, acceptance tests) — out of scope.