使用 Step Functions 調用 Amazon EKS

Step Functions 可以直接從Amazon States Language（ASL）控制某些 AWS 服務。如需了解詳細資訊，請參閱使用其他服務和將參數傳遞至服務 API。

優化的 Amazon EKS 整合與 Amazon EKS 開發套件整合有何不同 AWS

支援執行任務 (.sync)整合模式。
請求回應整合模式沒有最佳化。
不支援等候傳回任務字符的回呼整合模式。

如需Step Functions與其他 AWS 服務搭配使用時如何設定IAM權限的相關資訊，請參閱整合式服務的 IAM 政策。

Step Functions 提供兩種類型的服務整合 API，可與 Amazon Elastic Kubernetes Service 整合。一個允許您使用 Amazon EKS API 來創建和管理 Amazon EKS 集群。另一個可讓您使用 Kubernetes API 與叢集互動，並在應用程式工作流程中執行作業。您可以將 Kubernetes API 整合與使用 Step Functions 建立的 Amazon EKS 叢集搭配使用 eksctl 工具或 Amazon EKS 主控台建立的 Amazon EKS 叢集，或類似的方法。如需詳細資訊，請參閱 Amazon EKS 使用者指南中的建立 Amazon EKS 叢集。

注意

Step Functions EKS 整合僅支援具有公用端點存取權的 Kubernetes API。依預設，EKS 叢集 API 伺服器端點具有公開存取權。如需詳細資訊，請參閱 Amazon EKS 叢集端點存取控制 (英文) 中的 Amazon EKS 叢集端點存取控制。

如果停止執行，Step Functions 不會自動終止 Amazon EKS 叢集。如果您的狀態機器在 Amazon EKS 叢集終止之前停止，您的叢集可能會無限期地繼續執行，並可能產生額外費用。為避免這種情況，請確保您建立的任何 Amazon EKS 叢集都已正確終止。如需詳細資訊，請參閱：

刪除 Amazon EKS 使用者指南中的叢集。
執行任務 (.sync)在服務集成模式。

注意

「Step Functions 數」中的工作有最大輸入或結果資料大小的配額。當您傳送至其他服務或從其他服務接收資料時，這會將您限制為 256 KB 的資料，做為 UTF-8 編碼字串。請參閱與狀態機器執行相關的配額。

庫伯內特斯 API 整合

Step Functions 支援下列庫伯內特 API：

RunJob

eks:runJob服務整合可讓您在 Amazon EKS 叢集上執行任務。該eks:runJob.sync變體允許您等待工作完成，並選擇性地檢索日誌。

您的 Kubernetes API 伺服器必須將許可授與狀態機器使用的 IAM 角色。如需詳細資訊，請參閱許可。

對於執行 Job (.sync) 模式，工作的狀態是由輪詢決定。Step Functions 最初以每分鐘大約 1 次輪詢的速率進行輪詢。這個速率最終會減慢到大約每 5 分鐘進行 1 次調查。如果您需要更頻繁的輪詢，或需要對輪詢策略進行更多控制，則可以使用eks:call整合來查詢工作的狀態。

此eks:runJob整合特定於batch/v1庫伯尼特工作。如需詳細資訊，請參閱 Kubernetes 文件中的工作。如果您想要管理其他 Kubernetes 資源 (包括自訂資源)，請使用服務整合eks:call。您可以使用 Step Functions 來建立輪詢迴圈，如投票 Job 狀態 (Lambda、 AWS Batch) 範例專案中所示。

支援的參數包括：

