使用連接器存取 Kubernetes API 物件

Google Kubernetes Engine (GKE) 叢集包含一個控制層和稱為「節點」的工作站機器。您可以在 GKE 叢集中執行容器化 Kubernetes 工作負載。節點是執行容器化應用程式和其他工作負載的工作站機器，控制層則是叢集的統一端點。詳情請參閱「GKE 叢集架構」。

Kubernetes API 伺服器會在控制層上執行，讓您透過 Kubernetes API 呼叫與叢集中的 Kubernetes 物件互動。物件是 Kubernetes 系統中的永久實體，代表叢集的狀態。如需更多資訊，請參閱 Kubernetes 說明文件中的「Kubernetes 中的物件」和「API 總覽」，其中提供「Kubernetes API 參考資料」頁面的連結。

本文件說明如何在工作流程中使用 Kubernetes API 連接器，向 GKE 叢集控制平面上代管的 Kubernetes 服務端點提出要求。舉例來說，您可以使用連接器建立 Kubernetes 部署作業、執行工作、管理 Pod，或透過 Proxy 存取已部署的應用程式。詳情請參閱 Kubernetes API 連接器總覽。

事前準備

繼續執行本文件中的任務前，請確認您已完成特定先決條件。

啟用 API

您必須先啟用下列 API，才能使用 Kubernetes API 連接器存取 Kubernetes API 物件：

  • Google Kubernetes Engine API：使用 GKE 建構及管理容器型應用程式

  • Workflows API：用於管理工作流程定義和執行作業；啟用 Workflows API 會自動啟用 Workflow Executions API

主控台

啟用 API：

啟用 API

gcloud

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

  2. 啟用 API：

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

建立服務帳戶

建立由使用者管理的服務帳戶，做為工作流程的身份，並授予該帳戶 Kubernetes Engine 開發人員 (roles/container.developer) 角色，讓工作流程能夠存取叢集內的 Kubernetes API 物件。

主控台

  1. 前往 Google Cloud 控制台的「Service accounts」(服務帳戶) 頁面。

    前往「Service accounts」(服務帳戶)

  2. 選取專案，然後按一下「建立服務帳戶」。

  3. 在「Service account name」(服務帳戶名稱) 欄位中輸入名稱。 Google Cloud控制台會根據這個名稱填入「Service account ID」欄位。

    在「服務帳戶說明」欄位中輸入說明。例如：Service account for Kubernetes API。

  4. 按一下「建立並繼續」。

  5. 在「Select a role」(請選擇角色) 清單中，篩選並選取「Kubernetes Engine Developer」角色。

  6. 按一下「繼續」。

  7. 按一下「完成」，即可完成帳戶建立程序。

gcloud

  1. 建立服務帳戶：

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

    將 SERVICE_ACCOUNT_NAME 替換為服務帳戶名稱。

  2. 將 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。

請注意，您可以同時使用 IAM 和 Kubernetes 角色型存取控制 (RBAC) 來控制 GKE 叢集的存取權：

  • IAM 並非專屬於 Kubernetes，而是為多種 Google Cloud 產品提供身分管理功能，主要在 Google Cloud 專案層級運作。

  • Kubernetes RBAC 是 Kubernetes 的核心元件，可用於建立和授予叢集「內」任何物件或物件類型的角色 (即一組權限)。如果您主要都是使用 GKE，且叢集內的所有物件和作業都需要精細的權限設定，Kubernetes RBAC 會是最佳選擇。

詳情請參閱存取權控管一文。

建立 GKE 叢集

如要使用 Kubernetes API 連接器，您必須已建立公開或私人 GKE 叢集。在私人叢集中，節點只會有內部 IP 位址，也就是說，節點和 Pod 預設會與網際網路隔離。詳情請參閱「私人叢集」。

您也可以指定作業模式，提供不同程度的靈活性、責任和控制權。舉例來說，您可以建立 Autopilot 叢集，這是一種 GKE 作業模式，可讓 Google 管理您的叢集設定，包括節點、資源調度、安全性和其他預先設定。詳情請參閱「選擇 GKE 作業模式」。

如果您尚未建立 GKE 叢集，可以將容器化網頁伺服器應用程式部署至 GKE 叢集。或者，如要嘗試本文件中的操作說明，您可以完成下列步驟來建立 Autopilot 叢集。

控制台

  1. 在 Google Cloud 控制台中，前往「Kubernetes clusters」(Kubernetes 叢集) 頁面。

    前往 Kubernetes 叢集

  2. 按一下 「Create」(建立)。

  3. 如果系統要求您選取叢集模式，請選取「Autopilot」。

  4. 在「叢集基本資訊」部分中，完成下列操作：

    1. 輸入叢集的名稱，例如 hello-cluster。
    2. 為叢集選取區域，例如 us-central1。

  5. 按一下「下一步：網路」。

  6. 在「IPv4 網路存取」部分，如要建立具有可公開存取端點的叢集，請選擇「公開叢集」。

  7. 其他所有設定請接受預設值。

  8. 按一下 [建立]。

