使用 Terraform 和 Cloud Scheduler 创建和运行批处理作业

本教程介绍了如何使用 Terraform 通过 Cloud Scheduler Cron 作业创建和运行 Batch 作业。

Terraform 是一种开源工具，可让您通过在配置文件中指定所需状态来预配和管理基础架构。这些文件可以视为代码，并存储在 GitHub 等版本控制系统中。

虽然 Terraform 没有 Batch 的资源，但本教程展示了如何使用 Terraform 创建 Batch 作业。具体来说，您可以使用 Terraform 安排和运行 Cloud Scheduler cron 作业，该作业以 Batch API 为目标来创建和运行 Batch 作业。Cloud Scheduler 是一项 Google Cloud 服务，可让您自动调度 cron 作业，并支持 Terraform。

本教程面向已使用 Terraform 管理基础架构并希望将 Batch 作业纳入 Terraform 的 Batch 用户。

目标

• 创建一个 Terraform 目录和一个配置文件，用于定义一个 Cloud Scheduler cron 作业，该作业会创建 Batch 作业。
• 部署 Terraform 配置以运行 cron 作业。
• 验证 cron 作业是否创建了 Batch 作业。
• 更新 Terraform 配置以暂停 Cron 作业，使其停止创建 Batch 作业。

费用

在本文档中，您将使用 Google Cloud的以下收费组件：

• Batch
• Cloud Scheduler

如需根据您的预计使用情况来估算费用，请使用价格计算器。

新 Google Cloud 用户可能有资格申请免费试用。

完成本文档中描述的任务后，您可以通过删除所创建的资源来避免继续计费。如需了解详情，请参阅清理。

准备工作

1. 准备开发环境（Cloud Shell 或本地 shell）：

   Cloud Shell

   如需使用已设置 gcloud CLI 和 Terraform 的在线终端，请激活 Cloud Shell。

   Cloud Shell 会话会在页面底部启动，并显示命令行提示符。该会话可能需要几秒钟来完成初始化。

   本地 shell

   如需使用本地开发环境，请按照以下步骤操作：

   1. 安装 Google Cloud CLI。

   2. 配置 gcloud CLI 以使用您的联合身份。

      如需了解详情，请参阅使用联合身份登录 gcloud CLI。

   3. 如需初始化 gcloud CLI，请运行以下命令：

      gcloud init

   4. 安装 Terraform。

2. 创建或选择 Google Cloud 项目。

   选择或创建项目所需的角色

   • 选择项目：选择项目不需要特定的 IAM 角色，您可以选择已获授角色的任何项目。
   • 创建项目：如需创建项目，您需要拥有 Project Creator 角色 (roles/resourcemanager.projectCreator)，该角色包含 resourcemanager.projects.create 权限。了解如何授予角色。
   注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

   • 创建 Google Cloud 项目：

     gcloud projects create PROJECT_ID

     将 PROJECT_ID 替换为您要创建的 Google Cloud 项目的名称。

   • 选择您创建的 Google Cloud 项目：

     gcloud config set project PROJECT_ID

     将 PROJECT_ID 替换为您的 Google Cloud 项目名称。

3. 验证是否已为您的 Google Cloud 项目启用结算功能。

4. 启用 Batch、Compute Engine、Cloud Logging、Cloud Scheduler 和 Resource Manager API：

   启用 API 所需的角色

   如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

   gcloud services enable batch.googleapis.com compute.googleapis.com logging.googleapis.com cloudscheduler.googleapis.com cloudresourcemanager.googleapis.com

5. 确保您的项目至少有一个服务账号，且该账号具有本教程所需的权限。

   注意：如果您使用的是新项目，则无需执行此步骤，除非您的组织禁止为默认服务账号自动授予角色。 默认情况下，系统会自动向 Compute Engine 默认服务账号授予 Editor (roles/editor) IAM 角色，该角色已具备本教程所需的所有权限。

   具体来说，您可以使用同一服务账号或两个单独的服务账号来授予以下权限：

   • 允许 cron 作业创建 Batch 作业并附加 Batch 作业的服务账号。
   • 允许 Batch 作业创建和访问运行所需的资源。

   如需确保本教程的服务账号具有使用 Terraform 通过 Cloud Scheduler cron 作业创建 Batch 作业所需的权限，请让您的管理员为本教程的服务账号授予以下 IAM 角色：

   重要提示：您必须向本教程的服务账号（而不是向您的用户账号）授予这些角色。如果未能向正确的主账号授予这些角色，可能会导致权限错误。
   • Cloud Scheduler cron 作业的服务账号：
     • 项目的 Batch Job Editor (roles/batch.jobsEditor)
     • Service Account User (roles/iam.serviceAccountUser) 在批处理作业的服务账号上（即使是其本身）
   • 批处理作业的服务账号：
     • 项目的 Batch Agent Reporter (roles/batch.agentReporter)
     • 项目的 Logs Writer (roles/logging.logWriter)

   如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

   您的管理员还可以通过自定义角色或其他预定义角色向本教程的服务账号授予所需的权限。

