使用 Step Functions 调用亚马逊 EKS - Amazon Step Functions
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

使用 Step Functions 调用亚马逊 EKS

Step Functions 可以控制某些Amazon服务直接从 Amazon 状态语言中提供。有关使用的更多信息,请参阅。Amazon Step Functions及其集成,请参阅以下内容:

有关在将与其他一起使用时如何配置 IAM 的信息。Amazon服务,请参阅集成服务的 IAM 策略

Step Functions 提供了两种类型的服务集成 API,用于与 Amazon Elastic Kubernetes Service 集成。您可以使用 Amazon EKS API 创建和管理 Amazon EKS 集群。另一种方法允许您使用 Kubernetes API 与集群进行交互,并将作业作为应用程序工作流的一部分运行。您可以使用 Kubernetes API 集成与使用 Step Functions 创建的亚马逊 EKS 集群,并通过eksctl工具或Amazon EKS 控制台或类似的方法。Step Functions EKS 集成仅支持具有公共端点访问权限的 Kubernetes API。有关更多信息,请参阅 。创建 Amazon EKS 群集(在 Amazon EKS 用户指南中)。

如果执行停止,Step Functions 不会自动终止 Amazon EKS 集群。如果您的状态计算机在 Amazon EKS 集群终止之前停止运行,则您的集群可能会继续无限期运行,并可能产生额外费用。为避免这种情况,请确保您创建的任何 Amazon EKS 集群都已正确终止。有关更多信息,请参阅:

注意

在 Step Functions 中任务的最大输入或结果数据大小有一个配额。这将限制您在向另一个服务发送或接收其数据时,将数据作为 UTF-8 编码字符串的 262,144 字节。请参阅 与状态机执行相关的配额

Kubernetes API 集成

Step Functions 支持以下 Kubernetes API:

RunJob

这些区域有:eks:runJob服务集成允许您在 Amazon EKS 集群上运行作业。这些区域有:eks:runJob.sync变体允许您等待作业完成,并且(可选)检索日志。

您的 Kubernetes API 服务器必须向状态机使用的 IAM 角色授予权限。有关更多信息,请参阅 Permissions

对于运行作业(.sync)模式下,作业的状态由轮询决定。Step Functions 最初以大约每分钟 1 次轮询的速率进行轮询。此速度最终减慢到大约每 5 分钟 1 次调查。如果需要更频繁的轮询,或者需要更多地控制轮询策略,则可以使用eks:call集成来查询任务的状态。

这些区域有:eks:runJob集成是特定于batch/v1Kubernetes 乔布斯。有关更多信息,请参阅 。作业(在 Kubernetes 文档中)。如果要管理其他 Kubernetes 资源(包括自定义资源),请使用eks:call服务集成。您可以使用 Step Functions 构建轮询循环,如轮询作 Job 状态(Lambda,Amazon Batch) 示例项目。

支持的参数包括:

  • ClusterName:您要调用的 Amazon EKS 集群的名称。

    • Type: String

    • 必需:是

  • CertificateAuthority:与群集通信所需的 Base64 编码证书数据。您可以从Amazon EKS 控制台或使用亚马逊 EKSDescribeClusterAPI。

    • Type: String

    • 必需:是

  • Endpoint:Kubernetes API 服务器的终端节点 URL。您可以从Amazon EKS 控制台或使用亚马逊 EKSDescribeClusterAPI。

    • Type: String

    • 必需:是

  • Namespace:要在其中运行作业的命名空间。如果未提供,则命名空间default使用。

    • Type: String

    • 必需:否

  • Job:库伯内特人 Job 的定义。请参阅作业(在 Kubernetes 文档中)。

    • TypeJSONString

    • 必需:是

  • LogOptions:用于控制日志的可选检索的一组选项。仅当使用运行 Job (.sync) 服务集成模式等待作业完成时才适用。

    • Type: JSON

    • 必需:否

    • 日志包含在响应中的密钥logs。作业中可能有多个容器,每个窗格都有多个容器。

      { ... "logs": { "pods": { "pod1": { "containers": { "container1": { "log": <log> }, ... } }, ... } }
    • 将以最大努力执行日志检索。如果检索日志时出现错误,请代替log字段中,将有字段errorcause

  • LogOptions.RetrieveLogs:在作业完成后启用日志检索。默认情况下,不检索日志。

    • Type: Boolean

    • 必需:否

  • LogOptions.RawLogs:如果RawLogs设置为 true,则日志将作为原始字符串返回,而不尝试将它们解析为 JSON。默认情况下,如果可能,将日志反序列化为 JSON。在某些情况下,这种解析可能会引入不必要的更改,例如限制包含多个数字的数字的精度。

    • Type: Boolean

    • 必需:否

  • LogOptions.LogParameters:Kubernetes API 的读取日志 API 支持查询参数来控制日志检索。例如,您可以使用tailLines或者limitBytes来限制检索到的日志的大小,并保持在 “Step Functions” 数据大小配额内。有关更多信息,请参阅 。读取日志部分的 Kubernetes API 参考中的。

    • Type: 的映射StringList 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 API 服务器必须向状态机使用的 IAM 角色授予权限。有关更多信息,请参阅 Permissions

有关可用操作的更多信息,请参阅库贝内特 API 参考

支持的参数Call包括:

  • ClusterName:您要调用的 Amazon EKS 集群的名称。

    • Type:字符串

    • :必需 是

  • CertificateAuthority:与群集通信所需的 Base64 编码证书数据。您可以从Amazon EKS 控制台或使用亚马逊 EKSDescribeClusterAPI。

    • Type: String

    • :必需 是

  • Endpoint:Kubernetes API 服务器的终端节点 URL。您可以在Amazon EKS 控制台或使用亚马逊 EKS 的 DescribeCluster API。

    • Type: String

    • :必需 是

  • Method:请求中的 HTTP 方法。以下值之一:GETPOSTPUTDELETEHEADPATCH

    • Type: String

    • :必需 是

  • Path:库贝内特斯 REST API 操作的 HTTP 路径。

    • Type: String

    • :必需 是

  • QueryParameters:库贝内特斯 REST API 操作的 HTTP 查询参数。

    • Type: 的映射StringList of Strings

    • :必需 否

    • 示例:

      "QueryParameters": { "labelSelector": [ "job-name=example-job" ] }
  • RequestBody:库贝内特斯 REST API 操作的 HTTP 消息正文。

    • TypeJSONString

    • :必需 否

下面这个Task使用eks:call列出属于作业的窗格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 } } }

