/application-integration-basics

name: application-integration-basics
metadata:
  version: "1.0.0"
  category: ApplicationDevelopment
description: >-
  Explains Google Cloud Application Integration concepts, region provisioning, IAM roles,
  run-as service accounts, interface choices (REST, Python discovery client, Terraform, ADK),
  and platform limits. Use when setting up Application Integration in a Google Cloud project,
  enabling required APIs, provisioning a region, configuring IAM or run-as service accounts,
  choosing between Application Integration and custom code, or checking quotas and timeouts.
  Do not use for building, publishing, or invoking integrations (use application-integration-authoring) or diagnosing failed or stuck runs and logs (use application-integration-troubleshooting).

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.
• Ask the user before installing packages (`pip install`) or changing global gcloud settings such as `gcloud config set auth/impersonate_service_account`; show the exact command first.

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"`. | Application Default Credentials (`gcloud auth application-default login`) | | **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`) 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://in