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

Google Kubernetes Engine（GKE）クラスタは、コントロールプレーンと、ノードと呼ばれるワーカーマシンで構成されます。GKE クラスタでコンテナ化された Kubernetes ワークロードを実行できます。ノードは、コンテナ化されたアプリケーションとその他のワークロードを実行するワーカーマシンであり、コントロールプレーンはクラスタの統合エンドポイントです。詳細については、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 クラスタを作成します。

コンソール

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 のドキュメントで「Kubernetes API リファレンス」のページにリンクされている API の概要をご覧ください。
ワークフローで HTTP リクエストエラーをキャッチして処理できます。詳細については、ワークフローのエラーをご覧ください。

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

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

コンソール

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

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

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

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 など）。

[Deploy] をクリックします。

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

ワークフローを実行する

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

コンソール

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 コネクタ関数のリファレンスページをご覧ください。

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

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

コンソール

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

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

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

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 など）。

[Deploy] をクリックします。

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

ワークフローを実行する

コンソール

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 クラスタを作成する

コンソール

gcloud

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

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

コンソール

YAML

JSON

gcloud

YAML

JSON

ワークフローを実行する

コンソール

gcloud

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

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

コンソール

YAML

JSON

gcloud

YAML

JSON

ワークフローを実行する

コンソール

gcloud

次のステップ

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