コネクタを使用して Kubernetes API オブジェクトにアクセスする

Google Kubernetes Engine（GKE）クラスタは、コントロールプレーンと、ノードと呼ばれるワーカーマシンで構成されます。コンテナ化された Kubernetes ワークロードは GKE クラスタで実行できます。ノードは、コンテナ化されたアプリケーションや他のワークロードを実行するワーカーマシンです。コントロールプレーンはクラスタの統合エンドポイントです。詳細については、GKE クラスタアーキテクチャをご覧ください。

Kubernetes API サーバーはコントロールプレーンで実行され、Kubernetes API 呼び出しを介してクラスタ内の Kubernetes オブジェクトを操作できます。オブジェクトは Kubernetes システム内の永続的なエンティティであり、クラスタの状態を表します。詳細については、Kubernetes のドキュメントで、Kubernetes のオブジェクトと、「Kubernetes API リファレンス」ページにリンクされている API の概要をご覧ください。

このドキュメントでは、ワークフローで Kubernetes API コネクタを使用して、GKE クラスタのコントロールプレーンでホストされている Kubernetes サービスエンドポイントにリクエストを送信する方法について説明します。たとえば、コネクタを使用して Kubernetes Deployment の作成、Job の実行、Pod の管理、またはプロキシ経由でデプロイされたアプリへのアクセスを行うことができます。詳細については、Kubernetes API コネクタの概要をご覧ください。

始める前に

このドキュメントのタスクに進む前に、特定の前提条件を満たしていることを確認してください。

API を有効にする

Kubernetes API コネクタを使用して Kubernetes API オブジェクトにアクセスする前に、次の API を有効にする必要があります。

Google Kubernetes Engine API: GKE を使用してコンテナベースのアプリケーションを構築および管理します。
Workflows API: ワークフローの定義と実行を管理します。Workflows API を有効にすると、Workflow Executions API が自動的に有効になります。

コンソール

API を有効にします。

API を有効にする

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

API を有効にします。

gcloud services enable container.googleapis.com workflows.googleapis.com

サービスアカウントを作成する

ワークフローの ID として機能するサービスアカウントを作成し、Kubernetes Engine 開発者（roles/container.developer）のロールを付与し、ワークフローがクラスタ内から Kubernetes API オブジェクトにアクセスできるようにします。

コンソール

Google Cloud コンソールで、[サービスアカウント] ページに移動します。

[サービスアカウント] に移動
プロジェクトを選択し、[サービスアカウントを作成] をクリックします。
[サービスアカウント名] フィールドに名前を入力します。Google Cloud コンソールでは、この名前に基づいて [サービスアカウント ID] フィールドに値が設定されます。

[サービスアカウントの説明] フィールドに説明を入力します。例: Service account for Kubernetes API
[作成して続行] をクリックします。
[ロールを選択] リストで、[Kubernetes Engine 開発者] のロールをフィルタして選択します。
[続行] をクリックします。
アカウントの作成を完了するには、[完了] をクリックします。

gcloud

サービスアカウントを作成します。
```
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
```
SERVICE_ACCOUNT_NAME は、サービスアカウントの名前に置き換えます。

サービスアカウントに container.developer ロールを付与します。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/container.developer

PROJECT_ID は、実際の Google Cloud プロジェクト ID に置き換えます。

GKE クラスタへのアクセス制御には、IAM と Kubernetes のロールベースアクセス制御（RBAC）の両方を使用できます。

IAM は Kubernetes 固有のものではなく、複数の Google Cloud プロダクトの ID 管理を行います。基本的に、Google Cloud プロジェクトのレベルで機能します。
Kubernetes RBAC は Kubernetes のコアコンポーネントです。これにより、ロール（権限のセット）を作成してクラスタ内のオブジェクトやオブジェクトタイプに付与できます。主に GKE を使用していて、クラスタ内のすべてのオブジェクトとオペレーションに対してきめ細かいアクセス許可が必要な場合は、Kubernetes RBAC が最善の選択です。

詳しくは、アクセス制御をご覧ください。

GKE クラスタを作成する

