Skip to main content

Google Cloud Configuration Guide

Table of Contents​

  1. Google Cloud Overview
  2. Project Creation and Configuration
  3. Google OAuth 2.0 Configuration
  4. Cloud Run Configuration
  5. Cloud Build Configuration
  6. Artifact Registry Configuration
  7. Service Account Configuration
  8. API Enablement

Google Cloud Overview​

What is Google Cloud?​

Google Cloud Platform (GCP) is a cloud computing service platform provided by Google, offering various cloud services including computing, storage, networking, big data, and machine learning. In this project, we use the following Google Cloud services:

  • Cloud Run: Run containerized applications (serverless container runtime environment)
  • Cloud Build: Automatically build and deploy applications (CI/CD service)
  • Artifact Registry: Store Docker images (container image repository)
  • IAM (Identity and Access Management): Manage permissions for users and service accounts

Why Choose Google Cloud?​

  1. Google Ecosystem Integration: Seamless integration with Google Workspace (Sheets, Slides)
  2. Enterprise Intranet Support: Supports Google internal network deployment (Corp Run)
  3. Cost Control: Pay-as-you-go pricing, suitable for internal projects
  4. Unified Tech Stack: Consistent with other Google services used in the project (Gemini, OAuth)

Project Creation and Configuration​

Create Google Cloud Project​

  1. Access Google Cloud Console

  2. Create New Project

    • Click the project selector, select "New Project"
    • Enter project name (e.g., insighthub-production)
    • Select organization (if applicable)
    • Click "Create"

  3. Record Project ID

    • After project creation, record the project ID (format: grcn-sca-bigquery)
    • Project ID will be used for subsequent configuration

Enable Billing​

Note: Even when using enterprise intranet, some services (such as Cloud Run, Cloud Build) may still require billing to be enabled.

  1. Link Billing Account

    • In project settings, link the organization's billing account
    • Or create a new billing account

  2. Set Budget Alerts (Optional)

    • In "Budgets and Alerts," set budget limits
    • Configure alerts to avoid unexpected charges

Google OAuth 2.0 Configuration​

What is OAuth 2.0?​

OAuth 2.0 is an authorization protocol that allows users to authorize third-party applications to access their Google account information without providing passwords. In this project, OAuth 2.0 is used for:

  1. User Login: Verify user identity
  2. Access Google Sheets: Read Google Sheet data that users have permission to access

Create OAuth 2.0 Credentials​

1. Enable Google+ API​

  1. Open API Library
    • In Google Cloud Console, navigate to "APIs & Services" > "Library"
    • Search for "Google+ API" (or "Google Identity Services API")
    • Click "Enable"

Note: Google+ API is deprecated, but some OAuth flows still require it. If you can't find it, you can skip this step.

  1. Open OAuth Consent Screen

    • Navigate to "APIs & Services" > "OAuth consent screen"
    • Select user type (Internal or External)
    • Click "Create"

  2. Fill in Application Information

    • Application Name: CSA 3A (InsightHub)
    • User Support Email: Your email address
    • Application Logo: (Optional) Upload application icon
    • Application Homepage Link: Cloud Run service URL
    • Application Privacy Policy Link: (Optional)
    • Application Terms of Service Link: (Optional)

  3. Configure Scopes

    • Click "Add or Remove Scopes"
    • Add the following scopes:
      • https://www.googleapis.com/auth/userinfo.email (User email)
      • https://www.googleapis.com/auth/userinfo.profile (User basic information)
      • https://www.googleapis.com/auth/spreadsheets.readonly (Read-only access to Google Sheets)

  4. Add Test Users (If "External" user type is selected)

    • In the "Test Users" section, add email addresses of users allowed to access
    • After production environment is published, all users can access

  5. Save and Continue

    • After completing all steps, click "Save and Continue"
    • Confirm configuration information

