Google Cloud Workflows Client Library

1.21.0 verified Tue May 12 auth: no python install: verified quickstart: stale

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.

pip install google-cloud-workflows

Common errors

error Permission 'iam.serviceaccounts.actAs' denied on service account... ↓

cause 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.

fix

Grant 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.

error ModuleNotFoundError: No module named 'google.cloud.workflows' ↓

cause The `google-cloud-workflows` Python client library is not installed, or it's not accessible in the current Python environment.

fix

Install 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.

error Could not deploy workflow: failed to build: error in step... ↓

cause The workflow definition (YAML or JSON) contains syntax errors, references an undefined variable or step, or has incorrect indentation.

fix

Review 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.

error HTTP server responded with error code 404 in step... ↓

cause 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).

fix

Verify 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.

Warnings

breaking Workflows 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. ↓

fix Update your workflow definitions to access GKE control planes via their DNS-based endpoints. Refer to the official Workflows release notes for details.

gotcha Google 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. ↓

fix Google recommends using placeholders in your YAML/JSON workflow definition and replacing them at deployment time using your CI/CD pipeline.

gotcha Workflows 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. ↓

fix Design 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.

gotcha When defining workflows in YAML, placing a `for` loop directly after a `try` block will cause a deployment error. This is a syntax parsing issue. ↓

fix Add a named step (e.g., `steps: - loopStep:`) between the `try` block and the `for` loop to resolve the parsing conflict.

gotcha Each 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. ↓

fix Consider batching operations where possible, especially for I/O-bound tasks, to reduce the number of discrete steps.

gotcha Workflows 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. ↓

fix For 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.

breaking Google 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`. ↓

fix Ensure 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.

breaking The 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`. ↓

fix Ensure 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).

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 1.59s 68.5M

3.10 slim (glibc) - - 1.00s 66M

3.11 alpine (musl) - - 2.41s 73.3M

3.11 slim (glibc) - - 1.52s 71M

3.12 alpine (musl) - - 2.31s 64.7M

3.12 slim (glibc) - - 1.85s 62M

3.13 alpine (musl) - - 2.33s 64.3M

3.13 slim (glibc) - - 1.94s 62M

3.9 alpine (musl) - - 1.48s 68.6M

3.9 slim (glibc) - - 1.18s 66M

Imports

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).

Quickstart stale last tested: 2026-04-23

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}")