ClusterName：您要呼叫的 Amazon EKS 叢集的名稱。
- Type: String
- 必要：是
CertificateAuthority：與叢集通訊所需的 Base64 編碼憑證資料。您可以從 Amazon EKS 控制台或使用 Amazon EKS API 獲取此值。DescribeCluster
- Type: String
- 必要：是
Endpoint：您的 Kubernetes API 伺服器的端點網址。您可以從 Amazon EKS 控制台或使用 Amazon EKS API 獲取此值。DescribeCluster
- Type: String
- 必要：是
Namespace：執行工作的命名空間。如果未提供，則會使default用命名空間。
- Type: String
- 必要：否
Job：Job 的定義。請參閱 Kubernetes 文件中的工作。
- Type：JSON 或 String
- 必要：是
LogOptions：用於控制日誌的可選檢索的一組選項。只有在使用「執行 Job (.sync)」服務整合模式來等待工作完成時才適用。
- Type: JSON
- 必要：否
- 記錄會包含在金鑰下的回應中logs。工作中可能有多個網繭，每個 Pod 都有多個容器。
```
{ 
  ...
  "logs": { 
    "pods": { 
      "pod1": { 
        "containers": { 
          "container1": { 
            "log": <log> 
          },
          ...
        }
      },
      ...
    }
  }
```
- 記錄擷取是以最大的方式執行。如果擷取記錄檔時發生錯誤，則會有log欄位error和cause。
LogOptions.RetrieveLogs：在工作完成後啟用記錄擷取。依預設，不會擷取記錄檔。
- Type: Boolean
- 必要：否
LogOptions.RawLogs：如果設定RawLogs為 true，則會以原始字串傳回記錄，而不會嘗試將記錄剖析為 JSON。根據預設，記錄會在可能的情況下還原序列化為 JSON。在某些情況下，這種解析可能會引入不必要的更改，例如限制包含多個數字的數字的精度。
- Type: Boolean
- 必要：否
LogOptions.LogParameters：Kubernetes API 的讀取記錄 API 支援查詢參數以控制記錄擷取。例如，您可以使用tailLines或limitBytes限制擷取記錄檔的大小，並保留在 Step Functions 資料大小配額內。如需詳細資訊，請參閱 Kubernetes API 參考資料的「讀取記錄」一節。
- Type: String到的地圖 List of Strings
- 必要：否
- 範例：
```
"LogParameters": {
  "tailLines": [ "6" ]
}
```

下列範例包含執行工作、等待工作完成，然後擷取工作記錄的Task狀態：


{
  "StartAt": "Run a job on EKS",
  "States": {
    "Run a job on EKS": {
      "Type": "Task",
      "Resource": "arn:aws:states:::eks:runJob.sync",
      "Parameters": {
        "ClusterName": "MyCluster",
        "CertificateAuthority": "ANPAJ2UCCR6DPCEXAMPLE",
        "Endpoint": "https://AKIAIOSFODNN7EXAMPLE.yl4.us-east-1.eks.amazonaws.com",
        "LogOptions": {
          "RetrieveLogs": true
        },
        "Job": {
          "apiVersion": "batch/v1",
          "kind": "Job",
          "metadata": {
            "name": "example-job"
          },
          "spec": {
            "backoffLimit": 0,
            "template": {
              "metadata": {
                "name": "example-job"
              },
              "spec": {
                "containers": [
                  {
                    "name": "pi-2000",
                    "image": "perl",
                    "command": [ "perl" ],
                    "args": [
                      "-Mbignum=bpi",
                      "-wle",
                      "print bpi(2000)"
                    ]
                  }
                ],
                "restartPolicy": "Never"
              }
            }
          }
        }
      },
      "End": true
    }
  }
}

`Call`

eks:call服務整合可讓您使用 Kubernetes API 透過 Kubernetes API 端點讀取和寫入 Kubernetes 資源物件。

您的 Kubernetes API 伺服器必須將許可授與狀態機器使用的 IAM 角色。如需詳細資訊，請參閱許可。

如需有關可用作業的詳細資訊，請參閱 Kubernetes API 參考資料。

支援的參數Call包括：

