在 Cloud Run 環境中執行 Rails

目標

• 建立 Cloud SQL 資料庫，並將其連線至 Active Record
• 建立及使用 Secret Manager，安全地儲存及存取 Rails 主金鑰
• 在 Cloud Storage 上，從 Active Storage 存放使用者上傳的媒體和檔案
• 使用 Cloud Build 自動執行建構和資料庫遷移作業
• 將 Rails 應用程式部署至 Cloud Run

費用

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自體驗產品的實際應用成效。新客戶還能獲得價值 $300 美元的免費抵免額，能用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Run, Cloud SQL, Cloud Build, Secret Manager, and Compute Engine APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Run, Cloud SQL, Cloud Build, Secret Manager, and Compute Engine APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

1. 請確認用於本教學課程的帳戶具備足夠權限。

準備環境

本教學課程會使用多項 Google Cloud 服務，提供支援已部署 Rails 應用程式的資料庫、媒體儲存空間和密鑰儲存空間。請先設定要部署服務的區域，然後複製 Rails 應用程式，準備好環境。

設定預設專案和區域

1. 執行下列指令，為 gcloud CLI 設定預設專案設定：

   gcloud config set project PROJECT_ID
   

   將 PROJECT_ID 替換為您的 Google Cloud專案 ID

2. 設定區域：

   export REGION=REGION
   

   將 REGION 替換為適當位置。為提升服務間的效率，所有服務都應部署在同一個區域。如要進一步瞭解離您最近的區域，請參閱「各地區販售的產品」。

複製 Rails 應用程式

Rails 範例應用程式的程式碼位於 GitHub 的 GoogleCloudPlatform/ruby-docs-samples 存放區。

1. 複製存放區：

   git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples.git
   

2. 前往含有程式碼範例的目錄，然後執行下列指令，確保應用程式已正確設定必要的 Gem 和依附元件：

   Linux/macOS

   cd ruby-docs-samples/run/rails
   bundle install
   

   Windows

   cd ruby-docs-samples\run\rails
   bundle install
   

準備後端服務

本教學課程使用多項 Google Cloud 服務，提供支援已部署 Rails 專案的資料庫、媒體儲存空間和密鑰儲存空間。這些服務會部署在特定區域。為提高服務之間的效率，建議您將所有服務部署在同一個區域。如要進一步瞭解離您最近的區域，請參閱「依位置查看可用的產品」。

設定 PostgreSQL 適用的 Cloud SQL 執行個體

Rails 支援多個關聯式資料庫，包括 Cloud SQL 提供的多個資料庫。本教學課程使用 PostgreSQL，這是 Rails 應用程式常用的開放原始碼資料庫。

以下各節說明如何為 Rails 應用程式建立 PostgreSQL 執行個體、資料庫和資料庫使用者。

建立 PostgreSQL 執行個體。

建立資料庫

新增使用者

為資料庫使用者產生隨機密碼，並寫入名為 dbpassword 的檔案：

cat /dev/urandom | LC_ALL=C tr -dc '[:alpha:]'| fold -w 50 | head -n1 > dbpassword

設定 Artifact Registry 存放區

使用 Artifact Registry 建立存放區，儲存容器映像檔。

設定 Cloud Storage bucket

您可以使用 Cloud Storage，在具備高可用性的物件儲存庫中，代管 Rails 靜態資產和使用者上傳的媒體。

建立 bucket 後，如要公開上傳的圖片，請將圖片物件的權限變更為所有人皆可讀取。

將密鑰值儲存在 Secret Manager

後端服務設定完成後，Rails 需要密碼等安全資訊，才能存取這些服務。本教學課程不會直接將這些值放入 Rails 原始碼，而是使用 Rails 憑證和 Secret Manager 安全地儲存這項資訊。

建立加密憑證檔案，並將金鑰儲存為 Secret Manager 密鑰

Rails 會將 Secret 儲存在名為「config/credentials.yml.enc」的加密檔案中。您可以使用本機 config/master.key 或環境變數 ENV["RAILS_MASTER_KEY"] 解密檔案。您可以在憑證檔案中儲存 Cloud SQL 執行個體資料庫密碼，以及外部 API 的其他存取金鑰。

您可以將這組金鑰安全地儲存在 Secret Manager 中。接著，將存取權授予 Cloud Run 和 Cloud Build 的服務帳戶，即可授予這兩項服務金鑰存取權。服務帳戶會透過包含專案編號的電子郵件地址來識別。

