Step Functions を使用して Amazon EKSクラスターを作成および管理する - AWS Step Functions
Kubernetes API統合サポートされている Amazon EKS APIsアクセス許可IAM ポリシー

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Step Functions を使用して Amazon EKSクラスターを作成および管理する

Step Functions を Amazon と統合EKSして Kubernetes クラスターを管理する方法について説明します。Step Functions には、Amazon Elastic Kubernetes Service と統合APIsするための 2 種類のサービス統合が用意されています。1 つの では、Amazon EKS APIs を使用して Amazon EKSクラスターを作成および管理できます。もう 1 つは、Kubernetes を使用してクラスターを操作しAPI、アプリケーションのワークフローの一部としてジョブを実行することを可能にします。

Step Functions を使用して作成された Amazon EKSクラスター、eksctl ツールまたは Amazon EKSコンソールによって作成された Amazon EKSクラスター、または同様のメソッドとの Kubernetes API統合を使用できます。詳細については、「Amazon ユーザーガイド」の「Amazon EKSクラスターの作成」を参照してください。 EKS

Step Functions での AWS サービスとの統合については、 サービスとの統合「」および「」を参照してくださいStep Functions APIのサービスへのパラメータの受け渡し。

最適化された Amazon EKS統合の主な機能
注記

Step Functions EKS統合は、パブリックエンドポイントアクセスAPIsを持つ Kubernetes のみをサポートします。デフォルトでは、EKSクラスターAPIサーバーエンドポイントにはパブリックアクセスがあります。詳細については、「Amazon ユーザーガイド」の「Amazon EKSクラスターエンドポイントのアクセスコントロール」を参照してください。 EKS

実行が停止しても、Step Functions は Amazon EKSクラスターを自動的に終了しません。Amazon EKSクラスターが終了する前にステートマシンが停止した場合、クラスターは無期限に実行され続け、追加料金が発生する可能性があります。これを回避するには、作成した Amazon EKSクラスターが適切に終了していることを確認します。詳細については、以下を参照してください。

注記

Step Functions のタスクには入力データまたは結果データの最大サイズにはクォータがあります。これにより、別のサービスとの間でデータを送受信するときに、UTF-8 でエンコードされた文字列として 256 KiB のデータに制限されます。「ステートマシンの実行に関連するクォータ」を参照してください。

Kubernetes API統合

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

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 サービス統合を使用します。Lambda と でジョブステータスをポーリングする AWS Batch サンプルプロジェクトで示すように、Step Functions を使用してポーリングループを構築できます。

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

  • ClusterName: 呼び出す Amazon EKSクラスターの名前。

    • Type: String

    • 必須: はい

  • CertificateAuthority: ご自分のクラスターとの通信に必要な Base64 でエンコードされた証明書データ。この値は、Amazon EKSコンソールから、または Amazon EKS DescribeCluster を使用して取得できますAPI。

    • Type: String

    • 必須: はい

  • Endpoint: Kubernetes URL APIサーバーのエンドポイント。この値は、Amazon EKSコンソールから、または Amazon EKS DescribeCluster を使用して取得できますAPI。

    • 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 に設定されている場合、ログは に解析せずに raw 文字列として返されますJSON。デフォルトでは、ログはJSON可能であれば に逆シリアル化されます。場合によっては、このような解析によって、多くの桁数を含む数値の精度を制限するなど、望ましくない変更を導入しかねません。

    • Type: Boolean

    • 必須: いいえ

  • LogOptions.LogParameters: Kubernetes APIの読み取りログは、ログの取得を制御するクエリパラメータAPIをサポートします。例えば、tailLines または limitBytes を使用して、取得したログのサイズを制限し、Step Functions のデータサイズクォータ内に留まります。詳細については、Kubernetes 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 エンドポイントを介して Kubernetes リソースオブジェクトのAPI読み取りと書き込みを行うことができますAPI。

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