ClusterName：您要呼叫的 Amazon EKS 叢集的名稱。
- Type：String
- 必要：是
CertificateAuthority：與叢集通訊所需的 Base64 編碼憑證資料。您可以從 Amazon EKS 控制台或使用 Amazon EKS API 獲取此值。DescribeCluster
- Type: String
- 必要：是
Endpoint：您的 Kubernetes API 伺服器的端點網址。您可以在 Amazon EKS 控制台或使用 Amazon EKS 的 API 找到此值。 DescribeCluster
- Type: String
- 必要：是
Method：您的請求的 HTTP 方法。下列其中一項：GET、POST、PUT、DELETE、HEAD 或 PATCH。
- Type: String
- 必要：是
Path：執行 REST API 作業的 HTTP 路徑。
- Type: String
- 必要：是
QueryParameters：執行 REST API 作業的 HTTP 查詢參數。
- Type: String到的地圖 List of Strings
- 必要：否
- 範例：
```
"QueryParameters": {
  "labelSelector": [ "job-name=example-job" ]
}
```
RequestBody：執行 REST API 作業的 HTTP 訊息內文。
- Type：JSON 或 String
- 必要：否

以下包含用eks:call來列出屬於工作之網繭的Task狀態example-job。


{
  "StartAt": "Call EKS",
  "States": {
    "Call EKS": {
      "Type": "Task",
      "Resource": "arn:aws:states:::eks:call",
      "Parameters": {
        "ClusterName": "MyCluster",
        "CertificateAuthority": "ANPAJ2UCCR6DPCEXAMPLE",
        "Endpoint": "https://444455556666.yl4.us-east-1.eks.amazonaws.com",
        "Method": "GET",
        "Path": "/api/v1/namespaces/default/pods",
        "QueryParameters": {
          "labelSelector": [
            "job-name=example-job"
          ]
        }
      },
      "End": true
    }
  }
}

以下內容包括用eks:call來刪除工作的Task狀態example-job，並設定以確propagationPolicy保工作的網繭也會遭到刪除。


{
  "StartAt": "Call EKS",
  "States": {
    "Call EKS": {
      "Type": "Task",
      "Resource": "arn:aws:states:::eks:call",
      "Parameters": {
        "ClusterName": "MyCluster",
        "CertificateAuthority": "ANPAJ2UCCR6DPCEXAMPLE",
        "Endpoint": "https://444455556666.yl4.us-east-1.eks.amazonaws.com",
        "Method": "DELETE",
        "Path": "/apis/batch/v1/namespaces/default/jobs/example-job",
        "QueryParameters": {
          "propagationPolicy": [
            "Foreground"
          ]
        }
      },
      "End": true
    }
  }
}

支援的 Amazon EKS API

支援的 Amazon EKS API 和語法包括：

CreateCluster
- 請求語法
- 回應語法
  
  使用eks:createCluster服務整合建立 Amazon EKS 叢集時，IAM 角色會以管理員身分新增至 Kubernetes RBAC 授權表格 (具有系統:主要許可)。一開始，只有該 IAM 實體可以呼叫 Kubernetes API 伺服器。如需詳細資訊，請參閱：
  - 在 Amazon EKS 使用者指南中管理叢集的使用者或 IAM 角色
  - 該許可部分
  Amazon EKS 使用服務連結角色，其中包含 Amazon EKS 代表您呼叫其他服務所需的許可。如果這些服務連結角色不存在於您的帳戶中，您必須將iam:CreateServiceLinkedRole權限新增至 Step Functions 使用的 IAM 角色。如需詳細資訊，請參閱 Amazon EKS 使用者指南中的使用服務連結角色。
  
  Step Functions 使用的 IAM 角色必須具有iam:PassRole許可，才能將叢集 IAM 角色傳遞給 Amazon EKS。如需詳細資訊，請參閱 Amazon EKS 使用者指南中的 Amazon EKS 叢集 IAM 角色。
DeleteCluster
- 請求語法
- 回應語法
  
  您必須先刪除任何 Fargate 設定檔或節點群組，才能刪除叢集。
CreateFargateProfile
- 請求語法
- 回應語法
  
  Amazon EKS 使用服務連結角色，其中包含 Amazon EKS 代表您呼叫其他服務所需的許可。如果這些服務連結角色不存在於您的帳戶中，您必須將iam:CreateServiceLinkedRole權限新增至 Step Functions 使用的 IAM 角色。如需詳細資訊，請參閱 Amazon EKS 使用者指南中的使用服務連結角色。
  
  Fargate 上的 Amazon EKS 可能無法在所有地區提供。如需區域可用性的相關資訊，請參閱 Amazon EKS 使用者指南中關於 Fargate 的章節。
  
  Step Functions 使用的 IAM 角色必須具有iam:PassRole許可，才能將網繭執行 IAM 角色傳遞給 Amazon EKS。如需詳細資訊，請參閱 Amazon EKS 使用者指南中的網繭執行角色。
