Kubernetes API 統合サポートされる Amazon EKS API アクセス許可

Step Functions で Amazon EKS を呼び出す

Step Functions AWS は特定のサービスを Amazon ステートメント言語 (ASL) から直接制御できます。詳細については、「他のサービスでの使用」および「サービス API にパラメータを渡す」を参照してください。

最適化された Amazon EKS インテグレーションと Amazon EKS AWS SDK インテグレーションの違い

ジョブの実行 (.sync) 統合パターンがサポートされています。
レスポンスのリクエスト統合パターンの最適化はありません。
タスクトークンのコールバックまで待機する統合パターンはサポートされていません。

IAMStep Functions AWS 他のサービスと併用する場合のアクセス権限の設定方法については、を参照してください統合サービスの IAM ポリシー。

Step Functions は、Amazon Elastic Kubernetes Service と統合するため、2 種類のサービス統合 API を提供します。1 種類では、Amazon EKS API を使用して Amazon EKS クラスターを作成および管理できます。もう一方では、Kubernetes API を使用してクラスターと対話し、アプリケーションのワークフローの一部としてジョブを実行できるようにします。eksctl ツールまたは Amazon EKS コンソール、または同様の方法によって作成した Amazon EKS クラスターで Step Functions を使って作成した Amazon EKS クラスターとの Kubernetes API 統合を使用できます。詳細については、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 のタスクには入力データまたは結果データの最大サイズにはクォータがあります。これにより、別のサービスとの間でデータを送受信するときに、UTF-8 でエンコードされた文字列として 256 KB のデータに制限されます。ステートマシンの実行に関連するクォータを参照してください。

Kubernetes API 統合

Step Functions は、次の Kubernetes API をサポートしています。

RunJob

eks:runJob サービス統合によって、Amazon EKS クラスターでのジョブ実行が許可されます。eks:runJob.sync バリアントによって、ジョブの完了までの待機とオプションでのログ取得が許可されます。

Kubernetes API サーバーは、ステートマシンで使用される IAM ロールにアクセス権限を付与する必要があります。詳細については、「アクセス許可」を参照してください。

ジョブを実行する (.sync) パターンの場合、ジョブの状態はポーリングによって決定されます。Step Functions は、最初は 1 分あたり約 1 ポーリングの割合でポーリングします。このレートは低速になり、最終的には 5 分ごとに約 1 ポーリングとなります。ポーリングの頻度を増やす必要がある場合、またはこれまでよりもポーリング戦略の制御を行う必要がある場合は、eks:call 統合を使って、ジョブの状態のクエリを出すことができます。

eks:runJob 統合は、batch/v1 Kubernetes ジョブ固有のものです。詳細については、Kubernetes ドキュメントのジョブを参照してください。カスタムリソースを含む他の Kubernetes リソースを管理する場合は、eks:call サービス統合を使用します。Job ステータスの投票 (Lambda、) AWS Batch サンプルプロジェクトで示すように、Step Functions を使用してポーリングループを構築できます。

サポートされるパラメータには次のものが含まれます。

ClusterName: コールしたい Amazon EKS クラスター名。
- Type: String
- 必須: はい
CertificateAuthority: ご自分のクラスターとの通信に必要な Base64 でエンコードされた証明書データ。この値は、Amazon EKS コンソールから、または Amazon EKS DescribeClusterAPI を使用して取得できます。
- Type: String
- 必須: はい
Endpoint: Kubernetes API サーバーのエンドポイント。この値は、Amazon EKS コンソールから、または Amazon EKS DescribeClusterAPI を使用して取得できます。
- Type: String
- 必須: はい
Namespace: ジョブを実行する名前空間。提供されない場合は、名前空間 default が用いられる。
- Type: String
- 必須: いいえ
Job: Kubernetes Job の定義。Kubernetes ドキュメントのジョブを参照してください。
- Type: JSON または String
- 必須: はい
LogOptions: ログのオプションの取得を制御するオプションのセット。[Run a Job] (ジョブの実行) (.sync) サービス統合パターンを使用してジョブの完了を待機するために使われるのが唯一適切です。
- Type: JSON
- 必須: いいえ
- ログはキー logs の下のレスポンスに含まれます。ジョブ内には複数のポッドがあり、それぞれに複数のコンテナがあります。
```
{ 
  ...
  "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 のデータサイズクォータ内に留まります。詳細については、SDK for Go API リファレンスのログを読み取りセクションを参照してください。
- List of Strings への String の Type: マッピング
- 必須: いいえ
- 例：
```
"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 リファレンスを参照してください。

Call 用にサポートされているパラメータには以下が含まれます。

ClusterName: コールしたい Amazon EKS クラスター名。
- Type: 文字列
- 必須: はい
CertificateAuthority: ご自分のクラスターとの通信に必要な Base64 でエンコードされた証明書データ。この値は、Amazon EKS コンソールから、または Amazon EKS DescribeClusterAPI を使用して取得できます。
- Type: String
- 必須: はい
Endpoint: Kubernetes API サーバーのエンドポイント。この値は、Amazon EKS コンソールまたは Amazon EKS の DescribeCluster API を使用して確認できます。
- Type: String
- 必須: はい
Method: リクエストの HTTP メソッド。GET、POST、PUT、DELETE、HEAD、PATCH のいずれかです。
- Type: String
- 必須: はい
Path: Kubernetes REST API オペレーションの HTTP パス。
- Type: String
- 必須: はい
QueryParameters: Kubernetes REST API オペレーションの HTTP クエリパラメーター。
- List of Strings への String の Type: マッピング
- 必須: いいえ
- 例：
```
"QueryParameters": {
  "labelSelector": [ "job-name=example-job" ]
}
```
RequestBody: Kubernetes REST API オペレーションの HTTP メッセージ本文。
- Type: JSON または String
- 必須: いいえ