使用可能なオペレーションの詳細については、Kubernetes APIリファレンスを参照してください。

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

  • ClusterName: 呼び出す Amazon EKSクラスターの名前。

    • Type: 文字列

    • 必須: はい

  • CertificateAuthority: ご自分のクラスターとの通信に必要な Base64 でエンコードされた証明書データ。この値は、Amazon EKSコンソールから、または Amazon EKS DescribeCluster を使用して取得できますAPI。

    • Type: String

    • 必須: はい

  • Endpoint: Kubernetes URL APIサーバーのエンドポイント。この値は、Amazon EKSコンソールまたは Amazon EKS' を使用して確認できます DescribeCluster API。

    • Type: String

    • 必須: はい

  • Method: リクエストのHTTPメソッド。GET、POST、PUT、DELETE、HEAD、PATCH のいずれかです。

    • Type: String

    • 必須: はい

  • Path: Kubernetes RESTAPIオペレーションのHTTPパス。

    • Type: String

    • 必須: はい

  • QueryParameters: Kubernetes RESTAPIオペレーションのHTTPクエリパラメータ。

    • List of Strings への String の Type: マッピング

    • 必須: いいえ

    • 例:

      "QueryParameters": {
  "labelSelector": [ "job-name=example-job" ]
}

  • RequestBody: Kubernetes RESTAPIオペレーションの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 APIs

サポートされている Amazon EKSAPIsおよび 構文は次のとおりです。

以下には、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ロールは管理者として Kubernetes RBAC認可テーブルに追加され、アクセスsystem:masters許可が付与されます。最初は、そのIAMエンティティのみが Kubernetes APIサーバーを呼び出すことができます。たとえば、Step Functions ステートマシンと同じロールを引き受けない限り、または追加のIAMエンティティにアクセス許可を付与するように Kubernetes を設定しない限り、kubectl を使用して Kubernetes APIサーバーとやり取りすることはできません。詳細については、「Amazon EKSユーザーガイド」の「クラスターのユーザーまたはIAMロールの管理」を参照してください。

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

以下には、 を作成し、ユーザー aws-auth ConfigMap arn:aws:iam::123456789012:user/my-userとIAMロール にアクセスsystem:masters許可を付与する Task 状態が含まれています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
    }
  }
注記

などのパス /service-role/ を含む形式で表示される IAMロールARNの が表示される場合がありますarn:aws:iam::123456789012:role/service-role/my-role。aws-auth でロールを一覧表示するときは、この service-role パストークンを含めないでください。

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

クラスターが Step Functions の外部で作成された場合は、Kubernetes APIサーバーと通信するように kubectl を設定できます。次に、kubectl apply -f aws-auth.yaml を使って新しい aws-auth ConfigMap を作成します。または、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"
}

IAM Amazon を呼び出すための ポリシー EKS

次のサンプルテンプレートは、 がステートマシン定義のリソースに基づいてIAMポリシー AWS Step Functions を生成する方法を示しています。詳細については、Step Functions が統合サービスの IAM ポリシーを生成する方法およびStep Functions でサービス統合パターンを検出するを参照してください。

CreateCluster

リソース

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "eks:CreateCluster"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "eks:DescribeCluster",
                "eks:DeleteCluster"
            ],
            "Resource": "arn:aws:eks:sa-east-1:444455556666:cluster/*"
        },
        {
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": [
                "arn:aws:iam::444455556666:role/StepFunctionsSample-EKSClusterManag-EKSServiceRole-ANPAJ2UCCR6DPCEXAMPLE"
            ],
            "Condition": {
                "StringEquals": {
                    "iam:PassedToService": "eks.amazonaws.com"
                }
            }
        }
    ]
}

CreateNodeGroup

リソース

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeSubnets",
                "eks:CreateNodegroup"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "eks:DescribeNodegroup",
                "eks:DeleteNodegroup"
            ],
            "Resource": "arn:aws:eks:sa-east-1:444455556666:nodegroup/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:GetRole",
                "iam:ListAttachedRolePolicies"
            ],
            "Resource": "arn:aws:iam::444455556666:role/*"
        },
        {
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": [
                "arn:aws:iam::444455556666:role/StepFunctionsSample-EKSClusterMan-NodeInstanceRole-ANPAJ2UCCR6DPCEXAMPLE"
            ],
            "Condition": {
                "StringEquals": {
                    "iam:PassedToService": "eks.amazonaws.com"
                }
            }
        }
    ]
}

DeleteCluster

リソース

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "eks:DeleteCluster",
                "eks:DescribeCluster"
            ],
            "Resource": [
                "arn:aws:eks:sa-east-1:444455556666:cluster/ExampleCluster"
            ]
        }
    ]
}

DeleteNodegroup

リソース

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "eks:DeleteNodegroup",
                "eks:DescribeNodegroup"
            ],
            "Resource": [
                "arn:aws:eks:sa-east-1:444455556666:nodegroup/ExampleCluster/ExampleNodegroup/*"
            ]
        }
    ]
}

Step Functions EKSで Amazon を使用する方法の詳細については、「」を参照してくださいStep Functions を使用して Amazon EKSクラスターを作成および管理する。