The `google-cloud-workflows` Python client library, currently at version 1.21.0, allows developers to orchestrate and automate Google Cloud and HTTP-based API services with serverless workflows. It provides a programmatic interface for creating, deploying, and managing workflows. Google Cloud client libraries typically follow a frequent release cadence, with updates addressing new features, bug fixes, and API changes.
Install & Compatibility
Where this runs
tested against v1.22.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 1.970s · 69.7MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 5.5s · import 1.481s · 67MB
68MB installed
● package 68MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
WorkflowsClient
✓ from google.cloud.workflows_v1 import WorkflowsClient
Used for managing workflows (creating, deploying, deleting, getting definitions).
ExecutionsClient
✓ from google.cloud.workflows.executions_v1 import ExecutionsClient
Used for managing workflow executions (starting, getting status, listing).
This quickstart demonstrates how to create a new execution for an existing Google Cloud Workflow using the client library. It assumes you have authenticated via Application Default Credentials (e.g., `gcloud auth application-default login`) and that a workflow named `my-first-workflow` exists in `us-central1`. Replace placeholder values with your actual project ID, location, and workflow name. The example passes a JSON argument to the workflow.
import os
import json
from google.cloud.workflows_v1 import WorkflowsClient
from google.cloud.workflows.executions_v1 import ExecutionsClient
from google.cloud.workflows.executions_v1.types.executions import Execution
# Set your Google Cloud Project ID, region, and existing workflow name
PROJECT_ID = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-project-id')
LOCATION = os.environ.get('GOOGLE_CLOUD_LOCATION', 'us-central1')
WORKFLOW_NAME = os.environ.get('GOOGLE_CLOUD_WORKFLOW_NAME', 'my-first-workflow')
# Initialize clients
workflows_client = WorkflowsClient()
executions_client = ExecutionsClient()
# Construct the parent path for the workflow
parent_path = workflows_client.workflow_path(PROJECT_ID, LOCATION, WORKFLOW_NAME)
# Define optional runtime arguments for the workflow (as a JSON string)
runtime_arguments = {
"name": "World"
}
# Create an execution instance
execution = Execution(argument=json.dumps(runtime_arguments))
print(f"Creating execution for workflow: {WORKFLOW_NAME} in {LOCATION}...")
# Send the request to create the execution
response = executions_client.create_execution(parent=parent_path, execution=execution)
print(f"Created execution: {response.name} with state: {response.state.name}")
print("To view the execution in the console, visit:")
print(f"https://console.cloud.google.com/workflows/executions/{LOCATION}/{WORKFLOW_NAME}/{response.name.split('/')[-1]}?project={PROJECT_ID}")
Debug
Known issues
breakingWorkflows no longer supports HTTP requests to IP-based endpoints of Google Kubernetes Engine (GKE) cluster control planes. You must now use DNS-based endpoints for such communications.fixUpdate your workflow definitions to access GKE control planes via their DNS-based endpoints. Refer to the official Workflows release notes for details.
affects: All versions after January 28, 2025.
gotchaGoogle Cloud Workflows do not natively support user-defined environment variables within the workflow definition itself. This can complicate deploying the same workflow to multiple environments with different configurations.fixGoogle recommends using placeholders in your YAML/JSON workflow definition and replacing them at deployment time using your CI/CD pipeline.
affects: All versions.
gotchaWorkflows have strict resource limitations, including a maximum HTTP response size of 2MB (if saved to a variable) and a 512KB memory limit for all variables within a single execution. Events larger than the maximum argument size may fail to trigger executions.fixDesign workflows to handle smaller payloads or process data in chunks. For large events, ensure event sizes are within quotas. Filter data at the API level where possible.
affects: All versions.
gotchaWhen defining workflows in YAML, placing a `for` loop directly after a `try` block will cause a deployment error. This is a syntax parsing issue.fixAdd a named step (e.g., `steps: - loopStep:`) between the `try` block and the `for` loop to resolve the parsing conflict.
affects: All versions.
gotchaEach step in a Google Cloud Workflow incurs a latency overhead of approximately 100-200ms. For workflows with many sequential steps, this can significantly increase overall execution time.fixConsider batching operations where possible, especially for I/O-bound tasks, to reduce the number of discrete steps.
affects: All versions.
gotchaWorkflows have an execution limit of 10,000 steps per workflow. Long-running or data-intensive workflows that iterate many times may unexpectedly terminate if this limit is reached.fixFor processes that involve large datasets or extensive iteration, implement chunking mechanisms to process data in smaller, manageable segments across multiple workflow executions or external services.
affects: All versions.
breakingGoogle Cloud client libraries, including WorkflowsClient, require Application Default Credentials (ADC) to authenticate with Google Cloud APIs. If ADC are not found in the environment, client initialization will fail with a `DefaultCredentialsError`.fixEnsure Application Default Credentials are configured in the environment where the client library is run. This typically involves running `gcloud auth application-default login` for local development, providing a service account key file, or running the application on Google Cloud infrastructure (like GCE, Cloud Run, Cloud Functions) with appropriate service account permissions and scopes.
affects: All versions.
breakingThe Google Cloud client libraries require Application Default Credentials (ADC) to authenticate with Google Cloud services. If ADC are not properly configured or available in the execution environment, client initialization will fail with a `DefaultCredentialsError`.fixEnsure Application Default Credentials are configured in the execution environment. This typically involves running `gcloud auth application-default login`, setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to a service account key file path, or leveraging the service account attached to the execution environment (e.g., GCE, GKE, Cloud Run, Cloud Functions).
affects: All versions.
Errors
Common errors & fixes
Permission 'iam.serviceaccounts.actAs' denied on service account...
The service account attempting to deploy or execute the workflow lacks the necessary IAM permissions to interact with other Google Cloud resources or to act as another service account.
fixGrant the appropriate IAM roles to the service account associated with the workflow or the user deploying it. For example, ensure the service account has `Workflows Editor` or specific roles like `Service Account User` (`roles/iam.serviceAccountUser`) to act as another service account, and relevant roles (e.g., `Storage Object Creator` for Cloud Storage) for resources the workflow interacts with.
ModuleNotFoundError: No module named 'google.cloud.workflows'
The `google-cloud-workflows` Python client library is not installed, or it's not accessible in the current Python environment.
fixInstall the library using pip: `pip install google-cloud-workflows`. If using a virtual environment, ensure it's activated. If upgrading, use `pip install --upgrade google-cloud-workflows`.
Could not deploy workflow: failed to build: error in step...
The workflow definition (YAML or JSON) contains syntax errors, references an undefined variable or step, or has incorrect indentation.
fixReview the workflow's source code for syntax errors, incorrect indentation, misspelled variable names, or references to non-existent steps or subworkflows. The error message usually points to the specific step or line where the error occurred.
HTTP server responded with error code 404 in step...
The workflow is attempting to access a resource or API endpoint that does not exist, is misspelled, or is in an incorrect location (e.g., a Cloud Run service, Cloud Storage object, or a connector method).
fixVerify that the resource or API endpoint URL is correct, exists, and is accessible from the workflow. Ensure that any required location arguments (e.g., `us-central1`) are specified for connector methods, and that resource names are correctly URL-encoded if they contain special characters.
Audit
Dependencies
No dependency data recorded yet.