ジョブのサンドボックスを構成する

Cloud Run サンドボックスは、エージェント コードの実行、データ変換の実行、既存のジョブ内でのスクリプトの安全な実行を行うための、高速で安全な分離された環境を提供します。サンドボックスはレイテンシを考慮して高度に最適化されており、コンテナと同じインスタンス内で実行され、割り当てられた CPU とメモリを共有します。

このページでは、コンテナでサンドボックスを構成する方法について説明します。CLI を使用してサンドボックスを操作するコードの作成方法については、Cloud Run でのコード実行をご覧ください。

始める前に

  1. Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、アカウントを作成して、実際のシナリオで Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。
  2. 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

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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

  5. Verify that billing is enabled for your Google Cloud project.

  6. gcloud CLI をインストールして初期化します。
  7. Cloud Run ジョブを作成します。

必要なロール

Cloud Run ジョブの構成に必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

Cloud Run に関連付けられている IAM ロールと権限のリストについては、Cloud Run IAM ロールと Cloud Run IAM 権限をご覧ください。Cloud Run ジョブがGoogle Cloud API(Cloud クライアント ライブラリなど)と連携している場合は、サービス ID の構成ガイドをご覧ください。ロールの付与の詳細については、デプロイ権限とアクセスの管理をご覧ください。

サンドボックスを有効にする

Cloud Run ジョブでサンドボックスを有効にするには、Google Cloud CLI、YAML 構成、または Terraform を使用します。

gcloud

ジョブを作成または更新するには、--sandbox-launcher フラグを指定します。

  • ジョブを作成するには、次のコマンドを実行します。

    gcloud beta run jobs create JOB --image IMAGE_URL --sandbox-launcher

    次のように置き換えます。

    • JOB: Cloud Run ジョブの名前。
    • IMAGE_URL: コンテナ イメージへの参照(us-docker.pkg.dev/cloudrun/container/job:latest など)。
  • 既存のジョブを更新するには、次のコマンドを実行します。

    gcloud beta run jobs update JOB --sandbox-launcher

YAML

  1. 新しいジョブを作成する場合は、この手順をスキップします。既存のジョブを更新する場合は、その YAML 構成をダウンロードします。

    gcloud run jobs describe JOB --format export > job.yaml
  2. コンテナ構成内で sandboxLauncher 属性が true に設定されるように YAML ファイルを更新します。

    apiVersion: run.googleapis.com/v1
    kind: Job
    metadata:
      name: JOB
      annotations:
        run.googleapis.com/launch-stage: BETA
    spec:
      template:
        spec:
          template:
            spec:
              containers:
              - name: CONTAINER
                image: IMAGE_URL
                sandboxLauncher: true
    

    次のように置き換えます。

    • JOB: Cloud Run ジョブの名前。
    • CONTAINER: コンテナの名前。
    • IMAGE_URL: コンテナ イメージへの参照(us-docker.pkg.dev/cloudrun/container/job:latest など)。
  3. 次のコマンドを使用して、ジョブを作成または更新します。

    gcloud run jobs replace job.yaml

    gcloud run jobs replace コマンドは、job.yaml ファイルが存在する場合、デフォルトでこのファイルを使用します。

Terraform

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。

Terraform 構成の google_cloud_run_v2_job リソースに次の内容を追加します。
resource "google_cloud_run_v2_job" "default" {
  name     = "JOB"
  location = "REGION"

  template {
    template {
      containers {
        image            = "IMAGE_URL"
        sandbox_launcher = true
      }
    }
  }
}

次のように置き換えます。

  • JOB: Cloud Run ジョブの名前。
  • REGION: Google Cloud のリージョン。例: europe-west1
  • IMAGE_URL: コンテナ イメージへの参照(us-docker.pkg.dev/cloudrun/container/job:latest など)。

サンドボックスは、ホストコンテナに割り当てられた CPU とメモリを共有します。メインコンテナの CPU とメモリの上限が、アプリケーションと同時に実行するアクティブなサンドボックスの両方に対応できることを確認してください。

サンドボックスを無効にする

ジョブでサンドボックスを起動する機能を無効にするには、Google Cloud CLI または YAML 構成を使用します。

gcloud

次のコマンドを実行して、--no-sandbox-launcher フラグを使用してジョブを更新します。

gcloud beta run jobs update JOB --no-sandbox-launcher

JOB は、使用するジョブの名前に置き換えます。