DeleteFargateProfile
- 請求語法
- 回應語法
CreateNodegroup
- 請求語法
- 回應語法
  
  Amazon EKS 使用服務連結角色，其中包含 Amazon EKS 代表您呼叫其他服務所需的許可。如果這些服務連結角色不存在於您的帳戶中，您必須將iam:CreateServiceLinkedRole權限新增至 Step Functions 使用的 IAM 角色。如需詳細資訊，請參閱 Amazon EKS 使用者指南中的使用服務連結角色。
  
  Step Functions 使用的 IAM 角色必須具有iam:PassRole許可，才能將節點 IAM 角色傳遞給 Amazon EKS。如需詳細資訊，請參閱 Amazon EKS 使用者指南中的使用服務連結角色。
DeleteNodegroup
- 請求語法
- 回應語法

以下內容包括Task可建立 Amazon EKS 叢集的項目。


{
  "StartAt": "CreateCluster.sync",
  "States": {
    "CreateCluster.sync": {
      "Type": "Task",
      "Resource": "arn:aws:states:::eks:createCluster.sync",
      "Parameters": {
        "Name": "MyCluster",
        "ResourcesVpcConfig": {
          "SubnetIds": [
            "subnet-053e7c47012341234",
            "subnet-027cfea4b12341234"
          ]
        },
        "RoleArn": "arn:aws:iam::123456789012:role/MyEKSClusterRole"
      },
      "End": true
    }
  }
}

以下內容包括刪除 Amazon EKS 叢集的Task狀態。


{
  "StartAt": "DeleteCluster.sync",
  "States": {
    "DeleteCluster.sync": {
      "Type": "Task",
      "Resource": "arn:aws:states:::eks:deleteCluster.sync",
      "Parameters": {
        "Name": "MyCluster"
      },
      "End": true
    }
  }
}

以下內容包括建Task立 Fargate 設定檔的狀態。


{
  "StartAt": "CreateFargateProfile.sync",
  "States": {
    "CreateFargateProfile.sync": {
      "Type": "Task",
      "Resource": "arn:aws:states:::eks:createFargateProfile.sync",
      "Parameters": {
        "ClusterName": "MyCluster",
        "FargateProfileName": "MyFargateProfile",
        "PodExecutionRoleArn": "arn:aws:iam::123456789012:role/MyFargatePodExecutionRole",
        "Selectors": [{
            "Namespace": "my-namespace",
            "Labels": { "my-label": "my-value" }
          }]
      },
      "End": true
    }
  }
}

以下內容包括刪除 Fargate 設定檔的Task狀態。


{
  "StartAt": "DeleteFargateProfile.sync",
  "States": {
    "DeleteFargateProfile.sync": {
      "Type": "Task",
      "Resource": "arn:aws:states:::eks:deleteFargateProfile.sync",
      "Parameters": {
        "ClusterName": "MyCluster",
        "FargateProfileName": "MyFargateProfile"
      },
      "End": true
    }
  }
}

以下內容包括建Task立節點群組的狀態。


{
  "StartAt": "CreateNodegroup.sync",
  "States": {
    "CreateNodegroup.sync": {
      "Type": "Task",
      "Resource": "arn:aws:states:::eks:createNodegroup.sync",
      "Parameters": {
        "ClusterName": "MyCluster",
        "NodegroupName": "MyNodegroup",
        "NodeRole": "arn:aws:iam::123456789012:role/MyNodeInstanceRole",
        "Subnets": ["subnet-09fb51df01234", "subnet-027cfea4b1234"] 
      },
      "End": true
    }
  }
}

以下內容包括刪除節點群組的Task狀態。


