使用 Terraform 安排及執行 Cron 工作

本快速入門導覽課程說明如何使用 Terraform 建立 Cloud Scheduler Cron 工作。Terraform 是一種基礎架構即程式碼 (IaC) 工具，可讓您透過程式碼，以可預測的方式建立、變更及改善雲端基礎架構。進一步瞭解如何使用 Terraform 在 Google Cloud上佈建基礎架構。

Cloud Scheduler 提供免費方案，因此執行本快速入門導覽課程不會產生任何費用。詳情請參閱這篇文章，瞭解定價相關資訊。

在本快速入門導覽課程中，您將：

使用 Terraform 為 Cloud Scheduler 建立 Cron 工作。
為工作設定週期性排程。
將 Pub/Sub 主題指定為工作目標。
執行工作。
確認工作已成功執行。

事前準備

貴機構定義的安全性限制，可能會導致您無法完成下列步驟。如需疑難排解資訊，請參閱「在受限的 Google Cloud 環境中開發應用程式」。

If you don't already have one, sign up for a new account.

Install the Google Cloud CLI.

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

Create or select 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.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

如要使用現有專案進行本指南中的操作，請確認您具有完成本指南所需的權限。如果您建立新專案，則已具備必要權限。

Enable the Resource Manager and Service Usage APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable cloudresourcemanager.googleapis.com serviceusage.googleapis.com

Install the Google Cloud CLI.

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

Create or select 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.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

如要使用現有專案進行本指南中的操作，請確認您具有完成本指南所需的權限。如果您建立新專案，則已具備必要權限。

Enable the Resource Manager and Service Usage APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable cloudresourcemanager.googleapis.com serviceusage.googleapis.com

Cloud Shell 已整合 Terraform。如需安裝 Terraform，請參閱 HashiCorp Terraform 說明文件。

必要的角色

如要取得完成本快速入門導覽課程所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

Cloud Scheduler 管理員 (roles/cloudscheduler.admin)
Pub/Sub 編輯者 (roles/pubsub.editor)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

建立 Terraform 設定檔

如要搭配 Cloud Scheduler 使用 Terraform，您需要建立設定檔來描述基礎架構，並建立執行計畫。然後將設定檔套用至平台或服務，執行佈建基礎架構的作業。

請完成下列步驟，建立名為 main.tf 的 Terraform 設定檔：

開啟終端機並建立目錄：
```
mkdir terraform
```
前往 terraform 目錄：
```
cd terraform
```
在目錄中新增檔案 main.tf：
```
nano main.tf
```

將下列 Terraform 供應商新增至 Google Cloud 資源的 main.tf 檔案：

啟用 Cloud Scheduler 和 Pub/Sub API：

# Enable Cloud Scheduler API
resource "google_project_service" "scheduler" {
  service            = "cloudscheduler.googleapis.com"
  disable_on_destroy = false
}
# Enable Pub/Sub API
resource "google_project_service" "pubsub" {
  service            = "pubsub.googleapis.com"
  disable_on_destroy = false
}

建立 Pub/Sub 主題，做為發布端可傳送訊息的資源：
```
# Create Pub/Sub topic
resource "google_pubsub_topic" "default" {
  name = "pubsub_topic"
}
```
這會建立名為「pubsub_topic」的主題。

建立訂閱項目，接收發布至 Pub/Sub 主題的訊息：

# Create Pub/Sub subscription
resource "google_pubsub_subscription" "default" {
  name  = "pubsub_subscription"
  topic = google_pubsub_topic.default.name
}

使用 google_cloud_scheduler_job 資源建立 Cron 工作：
```
# Create a cron job using Cloud Scheduler
resource "google_cloud_scheduler_job" "default" {
  name        = "test-job"
  description = "test job"
  schedule    = "30 16 * * 7"
  region      = "us-central1"

  pubsub_target {
    topic_name = google_pubsub_topic.default.id
    data       = base64encode("Hello world!")
  }
}
```
範例中使用的引數如下：
- name：工作名稱。
- description：工作說明。
- schedule：工作的頻率，使用以 Unix-cron 為基礎的格式。
  
  在本範例中，30 16 * * 7 表示工作會在星期日 16:30 執行。詳情請參閱「Cron 工作格式和時區」。