6. 确保您拥有本教程所需的权限。

   注意：如果您创建了此项目，则无需执行此步骤。 作为项目创建者，您会自动获得 Owner (roles/owner) IAM 角色，该角色已拥有本教程所需的所有权限。

   具体而言，您需要拥有以下权限：

   • 创建 Cron 作业并关联该 Cron 作业的服务账号。
   • 查看和删除 cron 作业和批处理作业。

   如需获得使用 Terraform 通过 Cloud Scheduler cron 作业创建 Batch 作业所需的权限，请让您的管理员为您授予以下 IAM 角色：

   • Cloud Scheduler cron 作业的服务账号的 Service Account User (roles/iam.serviceAccountUser)
   • 项目的 Cloud Scheduler Admin (roles/cloudscheduler.admin)
   • 项目的 Batch Job Editor (roles/batch.jobsEditor)
   • 项目的 Logs Viewer (roles/logging.viewer) 角色

创建 Terraform 目录和配置文件

为 Terraform 创建一个目录，并创建一个配置文件，用于定义您要使用 Terraform 创建或更新的资源。本教程的示例配置文件定义了一个名为 batch-job-invoker 的 Cloud Scheduler cron 作业。启用后，batch-job-invoker Cron 作业每 5 分钟运行一次，以创建定义的批量作业的新实例。

1. 如需创建目录并在该目录中创建新的 Terraform 配置 (.tf) 文件，请输入以下命令，然后按 Enter：

   mkdir terraform && cd terraform && cat > main.tf
   

   此命令会创建 terraform 目录，将您导航到该目录，并在下一行开始定义新的 main.tf 配置文件。

2. 复制并粘贴以下 Terraform 配置：

   # define variables
   variable "project_id" {
     type        = string
     description = "The project name to use."
     default = "PROJECT_ID"
   }
   
   variable "project_number" {
     type        = string
     description = "The project number to use."
     default = "PROJECT_NUMBER"
   }
   
   variable "region" {
     type        = string
     description = "The region where resources are created."
     default = "us-central1"
   }
   
   variable "cloud_scheduler_service_account_email" {
     type        = string
     description = "The service account email."
     default = "CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL"
   }
   
   variable "batch_service_account_email" {
     type        = string
     description = "The service account email."
     default = "BATCH_SERVICE_ACCOUNT_EMAIL"
   }
   
   # define a Cloud Scheduler cron job which triggers Batch jobs
   resource "google_cloud_scheduler_job" "batch-job-invoker" {
     paused           = false # this cron job is enabled
     name             = "batch-job-invoker"
     project          = var.project_id
     region           = var.region
     schedule         = "*/5 * * * *" # when enabled, run every 5 minutes
     time_zone        = "America/Los_Angeles"
     attempt_deadline = "180s"
   
     retry_config {
       max_doublings        = 5
       max_retry_duration   = "0s"
       max_backoff_duration = "3600s"
       min_backoff_duration = "5s"
     }
   
     # when this cron job runs, create and run a Batch job
     http_target {
       http_method = "POST"
       uri = "https://batch.googleapis.com/v1/projects/${var.project_id}/locations/${var.region}/jobs"
       headers = {
         "Content-Type" = "application/json"
         "User-Agent"   = "Google-Cloud-Scheduler"
       }
       # Batch job definition
       body = base64encode(<<EOT
       {
         "taskGroups":[
           {
             "taskSpec": {
               "runnables":{
                 "script": {
                   "text": "echo Hello world! This job was created using Terraform and Cloud Scheduler."
                 }
               }
             }
           }
         ],
         "allocationPolicy": {
           "serviceAccount": {
             "email": "${var.batch_service_account_email}"
           }
         },
         "labels": {
           "source": "terraform_and_cloud_scheduler_tutorial"
         },
         "logsPolicy": {
           "destination": "CLOUD_LOGGING"
         }
       }
       EOT
       )
       oauth_token {
         scope                 = "https://www.googleapis.com/auth/cloud-platform"
         service_account_email = var.cloud_scheduler_service_account_email
       }
     }
   }
   
   

   替换以下内容：

   • PROJECT_ID：您的项目的项目 ID。
   • PROJECT_NUMBER：您的项目的项目编号。

   • CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL：您为 Cloud Scheduler cron 作业准备的服务账号的电子邮件地址。

     例如，如需使用 Compute Engine 默认服务账号，请指定以下内容：

     PROJECT_NUMBER-compute@
     

   • BATCH_SERVICE_ACCOUNT_EMAIL：您为 Batch 作业准备的服务账号的电子邮件地址。

     例如，如需使用 Compute Engine 默认服务账号，请指定以下内容：

     PROJECT_NUMBER-compute@
     

   此 Terraform 配置定义了一些输入变量和一个用于调用 API 方法以创建批量作业的 Cron 作业。

   目标：如果您想详细了解如何定义此 Terraform 配置以及如何编写自己的配置，请参阅以下页面：

   • 如需详细了解用于定义变量的字段，请参阅 Terraform 输入变量的相关文档。
   • 如需详细了解用于定义 Cron 作业的字段，请参阅 google_cloud_scheduler_job Terraform 资源的相关文档。
   • 如需详细了解用于请求创建批量作业的字段，请参阅 jobs.create Batch API 方法的文档。