1. 使用下列指令產生 config/credentials.yml.enc 檔案：

   bin/rails credentials:edit
   

   如果未定義主金鑰，指令會建立 config/master.key；如果 config/credentials.yml.enc 檔案不存在，則會建立該檔案。這會在預設 $EDITOR 中開啟臨時檔案，其中包含要新增密鑰的解密內容。

2. 從 dbpassword 檔案複製並貼上新建立的 PostgreSQL 執行個體資料庫密碼到憑證檔案：

   secret_key_base: GENERATED_VALUE
   gcp:
       db_password: PASSWORD
   

   您可以使用 Rails.application.credentials 存取密鑰。例如，Rails.application.credentials.secret_key_base 應傳回應用程式的密鑰庫，Rails.application.credentials.gcp[:db_password] 則應傳回資料庫密碼。

3. config/credentials/yml.enc 會以加密形式儲存，但 config/master.key 可以儲存在 Secret Manager 中。

   控制台

   1. 前往 Google Cloud 控制台的「Secret Manager」頁面。

      前往「Secret Manager」頁面

   2. 按一下「建立密鑰」。

   3. 在「Name」欄位中，輸入 Secret 名稱 RAILS_SECRET_NAME。

   4. 在「Secret value」(密鑰值) 對話方塊中，將 master.key 值貼到方塊中。

   5. 點選「建立密鑰」。

   6. 在密鑰的「Secret details」(密鑰詳細資料) 頁面，記下專案編號：

      projects/PROJECTNUM/secrets/RAILS_SECRET_NAME

   7. 在「權限」分頁中，按一下「新增成員」。

   8. 在「新增成員」欄位中輸入 PROJECTNUM-compute@developer.gserviceaccount.com，然後按 Enter。

   9. 在「新增成員」欄位中輸入 PROJECTNUM@cloudbuild.gserviceaccount.com，然後按 Enter。

   10. 在「角色」下拉式選單中，選取「Secret Manager Secret Accessor」(Secret Manager 密鑰存取者)。

   11. 按一下 [儲存]。

   gcloud

   1. 使用 config/master.key 的值建立新密鑰：

      gcloud secrets create RAILS_SECRET_NAME --data-file config/master.key
      

      將 RAILS_SECRET_NAME 替換為新 Secret 的名稱。

   2. 如要確認密鑰是否已建立，請檢查：

      gcloud secrets describe RAILS_SECRET_NAME
      
      gcloud secrets versions access latest --secret RAILS_SECRET_NAME
      

   3. 取得專案編號的值：

      gcloud projects describe PROJECT_ID --format='value(projectNumber)'
      

   4. 將密碼的存取權授予 Cloud Run 服務帳戶：

      gcloud secrets add-iam-policy-binding RAILS_SECRET_NAME \
          --member serviceAccount:PROJECTNUM-compute@developer.gserviceaccount.com \
          --role roles/secretmanager.secretAccessor
      

      將 PROJECTNUM 替換為專案編號值。

   5. 將密鑰的存取權授予 Cloud Build 服務帳戶：

      gcloud secrets add-iam-policy-binding RAILS_SECRET_NAME \
          --member serviceAccount:PROJECTNUM@cloudbuild.gserviceaccount.com \
          --role roles/secretmanager.secretAccessor
      

      在輸出內容中，確認 bindings 將這兩個服務帳戶列為成員。

將 Rails 應用程式連結至正式版資料庫和儲存空間

本教學課程會使用 PostgreSQL 執行個體做為正式版資料庫，並以 Cloud Storage 做為儲存空間後端。如要讓 Rails 連線至新建立的資料庫和儲存空間 bucket，您必須在 .env 檔案中指定存取這些資源所需的所有資訊。.env 檔案包含應用程式環境變數的設定。應用程式會使用 dotenv Gem 讀取這個檔案。由於密鑰儲存在 credentials.yml.enc 和 Secret Manager 中，因此 .env 不必加密，因為其中不含任何私密憑證。

1. 如要設定 Rails 應用程式，以便連線至資料庫和儲存空間 bucket，請開啟 .env 檔案。

2. 將 .env 檔案設定修改為下列內容。使用建立值區時使用的 MEDIA_BUCKET_SUFFIX 值。

   PRODUCTION_DB_NAME: DATABASE_NAME
   PRODUCTION_DB_USERNAME: DATABASE_USERNAME
   CLOUD_SQL_CONNECTION_NAME: PROJECT_ID:REGION:INSTANCE_NAME
   GOOGLE_PROJECT_ID: PROJECT_ID
   STORAGE_BUCKET_NAME: PROJECT_ID-MEDIA_BUCKET_SUFFIX
   

   現在，Rails 應用程式已設定完畢，可供部署至 Cloud Run 時使用 Cloud SQL 和 Cloud Storage。

