application-integration-basics

# Application Integration Basics Application Integration is Google Cloud's serverless, auto-scaling Integration-Platform-as-a-Service (iPaaS) for connecting Google Cloud services and third-party SaaS applications. It runs event-driven workflows made of triggers, tasks, data mappings, and Integration Connectors connections without requiring you to manage servers. Use this skill to decide whether Application Integration fits a workload, set up a project and region, configure IAM and run-as service accounts, choose the right API or tool interface, and design around platform limits. ## When to Use Application Integration vs. Custom Glue Code | Choose Application Integration when... | Choose custom code (Cloud Run / Cloud Functions) when... | | :--- | :--- | | Connecting SaaS apps (CRM, ERP, databases, Google Cloud services) via prebuilt Integration Connectors. | You need sub-second latency or custom binary protocols. | | Orchestrating event-driven workflows from API, Pub/Sub, Cloud Scheduler, Salesforce, or Connector Event triggers. | Total workflow data exceeds 30 MB (or 8 MB for API trigger inputs and Connector payloads). | | Transforming JSON/array data visually with Data Mapping or Jsonnet without deploying containers. | Synchronous runs take longer than 2 minutes or asynchronous runs take longer than 10 minutes. | | Pausing workflows for human review (`Approval` or `Suspend` tasks up to 31 days). | You must call VPC-only HTTP endpoints directly without Private Service Connect connectors (Call REST Endpoint reaches the public internet only). | | Exposing enterprise workflows or connectors as tools to AI agents via ADK `ApplicationIntegrationToolset`. | You need arbitrary language packages or heavy in-memory compute beyond JavaScript (V8) or Jsonnet tasks. | ## Safety and Confirmation Rules - **Read-only checks run freely**: You may run `gcloud services list`, `gcloud projects get-iam-policy`, and HTTP `GET` calls to `https://integrations.googleapis.com/v1/...` or `https://connectors.googleapis.com/v1/...` without asking first. - **Require explicit user confirmation before any state change**: Always show the exact command or request payload and wait for user approval before: - Enabling APIs (`gcloud services enable`). - Provisioning a region (`clients:provision` or `terraform apply` on `google_integrations_client`), especially with Customer-Managed Encryption Keys (CMEK), because **enabling CMEK for a region cannot be undone**. - Modifying IAM policies (`gcloud projects add-iam-policy-binding` or `gcloud iam service-accounts add-iam-policy-binding`). - Creating, uploading, publishing, unpublishing, executing, testing, or deleting any integration, version, auth profile, or connection. - **Never bundle destructive scripts** that delete integrations, versions, auth profiles, or connections unattended. - **Host changes require approval.** Before installing packages (`pip install`) or changing global gcloud or credential state (`gcloud config set ...` such as `auth/impersonate_service_account`, `gcloud auth application-default login` / `set-quota-project`), show the exact command and wait for the user's approval. ## Choosing the Interface Application Integration has **no `gcloud integrations` command group** (and no `gcloud connectors` command group), and **no Google-managed remote MCP server**. The REST API is the primary control and execution interface. | Interface | What it covers | Authentication | | :--- | :--- | :--- | | **REST API (`curl`)** | Full v1 surface: region provisioning, integrations, versions, download/upload, publish, execute, schedule, executions, suspensions, authConfigs, templates. | `Authorization: Bearer $(gcloud auth print-access-token)` | | **Python discovery client** | Full v1 surface via `googleapiclient.discovery.build("integrations", "v1")` (and v2 via `build("integrations", "v2")`; no dedicated Cloud Client Library exists). Install with `pip install "google-api-python-client>=2.100.0,<3" "google-auth>=2.20.0,<3"` (changes host or credential state; get the user's approval first). | Application Default Credentials (`gcloud auth application-default login`) (changes host or credential state; get the user's approval first) | | **Terraform (`hashicorp/google`)** | Infrastructure only: `google_integrations_client` (region setup), `google_integrations_auth_config`, and `google_integration_connectors_*`. Does **not** manage integration workflow versions. | ADC or Terraform provider credentials | | **ADK (`ApplicationIntegrationToolset`)** | Exposes published API-trigger integrations or Integration Connectors actions/entities as tools for ADK agents (Python v0.1.0+, Java v0.3.0+). | ADC (`gcloud auth application-default login`) (changes host or credential state; get the user's approval first) or service account JSON | | **Cloud console** | Visual drag-and-drop editor, Quick/Advanced region setup, Approval task resolution, OAuth 2.0 authorization code consent flow. | Browser Google Cloud sign-in | - Use `gcloud` only for generic Google Cloud tasks: enabling APIs (`gcloud services enable`), printing access tokens (`gcloud auth print-access-token`), managing IAM, and reading Cloud Logging (`gcloud logging read`). - Integration Connectors includes an outbound **MCP connector** (`MCP v1` and `v2`) that lets a workflow call an external MCP server as a connector target; this is an outbound connector, not a Google-managed MCP server for controlling Application Integration. - Always use the global endpoint `https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/...` consistently for REST calls. - **Note on draft testing (`integrations:test`)**: Although `POST .../integrations/INTEGRATION_NAME:test` exists in the v1 REST API, its required `TestIntegrationsRequest.clientId` value is not publicly documented, so do not invent one; test integrations by publishing to a non-production project and calling `:execute`. - See [references/api-access.md](references/api-access.md) for authentication setup, `curl` commands, Python discovery client patterns, and ADK `ApplicationIntegrationToolset` configuration. ## Step-by-Step Region Setup Workflow Application Integration is regional: confirm the target region is supported on [Application Integration locations](https://docs.cloud.google.com/application-integration/docs/locations.md.txt) and use `us-central1` as a well-supported default when the user has no preference. The region is the `LOCATION` in every REST path; no `gcloud` default-region setting applies to Application Integration. Provisioning is **per region**. Provisioning `us-central1` does not provision `europe-west1`; repeat region provisioning for every `LOCATION` you use in `PROJECT_ID`. Ensure an active billing account is attached to `PROJECT_ID` before setup—an active billing account is required even when usage stays within the monthly free tier (see the [Application Integration pricing page](https://cloud.google.com/application-integration/pricing)). ### 1. Check and enable required APIs First check which APIs are already enabled (read-only): ```bash gcloud services list --enabled --project=PROJECT_ID \ --filter="config.name:(integrations.googleapis.com OR connectors.googleapis.com OR secretmanager.googleapis.com OR cloudkms.googleapis.com)" ``` After getting user confirmation, enable the required APIs (add `cloudkms.googleapis.com` only if configuring CMEK): ```bash gcloud services enable \ integrations.googleapis.com \ connectors.googleapis.com \ secretmanager.googleapis.com \ --project=PROJECT_ID ``` ### 2. Verify setup IAM roles on the caller Setting up Application Integration requires `roles/integrations.integrationAdmin`, `roles/connectors.admin`, and `roles/editor` (plus `roles/cloudkms.admin` for CMEK). Check current bindings (read-only): ```bash gcloud projects get-iam-policy PROJECT_ID --format=json ``` ### 3. Provision the region (`LOCATION`) Choose one of the three supported paths after getting user confirmation: - **Option A: REST (`clients:provision`)** ```bash curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{}' \ "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clients:provision" ``` The response is `{}` when provisioning succeeds (`clients:provision` does not apply `runAsServiceAccount`; set the run-as identity on each integration version via `IntegrationVersion.runAsServiceAccount`). `{}` is also returned when the region is already provisioned; the call does not change an existing region's settings. Change HTTP calls or encryption on an existing region from the console's Regions page (when the region is already `ACTIVE`, `cloudKmsConfig`, `enableHttpCall`, and `enableManagedAiFeatures` on `clients:provision` are not applied). If `PROJECT_ID` was already registered through Apigee Integration, provisioning fails. - **Option B: Cloud console** Open `https://console.cloud.google.com/integrations`, select `LOCATION`, and click **Quick setup** (enables the APIs, creates the default service account, and uses Google-managed encryption) or **Advanced setup** (to configure CMEK, HTTP calls, AI features, governance, or variable masking). To add another region later, go to **Regions > Provision new region**. - **Option C: Terraform (`google_integrations_client`)** Use the `google_integrations_client` resource in `hashicorp/google`. Do **not** set `run_as_service_account` on `google_integrations_client`—that argument was removed in provider v8.0.0 (August 26, 2026), and it mapped to the `clients:provision` `runAsServiceAccount` field, which is likewise not applied; set the run-as identity on each integration version (`IntegrationVersion.runAsServiceAccount`) instead. ### 4. Sanity-check region access Run a read-only list call against the region; a successful `200 OK` response is a good sign that the API is reachable in `LOCATION`: ```bash curl -sS -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations" ``` See [references/provisioning-and-terraform.md](references/provisioning-and-terraform.md) for all `ProvisionClientRequest` fields, CMEK and governance options, and complete Terraform examples. ## Core Concepts at a Glance - **Integrations and Triggers**: An integration is a workflow started by one or more triggers. Synchronous runs (`SYNC`) wait for completion and return output (`integrations.execute`, console test, sync `Call Integration`). Asynchronous runs (`ASYNC`) are fire-and-forget (`integrations.schedule`, Schedule, Cloud Scheduler, Cloud Pub/Sub, Salesforce triggers, and runs resumed after a suspension or approval). - **Tasks**: Units of work chained after a trigger (such as `Data Mapping`, `Call REST Endpoint`, `Connectors`, `JavaScript` on V8, `Cloud Function`, `Approval`, `Suspend`, `Timer`, loops, and `Call Integration`). - **Versions and Edit Locks**: Only a `DRAFT` version can be edited (locked to its author for 15 minutes after the last update). Only an `ACTIVE` (published) version runs from triggers. Publishing a version automatically unpublishes the prior active version and cancels any suspended executions of that prior version. Unpublishing moves an active version to `SNAPSHOT` (`PREVIOUSLY_PUBLISHED`). Calling `versions.delete` soft-deletes a version into `ARCHIVED` (listed as `DELETED` on the Integration versions documentation page). - **Variables**: - **Integration variables**: Explicit inputs (`IN`), outputs (`OUT`), `IN_OUT`, or internal variables with `IN_OUT_TYPE_UNSPECIFIED` (`$varName$`). - **Task variables**: Auto-generated task outputs named `` `Task_<taskId>_<variableName>` `` where `taskId` is the bare task number in `taskConfigs[].taskId` (for example, `taskId` `"1"` -> `` $`Task_1_responseBody`$ ``). - **System variables**: keys are backtick-wrapped (`` `ExecutionId` ``, `` `ExecutionMode` ``, `` `ErrorInfo` `` [`message`, `code`], `` `IntegrationName` ``, `` `Region` ``, `` `ProjectId` ``); reference them as `` $`ExecutionId`$ `` (a bare `$ExecutionId$` names a nonexistent integration variable and fails). - **Config variables** (Preview): Environment-specific values defined in `integrationConfigParameters` (with defaults in `parameter.defaultValue`; a top-level `value` on a draft is discarded) and supplied per environment in `configParameters` at publish time (named `` `CONFIG_<NAME>` ``; keys in `configParameters` must **exactly match** a key in `integrationConfigParameters`, backticks included, such as `` "`CONFIG_target_url`" ``, because unknown keys are silently ignored—publish returns 200 and the default stays). **Never store secrets in config variables**—they are exported in plain text. Use an authentication profile (`authConfigs`) or the Secret Manager task instead. - **Suspensions**: `Suspend` tasks pause up to 31 days and are resumed via the Suspensions API (`suspensions:lift`, with an optional `suspensionResult`, requiring `integrations.suspensions.lift`). `Approval` tasks email approvers and can be approved or rejected in the Cloud console UI or via `suspensions:resolve` (`state`: `"LIFTED"` or `"REJECTED"`, requiring `integrations.suspensions.resolve`). Listing suspensions (`suspensions.list`) requires `integrations.suspensions.list`. All three permissions are included in `roles/integrations.suspensionResolver` (and `roles/integrations.integrationAdmin`), and resuming also requires `roles/iam.serviceAccountUser` on the integration's run-as service account; always confirm with the user before lifting or resolving. `Timer` tasks resume automatically. - **Authentication Profiles (`authConfigs`)**: Reusable regional credential records (`projects/PROJECT_ID/locations/LOCATION/authConfigs/AUTH_CONFIG_ID`). They are not included when downloading an integration version. See [references/core-concepts.md](references/core-concepts.md) for full details on version states, trigger types, task categories, variables, suspensions, and authentication profiles. ## IAM and the Run-As Service Account Requirement ### Key IAM roles and service agents - **Developer & operator roles**: `roles/integrations.integrationAdmin` (full CRUD + delete auth profiles), `roles/integrations.integrationEditor` (create/upload/edit/test/invoke/cancel/replay/publish, including `integrations.integrationVersions.create` and `integrations.integrationVersions.deploy`), `roles/integrations.integrationDeployer` (publish/unpublish via `integrations.integrationVersions.deploy`; holds `list`/`get`/`deploy` but not `create`, so it can publish an existing version but cannot upload), `roles/integrations.integrationInvoker` (invoke/cancel/replay), `roles/integrations.integrationViewer` (view integrations and logs), and `roles/integrations.suspensionResolver` (list, lift, and resolve suspensions: `integrations.suspensions.list`, `integrations.suspensions.lift`, `integrations.suspensions.resolve`; `suspensionResolver` alone cannot read execution records, so also grant `roles/integrations.integrationViewer` to inspect `taskExecutionDetails` or run `:troubleshoot`, or use the approval email link, which carries the execution and task IDs). - **Service agents**: - **Application Integration service agent**: `service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com` (granted `roles/integrations.serviceAgent`). - **Integration Connectors service agent**: `service-PROJECT_NUMBER@gcp-sa-connectors.iam.gserviceaccount.com` (granted `roles/connectors.serviceAgent`). ### Mandatory run-as service account rules (effective October 15, 2026) 1. **Explicit identity required**: For integrations created on or after October 15, 2026 (and for existing integrations at a later date), every run needs an explicit identity—either the triggering caller or a user-managed run-as service account set per integration version via `IntegrationVersion.runAsServiceAccount` (region provisioning via `clients:provision` does not apply `runAsServiceAccount`). 2. **Triggers other than API or Private require a run-as service account**: Integrations created on or after October 15, 2026 with any trigger other than an API or Private trigger (for example Schedule, Cloud Scheduler, Cloud Pub/Sub, Eventarc, Salesforce, or Connector Event) **cannot be tested or published unless `runAsServiceAccount` is set**. Private triggers are exempt like API triggers, so a sub-integration whose only trigger is Private can be published without `runAsServiceAccount`. 3. **Region governance**: If governance is enabled on the region, a run-as service account is mandatory for **every** new integration and version, including API-trigger integrations. 4. **Service Account User (`roles/iam.serviceAccountUser`)**: Whenever `runAsServiceAccount` is set on a version, the user (or principal) publishing or testing the version must hold `roles/iam.serviceAccountUser` on that service account (or its owning project). At runtime, the invoking caller or trigger service account—and anyone resolving or lifting a suspension—must also hold `roles/iam.serviceAccountUser` on it. 5. **Best practice**: Create one dedicated, minimally scoped user-managed service account per integration. When `runAsServiceAccount` is set and no task-level auth profile is set, it mints tokens for Connector, Call REST Endpoint, and Cloud Function tasks (an OAuth 2.0 or OIDC auth profile on a task takes precedence over `runAsServiceAccount`). See [references/iam-and-service-accounts.md](references/iam-and-service-accounts.md) for the complete IAM role tables, service agent permissions, credential precedence rules, and `gcloud` IAM commands. ## Key Quotas and Limits to Design Around | Limit | Value | Design impact | | :--- | :--- | :--- | | **SYNC execution timeout** | 2 minutes | Use async triggers or `integrations.schedule` for workflows exceeding 2 minutes; timed-out sync runs become `CANCELLED`. |