3. 如需保存并关闭文件，请按 Ctrl+D（在 macOS 上，按 Command+D）。

部署 Terraform 配置以创建 cron 作业

通过初始化 Terraform、生成计划更改并应用这些更改来部署 Terraform 配置。部署 Terraform 配置后，您可以描述项目中的资源，以验证 Terraform 是否已成功创建 batch-job-invoker cron 作业。

1. 在目录中初始化 Terraform：

   terraform init
   

   输出类似于以下内容：

   ...
   Terraform has been successfully initialized!
   
   You may now begin working with Terraform. Try running "terraform plan" to see
   any changes that are required for your infrastructure. All Terraform commands
   should now work.
   
   If you ever set or change modules or backend configuration for Terraform,
   rerun this command to reinitialize your working directory. If you forget, other
   commands will detect it and remind you to do so if necessary.
   

2. 基于项目的当前状态和配置文件生成 Terraform 执行计划：

   terraform plan
   

   输出类似于以下内容，其中显示了计划创建 batch-job-invoker cron 作业：

   Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
     + create
   
   Terraform will perform the following actions:
   
     # google_cloud_scheduler_job.batch-job-invoker will be created
     + resource "google_cloud_scheduler_job" "batch-job-invoker" {
         + id        = (known after apply)
         + name      = "batch-job-invoker"
         + paused    = false
         + project   = "PROJECT_ID"
         + region    = "us-central1"
         + schedule  = "*/5 * * * *"
         + state     = (known after apply)
         + time_zone = "America/Los_Angeles"
   
         + http_target {
             + body        = "..."
             + headers     = {
                 + "Content-Type" = "application/json"
                 + "User-Agent"   = "Google-Cloud-Scheduler"
               }
             + http_method = "POST"
             + uri         = "https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/jobs"
   
             + oauth_token {
                 + scope                 = "https://www.googleapis.com/auth/cloud-platform"
                 + service_account_email = "CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL"
               }
           }
   
         + retry_config {
             + max_backoff_duration = "3600s"
             + max_doublings        = 5
             + max_retry_duration   = "0s"
             + min_backoff_duration = "5s"
             + retry_count          = (known after apply)
           }
       }
   
   Plan: 1 to add, 0 to change, 0 to destroy.
   
   ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   
   Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform apply" now.
   

3. 如需应用该方案来创建 batch-job-invoker cron 作业，请按以下步骤操作：

   1. 输入以下命令：

      terraform apply
      

      输出与之前的 terraform plan 命令类似，只是结尾会显示确认提示。

   2. 如需确认并应用方案，请输入 yes。

      输出类似于以下内容：

      google_cloud_scheduler_job.batch-job-invoker: Creating...
      google_cloud_scheduler_job.batch-job-invoker: Creation complete after 0s [id=projects/PROJECT_ID/locations/us-central1/jobs/batch-job-invoker]
      
      Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
      

