Call Amazon EKS with Step Functions
Step Functions can control certain AWS services directly from the Amazon States Language. For more information, see the following:
For information on how to configure IAM when using Step Functions with other AWS services, see IAM Policies for Integrated Services.
Step Functions provides two types of service
integration APIs for integrating with Amazon Elastic Kubernetes Service. One lets
you use the Amazon EKS APIs to
create and manage an Amazon EKS cluster. The other lets you interact with your cluster
using
the Kubernetes API and run jobs as part of your application’s workflow. You can use
the
Kubernetes API integrations with Amazon EKS clusters created using Step Functions,
with Amazon EKS clusters
created by the eksctl tool or the Amazon EKS console
Step Functions does not terminate an Amazon EKS cluster automatically if execution is stopped. If your state machine stops before your Amazon EKS cluster has terminated, your cluster may continue running indefinitely, and can accrue additional charges. To avoid this, ensure that any Amazon EKS cluster you create is terminated properly. For more information, see:
-
Deleting a cluster in the Amazon EKS User Guide.
-
Run a Job in Service Integration Patterns.
There is a quota for the maximum input or result data size for a task in Step Functions. This restricts you to 262,144 bytes of data as a UTF-8 encoded string when you send to, or receive data from, another service. See Quotas Related to State Machine Executions.
Kubernetes API integrations
Step Functions supports the following Kubernetes APIs:
RunJob
The eks:runJob
service integration allows you to run a job on
your Amazon EKS cluster. The eks:runJob.sync
variant allows you to wait
for the job to complete, and, optionally retrieve logs.
Your Kubernetes API server must grant permissions to the IAM role used by your state machine. For more information, see Permissions.
For the Run a Job (.sync
) pattern, the
status of the job is determined by polling. Step Functions initially polls at a rate
of
approximately 1 poll per minute. This rate eventually slows to approximately 1
poll every 5 minutes. If you require more frequent polling, or require more
control over the polling strategy, you can use the eks:call
integration to query the status of the job.
Supported parameters include:
-
ClusterName
: The name of the Amazon EKS cluster you want to call.-
Type
:String
-
Required: yes
-
-
CertificateAuthority
: The Base64-encoded certificate data required to communicate with your cluster. You can obtain this value from the Amazon EKS consoleor by using the Amazon EKS DescribeCluster API. -
Type
:String
-
Required: yes
-
-
Endpoint
: The endpoint URL for your Kubernetes API server. You can obtain this value from the Amazon EKS consoleor by using the Amazon EKS DescribeCluster API. -
Type
:String
-
Required: yes
-
-
Namespace
: The namespace in which to run the job. If not provided, the namespacedefault
is used.-
Type
:String
-
Required: no
-
-
Job
: The definition of the Kubernetes Job. See Jobsin the Kubernetes documentation. -
Type
:JSON
orString
-
Required: yes
-
-
LogOptions
: A set of options to control the optional retrieval of logs. Only applicable if the Run a Job (.sync) service integration pattern is used to wait for the completion of the job.-
Type
:JSON
-
Required: no
-
Logs are included in the response under the key
logs
. There may be multiple pods within the job, each with multiple containers.{ ... "logs": { "pods": { "pod1": { "containers": { "container1": { "log":
<log>
}, ... } }, ... } } -
Log retrieval is performed on a best-effort basis. If there is an error retrieving a log, in place of the
log
field there will be the fieldserror
andcause
.
-
-
LogOptions.RetrieveLogs
: Enable log retrieval after the job completes. By default, logs are not retrieved.-
Type
:Boolean
-
Required: no
-
-
LogOptions.RawLogs
: IfRawLogs
is set to true, logs will be returned as raw strings without attempting to parse them into JSON. By default, logs are deserialized into JSON if possible. In some cases such parsing can introduce unwanted changes, such as limiting the precision of numbers containing many digits.-
Type
:Boolean
-
Required: no
-
-
LogOptions.LogParameters
: The Kubernetes API’s Read Log API supports query parameters to control log retrieval. For example, you can usetailLines
orlimitBytes
to limit the size of retrieved logs and remain within the Step Functions data size quota. For more information, see the Read Logsection of the Kubernetes API Reference. -
Type:
Map ofString
toList of Strings
-
Required: no
-
Example:
"LogParameters": { "tailLines": [ "6" ] }
-
The following example includes a Task
state that runs a job,
waits for it to complete, then retrieves the job’s logs:
{
"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
The eks:call
service integration allows you to use the Kubernetes
API to read and write Kubernetes resource objects via a Kubernetes API endpoint.
Your Kubernetes API server must grant permissions to the IAM role used by your state machine. For more information, see Permissions.
For more information about the available operations, see the Kubernetes API
Reference
Supported parameters for Call
include:
-
ClusterName
: The name of the Amazon EKS cluster you want to call.-
Type
: String -
Required: Yes
-
-
CertificateAuthority
: The Base64-encoded certificate data required to communicate with your cluster. You can obtain this value from the Amazon EKS consoleor by using the Amazon EKS DescribeCluster API. -
Type
:String
-
Required: Yes
-
-
Endpoint
: The endpoint URL for your Kubernetes API server. You can find this value on the Amazon EKS consoleor by using Amazon EKS’ DescribeCluster API. -
Type
:String
-
Required: Yes
-
-
Method
: The HTTP method of your request. One of:GET
,POST
,PUT
,DELETE
,HEAD
, orPATCH
.-
Type
:String
-
Required: Yes
-
-
Path
: The HTTP path of the Kubernetes REST API operation.-
Type
:String
-
Required: Yes
-
-
QueryParameters
: The HTTP query parameters of the Kubernetes REST API operation.-
Type:
Map ofString
toList of Strings
-
Required: No
-
Example:
"QueryParameters": { "labelSelector": [ "job-name=example-job" ] }
-
-
RequestBody
: The HTTP message body of the Kubernetes REST API operation.-
Type
:JSON
orString
-
Required: No
-
The following includes a Task
state that uses
eks:call
to list the pods belonging to the job
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
}
}
}
Supported Amazon EKS APIs
Supported Amazon EKS APIs and syntax include:
-
-
When an Amazon EKS cluster is created using the
eks:createCluster
service integration, the IAM role is added to the Kubernetes RBAC authorization table as the administrator (with system:masters permissions). Initially, only that IAM entity can make calls to the Kubernetes API server. For more information, see:-
Managing users or IAM roles for your cluster in the Amazon EKS User Guide
-
The Permissions section
Amazon EKS uses service-linked roles which contain the permissions Amazon EKS requires to call other services on your behalf. If these service-linked roles do not exist in your account already, you must add the
iam:CreateServiceLinkedRole
permission to the IAM role used by Step Functions. For more information, see Using Service-Linked Roles in the Amazon EKS User Guide.The IAM role used by Step Functions must have
iam:PassRole
permissions to pass the cluster IAM role to Amazon EKS. For more information, see Amazon EKS cluster IAM role in the Amazon EKS User Guide. -
-
-
You must delete any Fargate profiles or node groups before deleting a cluster.
-
-
Amazon EKS uses service-linked roles which contain the permissions Amazon EKS requires to call other services on your behalf. If these service-linked roles do not exist in your account already, you must add the
iam:CreateServiceLinkedRole
permission to the IAM role used by Step Functions. For more information, see Using Service-Linked Roles in the Amazon EKS User Guide.Amazon EKS on Fargate may not be available in all regions. For information on region availability, see the section on Fargate in the Amazon EKS User Guide.
The IAM role used by Step Functions must have
iam:PassRole
permissions to pass the pod execution IAM role to Amazon EKS. For more information, see Pod execution role in the Amazon EKS User Guide.
-
-
Amazon EKS uses service-linked role whichs contain the permissions Amazon EKS requires to call other services on your behalf. If these service-linked roles do not exist in your account already, you must add the
iam:CreateServiceLinkedRole
permission to the IAM role used by Step Functions. For more information, see Using Service-Linked Roles in the Amazon EKS User Guide.The IAM role used by Step Functions must have
iam:PassRole
permissions to pass the node IAM role to Amazon EKS. For more information, see Using Service-Linked Roles in the Amazon EKS User Guide.
The following includes a Task
that creates an Amazon EKS cluster.
{
"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
}
}
}
The following includes a Task
state that deletes an Amazon EKS
cluster.
{
"StartAt": "DeleteCluster.sync",
"States": {
"DeleteCluster.sync": {
"Type": "Task",
"Resource": "arn:aws:states:::eks:deleteCluster.sync",
"Parameters": {
"Name": "MyCluster"
},
"End": true
}
}
}
The following includes a Task
state that creates a Fargate
profile.
{
"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
}
}
}
The following includes a Task
state that deletes a Fargate
profile.
{
"StartAt": "DeleteFargateProfile.sync",
"States": {
"DeleteFargateProfile.sync": {
"Type": "Task",
"Resource": "arn:aws:states:::eks:deleteFargateProfile.sync",
"Parameters": {
"ClusterName": "MyCluster",
"FargateProfileName": "MyFargateProfile"
},
"End": true
}
}
}
The following includes a Task
state that creates a node group.
{
"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
}
}
}
The following includes a Task
state that deletes a node group.
{
"StartAt": "DeleteNodegroup.sync",
"States": {
"DeleteNodegroup.sync": {
"Type": "Task",
"Resource": "arn:aws:states:::eks:deleteNodegroup.sync",
"Parameters": {
"ClusterName": "MyCluster",
"NodegroupName": "MyNodegroup"
},
"End": true
}
}
}
Permissions
When an Amazon EKS cluster is created using the eks:createCluster
service
integration, the IAM role is added to the Kubernetes RBAC authorization table as
the administrator, with system:masters
permissions. Initially, only
that IAM entity can make calls to the Kubernetes API server. For example, you will
not be able to use kubectl to interact with your Kubernetes API
server, unless you assume the same role as your Step Functions state machine, or if
you
configure Kubernetes to grant permissions to additional IAM entities. For more
information, see Managing users or
IAM roles for your cluster in the Amazon EKS User Guide.
You can add permission for additional IAM entities, such as users or roles, by
adding them to the aws-auth
ConfigMap
in the kube-system namespace. If you are creating your
cluster from Step Functions, use the eks:call
service integration.
The following includes a Task
state that creates an
aws-auth
ConfigMap
and grants system:masters
permission to the
IAM user arn:aws:iam::123456789012:user/my-user
and the IAM role
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
}
}
You may see the ARN for an IAM role displayed in a format that includes the
path /service-role/, such as
arn:aws:iam::123456789012:role/
.
This service-role path token should not be included when
listing the role in service-role
/my-roleaws-auth
.
When your cluster is first created the aws-auth
ConfigMap
will not exist, but will be added automatically if you create
a Fargate profile. You can retrieve the current value of aws-auth
,
add the additional permissions, and PUT
a new version. It is usually
easier to create aws-auth
before the Fargate profile.
If your cluster was created outside of Step Functions, you can configure
kubectl to communicate with your Kubernetes API server.
Then, create a new aws-auth
ConfigMap
using kubectl apply -f aws-auth.yaml
or edit one
that already exists using kubectl edit -n kube-system
configmap/aws-auth
. For more information, see:
-
Create a kubeconfig for Amazon EKS in the Amazon EKS User Guide.
-
Managing users or IAM roles for your cluster in the Amazon EKS User Guide.
If your IAM role does not have sufficient permissions in Kubernetes, the
eks:call
or eks:runJob
service integrations will fail
with the following error:
Error:
EKS.401
Cause:
{
"ResponseBody": {
"kind": "Status",
"apiVersion": "v1",
"metadata": {},
"status": "Failure",
"message": "Unauthorized",
"reason": "Unauthorized",
"code": 401
},
"StatusCode": 401,
"StatusText": "Unauthorized"
}