PubSub-Secure-Asynchronous-Chatbot

Building a Secure, Asynchronous Google Chat Bot

This guide details the architecture and step-by-step process for creating a secure, scalable, and asynchronous Google Chat bot using Google Cloud Platform services. This pattern is ideal for bots that need to perform long-running tasks (over 30 seconds) without timing out in the Google Chat interface.

Core Technologies 🛠️

• Google Chat API: The service that allows applications to receive and respond to events from Google Chat.
• Cloud Run: A fully managed serverless platform used to run our containerized application code. We use two services: one to receive the initial webhook (ingestor) and one to do the processing (worker).
• Pub/Sub: A serverless, asynchronous messaging service that decouples our ingestor from our worker. This is the key to avoiding the 30-second timeout.
• IAM (Identity and Access Management): Used to create dedicated service accounts and grant fine-grained, least-privilege permissions to each component of the architecture.
• Secret Manager: Provides secure storage for sensitive data like API keys, ensuring they are not exposed in code or environment variables.
• Cloud Build & Artifact Registry: Used to build our Python code into secure, reproducible container images and store them.

Prerequisites

• A Google Cloud project with billing enabled.
• Permissions to create and manage the resources listed above (e.g., the Owner or Editor role for the project).
• The gcloud command-line tool installed and authenticated to your project.
• A local environment with Python and Docker installed to create the application code and build the container images.

Phase 0: Project Setup & API Enablement

First, the necessary APIs must be enabled for the Google Cloud project.

1. Navigate to the "APIs & Services" > "Library" section in the Google Cloud Console.
2. Search for and Enable each of the following APIs:
   • Cloud Build API
   • Cloud Run API
   • Pub/Sub API
   • Secret Manager API
   • Artifact Registry API
   • Google Chat API
   • IAM API (Identity and Access Management)

Phase 1: Create IAM Service Accounts

Create three dedicated service accounts to ensure a least-privilege security posture.

1. Navigate to "IAM & Admin" > "Service Accounts".
2. Click "+ CREATE SERVICE ACCOUNT" for each of the following:
   • Service Account 1:
     • Name: chat-ingestor-sa
   • Service Account 2:
     • Name: chat-worker-sa
   • Service Account 3:
     • Name: pubsub-push-sa
3. For each account, click "CREATE AND CONTINUE", then "DONE". Do not assign any roles at this stage.

Phase 2: Create Pub/Sub Topic & Secret

Next, create the messaging topic and a secret for the external API key.

Create the Secret:

1. Navigate to "Security" > "Secret Manager".
2. Click "+ CREATE SECRET".
   • Name: your-api-key
   • Secret value: my-super-secret-key-123
3. Click "CREATE SECRET".

Create the Pub/Sub Topic:

1. Navigate to "Pub/Sub" > "Topics".
2. Click "+ CREATE TOPIC".
   • Topic ID: chat-events
3. Click "CREATE".

Phase 3: Assign IAM Permissions

Grant the necessary permissions to the service accounts.

Permission 1: Allow Ingestor to publish to the Topic

1. Go to "Pub/Sub" > "Topics", select the chat-events topic.
2. In the info panel on the right, go to the "PERMISSIONS" tab and click "+ ADD PRINCIPAL".
   • New principal: chat-ingestor-sa@[YOUR_PROJECT_ID].iam.gserviceaccount.com
   • Role: Pub/Sub Publisher
3. Click "SAVE".

Permission 2: Allow Worker to access the Secret

1. Go to "Secret Manager", select the dummy-api-key secret.
2. In the info panel, go to the "PERMISSIONS" tab and click "+ ADD PRINCIPAL".
   • New principal: chat-worker-sa@[YOUR_PROJECT_ID].iam.gserviceaccount.com
   • Role: Secret Manager Secret Accessor
3. Click "SAVE".

Permission 3: Allow Cloud Build to run

1. Navigate to "IAM & Admin" > "IAM".
2. Find the principal ending in -compute@developer.gserviceaccount.com.
3. Click the pencil icon (Edit principal) for that row.
4. Click "+ ADD ANOTHER ROLE".
   • Role: Cloud Build Service Account
5. Click "SAVE".

Phase 4: Create Artifact Registry Repository

Create a repository to store the container images.

1. Navigate to "Artifact Registry".
2. Click "+ CREATE REPOSITORY".
   • Name: bot-poc-repo
   • Format: Select Docker.
   • Location Type: Select Region (e.g., us-central1).
3. Click "CREATE".

Phase 5: Build & Deploy the chat-ingestor Service

This service receives, validates, and forwards the event.