4. 如需验证 batch-job-invoker cron 作业是否存在并已启用，请对其进行说明：

   gcloud scheduler jobs describe batch-job-invoker --location us-central1
   

   输出类似于以下内容：

   attemptDeadline: 180s
   httpTarget:
     body: ...
     headers:
       Content-Type: application/json
       User-Agent: Google-Cloud-Scheduler
     httpMethod: POST
     oauthToken:
       scope: https://www.googleapis.com/auth/cloud-platform
       serviceAccountEmail: CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL
     uri: https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/jobs
   lastAttemptTime: '...'
   name: projects/PROJECT_ID/locations/us-central1/jobs/batch-job-invoker
   retryConfig:
     maxBackoffDuration: 3600s
     maxDoublings: 5
     maxRetryDuration: 0s
     minBackoffDuration: 5s
   schedule: '*/5 * * * *'
   scheduleTime: '...'
   state: ENABLED
   status: {}
   timeZone: America/Los_Angeles
   userUpdateTime: '...'
   

   在输出中，验证 state 字段是否已设置为 ENABLED。

验证 Cron 作业是否创建了批量作业

验证 batch-job-invoker cron 作业是否正确创建了批处理作业。

1. 您可以等待 5 分钟，让 cron 作业自动运行，也可以触发 cron 作业立即运行：

   gcloud scheduler jobs run batch-job-invoker --location us-central1
   

2. 列出由 batch-job-invoker cron 作业创建的 Batch 作业：

   gcloud batch jobs list \
   --filter labels.source=\"terraform_and_cloud_scheduler_tutorial\" \
   --sort-by ~createTime
   

   • --filter labels.source=\"terraform_and_cloud_scheduler_tutorial\" 标志会过滤列表，使其仅包含具有键为 source 且值为 terraform_and_cloud_scheduler_tutorial 的标签的 Batch 作业。
   • --sort-by ~createTime 标志可按从新到旧的顺序对列表进行排序。

更新 Terraform 配置以暂停 Cron 作业

在获得所需数量的 Batch 作业后，更新并部署 Terraform 配置以暂停 batch-job-invoker cron 作业。如果您想更新 cron 作业或未来批处理作业的其他属性，也可以使用此流程。

注意： 对于周期性工作负载，如果您想继续自动创建 Batch 作业，则无需暂停 Cloud Scheduler cron 作业。例如，您可以配置 Cron 作业时间表，以在每个月的第一天运行批量作业。

1. 更新 Terraform 配置文件，将 paused 字段设置为 true，以暂停 cron 作业：

   sed -i 's/paused           = false # this cron job is enabled/paused           = true # this cron job is paused/g' main.tf
   

2. 基于项目的当前状态和配置文件生成 Terraform 执行计划：

   terraform plan
   

   输出类似于以下内容，其中显示了将 paused 字段的值从 false 更新为 true 的计划：

   google_cloud_scheduler_job.batch-job-invoker: Refreshing state... [id=projects/PROJECT_ID/locations/us-central1/jobs/batch-job-invoker]
   
   Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
     ~ update in-place
   
   Terraform will perform the following actions:
   
     # google_cloud_scheduler_job.batch-job-invoker will be updated in-place
     ~ resource "google_cloud_scheduler_job" "batch-job-invoker" {
           id               = "projects/PROJECT_ID/locations/us-central1/jobs/batch-job-invoker"
           name             = "batch-job-invoker"
         ~ paused           = false -> true
           # (6 unchanged attributes hidden)
   
         ~ http_target {
             ~ headers     = {
                 + "User-Agent"   = "Google-Cloud-Scheduler"
                   # (1 unchanged element hidden)
               }
               # (3 unchanged attributes hidden)
   
               # (1 unchanged block hidden)
           }
   
           # (1 unchanged block hidden)
       }
   
   Plan: 0 to add, 1 to change, 0 to destroy.
   
   ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   
   Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform apply" now.
   