3. Create OAuth 2.0 Client ID​

  1. Open Credentials Page

    • Navigate to "APIs & Services" > "Credentials"
    • Click "Create Credentials" > "OAuth client ID"

  2. Select Application Type

    • Select "Web application"

  3. Configure Client

    • Name: InsightHub Web Client
    • Authorized JavaScript Origins:
      • Development environment: http://localhost:5173 (Vite default port)
      • Production environment: https://your-cloud-run-url.run.app
    • Authorized Redirect URIs:
      • Development environment: http://localhost:5173/auth/callback
      • Production environment: https://your-cloud-run-url.run.app/auth/callback

  4. Create and Record Credentials

    • Click "Create"
    • Important: Record the following information:
      • Client ID: Format like 123456789-abcdefghijklmnop.apps.googleusercontent.com
      • Client Secret: Format like GOCSPX-abcdefghijklmnopqrstuvwxyz
    • Client secret is only shown once, please save it securely

Configure Environment Variables​

Configure OAuth credentials to environment variables:

Development Environment (.env file):

VITE_GOOGLE_OAUTH_CLIENT_ID=123456789-abcdefghijklmnop.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-abcdefghijklmnopqrstuvwxyz

Production Environment (Cloud Build trigger):

  • Add substitution variable _VITE_GOOGLE_OAUTH_CLIENT_ID
  • Add substitution variable _GOOGLE_CLIENT_SECRET

Cloud Run Configuration​

Create Cloud Run Service​

1. First Deployment​

Cloud Run service will be automatically created during the first deployment; no manual creation is needed.

2. Service Configuration​

Configure service parameters in cloudbuild.yaml:

- '--region'
- '${_DEPLOY_REGION}'  # e.g., asia-northeast1
- '--platform'
- 'managed'
- '--allow-unauthenticated'  # Allow unauthenticated access

Configuration Notes:

  • region: Select the region closest to users (e.g., asia-northeast1 for Asia-Pacific)
  • platform: managed means fully managed, no need to manage infrastructure
  • allow-unauthenticated: Allow public access (if internal access is needed, this option can be removed)

3. Resource Configuration (Optional)​

Resource configuration can be added in Cloud Build:

- '--memory'
- '512Mi'
- '--cpu'
- '1'
- '--timeout'
- '300'
- '--max-instances'
- '10'
- '--min-instances'
- '0'

Configuration Notes:

  • memory: Memory per container instance (default 512 MiB)
  • cpu: Number of CPUs per container instance (default 1)
  • timeout: Request timeout (seconds, default 300)
  • max-instances: Maximum number of instances (default 100)
  • min-instances: Minimum number of instances (default 0, no instances running when idle)

Cloud Build Configuration​

Create Cloud Build Trigger​

1. Connect to Source Code Repository​

  1. Open Cloud Build Triggers

    • In Google Cloud Console, navigate to "Cloud Build" > "Triggers"
    • Click "Create Trigger"

  2. Select Source Code

    • Select source code repository (GitHub, GitLab, or Cloud Source Repositories)
    • Authorize Cloud Build to access the repository
    • Select repository and branch

2. Configure Trigger​

  1. Trigger Settings

    • Name: insighthub-deploy
    • Event: Push to a branch
    • Branch: ^main$ (or your main branch name)
    • Configuration Type: Cloud Build configuration file (yaml or json)
    • Location: cloudbuild.yaml

  2. Substitution Variables

    • Add the following substitution variables:
Variable NameDescriptionExample Value
_AR_HOSTNAMEArtifact Registry hostnameasia-northeast1-docker.pkg.dev
_AR_PROJECT_IDGoogle Cloud project IDgrcn-sca-bigquery
_AR_REPOSITORYArtifact Registry repository namecloudrun-source-deploy
_SERVICE_NAMECloud Run service namehelen-new-insighthub
_DEPLOY_REGIONDeployment regionasia-northeast1
_VITE_GEMINI_API_KEYGemini API KeyAIzaSy...
_VITE_GOOGLE_OAUTH_CLIENT_IDOAuth Client ID123456789-...
_VITE_GOOGLE_SLIDES_TEMPLATE_IDGoogle Slides template ID1a2b3c4d...
_VITE_HELP_DOCUMENT_URLHelp document URLhttps://...
_AUDIT_LOG_SPREADSHEET_IDAudit log Google Sheet ID1a2b3c4d...
_APPS_SCRIPT_SLIDES_IDImage insertion Apps Script ID5e6f7g8h...
_GOOGLE_CLIENT_SECRETOAuth Client SecretGOCSPX-...

