Google Cloud Orchestration Airflow API Client Library
raw JSON → 1.20.0 verified Tue May 12 auth: no python install: stale quickstart: stale
Cloud Composer is a fully managed Apache Airflow service that simplifies the creation, scheduling, monitoring, and management of workflows. This client library provides programmatic access to the Google Cloud Orchestration Airflow API, allowing Python developers to interact with Cloud Composer environments and their underlying Airflow instances. The current version is 1.20.0, and Google Cloud client libraries typically follow a continuous release cadence with frequent updates for new features, bug fixes, and API changes.
pip install google-cloud-orchestration-airflow Common errors
error PERMISSION_DENIED: User not authorized to act as service account <service-account-name> ↓
cause The service account used to create or manage the Cloud Composer environment lacks the necessary IAM permissions, such as `iam.serviceAccounts.actAs` or other required roles for the Composer service account or the caller.
fix
Ensure the user account initiating the environment creation/update has the 'Service Account User' role on the specified service account, and the service account itself has sufficient permissions (e.g., 'Cloud Composer API Service Agent Extension', 'Cloud Composer v2 API Service Agent Extension', 'Composer Worker') for the resources it needs to access.
error UPDATE operation on this environment failed with the following error message: An error occurred before the new web server image has been created. ↓
cause This error often indicates a conflict when installing custom Python packages (PyPI dependencies) in the Cloud Composer environment, typically due to incompatible versions between your custom packages and pre-installed Airflow packages.
fix
Inspect the Cloud Build logs (accessible from the 'Environments' page > 'Logs' tab > 'Composer logs' > 'Builds') to find the specific
pip error detailing the package conflict. Adjust the version constraints of your custom PyPI packages (e.g., use >=X.Y.Z instead of ==X.Y.Z) or install a compatible version. error CREATE operation on this environment failed ... Http error status code: 400 Http error message: BAD REQUEST ↓
cause This generic bad request error during environment creation can stem from various network configuration issues (e.g., overlapping IP ranges, incorrect VPC configuration, firewall rules), insufficient quotas, or problems with the underlying GKE cluster provisioning.
fix
Review the detailed error messages in the Cloud Composer operation logs and Cloud Logging for the environment. Check for specific GKE cluster errors, IP address conflicts, network setup, and ensure all required Google Cloud APIs (like App Engine and Kubernetes Engine API) are enabled and resource quotas are sufficient.
error ModuleNotFoundError: No module named 'your_custom_module' ↓
cause This occurs when a DAG attempts to import a Python module that is not available in the Cloud Composer environment's Python path. This could be due to incorrect PyPI package installation, the module not being placed in the correct `dags/data` or `dags/plugins` folder, or an incorrect import path within your DAG code.
fix
Ensure the custom module or package is correctly installed as a PyPI package for the Composer environment or uploaded to the
/dags/data folder (for Python modules/packages) or /dags/plugins folder (for Airflow plugins). Verify the import statement in your DAG matches the module's location and structure. For PyPI packages, check the build logs during installation for errors. Warnings
breaking When upgrading Cloud Composer or Airflow versions, ensure your existing DAGs and any custom PyPI packages are compatible. Incompatible changes can cause DAGs to fail. It's crucial to check the changelogs for the new Airflow version and associated provider packages. ↓
fix Review the Cloud Composer and Airflow release notes for breaking changes before upgrading. Test DAGs thoroughly in a staging environment.
gotcha The library's logging events are not handled by default and may contain sensitive information. Users must explicitly configure Python's standard logging functionality to capture and handle these events. ↓
fix Configure logging handlers and formatters for Python's `logging` module. Consider setting the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable for basic structured logging. Restrict access to logs containing sensitive data.
breaking The `apache-airflow-providers-google` package, which is heavily used by Cloud Composer users, has undergone several breaking changes, including the removal or renaming of various operators and hooks (e.g., `LifeSciencesRunPipelineOperator`, `BigQueryCreateEmptyTableOperator`). ↓
fix Consult the changelog for `apache-airflow-providers-google` to identify replacements for deprecated operators and hooks. Migrate to the recommended alternatives, such as `Google Cloud Batch operators` or specific Vertex AI operators.
deprecated Python versions 3.6 and below are no longer supported. Using an unsupported Python version can lead to installation failures, runtime errors, and security vulnerabilities. ↓
fix Upgrade your Python environment to Python 3.9 or higher. Google Cloud client libraries are compatible with all active and maintenance versions of Python.
breaking Attempting to import `EnvironmentsClient` from `google.cloud.orchestration.airflow.service.v1` resulted in a `ModuleNotFoundError`. The correct module path for the Google Cloud Composer service client is typically `google.cloud.orchestration.airflow.service_v1` (using an underscore instead of a dot for the version part). This error also occurs if the `google-cloud-orchestration-airflow` client library is not installed. ↓
fix Correct the import statement to `from google.cloud.orchestration.airflow.service_v1 import EnvironmentsClient`. Ensure the `google-cloud-orchestration-airflow` package is installed in your environment (`pip install google-cloud-orchestration-airflow`).
breaking The `ModuleNotFoundError: No module named 'google.cloud.orchestration.airflow.service.v1'` indicates that the Google Cloud Composer service client library is not installed or accessible in your Python environment. This library is required to interact with the Cloud Composer API. ↓
fix Ensure the `google-cloud-orchestration-airflow` Python package is installed in your environment using `pip install google-cloud-orchestration-airflow`. If running in a Cloud Composer environment, ensure the package is specified in the environment's PyPI packages list.
Install compatibility stale last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) wheel - - 71.4M
3.10 alpine (musl) - - - -
3.10 slim (glibc) wheel 5.9s - 69M
3.10 slim (glibc) - - - -
3.11 alpine (musl) wheel - - 76.4M
3.11 alpine (musl) - - - -
3.11 slim (glibc) wheel 5.2s - 74M
3.11 slim (glibc) - - - -
3.12 alpine (musl) wheel - - 67.8M
3.12 alpine (musl) - - - -
3.12 slim (glibc) wheel 4.5s - 66M
3.12 slim (glibc) - - - -
3.13 alpine (musl) wheel - - 67.5M
3.13 alpine (musl) - - - -
3.13 slim (glibc) wheel 4.5s - 65M
3.13 slim (glibc) - - - -
3.9 alpine (musl) wheel - - 71.5M
3.9 alpine (musl) - - - -
3.9 slim (glibc) wheel 7.0s - 69M
3.9 slim (glibc) - - - -
Imports
- EnvironmentsClient
from google.cloud.orchestration.airflow.service.v1 import EnvironmentsClient - types
from google.cloud.orchestration.airflow.service.v1 import types
Quickstart stale last tested: 2026-04-24
import os
from google.cloud.orchestration.airflow.service.v1 import EnvironmentsClient
from google.cloud.orchestration.airflow.service.v1 import types
def list_composer_environments(project_id: str, location: str):
"""Lists Cloud Composer environments in a given project and location."""
client = EnvironmentsClient()
parent = f"projects/{project_id}/locations/{location}"
try:
request = types.ListEnvironmentsRequest(parent=parent)
page_result = client.list_environments(request=request)
print(f"Cloud Composer Environments in {location}:")
found_any = False
for environment in page_result:
print(f" - {environment.name} (State: {environment.state.name})")
found_any = True
if not found_any:
print(" No environments found.")
except Exception as e:
print(f"Error listing environments: {e}")
if __name__ == "__main__":
project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id')
location = os.environ.get('GOOGLE_CLOUD_LOCATION', 'us-central1') # e.g., 'us-central1', 'europe-west1'
if project_id == 'your-gcp-project-id':
print("Please set the GOOGLE_CLOUD_PROJECT environment variable or replace 'your-gcp-project-id'.")
elif location == 'us-central1':
print("Please set the GOOGLE_CLOUD_LOCATION environment variable or choose your desired location.")
else:
list_composer_environments(project_id, location)