叢集可能需要幾分鐘的時間才能建立完畢。 建立叢集後，畫面上會顯示勾號 ，表示叢集正在運作。

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 的部署。部署作業會說明必要狀態；在本例中，您必須使用 nginx:1.14.2 映像檔執行三個 Pod，並在 80 號通訊埠上公開服務。(如未指定，project 和 location 預設為工作流程的值)。

詳情請參閱 Kubernetes API 連接器函式 gke.request 的參考頁面。

注意事項：

  • path 欄位對應至 Kubernetes API 方法路徑。如需更多資訊，請參閱 Kubernetes 說明文件中的「API 總覽」，其中提供「Kubernetes API 參考資料」頁面的連結。
  • 您可以在工作流程中擷取及處理 HTTP 要求錯誤。詳情請參閱「工作流程錯誤」。

部署工作流程

您必須先建立並部署工作流程，才能執行。

控制台

  1. 前往 Google Cloud 控制台的「Workflows」頁面。

    前往「Workflows」頁面

  2. 按一下「建立」。

  3. 輸入新工作流程的名稱，例如 kubernetes-api-request。

  4. 在「Region」(區域) 清單中選取「us-central1」。

  5. 選取先前建立的「Service account」(服務帳戶)。

  6. 點按「Next」。

  7. 在工作流程編輯器中，輸入工作流程的定義：

    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

  8. 按一下 [Deploy] (部署)。

gcloud

  1. 建立工作流程的原始碼檔案：

    touch kubernetes-api-request.JSON_OR_YAML

    視工作流程的格式而定，將 JSON_OR_YAML 替換為 yaml 或 json。

  2. 在文字編輯器中，將下列工作流程複製到原始碼檔案：

    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

  3. 部署工作流程：

    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

執行工作流程

工作流程部署完成後，您就可以執行工作流程。執行工作流程會執行與工作流程相關聯的目前工作流程定義。

控制台

  1. 前往 Google Cloud 控制台的「Workflows」頁面。

    前往「Workflows」頁面

  2. 在「工作流程」頁面中選取工作流程，前往該工作流程的詳細資料頁面。

  3. 在「Workflow details」(工作流程詳細資料)頁面中，按一下 「Execute」(執行)。

  4. 再次按一下「執行」。

  5. 在「Output」窗格中查看工作流程的結果。

    如果成功，執行狀態應為 Succeeded，並傳回回應主體。

gcloud

執行工作流程：

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

如果成功，狀態應為 SUCCEEDED，並傳回回應主體。

使用連接器執行 Kubernetes 工作

您可以使用 Kubernetes API 連接器，在 GKE 叢集中部署及執行 Kubernetes 工作。以下工作流程會建立 Kubernetes 工作，執行 Bash 指令碼，以便逐一處理一連串的數字。工作流程最多會等待 90 秒，等待 Kubernetes 工作完成；否則，系統會擲回錯誤。如果工作完成，系統就會刪除該工作。

請注意，如果工作狀態包含 Complete 條件類型，系統就會將該工作視為已完成。例如：

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

如果工作失敗，系統會傳回 FailedJobError 標記。例如：

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

如需更多資訊，請參閱下列 Kubernetes API 連接器函式的參考資料頁面：

部署工作流程

您必須先建立並部署工作流程，才能執行。

控制台

  1. 前往 Google Cloud 控制台的「Workflows」頁面。

    前往「Workflows」頁面

  2. 按一下「建立」。

  3. 輸入新工作流程的名稱，例如 kubernetes-api-job。

  4. 在「Region」(區域) 清單中選取「us-central1」。

  5. 選取先前建立的「Service account」(服務帳戶)。

  6. 點按「Next」。

  7. 在工作流程編輯器中，輸入工作流程的定義：

    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 工作名稱，例如 hello-job

  8. 按一下 [Deploy] (部署)。

gcloud

  1. 建立工作流程的原始碼檔案：

    touch kubernetes-api-job.JSON_OR_YAML

    視工作流程的格式而定，將 JSON_OR_YAML 替換為 yaml 或 json。

  2. 在文字編輯器中，將下列工作流程複製到原始碼檔案：

    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 工作名稱，例如 hello-job

  3. 部署工作流程：

    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

執行工作流程

工作流程部署完成後，您就可以執行工作流程。執行工作流程會執行與工作流程相關聯的目前工作流程定義。

控制台

  1. 前往 Google Cloud 控制台的「Workflows」頁面。

    前往「Workflows」頁面

  2. 在「工作流程」頁面中選取工作流程，前往該工作流程的詳細資料頁面。

  3. 在「Workflow details」(工作流程詳細資料)頁面中，按一下 「Execute」(執行)。

  4. 再次按一下「執行」。

    工作流程執行作業可能需要幾分鐘的時間。

  5. 在「Output」窗格中查看工作流程的結果。

    結果應類似於以下內容：

    {
...
  },
  "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": {}
  }
}

後續步驟