Security Recommendations:

  • Sensitive information (such as API Key, Client Secret) should be stored using Google Secret Manager
  • Read from Secret Manager in triggers instead of direct configuration
  1. Service Account
    • Select the service account used by Cloud Build
    • Ensure the service account has the following permissions:
      • Cloud Build Service Account
      • Artifact Registry Writer
      • Cloud Run Admin

3. Save Trigger​

  • Click "Create" to save the trigger
  • Trigger will automatically execute when code is pushed to the specified branch

Artifact Registry Configuration​

What is Artifact Registry?​

Artifact Registry is Google Cloud's container image repository service, used to store and manage Docker images. Images built by Cloud Build are pushed to Artifact Registry, and then Cloud Run pulls images from Artifact Registry to run.

Create Artifact Registry Repository​

1. Open Artifact Registry​

  • In Google Cloud Console, navigate to "Artifact Registry"
  • Click "Create Repository"

2. Configure Repository​

  • Name: cloudrun-source-deploy (or your chosen name)
  • Format: Docker
  • Mode: Standard
  • Location: Select the same region as Cloud Run (e.g., asia-northeast1)

3. Permission Configuration​

  • Access Control: Use IAM permissions to control access
  • Ensure Cloud Build service account has "Artifact Registry Writer" role
  • Ensure Cloud Run service account has "Artifact Registry Reader" role

Service Account Configuration​

What is a Service Account?​

A service account is a special type of account in Google Cloud used to represent applications accessing Google Cloud services, rather than representing users. In this project, service accounts are used for:

  1. Cloud Build: Execute build and deployment operations
  2. Apps Script Calls: Call Apps Script through Execution API
  3. Google Workspace Access: Access Google Sheets and Google Slides

Create Service Account​

1. Open IAM & Admin​

  • In Google Cloud Console, navigate to "IAM & Admin" > "Service Accounts"
  • Click "Create Service Account"

2. Configure Service Account​

  • Service Account Name: insighthub-service-account
  • Service Account ID: Auto-generated (can be modified)
  • Description: InsightHub application service account

3. Grant Roles​

Add the following roles:

RoleDescription
Cloud Run InvokerAllow invoking Cloud Run services
Artifact Registry ReaderAllow reading images from Artifact Registry
Service Account UserAllow using service account

4. Create Key​

  1. Open Service Account Details

    • Click the created service account
    • Switch to "Keys" tab

  2. Add Key

    • Click "Add Key" > "Create New Key"
    • Select "JSON" format
    • Click "Create"
    • Important: JSON key file will be downloaded to local, please save it securely

  3. Configure Environment Variables

    • Development Environment: Save JSON file to project directory, configure GOOGLE_SERVICE_ACCOUNT_KEY_PATH
    • Production Environment: Configure JSON content to GOOGLE_SERVICE_ACCOUNT_JSON environment variable

Service Account Permission Configuration​

Apps Script Call Permissions​

Service account needs to be able to call Apps Script Execution API:

  1. Enable Apps Script API

    • In Google Cloud Console, navigate to "APIs & Services" > "Library"
    • Search for "Apps Script API"
    • Click "Enable"

  2. Grant Execution Permission

    • In Apps Script project, add service account email as "Viewer" or "Editor"
    • Service account email format: service-account-name@project-id.iam.gserviceaccount.com

Google Workspace Access Permissions​

If service account needs to access Google Sheets or Google Slides:

  1. Share Resources

    • In Google Sheets/Slides, add service account email as "Editor"
    • Service account email format: service-account-name@project-id.iam.gserviceaccount.com

  2. Domain-Wide Delegation (Optional)

    • If access to all resources within the organization is needed, domain-wide delegation can be configured
    • This requires Google Workspace administrator permissions

API Enablement​

