Skip to main content

​
Overview

Use the Google Drive integration after the shared GCP setup to ingest selected shared drives. The current Google Drive integration supports shared drives only, with real-time change ingestion, an initial backfill, and scheduled watch renewal.

​
Before you start

  • Run the shared GCP setup first with ./cloud-providers/gcp/scripts/init.sh.
  • Install Terraform >= 1.9, gcloud, jq, curl, openssl, and python3.
  • Make sure the Google account you will use for the OAuth flow has access to every shared drive you want to ingest.
  • If the OAuth client lives in a different GCP project than the base install, enable the Google Drive API in that OAuth project before you run the installer.
  • If you have more than one generated GCP install under generated/gcp/, decide which install-state.json you want to use and pass it with --install-state PATH.
  • Use a GCP identity that can create Google Drive integration resources and deploy the Google Drive workloads.

​
Fill install.yaml

The Google Drive installer reads cloud-providers/gcp/scripts/integrations/google-drive/install.yaml by default. Google Drive inherits the hosting mode, project ID, region, and other shared values from the base install-state.json. You do not set those again here. Fill in these fields:
  • google_drive.drives: required. Use shared-drive IDs or exact shared-drive names.
  • In self-hosting, set google_drive.oauth.client_id and google_drive.oauth.client_secret before the first install. Later reruns can omit them only if the installer already stored the app secret in Secret Manager.
  • google_drive.oauth.state_secret is optional if you want to set it yourself.
  • In cloud-hosting, usually leave google_drive.oauth.* blank and set:
    • ASYMPTOTE_GOOGLE_DRIVE_CLIENT_ID
    • ASYMPTOTE_GOOGLE_DRIVE_CLIENT_SECRET
    • Optional: ASYMPTOTE_GOOGLE_DRIVE_STATE_SECRET
  • The remaining google_drive.* fields are optional naming overrides for Google Drive-specific resources and jobs.
Config shape: 
google_drive:
  drives:
    - "0AExampleDriveUk9PVA"
    - "Engineering"
  oauth:
    client_id: ""
    client_secret: ""
    state_secret: ""
  connector_subnet_name: ""
  connector_subnet_cidr: ""
  app_secret_name: ""
  installation_secret_name: ""
  artifact_registry_repository_id: ""
  events_function_name: ""
  ingest_function_name: ""
  topic_name: ""
  subscription_name: ""
  backfill_job_name: ""
  watch_renewal_job_name: ""
  watch_renewal_scheduler_name: ""
  watch_renewal_schedule: ""
  watch_renewal_time_zone: ""
  content_bucket_name: ""

​
Hosting modes

​
Self-hosting mode

Use base mode: self-hosting.
  • The first install uses a customer-owned Google OAuth client and stores the normalized app and installation details in Secret Manager.
  • The Google account that completes the OAuth flow must have access to every shared drive listed in google_drive.drives.
  • If the OAuth client is created in the same GCP project as the base install, Terraform enables drive.googleapis.com automatically. Otherwise, enable the Google Drive API manually in the OAuth client project before you run the installer.

​
Create the Google OAuth client in Google Cloud Console

Create the OAuth client before the first self-hosted install, then copy its client ID and secret into install.yaml.
1

Open the Google Cloud project that will own the OAuth client

Use the Google Cloud project where you want the Google OAuth client to live. If this is not the same project as the base GCP install, make sure the Google Drive API is enabled in that OAuth client project before you continue.
2

Go to `APIs & Services` > `Credentials`

In the Google Cloud Console, open the Credentials page for that project.
3

Create a new OAuth client ID

Click Create Credentials, then choose OAuth client ID.If Google prompts you to configure the OAuth consent screen first, complete that setup for your organization, then return to the Credentials page.
4

Choose the client type and redirect URI

Set Application type to Web application.Give the client a descriptive name such as asymptote-google-drive.Under Authorized redirect URIs, add:
http://127.0.0.1:49161/google-drive-oauth/callback
5