- region：工作所在的區域。
- pubsub_target：Pub/Sub 主題目標，包括主題的完整資源名稱 (topic_name)，工作執行時，訊息酬載 (data) 會發布至該主題。
系統支援其他引數。詳情請參閱 Terraform 登錄引數參考資料。

如需搭配 Cloud Scheduler 使用 Terraform 的其他範例，請參閱「依排程執行 Cloud Run 服務」。

建立 Cron 工作

部署 Terraform 資源，建立 Cron 工作。

開啟終端機，並在 terraform 目錄中初始化 Terraform：
```
terraform init
```
確認您透過 Terraform 提議的變更符合預期計畫：
```
terraform plan
```
您可以忽略有關不使用 -out 選項的附註。
建立 Cron 工作：
```
terraform apply
```
在「Enter a value」(輸入值) 提示中輸入 yes，繼續建立資源。

確認已建立工作：

gcloud scheduler jobs describe test-job --location=us-central1

畫面會顯示如下的輸出內容：

description: test job
lastAttemptTime: '2024-04-04T13:56:00.669530Z'
name: projects/PROJECT_ID/locations/us-central1/jobs/test-job
pubsubTarget:
data: dGVzdA==
topicName: projects/PROJECT_ID/topics/pubsub_topic
schedule: '30 16 * * 7'
scheduleTime: '2024-04-04T13:58:00.737907Z'
state: ENABLED

您已建立一項工作，會在星期日 16:30 將訊息傳送至 Pub/Sub 主題。現在可以執行工作。

執行工作

除了按照指定時間表執行作業，您也可以執行下列指令，強制立即執行作業。

gcloud scheduler jobs run test-job --location=us-central1

請注意，由於某些初始設定的影響，在專案中建立的第一項工作可能需要幾分鐘的時間才能執行。

驗證結果

確認 Pub/Sub 主題是否收到工作傳送的訊息。

從訂閱項目提取 Pub/Sub 訊息：
```
gcloud pubsub subscriptions pull pubsub_subscription --limit 5
```
如果一開始並沒有提取任何訊息，請再次執行指令。

查看執行工作的結果。畫面會顯示類似以下的輸出內容：

DATA: Hello world!
MESSAGE_ID: 5028933846601543
ORDERING_KEY:
ATTRIBUTES:
DELIVERY_ATTEMPT:
ACK_ID: RFAGFixdRkhRNxkIaFEOT14jPzUgKEUQAgVPAihdeTFXLkFacGhRDRlyfWB9[...]

清除所用資源

為了避免系統向您的 Google Cloud 帳戶收取本頁面所用資源的費用，請刪除含有這些資源的 Google Cloud 專案。

刪除 Google Cloud 專案後，系統就會停止對專案使用的所有資源收取費用。請注意，根據預設，Cloud Shell 主目錄中的任何檔案 (例如任何 Terraform 檔案) 都會在工作階段之間保留。
注意：刪除專案會造成以下結果：
- 專案中的所有內容都會遭到刪除。如果使用現有專案來進行本文中的任務，刪除專案將一併移除當中已完成的其他任務'。
- 自訂專案 ID 會消失。當您之前建立這個專案時，可能建立了想要在日後使用的自訂專案 ID。如要保留使用該專案 ID 的網址 (例如 appspot.com 網址)，請刪除在該專案中選取的資源，而不是刪除整個專案。
Delete a Google Cloud project:
```
gcloud projects delete PROJECT_ID
```
或者，您也可以刪除使用 Terraform 建立的所有資源。

terraform destroy 指令會終止Terraform 狀態中指定的所有資源。不會刪除目前 Terraform 專案未管理的資源。您的 Terraform 設定檔不會遭到毀損。詳情請參閱「摧毀基礎架構」。
```
terraform destroy
```

後續步驟

What is Terraform? (什麼是 Terraform？)
查看 Cloud Scheduler 記錄