Zcc Skill

Zscaler Client Connector (ZCC) Skill

Diagnose-first guidance for end users writing Terraform HCL that consumes the zscaler/zcc provider. ZCC manages Zscaler Client Connector configuration — trusted networks, forwarding profiles, fail-open policy, and bypass apps. This skill does not cover provider Go code.

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

Provider status (as of 2026-04): the zscaler/zcc provider is targeting first publication. Expect ~> 0.1.x initially. Pin to the exact patch version in production until 1.0 ships.

Response Contract

Every ZCC HCL response must include:

1. Assumptions & version floor — zscaler/zcc provider version (~> 0.1.x), Terraform/OpenTofu version, auth mode (ASK if not stated — provider supports both OneAPI and legacy ZCC v2 as first-class options), cloud target (only set if non-default), and whether the resource being touched is a singleton / existing-only (which means delete is a no-op).
2. Risk category addressed — one or more of: auth misconfiguration, singleton/existing-only confusion, drift, schema-quirk handling (condition_type, GUID), secret exposure.
3. Chosen approach & tradeoffs.
4. Validation plan — terraform fmt -check, terraform validate, terraform plan -out=tfplan. No activation step exists for ZCC — changes apply directly to the API.
5. Rollback notes — for singleton resources (zcc_failopen_policy, zcc_web_app_service), terraform destroy only removes from state; the underlying API object persists. State the rollback procedure explicitly.

Workflow

1. Capture context (see fields below).
2. Diagnose intent using the routing table.
3. Load only the matching reference file(s).
4. Identify lifecycle type for the targeted resource:
   • Standard CRUD: zcc_trusted_network, zcc_forwarding_profile — full create / update / delete.
   • Singleton: zcc_failopen_policy — pre-existing per-company, create = update settings, delete = state-only.
   • Existing-only: zcc_web_app_service — create = locate by app_name and apply changes; delete = state-only.
5. Propose HCL grounded in references/resource-catalog.md — never invent attribute names.
6. Validate and 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; condensing it to # ZSCALER_CLIENT_ID, ZSCALER_CLIENT_SECRET, ZSCALER_VANITY_DOMAIN hides that fact.

OneAPI (Zidentity tenants)

terraform {
  required_version = "~> 1.9"
  required_providers {
    zcc = {
      source  = "zscaler/zcc"
      version = "~> 0.1.0"   # pin tight: pre-1.0
    }
  }
}

provider "zcc" {
  # In CI, set these env vars instead of hardcoding. The first three are required,
  # the fourth 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)
  #   ZSCALER_CLOUD           (optional — only set for non-prod, e.g. "beta")
}

Legacy ZCC v2 (pre-Zidentity tenants)

provider "zcc" {
  use_legacy_client = true
  # Env vars:
  #   ZCC_CLIENT_ID, ZCC_CLIENT_SECRET
  #   ZCC_CLOUD               ← legacy cloud name
  #   ZSCALER_USE_LEGACY_CLIENT=true
}

❌ Do not set zscaler_cloud = "zscaler" on OneAPI — zscaler is a legacy cloud name. On OneAPI, omit zscaler_cloud entirely for production tenants.

For private-key auth and credential hygiene, see Auth & Providers.

Resource Hierarchy — Small On Purpose

ZCC has a deliberately compact resource surface (4 resources). Most ZCC objects live in other systems (devices come from the agent, users from your IdP, apps from zia_*). The ZCC provider exists to manage policy on top of those objects.

For everything else (users, devices, apps), ZCC exposes data sources only — there is no resource counterpart, so do not try to manage them with resource blocks.

See Resource Catalog: Data Sources for the full schema of each.

What ZCC Does Not Have

These are common LLM hallucinations because ZIA / ZTC / ZPA do have them. ZCC does not:

• ❌ No order field on any resource — there is no rule-ordering concept.
• ❌ No state = "ENABLED" style state field — active is a boolean, not a string enum.
• ❌ No zcc_activation_status or activation step — changes apply directly.
• ❌ No zia_workload_groups-style cross-product references.
• ❌ No predefined-rule mechanic.
• ❌ No microtenant_id.

If you see a generated HCL block claiming any of these, reject it.

Naming Conventions

• Use descriptive names: resource "zcc_trusted_network" "corp_office", not ... "this".
• Reserve "this" for genuine singletons (zcc_failopen_policy).
• Standard files: main.tf, variables.tf, outputs.tf, versions.tf, providers.tf.

Critical Schema Quirks

• ❌ zcc_trusted_network.condition_type accepts both 0 and 1 depending on what the API GET returns. Set whatever the GET response shows; omit on update to leave the remote value unchanged.
• ❌ zcc_trusted_network.guid is a read-only field set by the API on create and sent automatically on PUT updates. Don't try to set it manually.
• ❌ zcc_web_app_service.app_name must match an existing tenant object — create does not create a new web app service, it locates and updates one.
• ❌ zcc_failopen_policy is a singleton per company. Multiple resource "zcc_failopen_policy" blocks in the same state will fight each other.

Full mechanics in Resource Catalog and Troubleshooting.

Credential Hygiene

• ❌ Never put client_secret, private_key, or legacy zcc_client_secret in checked-in .tfvars.
• ❌ Never echo credentials in CI job logs.
• ✅ Use env vars: ZSCALER_CLIENT_ID, ZSCALER_CLIENT_SECRET, ZSCALER_VANITY_DOMAIN, ZSCALER_CLOUD (OneAPI) or ZCC_CLIENT_ID, ZCC_CLIENT_SECRET, ZCC_CLOUD, ZSCALER_USE_LEGACY_CLIENT=true (legacy ZCC v2).
• ✅ Never mix OneAPI and legacy env vars in the same job — the provider will pick one based on use_legacy_client and the rest are ignored, which makes misconfigurations silent.
• ✅ Mark every HCL variable carrying a credential sensitive = true.

State considerations:

• The OneAPI client secret is not persisted to state.
• For singleton / existing-only resources, state contains a reference to the pre-existing API object — losing state means losing the binding, not the object.

Reference Files

Progressive disclosure:

• Auth & Providers — OneAPI vs legacy ZCC v2, env vars (and the trap of mixing them), credential hygiene.
• Resource Catalog — minimum-viable HCL per resource, singleton & existing-only patterns, data source cheat sheet.
• Troubleshooting — drift causes, schema quirks (condition_type, GUID), import semantics, never-state rm, debug logging.
• Recent Provider Changes — auto-mined from the upstream provider CHANGELOG.

Cross-cutting engineering discipline (state organization, 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 zcc_* resource.

Authoring Rule — Grounding for Uncatalogued Resources

ZCC ships a small surface (4 resources, 12 data sources), all enumerated in Resource Catalog. When asked about anything that isn't in the catalog:

1. Fetch the official Registry page first before generating any HCL:
   • Resource: https://registry.terraform.io/providers/zscaler/zcc/latest/docs/resources/<name_without_zcc_prefix>
   • Data source: https://registry.terraform.io/providers/zscaler/zcc/latest/docs/data-sources/<name_without_zcc_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 zcc_<name>, the resource does not exist — say so explicitly. (Reminder: zcc_* does not support order, state, zcc_activation_status, or microtenant_id.)

What This Skill Will Not Do

• Generate HCL with attribute names not documented on the official Terraform Registry page for that resource.
• Generate order, state = "ENABLED", zcc_activation_status, or microtenant_id — none of these exist in ZCC.
• Recommend terraform destroy on zcc_failopen_policy or zcc_web_app_service without warning that the API object persists.
• Cover provider development (the ZCC provider is built on terraform-plugin-framework, not SDK v2 — different schema/diagnostic mechanics, out of scope).