YAML

  1. 新しいジョブを作成する場合は、この手順をスキップします。既存のジョブを更新する場合は、その YAML 構成をダウンロードします。

    gcloud run jobs describe JOB --format export > job.yaml
  2. YAML ファイルを更新して、コンテナ構成内の sandboxLauncher 属性を削除します。

    apiVersion: run.googleapis.com/v1
    kind: Job
    metadata:
      name: JOB
    spec:
      template:
        spec:
          template:
            spec:
              containers:
              - name: CONTAINER
                image: IMAGE_URL
    

    次のように置き換えます。

    • JOB: Cloud Run ジョブの名前。
    • CONTAINER: コンテナの名前。
    • IMAGE_URL: コンテナ イメージへの参照(us-docker.pkg.dev/cloudrun/container/job:latest など)。
  3. 次のコマンドを使用して、ジョブを作成または更新します。

    gcloud run jobs replace job.yaml

    gcloud run jobs replace コマンドは、job.yaml ファイルが存在する場合、デフォルトでこのファイルを使用します。

サンドボックスの設定を表示する

Cloud Run ジョブの現在のサンドボックス設定を表示するには:

コンソール

  1. Google Cloud コンソールで、Cloud Run の [ジョブ] ページに移動します。

    Cloud Run の [ジョブ] に移動

  2. ジョブをクリックして、[ジョブの詳細] ページを開きます。

  3. [履歴] タブで、実行されたジョブの ID をリストからクリックします。

  4. [コンテナ] タブで、[サンドボックス ランチャー] の設定を見つけて、サンドボックス化されたコンテナが有効か無効かを確認します。

gcloud

  1. 次のコマンドを使用します。

    gcloud run jobs executions describe EXECUTION_NAME --format yaml

    EXECUTION_NAME は、ジョブ実行の名前に置き換えます。

  2. サンドボックス化されたコンテナが有効になっていることを確認するには、返された構成で sandboxLauncher: true 属性を見つけます。

ジョブからサンドボックスで信頼できないコードを実行するには、Cloud Run でのコード実行をご覧ください。

サンドボックス テンプレートを構成する

サンドボックス テンプレートを使用すると、サンドボックスのコンテナ イメージを定義できます。sandbox do --template コマンドと sandbox run --template コマンドは、メインのアプリケーション コンテナ内でサンドボックス セッションを実行するのではなく、指定されたイメージ(Python、Node.js、カスタム実行環境など)を使用して新しいコンテナを起動します。これらのサンドボックスは独自のコンテナで実行され、メインコンテナの CPU とメモリの上限を共有します。テンプレートに CPU とメモリの上限を個別に設定することはできません。Cloud Run は、最大 10 個のサンドボックス テンプレートをサポートしています。ボリューム マウントは、Cloud Run リソースのインメモリ ボリュームを参照する必要があります。サンドボックス テンプレートには次の機能があります。

  • 専用コンテナ イメージ: python:3.12-slim や busybox:latest などの個別のコンテナ イメージをサンドボックス テンプレートとして宣言します。メインコンテナで必要のないサンドボックスに、他のランタイムやツールを使用することもできます。これにより、サンドボックス化にのみ使用されるツールとランタイムが分離され、メインコンテナを軽量に保つことができます。

  • オンデマンド インスタンス化: サンドボックス CLI(/usr/local/gcp/bin/sandbox)は、新しい VM をプロビジョニングしたり、新しいインスタンスに課金したりすることなく、テンプレートから新しいサンドボックス コンテナを生成します。

  • サンドボックスごとの分離されたファイル共有: メインコンテナと複数のサンドボックス間でインメモリ ボリュームを共有しながら、各サンドボックスを独自の分離されたサブディレクトリに制限して、サンドボックスが他のファイルを表示または変更できないようにします。

サンドボックス テンプレートは、YAML 構成または Cloud Run Admin API を使用して構成できます。