Copy the credentials into `install.yaml`

After Google creates the client, copy the generated client ID and client secret into:
google_drive:
  oauth:
    client_id: "YOUR_CLIENT_ID"
    client_secret: "YOUR_CLIENT_SECRET"
These values must be present in the YAML config before the first self-hosted install.

​
Cloud-hosting mode

Use base mode: cloud-hosting.
  • Use the Asymptote-managed Google OAuth client instead of creating your own.
  • Before you run the installer, export:
    • ASYMPTOTE_GOOGLE_DRIVE_CLIENT_ID
    • ASYMPTOTE_GOOGLE_DRIVE_CLIENT_SECRET
  • Optional:
    • ASYMPTOTE_GOOGLE_DRIVE_STATE_SECRET

​
Run the installer

1

Update `cloud-providers/gcp/scripts/integrations/google-drive/install.yaml`

Fill in the shared drives you want to ingest and any Google Drive-specific settings you need.
2

Run the script

From the repository root, run:
./cloud-providers/gcp/scripts/integrations/install-integration.sh google-drive
3

Approve the planned changes

Review the planned changes and approve them to continue.
If you want to use a different config file, target a specific base install, or skip confirmation prompts: 
./cloud-providers/gcp/scripts/integrations/install-integration.sh google-drive --config /path/to/install.yaml
./cloud-providers/gcp/scripts/integrations/install-integration.sh google-drive --install-state /path/to/install-state.json
./cloud-providers/gcp/scripts/integrations/install-integration.sh google-drive --auto-approve

​
What happens at a high level

After the Google Drive setup completes successfully:
  • The selected shared drives are connected to the integration.
  • The customer-owned Google OAuth client is used or reused in self-hosting, or the Asymptote-managed client is used in cloud-hosting.
  • The Google Drive webhook ingress, Pub/Sub ingest function, backfill job, and watch-renewal job are deployed.
  • An initial historical backfill is triggered.
  • Extracted text snapshots are stored in GCS, while metadata and object references are written to PostgreSQL.
When the script finishes, it prints the mode, the Google Drive function URLs, the backfill and watch-renewal job names, the content bucket, and the initial backfill execution ID.

​
Add drives later

If Google Drive is already connected and you want to add more shared drives, update the existing Google Drive integration instead of rerunning the base GCP setup.
1

Update `google_drive.drives`

Edit cloud-providers/gcp/scripts/integrations/google-drive/install.yaml and keep the full set of shared drives you want connected. Add the new shared drives to google_drive.drives rather than replacing the existing list unless you want to remove drives from the integration.
2

Confirm drive access

Make sure the Google account used by the integration can access every shared drive listed in google_drive.drives, including the newly added ones.
3

Rerun only the Google Drive installer

Run:
./cloud-providers/gcp/scripts/integrations/install-integration.sh google-drive
If needed, pass --install-state /path/to/install-state.json to target the existing base setup you want to update.
After that rerun, the existing Google Drive connection stays in place and the newly added shared drives are picked up by the integration. Every shared drive you want to ingest must be listed in google_drive.drives and accessible to the Google account that authorized the integration.

​
Troubleshooting

  • If the installer cannot find the base setup you want, pass --install-state /path/to/install-state.json.
  • If you are using cloud-hosting, make sure ASYMPTOTE_GOOGLE_DRIVE_CLIENT_ID and ASYMPTOTE_GOOGLE_DRIVE_CLIENT_SECRET are set before running the installer.
  • If the OAuth flow succeeds but the installer says it cannot access any selected shared drives, make sure the Google account that authorized the app can open each drive listed in google_drive.drives.
  • If the Google Drive OAuth exchange does not return a refresh_token, revoke the prior grant for that app in Google and rerun the installer.
  • If the OAuth client lives in a separate GCP project, make sure the Google Drive API is enabled in that project.