1. Prepare the Code: On CloudShell, create a directory named chat-ingestor and add the three corresponding files (main.py, requirements.txt, Dockerfile) from the Code in the repository.
2. Build the Image: From a terminal inside the chat-ingestor directory, run the build command:

   gcloud builds submit --tag [YOUR_REGION]-docker.pkg.dev/[YOUR_PROJECT_ID]/bot-poc-repo/chat-ingestor:latest

3. Deploy the Service (UI):
   1. Navigate to "Cloud Run" and click "+ CREATE SERVICE".
   2. Select "Deploy one revision from an existing container image".
   3. Click "SELECT" and find the chat-ingestor:latest image.
   4. Service name: chat-ingestor
   5. Authentication: Select "Allow unauthenticated invocations".
   6. Expand "Containers, Volumes, Networking, Security".
   7. Go to the "SECURITY" tab and select the chat-ingestor-sa service account.
   8. Go to the "CONTAINERS" tab. Under "Environment Variables", click "+ ADD VARIABLE" and add:
      • GCP_PROJECT: Your Project ID
      • PUB_SUB_TOPIC: chat-events
   9. Click "CREATE".
4. Once deployed, copy the URL it provides.

Phase 6: Configure the Google Chat App

Point the Chat App to the chat-ingestor service.

1. Navigate to "APIs & Services" > "Google Chat API" and click the "Configuration" tab.
2. Fill in the app details (App Name, Avatar URL, Description).
3. Under "Connection settings", select "HTTP endpoint URL" and paste the chat-ingestor URL you just copied.
4. Under "Visibility", add the users/groups who can test the app.
5. Click "SAVE".
6. IMPORTAN Do not create as an Add-on, uncheck this box

Phase 7: Build & Deploy the chat-worker Service

This service performs the long-running task.

1. Prepare the Code: Create a new directory named chat-worker in Cloud Shell and add the three corresponding files (main.py, requirements.txt, Dockerfile) from the Code repository.
2. Build the Image: From a terminal inside the chat-worker directory, run the build command:

   gcloud builds submit --tag [YOUR_REGION]-docker.pkg.dev/[YOUR_PROJECT_ID]/bot-poc-repo/chat-worker:latest

3. Deploy the Service (UI):
   1. Navigate to "Cloud Run" and click "+ CREATE SERVICE".
   2. Select the chat-worker:latest image.
   3. Service name: chat-worker
   4. Authentication: Select "Require authentication".
   5. Ingress control: Select "Internal".
   6. Expand "Containers, Volumes, Networking, Security".
   7. Go to the "SECURITY" tab and select the chat-worker-sa service account.
   8. Go to the "CONTAINERS" tab. Under "Environment Variables", click "+ ADD VARIABLE" and add:
      • GCP_PROJECT: Your Project ID
      • SECRET_ID: your-api-key
   9. Click "CREATE".
4. Once deployed, copy its URL.

Phase 8: Create the Authenticated Push Subscription

Connect Pub/Sub to the internal chat-worker service.

Step 8a: Allow Pub/Sub to invoke the Worker

1. Navigate to the main Cloud Run services list.
2. Click the checkbox on the far left of the chat-worker row.
3. An Info panel will open on the right.
4. Click the "PERMISSIONS" tab and then "+ ADD PRINCIPAL".
   • New principal: pubsub-push-sa@[YOUR_PROJECT_ID].iam.gserviceaccount.com
   • Role: Cloud Run Invoker
5. Click "SAVE".

Step 8b: Allow the Pub/Sub Service to Create Tokens

1. Navigate to "IAM & Admin" > "IAM".
2. Click "+ GRANT ACCESS".
   • New principal: service-[YOUR_PROJECT_NUMBER]@gcp-sa-pubsub.iam.gserviceaccount.com
   • Role: Service Account Token Creator
3. Click "SAVE".

Step 8c: Create the Push Subscription

1. Navigate to "Pub/Sub" > "Topics" and click on your chat-events topic.
2. Go to the "SUBSCRIPTIONS" tab and click "+ CREATE SUBSCRIPTION".
   • Subscription ID: chat-worker-subscription
   • Delivery Type: Select "Push".
   • Endpoint URL: Paste the chat-worker URL from Phase 7.
   • Check the box for "Enable authentication".
   • Service account: Select your pubsub-push-sa service account.
3. Click "CREATE".

Phase 9: Test & Iterate

Test:

• Go to Google Chat and find your bot.
• Add it to a space (this should trigger a welcome message).
• Send it a direct message (e.g., "test").

Expected Result:

• The bot should respond asynchronously with: "Hello, [Your Name]! This is your async reply. ... Response title: 'sunt aut facere repellat provident occaecati excepturi optio reprehenderit'"

Troubleshoot:

• If the bot shows "not responding", check the logs for the chat-ingestor service.
• If you don't receive a reply, check the logs for the chat-worker service.