YAML

  1. 新しいジョブを作成する場合は、この手順をスキップします。既存のジョブを更新する場合は、その YAML 構成をダウンロードします。

    gcloud run jobs describe JOB --format export > job.yaml
  2. sandboxes テンプレート構成が含まれるようにジョブ YAML ファイルを更新します。

    apiVersion: run.googleapis.com/v1
    kind: Job
    metadata:
      name: JOB
      annotations:
        run.googleapis.com/launch-stage: BETA
    spec:
      template:
        spec:
          template:
            spec:
              containers:
              - image: IMAGE_URL
                sandboxLauncher: true
                volumeMounts:
                - name: VOLUME_NAME
                  mountPath: CONTAINER_MOUNT_PATH
              volumes:
              - name: VOLUME_NAME
                emptyDir:
                  medium: Memory
              sandboxes:
                templates:
                - name: TEMPLATE_NAME
                  image: TEMPLATE_IMAGE_URL
                  volumeMounts:
                  - name: VOLUME_NAME
                    mountPath: SANDBOX_MOUNT_PATH
                    subPath: SUBPATH
    

    次のように置き換えます。

    • JOB: Cloud Run ジョブの名前。

    • IMAGE_URL: メインコンテナに使用するコンテナ イメージの URL。
    • TEMPLATE_NAME: テンプレートの名前。
    • TEMPLATE_IMAGE_URL: サンドボックス テンプレートに使用するコンテナ イメージの URL。
    • 省略可: VOLUME_NAME: マウントするボリュームの名前。
    • 省略可: CONTAINER_MOUNT_PATH: メインコンテナ内でボリュームがマウントされるパス。
    • 省略可: SANDBOX_MOUNT_PATH: ボリュームがサンドボックス コンテナ内にマウントされるパス。
    • 省略可: SUBPATH: サンドボックス コンテナにマウントするボリューム内の相対サブディレクトリ パス(my-subdir など)。実行時にサンドボックスごとに異なるサブディレクトリを設定するには、$(SANDBOX_DIR) などの $(VARIABLE_NAME) プレースホルダを使用します。
      • VARIABLE_NAME には ASCII 文字とアンダースコアのみを使用できます。数字とハイフンはサポートされていません。
      • 実行時にプレースホルダを解決するには、--template とともに --template-var=VARIABLE_NAME=VALUE フラグを渡します。
      • subPath はディレクトリを自動的に作成しません。sandbox do または sandbox run を実行する前に、メインコンテナからボリュームに解決済みの SUBPATH ディレクトリを作成します(mkdir -p を使用するなど)。
  3. 次のコマンドを使用して、ジョブを作成または更新します。

    gcloud run jobs replace job.yaml

    gcloud run jobs replace コマンドは、job.yaml ファイルが存在する場合、デフォルトでこのファイルを使用します。

REST API

サンドボックス テンプレートを構成するには、Cloud Run Admin API に PATCH リクエストを送信します。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-X PATCH \
"https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB" \
-d '{
  "launchStage": "BETA",
  "template": {
    "template": {
      "containers": [
        {
          "image": "IMAGE_URL",
          "sandboxLauncher": true,
          "volumeMounts": [
            {
              "name": "VOLUME_NAME",
              "mountPath": "CONTAINER_MOUNT_PATH"
            }
          ]
        }
      ],
      "sandboxes": {
        "templates": [
          {
            "name": "TEMPLATE_NAME",
            "image": "TEMPLATE_IMAGE_URL",
            "volumeMounts": [
              {
                "name": "VOLUME_NAME",
                "mountPath": "SANDBOX_MOUNT_PATH",
                "subPath": "SUBPATH"
              }
            ]
          }
        ]
      },
      "volumes": [
        {
          "name": "VOLUME_NAME",
          "emptyDir": {
            "medium": "MEMORY"
          }
        }
      ]
    }
  }
}'

次のように置き換えます。

  • JOB: Cloud Run ジョブの名前。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • REGION: Cloud Run リソースがデプロイされているリージョン。
  • IMAGE_URL: メインコンテナに使用するコンテナ イメージの URL。
  • TEMPLATE_NAME: テンプレートの名前。
  • TEMPLATE_IMAGE_URL: サンドボックス テンプレートに使用するコンテナ イメージの URL。
  • 省略可: VOLUME_NAME: マウントするボリュームの名前。
  • 省略可: CONTAINER_MOUNT_PATH: メインコンテナ内でボリュームがマウントされるパス。
  • 省略可: SANDBOX_MOUNT_PATH: ボリュームがサンドボックス コンテナ内にマウントされるパス。
  • 省略可: SUBPATH: サンドボックス コンテナにマウントするボリューム内の相対サブディレクトリ パス(my-subdir など)。実行時にサンドボックスごとに異なるサブディレクトリを設定するには、$(SANDBOX_DIR) などの $(VARIABLE_NAME) プレースホルダを使用します。
    • VARIABLE_NAME には ASCII 文字とアンダースコアのみを使用できます。数字とハイフンはサポートされていません。
    • 実行時にプレースホルダを解決するには、--template とともに --template-var=VARIABLE_NAME=VALUE フラグを渡します。
    • subPath はディレクトリを自動的に作成しません。sandbox do または sandbox run を実行する前に、メインコンテナからボリュームに解決済みの SUBPATH ディレクトリを作成します(mkdir -p を使用するなど)。

ジョブコンテナ内から CLI を使用してテンプレートを実行するには、サンドボックス テンプレートを使用してコマンドを実行するをご覧ください。