3. 如需应用该方案来更新 batch-job-invoker cron 作业，请按以下步骤操作：

   1. 输入以下命令：

      terraform apply
      

      输出与之前的 terraform plan 命令类似，只是结尾会显示确认提示。

   2. 如需确认并应用方案，请输入 yes。

      输出类似于以下内容：

      google_cloud_scheduler_job.batch-job-invoker: Modifying... [id=projects/PROJECT_ID/locations/us-central1/jobs/batch-job-invoker]
      google_cloud_scheduler_job.batch-job-invoker: Modifications complete after 1s [id=projects/PROJECT_ID/locations/us-central1/jobs/batch-job-invoker]
      
      Apply complete! Resources: 0 added, 1 changed, 0 destroyed.
      

4. 如需验证 batch-job-invoker cron 作业是否已暂停，请描述该作业：

   gcloud scheduler jobs describe batch-job-invoker --location us-central1
   

   输出类似于以下内容：

   attemptDeadline: 180s
   httpTarget:
     body: ...
     headers:
       Content-Type: application/json
       User-Agent: Google-Cloud-Scheduler
     httpMethod: POST
     oauthToken:
       scope: https://www.googleapis.com/auth/cloud-platform
       serviceAccountEmail: CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL
     uri: https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/jobs
   lastAttemptTime: '...'
   name: projects/PROJECT_ID/locations/us-central1/jobs/batch-job-invoker
   retryConfig:
     maxBackoffDuration: 3600s
     maxDoublings: 5
     maxRetryDuration: 0s
     minBackoffDuration: 5s
   schedule: '*/5 * * * *'
   scheduleTime: '...'
   state: PAUSED
   status: {}
   timeZone: America/Los_Angeles
   userUpdateTime: '...'
   

   在输出中，验证 state 字段是否已设置为 PAUSED。

清理

为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用，请删除包含这些资源的项目，或者保留项目但删除各个资源。

删除项目

1. 注意：删除项目会产生以下影响：

   • 项目中的所有内容都会被删除。如果您将现有项目用于本文档中的任务，则删除该项目后，还将删除您已在该项目中完成的任何其他工作。
   • 自定义项目 ID 丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。要保留使用该项目 ID 的网址（例如 appspot.com 网址），请删除项目内的所选资源，而不是删除整个项目。

   如果您打算探索多个架构、教程或快速入门，则重复使用项目可以帮助您避免超出项目配额限制。

   删除 Google Cloud 项目：

   gcloud projects delete PROJECT_ID

2. 前往父目录，然后删除 Terraform 目录及其所有文件。

   cd .. && rm -r terraform
   

删除各个资源

1. 删除 batch-job-invoker cron 作业。

   注意： 在本教程中，最简单的方法是使用以下 terraform destroy 命令，该命令会删除 Terraform 配置文件管理的所有资源。不过，如果 Terraform 配置文件中包含您不想删除的其他资源，请改为更新 Terraform 配置。

   terraform destroy
   

2. 如需删除本教程中的所有 Batch 作业，请按以下步骤操作：

   1. 列出由 batch-job-invoker cron 作业创建的所有 Batch 作业：

      gcloud batch jobs list \
      --filter labels.source=\"terraform_and_cloud_scheduler_tutorial\" \
      --sort-by ~createTime
      

      记录需要删除的每个作业的名称。

   2. 删除本教程中的批量作业：

      gcloud batch jobs delete JOB_NAME --location us-central1
      

      将 JOB_NAME 替换为批量作业的名称。

      针对所有 Batch 作业重复此步骤。

3. 如果您为此教程创建了服务账号，请删除该服务账号：

   gcloud iam service-accounts delete SERVICE_ACCOUNT_EMAIL
   

   将 SERVICE_ACCOUNT_EMAIL 替换为您为此教程创建的服务账号的电子邮件地址。具体而言，您使用了以下服务账号：

   • CLOUD_SCHEDULER_SERVICE_ACCOUNT_EMAIL：Cloud Scheduler 的服务账号。
   • BATCH_SERVICE_ACCOUNT_EMAIL：Batch 的服务账号。

   如果您创建了两个单独的服务账号，请重复此步骤。

4. 前往父目录，然后删除 Terraform 目录及其所有文件。

   cd .. && rm -r terraform
   

后续步骤

• 详细了解如何将 Terraform 与 Google Cloud搭配使用：
  • Google Cloud的 Terraform 文档
  • Google Cloud 的 Terraform 文档
• 详细了解 Cloud Scheduler Cron 作业。
• 详细了解批处理作业。