以下には、eks:call を使用して、ジョブ example-job に所属するポッドをリストする Task 状態が含まれます。


{
  "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 を使用して、ジョブ example-job を削除する Task 状態が含まれ、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 が必要な許可を含むサービスにリンクされたロールを使用します。これらのサービスにリンクされたロールがアカウントにまだ存在しない場合は、Step Functions で使用される IAM ロールに対する iam:CreateServiceLinkedRole 許可を追加する必要があります。詳細については、Amazon EKS ユーザーガイドのサーバーがリンクしたロールを使用を参照してください。
  
  Step Functions が使用する IAM ロールには、クラスタ IAM ロールを Amazon EKS に渡す iam:PassRole 許可がおりている必要があります。詳細については、Amazon EKS ユーザーガイドの Amazon EKS クラスターの IAM ロールを参照してください。
DeleteCluster
- リクエストの構文
- レスポンスの構文
  
  クラスターを削除する前に、Fargate プロファイルまたはノードグループを削除する必要があります。
CreateFargateProfile
- リクエストの構文
- レスポンスの構文
  
  Amazon EKS は、ユーザーに代わって他のサービスを呼び出すために Amazon EKS が必要な許可を含むサービスにリンクされたロールを使用します。これらのサービスにリンクされたロールがアカウントにまだ存在しない場合は、Step Functions で使用される IAM ロールに対する iam:CreateServiceLinkedRole 許可を追加する必要があります。詳細については、Amazon EKS ユーザーガイドのサーバーがリンクしたロールを使用を参照してください。
  
  Fargate 上の Amazon EKS はすべてのリージョンで利用可能なわけではありません。リージョンの可用性の詳細については、Fargate の Amazon EKS ユーザーガイドの Fargate に関するセクションを参照してください。
  
  Step Functions で使用されている IAM ロールには、ポッド実行 IAM ロールを Amazon EKS に渡す iam:PassRole 許可が必要です。詳細については、Amazon EKS ユーザーガイドのポッド実行ロールを参照してください。
DeleteFargateProfile
- リクエストの構文
- レスポンスの構文
CreateNodegroup
- リクエストの構文
- レスポンスの構文
  
  Amazon ECS は、お客様に代わって Amazon EKS がその他のサービスを呼び出すために必要な許可を含むサービスにリンクされたロールを使用します。これらのサービスにリンクされたロールがアカウントにまだ存在しない場合は、Step Functions で使用される IAM ロールに対する iam:CreateServiceLinkedRole 許可を追加する必要があります。詳細については、Amazon EKS ユーザーガイドのサーバーがリンクしたロールを使用を参照してください。
  
  Step Functions で使用される IAM ロールには、ノード IAM ロールを Amazon EKS に渡すため iam:PassRole 許可が必要です。詳細については、Amazon EKS ユーザーガイドのサーバーがリンクしたロールを使用を参照してください。
DeleteNodegroup
- リクエストの構文
- レスポンスの構文

以下には Amazon EKS クラスターを作成する Task が含まれています。


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

以下には Fargate プロファイルを作成する Task 状態が含まれています。


{
  "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 ロールを system:masters 許可を受けた管理者として、Kubernetes RBAC 認可テーブルに追加されています。初期状態では、その IAM エンティティのみが、Kubernetes API サーバーを呼び出すことができます。例えば、Step Functions ステートマシンと同じロールを引き受けるのでなければ、または追加の IAM エンティティに許可を付与するように Kubernetes を構成している場合は、kubectl を使用して、Kubernetes API と対話することはできません。詳細については、Amazon EKS ユーザーガイドのクラスター用ユーザーまたは IAM ロールを管理を参照してください。

kube-system 名前空間の中の aws-auth ConfigMap に追加して、ユーザーまたはロールなど、追加 IAM エンティティの許可を追加できます。Step Functions からクラスターを作成する場合は、eks:call サービス統合を使用します。

以下には、aws-auth ConfigMap を作成し、ユーザー arn:aws:iam::123456789012:user/my-user と IAM ロール arn:aws:iam::123456789012:role/my-role に system:masters 許可を付与する Task 状態が含まれます。


{
  "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 などのパス /service-role/ を含む形式で表示されるのをご覧になるかもしれません。aws-auth でロールを一覧表示するときは、この service-role パストークンを含めないでください。

クラスターが最初に作成されるときは、aws-auth ConfigMap は存在しませんが、Fargate プロファイルを作成すると、自動的に追加されます。aws-auth の現在の値を取得し、追加許可を追加し、新しいバージョンを PUT します。通常、Fargate プロファイルの前に aws-auth を作成するほうが簡単です。

Step Functions の外部でクラスターが作成された場合は、kubectl を設定して、Kubernetes API サーバーと通信します。次に、kubectl apply -f aws-auth.yaml を使って新しい aws-auth ConfigMap を作成します。または、kubectl edit -n kube-system configmap/aws-auth を使用して既に存在するものを編集します。詳細については、以下を参照してください。

Amazon EKS ユーザーガイドの Amazon EKS 用 kubeconfig を作成します。
Amazon EKS ユーザーガイドのクラスターのユーザーまたは IAM ロールを管理。

Kubernetes で IAM ロールに十分な許可がない場合、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 が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

Amazon EMR on EKS

Amazon EMR Serverless