下面这个Task使用eks:call删除作业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

支持的亚马逊 EKS API 和语法包括:

  • CreateCluster

    • 请求语法

    • 响应语法

      当 Amazon EKS 群集使用eks:createCluster服务集成后,IAM 角色将添加到 Kubernetes RBAC 授权表作为管理员(具有系统:主机权限)。最初,仅该 IAM 实体可以调用 Kubernetes API 服务器。有关更多信息,请参阅:

      Amazon EKS 使用服务相关角色,其中包含 Amazon EKS 代表您调用其他服务所需的权限。如果您的帐户中尚不存在这些与服务关联的角色,则必须将iam:CreateServiceLinkedRole权限设置为 Step Functions 使用的 IAM 角色。有关更多信息,请参阅 。使用服务相关角色中的Amazon EKS 用户指南

      Step Functions 使用的 IAM 角色必须具有iam:PassRole权限将集群 IAM 角色传递给 Amazon EKS。有关更多信息,请参阅 。Amazon EKS 群集 IAM 角色中的Amazon EKS 用户指南

  • DeleteCluster

  • CreateFargateProfile

    • 请求语法

    • 响应语法

      Amazon EKS 使用服务相关角色,其中包含 Amazon EKS 代表您调用其他服务所需的权限。如果您的帐户中尚不存在这些与服务关联的角色,则必须将iam:CreateServiceLinkedRole权限设置为 Step Functions 使用的 IAM 角色。有关更多信息,请参阅 。使用服务相关角色中的Amazon EKS 用户指南

      Fargate 上的 Amazon EKS 可能并未在所有区域提供。有关地区可用性的信息,请参阅Fargate中的Amazon EKS 用户指南

      Step Functions 使用的 IAM 角色必须具有iam:PassRole权限将容器执行 IAM 角色传递给 Amazon EKS。有关更多信息,请参阅 。Pod 执行角色中的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 } } }

下面这个Task状态,删除 Amazon EKS 群集的。

{ "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 } } }

下面这个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 } } }

Permissions

当 Amazon EKS 群集使用eks:createCluster服务集成后,IAM 角色将添加到 Kubernetes RBAC 授权表作为管理员,并使用system:masters权限。最初,仅该 IAM 实体可以调用 Kubernetes API 服务器。例如,您无法使用库贝特与 Kubernetes API 服务器交互,除非您承担与您的 Step Functions 状态机相同的角色,或者您将 Kubernetes 配置为向其他 IAM 实体授予权限。有关更多信息,请参阅 。管理集群的用户或 IAM 角色中的Amazon EKS 用户指南

您可以为其他 IAM 实体(如用户或角色)添加权限,方法是将它们添加到aws-auth ConfigMap在 kube 系统命名空间中。如果要通过 Step Functions 创建集群,请使用eks:call服务集成。

下面这个Task状态,用于创建aws-auth ConfigMap和赠款system:mastersIAM 用户的权限arn:aws:iam::123456789012:user/my-user和 IAM 角色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

首次创建集群时,aws-auth ConfigMap将不存在,但如果您创建 Fargate 配置文件,则会自动添加。您可以检索aws-auth,添加附加权限,然后PUT新版本。它通常更容易创建aws-auth(在 Fargate 配置文件之前)。

如果您的集群是在 Step Functions 之外创建的,则可以配置库贝特来与您的 Kubernetes API 服务器通信。然后,创建新的aws-auth ConfigMap,使用kubectl apply -f aws-auth.yaml或编辑已经存在的kubectl edit -n kube-system configmap/aws-auth。有关更多信息,请参阅:

如果您的 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" }