{
  "StartAt": "DeleteNodegroup.sync",
  "States": {
    "DeleteNodegroup.sync": {
      "Type": "Task",
      "Resource": "arn:aws:states:::eks:deleteNodegroup.sync",
      "Parameters": {
        "ClusterName": "MyCluster",
        "NodegroupName": "MyNodegroup"
      },
      "End": true
    }
  }
}

許可

使用eks:createCluster服務整合建立 Amazon EKS 叢集時，IAM 角色會以管理員身分新增至 Kubernetes RBAC 授權資料表，並具有許可。system:masters一開始，只有該 IAM 實體可以呼叫 Kubernetes API 伺服器。例如，您將無法使用 kubectl 與 Ku bernetes API 伺服器互動，除非您承擔與 Step Functions 狀態機器相同的角色，或者設定 Kubernetes 將許可授與其他 IAM 實體。如需詳細資訊，請參閱 Amazon EKS 使用者指南中的管理叢集的使用者或 IAM 角色。

您可以將其他 IAM 實體 (例如使用者或角色) 新增權限，方法是將這些實體新增至 kube-system 命名空aws-authConfigMap間中的。如果您要從 Step Functions 建立叢集，請使用eks:call服務整合。

以下包含建Task立aws-authConfigMap並授與使用者arn:aws:iam::123456789012:user/my-user和 IAM 角色system:masters權限的狀態arn:aws:iam::123456789012:role/my-role。


{
  "StartAt": "Add authorized user",
  "States": {
    "Add authorized user": {
      "Type": "Task",
      "Resource": "arn:aws:states:::eks:call",
      "Parameters": {
        "ClusterName": "MyCluster",
        "CertificateAuthority": "LS0tLS1CRUd...UtLS0tLQo=",
        "Endpoint": "https://444455556666.yl4.us-east-1.eks.amazonaws.com",
        "Method": "POST",
        "Path": "/api/v1/namespaces/kube-system/configmaps",
        "RequestBody": {
           "apiVersion": "v1",
           "kind": "ConfigMap",
           "metadata": {
              "name": "aws-auth",
              "namespace": "kube-system"
           },
           "data": {
             "mapUsers": "[{ \"userarn\": \"arn:aws:iam::123456789012:user/my-user\", \"username\": \"my-user\", \"groups\": [ \"system:masters\" ] } ]",
             "mapRoles": "[{ \"rolearn\": \"arn:aws:iam::123456789012:role/my-role\", \"username\": \"my-role\", \"groups\": [ \"system:masters\" ] } ]"
           }
        }
      },
      "End": true
    }
  }

注意

您可能會看到 IAM 角色的 ARN 以包含路徑 /服務角色/ 的格式顯示，例如。arn:aws:iam::123456789012:role/service-role/my-role在aws-auth中列出角色時，不應包含此服務角色路徑 Token。

第一次建立叢集時，aws-authConfigMap將不存在，但如果您建立 Fargate 設定檔，則會自動新增叢集。您可以擷取的目前值aws-auth、新增其他權限以及PUT新版本。通常在 Fargate 配置文件aws-auth之前創建更容易。

如果您的叢集是在 Step Functions 之外建立的，您可以設定 kubectl 與您的 Kubernetes API 伺服器進行通訊。然後，使用創建一個新的kubectl apply -f aws-auth.yaml或aws-authConfigMap使用編輯已存在的kubectl edit -n kube-system configmap/aws-auth。如需詳細資訊，請參閱：

在 Amazon EKS 用戶指南中為 Amazon EKS 創建庫貝配置。
在 Amazon EKS 使用者指南中管理叢集的使用者或 IAM 角色。

如果您的 IAM 角色在 Kubernetes 中沒有足夠的許可，eks:call或eks:runJob服務整合將失敗，並出現以下錯誤：


Error:
EKS.401

Cause:
{
  "ResponseBody": {
    "kind": "Status",
    "apiVersion": "v1",
    "metadata": {},
    "status": "Failure",
    "message": "Unauthorized",
    "reason": "Unauthorized",
    "code": 401
  },
  "StatusCode": 401,
  "StatusText": "Unauthorized"
}

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

Amazon EC/Fargate

Amazon EMR