將應用程式部署至 Cloud Run

設定後端服務後，您現在可以將應用程式部署為 Cloud Run 服務。

1. 使用提供的 cloudbuild.yaml，透過 Cloud Build 建構映像檔、執行資料庫遷移作業，以及填入靜態資產：

   gcloud builds submit --config cloudbuild.yaml \
       --substitutions _SERVICE_NAME=SERVICE_NAME,_INSTANCE_NAME=INSTANCE_NAME,_REGION=REGION,_SECRET_NAME=RAILS_SECRET_NAME
   

   將 SERVICE_NAME 替換為服務名稱。首次建構作業需要幾分鐘才能完成。如果建構作業逾時，請在建構指令中插入 --timeout=2000s，延長逾時時間。

2. 建構成功後，請首次部署 Cloud Run 服務，並設定服務區域、基礎映像檔和已連線的 Cloud SQL 執行個體：

   gcloud run deploy SERVICE_NAME \
           --region REGION \
           --image REGION-docker.pkg.dev/PROJECT_ID/cloud-run-source-deploy/SERVICE_NAME \
           --add-cloudsql-instances PROJECT_ID:REGION:INSTANCE_NAME \
           --allow-unauthenticated
   

   輸出內容應會顯示部署作業成功，並提供服務網址。

3. 如要查看已部署的服務，請前往服務網址。

   

4. 請嘗試上傳新相片。如果相片上傳成功，表示 Rails 應用程式已順利部署。

   

更新應用程式

雖然初始佈建和部署步驟較為複雜，但更新程序相對簡單：

1. 執行 Cloud Build 建構和遷移指令碼：

   gcloud builds submit --config cloudbuild.yaml \
           --substitutions _SERVICE_NAME=SERVICE_NAME,_INSTANCE_NAME=INSTANCE_NAME,_REGION=REGION,_SECRET_NAME=RAILS_SECRET_NAME
   

2. 部署服務，僅指定區域和映像檔：

   gcloud run deploy SERVICE_NAME \
           --region REGION \
           --image REGION-docker.pkg.dev/PROJECT_ID/cloud-run-source-deploy/SERVICE_NAME
   

瞭解程式碼

Rails 範例應用程式是使用標準 Rails 指令建立，下列指令會建立 cat_album 應用程式，並使用 scaffold 指令產生 Photo 資源的模型、控制器和檢視畫面：

rails new cat_album
rails generate scaffold Photo caption:text

資料庫連線

config/database.yml 檔案包含在不同環境 (開發、測試、正式) 中存取資料庫所需的設定。舉例來說，生產環境資料庫已設定為在 PostgreSQL 適用的 Cloud SQL 中執行。資料庫名稱和使用者名稱是在 .env 檔案中透過環境變數設定，而資料庫密碼則儲存在 config/credentials.yml.enc 檔案中，需要 RAILS_MASTER_KEY 才能解密。

應用程式在 Cloud Run (全代管) 上執行時，會使用 Cloud Run 環境提供的通訊端連線至 PostgreSQL 執行個體。應用程式在本機電腦上執行時，會使用 Cloud SQL Auth Proxy 連線至 PostgreSQL 執行個體。

production:
  <<: *default
  database: <%= ENV["PRODUCTION_DB_NAME"] %>
  username: <%= ENV["PRODUCTION_DB_USERNAME"] %>
  password: <%= Rails.application.credentials.gcp[:db_password] %>
  host: "<%= ENV.fetch("DB_SOCKET_DIR") { '/cloudsql' } %>/<%= ENV["CLOUD_SQL_CONNECTION_NAME"] %>"

使用者上傳並儲存在雲端的媒體

Rails 會使用 Active Storage 將檔案上傳至儲存空間供應商。config/storage.yml 和 config/environments/production.rb 檔案會將 Cloud Storage 指定為正式環境中的服務供應商。

google:
  service: GCS
  project: <%= ENV["GOOGLE_PROJECT_ID"] %>
  bucket: <%= ENV["STORAGE_BUCKET_NAME"] %>

# Store uploaded files on the local file system (see config/storage.yml for options).
config.active_storage.service = :google