Kubernetes API コネクタを使用するには、一般公開または限定公開 GKE クラスタをすでに作成している必要があります。限定公開クラスタでは、ノードに内部 IP アドレスのみがあるため、ノードと Pod がデフォルトでインターネットから隔離されています。詳細については、限定公開クラスタをご覧ください。

オペレーションモードを指定することもできます。これにより、さまざまなレベルの柔軟性、責任範囲、制御を設定できます。たとえば、ノード、スケーリング、セキュリティ、その他の事前構成された設定など、クラスタ構成を Google が管理する GKE でのオペレーションモードである Autopilot クラスタを作成できます。詳細については、GKE のオペレーションモードを選択するをご覧ください。

GKE クラスタをまだ作成していない場合は、GKE クラスタにウェブサーバーコンテナ化アプリケーションをデプロイできます。また、このドキュメントの手順を行うには、以下のステップに沿って Autopilot クラスタを作成します。

Console

Google Cloud コンソールで、[Kubernetes クラスタ] ページに移動します。

Kubernetes クラスタに移動
[ 作成] をクリックします。
クラスタモードを選択するように求められたら、[Autopilot] を選択します。
[クラスタの基本] セクションで、次の操作を行います。
1. クラスタの名前（hello-cluster など）を入力します。
2. クラスタのリージョン（us-central1 など）を選択します。
[次へ: ネットワーキング] をクリックします。
[IPv4 ネットワークアクセス] セクションで、一般公開されているエンドポイントを含むクラスタを作成するために [一般公開クラスタ] を選択します。
その他の設定はすべてデフォルトのままにします。
[作成] をクリックします。

クラスタの作成が完了するまでに数分かかることがあります。クラスタが作成されると、チェックマークでクラスタが実行中であることが示されます。

gcloud

次のコマンドを実行します。

gcloud container clusters create-auto CLUSTER_NAME \
    --location=LOCATION \
    --project=PROJECT_ID

以下を置き換えます。

CLUSTER_NAME: GKE クラスタの名前（hello-cluster など）。
LOCATION: クラスタのリージョン（us-central1 など）。
PROJECT_ID: 実際の Google Cloud プロジェクト ID

クラスタの作成が完了するまでに数分かかることがあります。クラスタの作成が完了すると、出力は次のようになります。

