{"id":19226779,"url":"https://github.com/zscaler/zpacloud-ansible","last_synced_at":"2026-05-30T08:00:52.292Z","repository":{"id":232596283,"uuid":"693967452","full_name":"zscaler/zpacloud-ansible","owner":"zscaler","description":"Ansible collection that automates the configuration and operational tasks on Zscaler Private Access, using the ZPA API.","archived":false,"fork":false,"pushed_at":"2026-05-29T04:10:52.000Z","size":55580,"stargazers_count":6,"open_issues_count":2,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-05-29T06:10:26.083Z","etag":null,"topics":["ansible","ansible-galaxy","automation","automation-hub","redhat","zero-trust","zpa","zscaler"],"latest_commit_sha":null,"homepage":"https://zscaler.github.io/zpacloud-ansible/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zscaler.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-09-20T04:17:00.000Z","updated_at":"2026-05-29T04:10:49.000Z","dependencies_parsed_at":"2024-05-23T08:28:08.656Z","dependency_job_id":"2e1d3539-74ac-4db7-8597-8093e3604641","html_url":"https://github.com/zscaler/zpacloud-ansible","commit_stats":null,"previous_names":["zscaler/zpacloud-ansible"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/zscaler/zpacloud-ansible","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zscaler%2Fzpacloud-ansible","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zscaler%2Fzpacloud-ansible/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zscaler%2Fzpacloud-ansible/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zscaler%2Fzpacloud-ansible/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zscaler","download_url":"https://codeload.github.com/zscaler/zpacloud-ansible/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zscaler%2Fzpacloud-ansible/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33684413,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","ansible-galaxy","automation","automation-hub","redhat","zero-trust","zpa","zscaler"],"created_at":"2024-11-09T15:20:08.977Z","updated_at":"2026-05-30T08:00:52.285Z","avatar_url":"https://github.com/zscaler.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zscaler Private Access (ZPA) Ansible Collection\n\n[![Galaxy version](https://img.shields.io/badge/dynamic/json?style=flat\u0026label=Galaxy\u0026prefix=v\u0026url=https://galaxy.ansible.com/api/v3/plugin/ansible/content/published/collections/index/zscaler/zpacloud/versions/?is_highest=true\u0026query=data[0].version)](https://galaxy.ansible.com/ui/repo/published/zscaler/zpacloud/)\n[![Ansible Lint](https://github.com/zscaler/zpacloud-ansible/actions/workflows/ansible-test-lint.yml/badge.svg?branch=master)](https://github.com/zscaler/zpacloud-ansible/actions/workflows/ansible-test-lint.yml)\n[![sanity](https://github.com/zscaler/zpacloud-ansible/actions/workflows/ansible-test-sanity.yml/badge.svg?branch=master)](https://github.com/zscaler/zpacloud-ansible/actions/workflows/ansible-test-sanity.yml)\n[![Documentation Status](https://readthedocs.org/projects/zpacloud-ansible/badge/?version=latest)](https://zpacloud-ansible.readthedocs.io/en/latest/?badge=latest)\n[![License](https://img.shields.io/github/license/zscaler/zpacloud-ansible?color=blue)](https://github.com/zscaler/zpacloud-ansible/v2/blob/master/LICENSE)\n[![Zscaler Community](https://img.shields.io/badge/zscaler-community-blue)](https://community.zscaler.com/)\n\n## Zscaler Support\n\n-\u003e **Disclaimer:** Please refer to our [General Support Statement](https://zscaler.github.io/zpacloud-ansible/support.html) before proceeding with the use of this collection. You can also refer to our [troubleshooting guide](https://zscaler.github.io/zpacloud-ansible/troubleshooting.html) for guidance on typical problems.\n\nThis collection contains modules and plugins to assist in automating the configuration and operational tasks on Zscaler Private Access cloud, and API interactions with Ansible.\n\n- Free software: [MIT License](https://github.com/zscaler/zpacloud-ansible/blob/master/LICENSE)\n- [Documentation](https://zscaler.github.io/zpacloud-ansible)\n- [Repository](https://github.com/zscaler/zpacloud-ansible)\n- [Example Playbooks](https://github.com/zscaler/zpacloud-playbooks)\n\n## Tested Ansible Versions\n\nThis collection is tested with the most current Ansible releases. Ansible versions\nbefore 2.15 are **not supported**.\n\n## Python dependencies\n\nThe minimum python version for this collection is python `3.9`.\n\nThe Python module dependencies are not automatically handled by `ansible-galaxy`. To manually install these dependencies, you have the following options:\n\n1. Utilize the `requirements.txt` file located [here](https://github.com/zscaler/zpacloud-ansible/blob/master/requirements.txt) to install all required packages:\n\n  ```sh\n    pip install -r requirements.txt\n  ```\n\n2. Alternatively, install the [Zscaler SDK Python](https://pypi.org/project/zscaler-sdk-python/) package directly:\n\n  ```sh\n    pip install zscaler-sdk-python\n  ```\n\n## Installation\n\nInstall this collection using the Ansible Galaxy CLI:\n\n```sh\nansible-galaxy collection install zscaler.zpacloud\n```\n\nYou can also include it in a `requirements.yml` file and install it via `ansible-galaxy collection install -r requirements.yml`, using the format:\n\n```yaml\n  collections:\n    - zscaler.zpacloud\n```\n\n## Zscaler OneAPI New Framework\n\nThe ZPA Ansible Collection now offers support for [OneAPI](https://help.zscaler.com/oneapi/understanding-oneapi) OAuth2 authentication through [Zidentity](https://help.zscaler.com/zidentity/what-zidentity).\n\n**NOTE** As of version v2.0.0, this Ansible Collection offers backwards compatibility to the Zscaler legacy API framework. This is the recommended authentication method for organizations whose tenants are still not migrated to [Zidentity](https://help.zscaler.com/zidentity/what-zidentity).\n\n**NOTE** Notice that OneAPI and Zidentity is not currently supported for the following clouds: `GOV` and `GOVUS`. Refer to the [Legacy API Framework](https://github.com/zscaler/zpacloud-ansible/blob/master/README.md#legacy-api-framework) for more information on how authenticate to these environments\n\n## OneAPI - Using modules from the ziacloud Collection in your playbooks\n\nIt's preferable to use content in this collection using their [Fully Qualified Collection Namespace (FQCN)](https://ansible.readthedocs.io/projects/lint/rules/fqcn/), for example `zscaler.zpacloud.zpa_application_segment`:\n\n### Examples Usage - Client Secret Authentication\n\n```yaml\n---\n- name: ZPA Application Segment\n  hosts: localhost\n\n  vars:\n    zpa_cloud:\n      client_id: \"{{ lookup('env', 'ZSCALER_CLIENT_ID') }}\"\n      client_secret: \"{{ lookup('env', 'ZSCALER_CLIENT_SECRET') }}\"\n      vanity_domain: \"{{ lookup('env', 'ZSCALER_VANITY_DOMAIN') }}\"\n      customer_id: '{{ lookup(\"env\", \"ZPA_CUSTOMER_ID\") | default(omit) }}'\n      cloud: \"{{ lookup('env', 'ZSCALER_CLOUD') | default(omit) }}\"\n\n  tasks:\n    - name: Create an Application Segment\n      zscaler.zpacloud.zpa_application_segment:\n        provider: \"{{ zpa_cloud }}\"\n        state: present\n        name: app_segment_01_ansible\n        description: app_segment_01_ansible test\n        enabled: true\n        is_cname_enabled: true\n        tcp_keep_alive: true\n        passive_health_enabled: true\n        health_check_type: DEFAULT\n        health_reporting: ON_ACCESS\n        bypass_type: NEVER\n        icmp_access_type: true\n        tcp_port_range:\n          - from: \"8000\"\n            to: \"8000\"\n        udp_port_range:\n          - from: \"8000\"\n            to: \"8000\"\n        domain_names:\n          - server1.example.com\n          - server2.example.com\n          - server4.example.com\n          - server3.example.com\n        segment_group_id: \"72058304855114308\"\n        server_group_ids:\n          - \"72058304855090128\"\n      register: created_app\n    - debug:\n        msg: \"{{ created_app }}\"\n```\n\n(Note that [use of the `collections` key is now discouraged](https://ansible-lint.readthedocs.io/rules/fqcn/))\n\n**NOTE**: The `zscaler_cloud` is optional and only required when authenticating to other environments i.e `beta`\n\n⚠️ **WARNING:** Hard-coding credentials into any Ansible playbook configuration is not recommended, and risks secret leakage should this file be committed to public version controls.\n\n```yaml\n---\n- name: ZPA Application Segment\n  hosts: localhost\n\n  vars:\n    zpa_cloud:\n      client_id: \"{{ client_id | default(omit) }}\"\n      private_key: \"{{ lookup('file', 'private_key.pem') | default(omit) }}\"\n      vanity_domain: \"{{ vanity_domain | default(omit) }}\"\n      customer_id: \"{{ customer_id | default(omit) }}\"\n      cloud: \"{{ cloud | default(omit) }}\"\n\n  tasks:\n    - name: Create an Application Segment\n      zscaler.zpacloud.zpa_application_segment:\n        provider: \"{{ zpa_cloud }}\"\n        state: present\n        name: app_segment_01_ansible\n        description: app_segment_01_ansible test\n        enabled: true\n        is_cname_enabled: true\n        tcp_keep_alive: true\n        passive_health_enabled: true\n        health_check_type: DEFAULT\n        health_reporting: ON_ACCESS\n        bypass_type: NEVER\n        icmp_access_type: true\n        tcp_port_range:\n          - from: \"8000\"\n            to: \"8000\"\n        udp_port_range:\n          - from: \"8000\"\n            to: \"8000\"\n        domain_names:\n          - server1.example.com\n          - server2.example.com\n          - server4.example.com\n          - server3.example.com\n        segment_group_id: \"72058304855114308\"\n        server_group_ids:\n          - \"72058304855090128\"\n      register: created_app\n    - debug:\n        msg: \"{{ created_app }}\"\n```\n\n## Authentication - OneAPI New Framework\n\nAs of version v2.0.0, this provider supports authentication via the new Zscaler API framework [OneAPI](https://help.zscaler.com/oneapi/understanding-oneapi)\n\nZscaler OneAPI uses the OAuth 2.0 authorization framework to provide secure access to Zscaler Private Access (ZPA) APIs. OAuth 2.0 allows third-party applications to obtain controlled access to protected resources using access tokens. OneAPI uses the Client Credentials OAuth flow, in which client applications can exchange their credentials with the authorization server for an access token and obtain access to the API resources, without any user authentication involved in the process.\n\n- [ZPA API](https://help.zscaler.com/oneapi/understanding-oneapi#:~:text=Workload%20Groups-,ZPA%20API,-Zscaler%20Private%20Access)\n\n### Default Environment variables\n\nYou can provide credentials via the `ZSCALER_CLIENT_ID`, `ZSCALER_CLIENT_SECRET`, `ZSCALER_VANITY_DOMAIN`, `ZSCALER_CLOUD` environment variables, representing your Zidentity OneAPI credentials `clientId`, `clientSecret`, `vanityDomain` and `zscaler_cloud` respectively.\n\n| Argument        | Description                                                                                         | Environment Variable     |\n|-----------------|-----------------------------------------------------------------------------------------------------|--------------------------|\n| `client_id`     | _(String)_ Zscaler API Client ID, used with `client_secret` or `private_key` OAuth auth mode.         | `ZSCALER_CLIENT_ID`      |\n| `client_secret` | _(String)_ Secret key associated with the API Client ID for authentication.                         | `ZSCALER_CLIENT_SECRET`  |\n| `private_key`    | _(String)_ A string Private key value.                                                              | `ZSCALER_PRIVATE_KEY`    |\n| `vanity_domain` | _(String)_ Refers to the domain name used by your organization.                                     | `ZSCALER_VANITY_DOMAIN`  |\n| `customer_id` | _(String)_ A string that contains the ZPA customer ID which identifies the tenant                                      | `ZPA_CUSTOMER_ID`  |\n| `zscaler_cloud`         | _(String)_ The name of the Zidentity cloud, e.g., beta.                                             | `ZSCALER_CLOUD`          |\n\n### Alternative OneAPI Cloud Environments\n\nOneAPI supports authentication and can interact with alternative Zscaler enviornments i.e `beta`. To authenticate to these environments you must provide the following values:\n\n| Argument         | Description                                                                                         |   | Environment Variable     |\n|------------------|-----------------------------------------------------------------------------------------------------|---|--------------------------|\n| `vanity_domain`   | _(String)_ Refers to the domain name used by your organization |   | `ZSCALER_VANITY_DOMAIN`  |\n| `zscaler_cloud`          | _(String)_ The name of the Zidentity cloud i.e beta      |   | `ZSCALER_CLOUD`          |\n\nFor example: Authenticating to Zscaler Beta environment:\n\n```sh\nexport ZSCALER_VANITY_DOMAIN=\"acme\"\nexport ZSCALER_CLOUD=\"beta\"\n```\n\n### OneAPI (API Client Scope)\n\nOneAPI Resources are automatically created within the ZIdentity Admin UI based on the RBAC Roles\napplicable to APIs within the various products. For example, in ZPA, navigate to `Administration -\u003e Role\nManagement` and select `Add API Role`.\n\nOnce this role has been saved, return to the ZIdentity Admin UI and from the Integration menu\nselect API Resources. Click the `View` icon to the right of Zscaler APIs and under the ZPA\ndropdown you will see the newly created Role. In the event a newly created role is not seen in the\nZIdentity Admin UI a `Sync Now` button is provided in the API Resources menu which will initiate an\non-demand sync of newly created roles.\n\n## Legacy API Framework\n\n### ZPA Native Authentication\n\n- As of version v2.0.0, this Ansible Collection offers backwards compatibility to the Zscaler legacy API framework. This is the recommended authentication method for organizations whose tenants are still **NOT** migrated to [Zidentity](https://help.zscaler.com/zidentity/what-zidentity).\n\n### Examples Usage\n\n```yaml\n- name: ZPA App Connector Group\n  hosts: localhost\n\n  vars:\n    zia_cloud:\n      zpa_client_id: \"{{ zpa_client_id | default(omit) }}\"\n      zpa_client_secret: \"{{ zpa_client_secret | default(omit) }}\"\n      zpa_customer_id: \"{{ zpa_customer_id | default(omit) }}\"\n      zpa_cloud: \"{{ zpa_cloud | default(omit) }}\"\n      use_legacy_client: \"{{ use_legacy_client | default(omit) }}\"\n\n  tasks:\n    - name: Get Information Details of All Customer Version Profiles\n      zscaler.zpacloud.zpa_customer_version_profile_facts:\n      register: version_profile_id\n\n    - name: Create App Connector Group Example\n      zscaler.zpacloud.zpa_app_connector_groups:\n        provider: '{{ zpa_cloud }}'\n        name: \"Example\"\n        description: \"Example\"\n        enabled: true\n        city_country: \"California, US\"\n        country_code: \"US\"\n        latitude: \"37.3382082\"\n        longitude: \"-121.8863286\"\n        location: \"San Jose, CA, USA\"\n        upgrade_day: \"SUNDAY\"\n        upgrade_time_in_secs: \"66600\"\n        override_version_profile: true\n        version_profile_id: \"{{ version_profile_id.data[0].id }}\"\n        dns_query_type: \"IPV4\"\n```\n\nThe ZPA Cloud is identified by several cloud name prefixes, which determines which API endpoint the requests should be sent to. The following cloud environments are supported:\n\n- `BETA`\n- `GOV`\n- `GOVUS`\n- `ZPATWO`\n\n### Environment variables\n\nYou can provide credentials via the `ZPA_CLIENT_ID`, `ZPA_CLIENT_SECRET`, `ZPA_CUSTOMER_ID`, `ZPA_MICROTENANT_ID`,, `ZPA_CLOUD`, `ZSCALER_USE_LEGACY_CLIENT` environment variables, representing your ZPA `zpa_client_id`, `zpa_client_secret`, `zpa_customer_id`, `zpa_microtenant_id`, `zpa_cloud` and `use_legacy_client` respectively.\n\n| Argument     | Description | Environment variable |\n|--------------|-------------|-------------------|\n| `zpa_client_id`       | _(String)_ The ZPA API client ID generated from the ZPA console.| `ZPA_CLIENT_ID` |\n| `zpa_client_secret`       | _(String)_ The ZPA API client secret generated from the ZPA console.| `ZPA_CLIENT_SECRET` |\n| `zpa_customer_id`       | _(String)_ The ZPA tenant ID found in the Administration \u003e Company menu in the ZPA console.| `ZPA_CUSTOMER_ID` |\n| `zpa_microtenant_id`       | _(String)_ The ZPA microtenant ID found in the respective microtenant instance under Configuration \u0026 Control \u003e Public API \u003e API Keys menu in the ZPA console.| `ZPA_MICROTENANT_ID` |\n| `zpa_cloud`       | _(String)_ The Zscaler cloud for your tenancy.| `ZPA_CLOUD` |\n| `use_legacy_client`       | _(Bool)_ Enable use of the legacy ZPA API Client.| `ZSCALER_USE_LEGACY_CLIENT` |\n\n```sh\n# Change place holder values denoted by brackets to real values, including the\n# brackets.\n\n$ export ZPA_CLIENT_ID=\"[ZPA_CLIENT_ID]\"\n$ export ZPA_CLIENT_SECRET=\"[ZPA_CLIENT_SECRET]\"\n$ export ZPA_CUSTOMER_ID=\"[ZPA_CUSTOMER_ID]\"\n$ export ZPA_CLOUD=\"[ZPA_CLOUD]\"\n$ export ZPA_MICROTENANT_ID=\"[ZPA_MICROTENANT_ID]\" # REQUIRED ONLY IF USING MICROTENANTS\n$ export ZSCALER_USE_LEGACY_CLIENT=true\n```\n\n⚠️ **WARNING:** Hard-coding credentials into any Ansible playbook configuration is not recommended, and risks secret leakage should this file be committed to public version control\n\nFor details about how to retrieve your tenant Base URL and API key/token refer to the Zscaler help portal. \u003chttps://help.zscaler.com/zpa/getting-started-zpa-api\u003e\n\n(Note that [use of the `collections` key is now discouraged](https://ansible-lint.readthedocs.io/rules/fqcn/))\n\n## Releasing, changelogs, versioning and deprecation\n\nThe intended release frequency for major and minor versions are performed whenever there is a need for fixing issues or to address security concerns.\n\nChangelog details are created automatically and more recently can be found [here](https://github.com/zscaler/zpacloud-ansible/blob/master/README.md), but also the full history is [here](https://github.com/zscaler/zpacloud-ansible/releases).\n\n[Semantic versioning](https://semver.org/) is adhered to for this project.\n\nDeprecations are done by version number, not by date or by age of release. Breaking change deprecations will only be made with major versions.\n\n## Support\n\nThe Zscaler Private Access (ZPA) Collection of Ansible Modules is [certified on Ansible Automation Hub](https://console.redhat.com/ansible/automation-hub/repo/published/zscaler/zpacloud) and officially supported for Ansible subscribers. Ansible subscribers can engage for support through their usual route towards Red Hat.\n\nFor those who are not Ansible subscribers, this Collection of Ansible Modules is also [published on Ansible Galaxy](https://galaxy.ansible.com/ui/repo/published/zscaler/zpacloud) and also supported via the formal Zscaler suppport process. Please refer to our [General Support Statement](https://zscaler.github.io/zpacloud-ansible/support.html)\n\n## MIT License\n\nCopyright (c) 2023 [Zscaler](https://github.com/zscaler)\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzscaler%2Fzpacloud-ansible","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzscaler%2Fzpacloud-ansible","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzscaler%2Fzpacloud-ansible/lists"}