使用 Cloud Build 自動化

cloudbuild.yaml 檔案不僅會執行一般的映像檔建構步驟 (建立容器映像檔並推送至 Artifact Registry)，也會執行 Rails 資料庫遷移作業。這項遷移作業是透過 Cloud Run 工作執行，使用自訂指令，讓容器執行遷移作業，而非預設的網頁伺服器。

steps:
  - id: "build image"
    name: "gcr.io/cloud-builders/docker"
    entrypoint: 'bash'
    args: ["-c", "docker build --build-arg MASTER_KEY=$$RAILS_KEY -t ${_IMAGE_NAME} . "]
    secretEnv: ["RAILS_KEY"]

  - id: "push image"
    name: "gcr.io/cloud-builders/docker"
    args: ["push", "${_IMAGE_NAME}"]

  - id: "apply migrations"
    name: "gcr.io/google.com/cloudsdktool/cloud-sdk"
    entrypoint: /bin/bash
    secretEnv: ["RAILS_KEY"]
    args:
      - "-c"
      - |
        gcloud run jobs create migrate-job \
          --region ${_REGION} \
          --image ${_IMAGE_NAME} \
          --set-cloudsql-instances ${_CLOUD_SQL_CONNECTION_NAME} \
          --set-env-vars RAILS_MASTER_KEY=$$RAILS_KEY \
          --command bundle \
          --args exec,rails,db:migrate \
          --execute-now --wait && \
          gcloud run jobs delete  migrate-job --region ${_REGION} -q

options:
  dynamicSubstitutions: true

substitutions:
  _REGION: us-central1
  _SERVICE_NAME: rails-cat-album
  _INSTANCE_NAME: cat-album
  _SECRET_NAME: rails-master-key
  _AR_REPO_NAME: cloud-run-source-deploy
  _IMAGE_NAME: ${_REGION}-docker.pkg.dev/${PROJECT_ID}/${_AR_REPO_NAME}/${_SERVICE_NAME}
  _CLOUD_SQL_CONNECTION_NAME: ${PROJECT_ID}:${_REGION}:${_INSTANCE_NAME}

availableSecrets:
  secretManager:
  - versionName: projects/${PROJECT_ID}/secrets/${_SECRET_NAME}/versions/latest
    env: RAILS_KEY

images:
  - "${_IMAGE_NAME}"

這項設定會使用替代變數。直接變更檔案中的值，表示可以在遷移時捨棄 --substitutions 旗標。

在此設定中，系統只會套用 db/migrate 目錄中的現有遷移作業。如要建立遷移檔案，請參閱「Active Record 遷移」。

如要建構映像檔及套用遷移作業，Cloud Build 設定需要存取 Secret Manager 中的 RAILS_MASTER_KEY 密碼。availableSecrets 欄位會設定要用於密鑰的密鑰版本和環境變數。主金鑰密鑰會在建構映像檔步驟中做為引數傳入，然後在建構映像檔時，設為 Dockerfile 中的 RAILS_MASTER_KEY。

ARG MASTER_KEY
ENV RAILS_MASTER_KEY=${MASTER_KEY}

如要擴充 Cloud Build 建構設定，在一個設定中納入部署作業，不必執行兩項指令，請參閱「透過 Cloud Build 從 Git 持續部署」。如上所述，這需要變更 IAM。

Cloud Logging 和 Error Reporting

根據預設，使用 RAILS_LOG_TO_STDOUT 設定時，Rails 會在正式版中記錄到 stdout。應用程式在 Cloud Run 上執行時，環境會自動擷取寫入 stdout 和 stderr 的記錄，並儲存在 Cloud Logging 中。

如要自動擷取未處理的例外狀況，並在 Error Reporting 中顯示格式化的堆疊追蹤，請將 google-cloud-error_reporting gem 新增至 Gemfile：

gem "google-cloud-error_reporting"

當 Rails 應用程式在正式環境模式下啟動時，Bundler 會自動載入程式庫，並設定 Error Reporting 來擷取 Rack 堆疊中的例外狀況。詳情請參閱「設定 Ruby 的 Error Reporting 功能」。

清除所用資源

1. 前往 Google Cloud 控制台的「Manage resources」(管理資源) 頁面。

   前往「Manage resources」(管理資源)

2. 在專案清單中選取要刪除的專案，然後點選「Delete」(刪除)。
3. 在對話方塊中輸入專案 ID，然後按一下 [Shut down] (關閉) 以刪除專案。