Creating cluster hello-cluster...done.
Created [https://container.googleapis.com/v1/projects/MY_PROJECT/zones/us-central1/clusters/hello-cluster].
[...]
STATUS: RUNNING

コネクタを使用して HTTP リクエストを送信する

Kubernetes API コネクタを使用すると、HTTP リクエストを GKE クラスタのコントロールプレーンに送信できます。たとえば、次のワークフローでは、指定された Kubernetes クラスタに nginx-deployment という名前の Deployment を作成します。Deployment が必要な状態を記述します。この場合、nginx:1.14.2 イメージを使用して 3 つの Pod を実行し、その Service をポート 80 で公開します。（指定されていない場合、project と location はデフォルトでワークフローの値になります。）

詳細については、Kubernetes API コネクタ関数 gke.request のリファレンスページをご覧ください。

次の点にご注意ください。

path フィールドは、Kubernetes API メソッドパスに対応しています。詳細については、Kubernetes のドキュメントで、API の概要をご覧ください。このページには、[Kubernetes API リファレンス] ページへのリンクがあります。
ワークフローで HTTP リクエストのエラーを検出して処理できます。詳細については、ワークフローのエラーをご覧ください。

ワークフローをデプロイする

ワークフローを実行する前に、ワークフローを作成してデプロイする必要があります。

Console

Google Cloud コンソールの [ワークフロー] ページに移動します。

[ワークフロー] に移動
[ 作成] をクリックします。
新しいワークフローの名前を入力します（例: kubernetes-api-request）。
[リージョン] リストで [us-central1] を選択します。
先ほど作成したサービスアカウントを選択します。
[次へ] をクリックします。

ワークフローエディタで、次のワークフローの定義を入力します。

YAML

main:
  steps:
    - create_deployment:
        call: gke.request
        args:
          cluster_id: "CLUSTER_NAME"
          project: "PROJECT_ID"
          location: "LOCATION"
          method: "POST"
          path: "/apis/apps/v1/namespaces/default/deployments"
          body:
            kind: Deployment
            metadata:
              name: nginx-deployment
              labels:
                app: nginx
            spec:
              replicas: 3
              selector:
                matchLabels:
                  app: nginx
              template:
                metadata:
                  labels:
                    app: nginx
                spec:
                  containers:
                    - name: nginx
                      image: nginx:1.14.2
                      ports:
                        - containerPort: 80
        result: result
    - returnResult:
        return: '${result}'

JSON

{
  "main": {
    "steps": [
      {
        "create_deployment": {
          "call": "gke.request",
          "args": {
            "cluster_id": "CLUSTER_NAME",
            "project": "PROJECT_ID",
            "location": "LOCATION",
            "method": "POST",
            "path": "/apis/apps/v1/namespaces/default/deployments",
            "body": {
              "kind": "Deployment",
              "metadata": {
                "name": "nginx-deployment",
                "labels": {
                  "app": "nginx"
                }
              },
              "spec": {
                "replicas": 3,
                "selector": {
                  "matchLabels": {
                    "app": "nginx"
                  }
                },
                "template": {
                  "metadata": {
                    "labels": {
                      "app": "nginx"
                    }
                  },
                  "spec": {
                    "containers": [
                      {
                        "name": "nginx",
                        "image": "nginx:1.14.2",
                        "ports": [
                          {
                            "containerPort": 80
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "result": "result"
        }
      },
      {
        "returnResult": {
          "return": "${result}"
        }
      }
    ]
  }
}

以下を置き換えます。

CLUSTER_NAME: GKE クラスタの名前（hello-cluster など）。
PROJECT_ID: 実際の Google Cloud プロジェクト ID
LOCATION: クラスタのリージョン（us-central1 など）。

[デプロイ] をクリックします。

gcloud

ワークフローのソースコードファイルを作成します。
```
touch kubernetes-api-request.JSON_OR_YAML
```
ワークフローの形式に応じて、JSON_OR_YAML を yaml または json に置き換えます。

テキストエディタで、次のワークフローをソースコードファイルにコピーします。

YAML

main:
  steps:
    - create_deployment:
        call: gke.request
        args:
          cluster_id: "CLUSTER_NAME"
          project: "PROJECT_ID"
          location: "LOCATION"
          method: "POST"
          path: "/apis/apps/v1/namespaces/default/deployments"
          body:
            kind: Deployment
            metadata:
              name: nginx-deployment
              labels:
                app: nginx
            spec:
              replicas: 3
              selector:
                matchLabels:
                  app: nginx
              template:
                metadata:
                  labels:
                    app: nginx
                spec:
                  containers:
                    - name: nginx
                      image: nginx:1.14.2
                      ports:
                        - containerPort: 80
        result: result
    - returnResult:
        return: '${result}'

JSON

{
  "main": {
    "steps": [
      {
        "create_deployment": {
          "call": "gke.request",
          "args": {
            "cluster_id": "CLUSTER_NAME",
            "project": "PROJECT_ID",
            "location": "LOCATION",
            "method": "POST",
            "path": "/apis/apps/v1/namespaces/default/deployments",
            "body": {
              "kind": "Deployment",
              "metadata": {
                "name": "nginx-deployment",
                "labels": {
                  "app": "nginx"
                }
              },
              "spec": {
                "replicas": 3,
                "selector": {
                  "matchLabels": {
                    "app": "nginx"
                  }
                },
                "template": {
                  "metadata": {
                    "labels": {
                      "app": "nginx"
                    }
                  },
                  "spec": {
                    "containers": [
                      {
                        "name": "nginx",
                        "image": "nginx:1.14.2",
                        "ports": [
                          {
                            "containerPort": 80
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "result": "result"
        }
      },
      {
        "returnResult": {
          "return": "${result}"
        }
      }
    ]
  }
}

以下を置き換えます。

CLUSTER_NAME: GKE クラスタの名前（hello-cluster など）。
LOCATION: クラスタのリージョン（us-central1 など）。

ワークフローをデプロイします。

gcloud workflows deploy kubernetes-api-request \
    --source=kubernetes-api-request.JSON_OR_YAML \
    --location=LOCATION \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

ワークフローを実行する

ワークフローが正常にデプロイされたら、そのワークフローを実行できます。ワークフローを実行すると、そのワークフローに関連付けられた現在のワークフロー定義が実行されます。

Console

Google Cloud コンソールの [ワークフロー] ページに移動します。

[ワークフロー] に移動
[ワークフロー] ページで、ワークフローを選択して詳細ページに移動します。
[ワークフローの詳細] ページで [ 実行] を選択します。
もう一度 [Execute] をクリックします。
ワークフローの結果が [出力] ペインに表示されます。

成功した場合、実行ステータスは Succeeded になり、レスポンスの本文が返されます。

gcloud

ワークフローを実行します。

gcloud workflows run kubernetes-api-request \
    --location=LOCATION

成功すると、ステータスは SUCCEEDED になり、レスポンスの本文が返されます。

コネクタを使用して Kubernetes Job を実行する

Kubernetes API コネクタを使用して、GKE クラスタに Kubernetes Job をデプロイして実行できます。次のワークフローでは、一連の番号を反復処理する Bash スクリプトを実行する Kubernetes Job を作成します。ワークフローは、Kubernetes Job が完了するまで最大 90 秒間待機します。それ以外の場合は、エラーが発生します。Job が完了した場合、削除されます。

Job のステータスに Complete の条件タイプが含まれている場合、Job は完了とみなされます。次に例を示します。

  "status": {
    "conditions": [
      {
        "type": "Complete",
        "status": "True"
      }
    ]
  }

Job が失敗した場合、FailedJobError タグが返されます。次に例を示します。

{
  "tags": ["FailedJobError"]
  "job": {...}
  "message":"Kubernetes job failed"
}

詳細については、次の Kubernetes API コネクタ関数のリファレンスページをご覧ください。

ワークフローをデプロイする

ワークフローを実行する前に、ワークフローを作成してデプロイする必要があります。

Console

Google Cloud コンソールの [ワークフロー] ページに移動します。

[ワークフロー] に移動
[ 作成] をクリックします。
新しいワークフローの名前を入力します（例: kubernetes-api-job）。
[リージョン] リストで [us-central1] を選択します。
先ほど作成したサービスアカウントを選択します。
[次へ] をクリックします。

ワークフローエディタで、次のワークフローの定義を入力します。

YAML

main:
  steps:
    - init:
        assign:
          - project: "PROJECT_ID"
          - location: "LOCATION"
          - cluster_id: "CLUSTER_NAME"
          - job_name: "JOB_NAME"
          - namespace: "default"
    - create_job:
        call: gke.create_job
        args:
          cluster_id: '${cluster_id}'
          location: '${location}'
          project: '${project}'
          namespace: '${namespace}'
          job:
            apiVersion: batch/v1
            kind: Job
            metadata:
              name: "${job_name}"
            spec:
              template:
                spec:
                  containers:
                    - name: counter
                      image: centos:7
                      command:
                        - "bin/bash"
                        - "-c"
                        - "for i in 9 8 7 6 5 4 3 2 1 ; do echo $i ; done"
                  restartPolicy: Never
        result: job
    - wait_for_job:  # if job fails, raise error with "FailedJobError" tag and "job" field
        call: gke.await_job
        args:
          cluster_id: '${cluster_id}'
          job_name: '${job_name}'
          location: '${location}'
          project: '${project}'
          timeout: 90  # 90 seconds
        result: completed_job
    - cleanup_job:
        call: gke.delete_job
        args:
          cluster_id: '${cluster_id}'
          job_name: '${job_name}'
          location: '${location}'
          project: '${project}'
          query:
            propagationPolicy: "Foreground"  # delete child Pods
    - return_job:
        return: '${completed_job}'

JSON

{
  "main": {
    "steps": [
      {
        "init": {
          "assign": [
            {
              "project": "PROJECT_ID"
            },
            {
              "location": "LOCATION"
            },
            {
              "cluster_id": "CLUSTER_NAME"
            },
            {
              "job_name": "JOB_NAME"
            },
            {
              "namespace": "default"
            }
          ]
        }
      },
      {
        "create_job": {
          "call": "gke.create_job",
          "args": {
            "cluster_id": "${cluster_id}",
            "location": "${location}",
            "project": "${project}",
            "namespace": "${namespace}",
            "job": {
              "apiVersion": "batch/v1",
              "kind": "Job",
              "metadata": {
                "name": "${job_name}"
              },
              "spec": {
                "template": {
                  "spec": {
                    "containers": [
                      {
                        "name": "counter",
                        "image": "centos:7",
                        "command": [
                          "bin/bash",
                          "-c",
                          "for i in 9 8 7 6 5 4 3 2 1 ; do echo $i ; done"
                        ]
                      }
                    ],
                    "restartPolicy": "Never"
                  }
                }
              }
            }
          },
          "result": "job"
        }
      },
      {
        "wait_for_job": {
          "call": "gke.await_job",
          "args": {
            "cluster_id": "${cluster_id}",
            "job_name": "${job_name}",
            "location": "${location}",
            "project": "${project}",
            "timeout": 90
          },
          "result": "completed_job"
        }
      },
      {
        "cleanup_job": {
          "call": "gke.delete_job",
          "args": {
            "cluster_id": "${cluster_id}",
            "job_name": "${job_name}",
            "location": "${location}",
            "project": "${project}",
            "query": {
              "propagationPolicy": "Foreground"
            }
          }
        }
      },
      {
        "return_job": {
          "return": "${completed_job}"
        }
      }
    ]
  }
}

以下を置き換えます。

LOCATION: クラスタのリージョン（us-central1 など）。
CLUSTER_NAME: GKE クラスタの名前（hello-cluster など）。
JOB_NAME: Kubernetes Job の名前（hello-job など）

[デプロイ] をクリックします。

gcloud

ワークフローのソースコードファイルを作成します。
```
touch kubernetes-api-job.JSON_OR_YAML
```
ワークフローの形式に応じて、JSON_OR_YAML を yaml または json に置き換えます。

テキストエディタで、次のワークフローをソースコードファイルにコピーします。

YAML

main:
  steps:
    - init:
        assign:
          - project: "PROJECT_ID"
          - location: "LOCATION"
          - cluster_id: "CLUSTER_NAME"
          - job_name: "JOB_NAME"
          - namespace: "default"
    - create_job:
        call: gke.create_job
        args:
          cluster_id: '${cluster_id}'
          location: '${location}'
          project: '${project}'
          namespace: '${namespace}'
          job:
            apiVersion: batch/v1
            kind: Job
            metadata:
              name: "${job_name}"
            spec:
              template:
                spec:
                  containers:
                    - name: counter
                      image: centos:7
                      command:
                        - "bin/bash"
                        - "-c"
                        - "for i in 9 8 7 6 5 4 3 2 1 ; do echo $i ; done"
                  restartPolicy: Never
        result: job
    - wait_for_job:  # if job fails, raise error with "FailedJobError" tag and "job" field
        call: gke.await_job
        args:
          cluster_id: '${cluster_id}'
          job_name: '${job_name}'
          location: '${location}'
          project: '${project}'
          timeout: 90  # 90 seconds
        result: completed_job
    - cleanup_job:
        call: gke.delete_job
        args:
          cluster_id: '${cluster_id}'
          job_name: '${job_name}'
          location: '${location}'
          project: '${project}'
          query:
            propagationPolicy: "Foreground"  # delete child Pods
    - return_job:
        return: '${completed_job}'

JSON

{
  "main": {
    "steps": [
      {
        "init": {
          "assign": [
            {
              "project": "PROJECT_ID"
            },
            {
              "location": "LOCATION"
            },
            {
              "cluster_id": "CLUSTER_NAME"
            },
            {
              "job_name": "JOB_NAME"
            },
            {
              "namespace": "default"
            }
          ]
        }
      },
      {
        "create_job": {
          "call": "gke.create_job",
          "args": {
            "cluster_id": "${cluster_id}",
            "location": "${location}",
            "project": "${project}",
            "namespace": "${namespace}",
            "job": {
              "apiVersion": "batch/v1",
              "kind": "Job",
              "metadata": {
                "name": "${job_name}"
              },
              "spec": {
                "template": {
                  "spec": {
                    "containers": [
                      {
                        "name": "counter",
                        "image": "centos:7",
                        "command": [
                          "bin/bash",
                          "-c",
                          "for i in 9 8 7 6 5 4 3 2 1 ; do echo $i ; done"
                        ]
                      }
                    ],
                    "restartPolicy": "Never"
                  }
                }
              }
            }
          },
          "result": "job"
        }
      },
      {
        "wait_for_job": {
          "call": "gke.await_job",
          "args": {
            "cluster_id": "${cluster_id}",
            "job_name": "${job_name}",
            "location": "${location}",
            "project": "${project}",
            "timeout": 90
          },
          "result": "completed_job"
        }
      },
      {
        "cleanup_job": {
          "call": "gke.delete_job",
          "args": {
            "cluster_id": "${cluster_id}",
            "job_name": "${job_name}",
            "location": "${location}",
            "project": "${project}",
            "query": {
              "propagationPolicy": "Foreground"
            }
          }
        }
      },
      {
        "return_job": {
          "return": "${completed_job}"
        }
      }
    ]
  }
}

以下を置き換えます。

LOCATION: クラスタのリージョン（us-central1 など）。
CLUSTER_NAME: GKE クラスタの名前（hello-cluster など）。
JOB_NAME: Kubernetes Job の名前（hello-job など）

ワークフローをデプロイします。

gcloud workflows deploy kubernetes-api-job \
    --source=kubernetes-api-job.JSON_OR_YAML \
    --location=LOCATION \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

ワークフローを実行する

Console

Google Cloud コンソールの [ワークフロー] ページに移動します。

[ワークフロー] に移動
[ワークフロー] ページで、ワークフローを選択して詳細ページに移動します。
[ワークフローの詳細] ページで [ 実行] を選択します。
もう一度 [Execute] をクリックします。

ワークフローの実行には数分かかることがあります。

ワークフローの結果が [出力] ペインに表示されます。

結果の例を以下に示します。

{
...
  },
  "status": {
    "completionTime": "2023-10-31T17:04:32Z",
    "conditions": [
      {
        "lastProbeTime": "2023-10-31T17:04:33Z",
        "lastTransitionTime": "2023-10-31T17:04:33Z",
        "status": "True",
        "type": "Complete"
      }
    ],
    "ready": 0,
    "startTime": "2023-10-31T17:04:28Z",
    "succeeded": 1,
    "uncountedTerminatedPods": {}
  }
}

gcloud

ワークフローを実行します。

gcloud workflows run kubernetes-api-job \
    --location=LOCATION

ワークフローの実行には数分かかることがあります。結果は以下のようになります。

{
...
  },
  "status": {
    "completionTime": "2023-10-31T17:04:32Z",
    "conditions": [
      {
        "lastProbeTime": "2023-10-31T17:04:33Z",
        "lastTransitionTime": "2023-10-31T17:04:33Z",
        "status": "True",
        "type": "Complete"
      }
    ],
    "ready": 0,
    "startTime": "2023-10-31T17:04:28Z",
    "succeeded": 1,
    "uncountedTerminatedPods": {}
  }
}

コネクタを使用して Kubernetes API オブジェクトにアクセスする

始める前に

API を有効にする

コンソール

gcloud

サービス アカウントを作成する

コンソール

gcloud

GKE クラスタを作成する

Console

gcloud

コネクタを使用して HTTP リクエストを送信する

ワークフローをデプロイする

Console

YAML

JSON

gcloud

YAML

JSON

ワークフローを実行する

Console

gcloud

コネクタを使用して Kubernetes Job を実行する

ワークフローをデプロイする

Console

YAML

JSON

gcloud

YAML

JSON

ワークフローを実行する

Console

gcloud

次のステップ

サービスアカウントを作成する