Use when writing, reviewing, or debugging Terraform HCL that uses the Zscaler Zero Trust Cloud (ZTC, formerly Cloud Branch Connector) provider — covers provider auth (OneAPI / legacy / multi-cloud), the resource catalog (edge connector groups, location management, forwarding gateways, traffic forwarding rules, network services, IP source/destination/pool groups, workload groups, ZIA forwarding gateways), rule ordering semantics, the activation lifecycle (`ztc_activation_status`), and the data-source-first pattern for cloud-orchestrated objects.
How this skill is triggered — by the user, by Claude, or both
Slash command
/zscaler-terraform-skills:ztc-skillThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Diagnose-first guidance for **end users writing Terraform HCL that consumes the `zscaler/ztc` provider**. ZTC is the Zscaler Zero Trust Cloud product (formerly Cloud Branch Connector — the rebrand affects branding only; resource names still use `ztc_` and the API path remains `/cloud-branch-connector`). This skill does not cover provider Go code.
Diagnose-first guidance for end users writing Terraform HCL that consumes the zscaler/ztc provider. ZTC is the Zscaler Zero Trust Cloud product (formerly Cloud Branch Connector — the rebrand affects branding only; resource names still use ztc_ and the API path remains /cloud-branch-connector). This skill does not cover provider Go code.
Canonical source of truth for resource/data-source schemas: https://registry.terraform.io/providers/zscaler/ztc/latest/docs.
Every ZTC HCL response must include:
zscaler/ztc provider version (~> 0.1.x is current; the provider is pre-1.0), Terraform/OpenTofu version, auth mode (ASK if not stated — provider supports both OneAPI and legacy v3 as first-class options), cloud target (only set if non-default), and whether the configuration creates or modifies any resource (which makes activation mandatory).terraform fmt -check, terraform validate, terraform plan -out=tfplan, plus a ztc_activation_status step if any resource is created/modified (changes are draft until activated).terraform state rm a ZTC resource backed by a real API object.The provider is pre-1.0 (~> 0.1.x). Surface this in the assumptions: schemas may change between minor releases. Pin to the exact patch version in production until 1.0 ships.
references/resource-catalog.md — never invent attribute names.ztc_activation_status resource or document a manual activation step.| Field | Why it matters | Default if missing |
|---|---|---|
| Provider version | Pre-1.0; schemas may change. Latest stable is ~> 0.1.x. | Assume latest 0.1.x and state it. |
| Auth mode | OneAPI and legacy v3 are both first-class. Tenant must be migrated to Zidentity for OneAPI; otherwise legacy is the only option. zscalergov / zscalerten are legacy-only. | Ask. Do not default. State both options if unclear. |
| Cloud target | OneAPI: zscaler_cloud is optional and only set for non-prod (e.g. beta). Legacy: ztc_cloud is required and names the cloud (zscaler, zscloud, zscalergov, …). | Omit zscaler_cloud for production OneAPI. Ask for legacy. |
| Activation | ANY create/update/delete on a ZTC resource needs ztc_activation_status. Pure data-source workflows do not. | If any resource is touched: include activation. Always. |
| Cloud orchestration | Which objects already exist in the tenant (created by AWS/Azure/GCP integrations) vs. what TF should create. | Ask. Default: locations and edge connector groups exist. |
| Rule ordering | order and rank apply to traffic forwarding rules — must follow the same rules as ZIA. | Ask if rule order matters. |
| Terraform runtime | Affects optional(), moved, import, removed availability. | Assume terraform ~> 1.9. |
| Failure category | Symptoms | Primary references |
|---|---|---|
| Auth misconfiguration | 401 unauthorized, vanity_domain not found, GOV cloud rejecting OneAPI | Auth & Providers |
| Cloud-orchestrated resource confusion | Trying to resource "ztc_location_management" instead of data — the object is created by the cloud integration | Resource Catalog: Cloud-Orchestrated Objects |
| Resource catalog mismatch | Invented attribute names, wrong block structure | Resource Catalog |
| Rule ordering | order = 0 rejected, rules drift after a delete, rule reorder race conditions | Rules & Ordering |
| Activation forgotten | terraform apply succeeds but config doesn't take effect | Rules & Ordering: Activation |
| OneAPI vs Legacy availability gap | Resource works on legacy auth but read returns empty / partial data on OneAPI (or vice versa) | Troubleshooting: OneAPI vs Legacy gaps |
| Drift on every plan | Bool flips, computed defaults churn | Troubleshooting: Drift Causes |
| Secret exposure | Credentials in .tfvars, in state, in CI logs | Auth & Providers: Credential Hygiene |
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_CLOUDwith itsoptionalannotation. Users need to discover thatZSCALER_CLOUDexists as a supported (but optional) parameter; condensing it to# ZSCALER_CLIENT_ID, ZSCALER_CLIENT_SECRET, ZSCALER_VANITY_DOMAINhides that fact.
terraform {
required_version = "~> 1.9"
required_providers {
ztc = {
source = "zscaler/ztc"
version = "~> 0.1.8" # pin tight: provider is pre-1.0
}
}
}
provider "ztc" {
# 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")
}
zscalerten)provider "ztc" {
use_legacy_client = true
# Env vars:
# ZTC_USERNAME, ZTC_PASSWORD, ZTC_API_KEY
# ZTC_CLOUD ← REQUIRED on legacy: zscaler | zscloud | zscalerbeta | zscalergov | zscalerten | zspreview
# 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.
| Layer | Purpose | Typical access pattern |
|---|---|---|
| Edge connector groups | The compute fleet running the connector | Data source (data "ztc_edge_connector_group") — created by cloud orchestration |
| Locations | A site / VPC / VNet | Data source (data "ztc_location_management") — created by cloud orchestration |
| Location templates | Templates for locations | Resource: ztc_location_template |
| Forwarding gateways | Outbound gateways (to ZIA, direct, third-party) | Resource: ztc_forwarding_gateway, ztc_dns_forwarding_gateway, ztc_zia_forwarding_gateway |
| DNS gateways | DNS resolution gateways | Resource: ztc_dns_gateway |
| Traffic forwarding rules | Where traffic goes (rule with order, rank) | Resource: ztc_traffic_forwarding_rule, ztc_traffic_forwarding_dns_rule, ztc_traffic_forwarding_log_rule |
| Network services | Network service objects | Resource: ztc_network_services, ztc_network_services_groups |
| IP groups | Source / destination / pool address groups | Resource: ztc_ip_source_groups, ztc_ip_destination_groups, ztc_ip_pool_groups |
| Workload groups | Workload classification (cross-references ZIA) | Resource: ztc_workload_groups (also data source from zia_workload_groups) |
| Provisioning URL | Per-edge bootstrap URL | Resource: ztc_provisioning_url |
| Activation | Required to push draft changes live | Resource: ztc_activation_status |
resource "ztc_traffic_forwarding_rule" "direct_to_branch_a", not ... "this"."this" for genuine singletons (ztc_activation_status).main.tf, variables.tf, outputs.tf, versions.tf, providers.tf.In ZTC, edge connector groups and locations are typically created automatically when a cloud connector spins up in AWS / Azure / GCP. The provider exposes them only as data sources (and where a resource exists, you usually still want to read the orchestrated one rather than create a new one). Trying to resource "ztc_location_management" with the same name as an existing orchestrated location will fail with DUPLICATE_ITEM.
data "ztc_location_management" "aws_vpc" {
name = "AWS-CAN-ca-central-1-vpc-05c7f364cf47c2b93"
}
data "ztc_edge_connector_group" "aws_vpc_a" {
name = "zs-cc-vpc-096108eb5d9e68d71-ca-central-1a"
}
resource "ztc_traffic_forwarding_rule" "this" {
# ...
locations { id = [data.ztc_location_management.aws_vpc.id] }
}
❌ Do not resource "ztc_location_management" for cloud-orchestrated locations. ✅ Always go through the data source for these. See Resource Catalog: Cloud-Orchestrated Objects.
These apply to every rule-style resource: ztc_traffic_forwarding_rule, ztc_traffic_forwarding_dns_rule, ztc_traffic_forwarding_log_rule.
order = 0 or negative — rejected.ztc_activation_status resource to push draft changes live.The provider has known reorder race conditions across rule types; v0.1.7 fixed an async race where the reorder timer fired before all rules were registered. Pin to v0.1.8+ if you manage multiple rule types in one apply. See Rules & Ordering.
Every create/update/delete on a ZTC resource produces a draft change that must be activated to take effect. Only pure data-source workflows (read-only) skip it.
| Pattern | When |
|---|---|
Manage ztc_activation_status in TF | Atomic per-apply activation — recommended for CI/CD. |
ztcActivator CLI out-of-band | When activation is decoupled (e.g. nightly batch). |
| Skip activation entirely | Only when the configuration uses data "ztc_…" exclusively — no resource "ztc_…". |
Reference pattern (atomic activation):
resource "ztc_traffic_forwarding_rule" "direct_to_branch_a" {
name = "DIRECT_to_branch_a"
order = 1
state = "ENABLED"
type = "EC_RDR"
forward_method = "DIRECT"
# …
}
resource "ztc_activation_status" "this" {
status = "ACTIVE"
depends_on = [ztc_traffic_forwarding_rule.direct_to_branch_a]
}
See Rules & Ordering: Activation.
ZTC exposes 19 data sources but only 14 resources. Some objects are read-only because they are populated by cloud orchestration or by another Zscaler product:
| Data source | Why it's read-only |
|---|---|
ztc_edge_connector_group | Created by AWS / Azure / GCP cloud connector orchestration when a connector VM spins up. |
ztc_location_management | Auto-provisioned per VPC / VNet by the cloud integration. (A resource exists too, but use the data source for orchestrated locations.) |
ztc_account_groups | Tenant-level grouping; managed in the ZTC console. |
ztc_supported_regions | Cloud-provider region catalog the connector can run in. |
ztc_activation_status | Read-side companion to the activation resource — useful for asserting state in tests. |
❌ Do not propose a resource "ztc_edge_connector_group". It does not exist; use data "ztc_edge_connector_group" { name = "…" } to look one up.
client_secret, private_key, legacy password, or api_key in checked-in .tfvars.ZSCALER_* and ZTC_* env vars in the same job — the provider picks one path based on use_legacy_client and silently ignores the other namespace.ZSCALER_CLIENT_ID, ZSCALER_CLIENT_SECRET (or ZSCALER_PRIVATE_KEY), ZSCALER_VANITY_DOMAIN, optionally ZSCALER_CLOUD for non-prod.ZTC_USERNAME, ZTC_PASSWORD, ZTC_API_KEY, ZTC_CLOUD, ZSCALER_USE_LEGACY_CLIENT=true.sensitive = true.Progressive disclosure:
zscalerten, multi-tenant aliases, credential hygiene.order and rank semantics, contiguous ordering, rule-reorder race conditions, activation lifecycle.state rm.Cross-cutting engineering discipline (state organization, CI/CD with the activation step, 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 ztc_* resource.
The reference catalog ships canonical HCL for the most-used ztc_* resources, but ZTC exposes 14 resources and 19 data sources. When asked about an object not in Resource Catalog:
https://registry.terraform.io/providers/zscaler/ztc/latest/docs/resources/<name_without_ztc_prefix>https://registry.terraform.io/providers/zscaler/ztc/latest/docs/data-sources/<name_without_ztc_prefix>Assumptions section.❌ Never invent attribute names. ✅ If the Registry page does not exist for a ztc_<name>, the resource does not exist — say so explicitly.
terraform state rm for ZTC resources backed by real API objects.ztc_location_management resource for a cloud-orchestrated location.npx claudepluginhub zscaler/zscaler-terraform-skills --plugin zscaler-terraform-skillsProvides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.