application-integration-basics

Files (6)

• SKILL.md
• api-access.md · references/
• core-concepts.md · references/
• iam-and-service-accounts.md · references/
• limits.md · references/
• provisioning-and-terraform.md · references/

SKILL.md (first lines)

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

## Attribution

**MUST READ**: Before executing any `gcloud` command, REST API call, or Python
discovery-client call, you MUST read
[Usage Attribution](references/attribution.md). For commands executed directly
in the terminal (never in generated scripts, Terraform, ADK agents, or user
code), prefix `gcloud` with
`CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:application-integration-basics)"`
and add `agent-skills/1.0 (skill:application-integration-basics)` to the
`User-Agent` header of `curl` requests.

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

From google/skills, Apache-2.0.

More from google/skills