Required APIs​

The following APIs need to be enabled in the Google Cloud project:

API NamePurposeRequired
Cloud Run APIRun containerized applications✅ Required
Cloud Build APIBuild and deploy applications✅ Required
Artifact Registry APIStore Docker images✅ Required
Apps Script APICall Apps Script⚠️ Optional
Google Sheets APIAccess Google Sheets⚠️ Optional (if using Google Sheet features)
Google Slides APIAccess Google Slides⚠️ Optional (if using Google Slides features)
Google Identity Services APIOAuth 2.0 authentication✅ Required

Enable APIs​

  1. Open API Library

    • In Google Cloud Console, navigate to "APIs & Services" > "Library"

  2. Search and Enable

    • Search for API name
    • Click API card
    • Click "Enable" button

  3. Verify Enablement Status

    • View in "APIs & Services" > "Enabled APIs"
    • Ensure all required APIs are enabled

Configuration Checklist​

Project Configuration​

  • Google Cloud project created
  • Project ID recorded
  • Billing enabled (if needed)

OAuth 2.0 Configuration​

  • OAuth consent screen configured
  • OAuth client ID created
  • Client ID and secret recorded
  • Redirect URIs configured (development and production environments)
  • Environment variables configured

Cloud Run Configuration​

  • Service region selected
  • Resource configuration set (if needed)
  • Environment variables configured

Cloud Build Configuration​

  • Trigger created
  • Source code repository connected
  • Substitution variables configured
  • Service account permissions granted

Artifact Registry Configuration​

  • Repository created
  • Repository region selected
  • Permissions configured

Service Account Configuration​

  • Service account created
  • Key downloaded
  • Roles granted
  • Apps Script permissions configured
  • Google Workspace resources shared

API Enablement​

  • Cloud Run API enabled
  • Cloud Build API enabled
  • Artifact Registry API enabled
  • Apps Script API enabled (if needed)
  • Google Identity Services API enabled

Frequently Asked Questions​

Q1: OAuth redirect URI mismatch error?​

Error Message: redirect_uri_mismatch

Cause: Redirect URI doesn't match OAuth client configuration

Solution:

  1. Check "Authorized Redirect URIs" in OAuth client configuration
  2. Ensure it includes the actual redirect URI used (including protocol, domain, path)
  3. Development and production environments need to be configured separately

Q2: Service account cannot call Apps Script?​

Error Message: PERMISSION_DENIED or Script function not found

Cause:

  1. Apps Script API not enabled
  2. Service account doesn't have access permission to Apps Script project
  3. Script ID configuration error

Solution:

  1. Enable Apps Script API
  2. In Apps Script project, add service account email as "Viewer"
  3. Verify Script ID is correct (obtain from Apps Script editor URL)

Q3: Cloud Build build fails with insufficient permissions?​

Error Message: PERMISSION_DENIED

Cause: Cloud Build service account lacks necessary permissions

Solution:

  1. Check the service account used by Cloud Build
  2. Ensure service account has the following roles:
    • Cloud Build Service Account
    • Artifact Registry Writer
    • Cloud Run Admin
    • Service Account User

Q4: How to view service account email address?​

Method 1: Through Cloud Console

  1. Open "IAM & Admin" > "Service Accounts"
  2. Click service account name
  3. View "Email" field in details page

Method 2: Through Format Inference Service account email format: service-account-name@project-id.iam.gserviceaccount.com

Summary​

This section detailed Google Cloud configuration steps, including:

  1. Project Creation: How to create and configure Google Cloud project
  2. OAuth 2.0 Configuration: How to configure user login and Google Workspace access
  3. Cloud Run Configuration: How to configure serverless container runtime environment
  4. Cloud Build Configuration: How to configure automated build and deployment
  5. Artifact Registry Configuration: How to configure container image repository
  6. Service Account Configuration: How to create and configure service accounts
  7. API Enablement: Google Cloud APIs that need to be enabled

Correctly configuring Google Cloud is the foundation for system deployment and operation. Please complete the configuration step by step according to the checklist.

Related Documentation: