Llamar a Amazon EKS con Step Functions - AWS Step Functions
Integraciones de API de KubernetesAPI de Amazon EKS compatiblesPermisos

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Llamar a Amazon EKS con Step Functions

Step Functions puede controlar ciertos AWS servicios directamente desde Lenguaje de estados de Amazon (ASL). Para obtener más información, consulte Trabajo con otros servicios y Cómo pasar parámetros a una API de servicio.

En qué se diferencia la integración optimizada de Amazon EKS de la integración del AWS SDK de Amazon EKS

Para obtener información sobre cómo configurar IAM los permisos cuando se utilizan Step Functions con otros AWS servicios, consultePolíticas de IAM para servicios integrados.

Step Functions proporciona dos tipos de API de integración de servicios para integrarse con Amazon Elastic Kubernetes Service. Uno le permite usar las API de Amazon EKS para crear y administrar un clúster de Amazon EKS. El otro le permite interactuar con el clúster mediante la API de Kubernetes y ejecutar trabajos como parte del flujo de trabajo de la aplicación. Puede utilizar las integraciones de la API de Kubernetes con los clústeres de Amazon EKS creados con Step Functions, con los clústeres de Amazon EKS creados con la herramienta eksctl o la consola de Amazon EKS, o métodos similares. Para obtener más información, consulte Creación de un clúster de Amazon EKS en la Guía del usuario de Amazon EKS.

nota

La integración de Step Functions EKS solo admite las API de Kubernetes con acceso a puntos de conexión públicos. De forma predeterminada, los puntos de conexión del servidor API de los clústeres EKS tienen acceso público. Para obtener más información, consulte Control de acceso al punto de conexión del clúster de Amazon EKS en la Guía del usuario de Amazon EKS.

Step Functions no finaliza automáticamente un clúster de Amazon EKS si se detiene la ejecución. Si su máquina de estado se detiene antes de que su clúster de Amazon EKS finalice, es posible que el clúster siga ejecutándose indefinidamente y que se acumulen cargos adicionales. Para evitarlo, asegúrese de que cualquier clúster de Amazon EKS que cree finalice correctamente. Para obtener más información, consulte:

nota

Hay una cuota para el tamaño máximo de los datos de entrada o resultado para una tarea en Step Functions. Esto limita a 256 KB de datos como cadena codificada en UTF-8 al enviar o recibir datos de otro servicio. Consulte Cuotas relacionadas con ejecuciones de máquinas de estado.

Integraciones de API de Kubernetes

Step Functions admite las siguientes API de Kubernetes:

RunJob

La integración del servicio eks:runJob le permite ejecutar un trabajo en el clúster de Amazon EKS. Con la variante eks:runJob.sync, puede esperar a que se complete el trabajo y, opcionalmente, recuperar los registros.

El servidor de la API de Kubernetes debe conceder permisos al rol de IAM que utiliza la máquina de estado. Para obtener más información, consulte Permisos.

Para el patrón Ejecutar un trabajo (.sync), el estado del trabajo se determina mediante un sondeo. Step Functions sondea inicialmente a una velocidad de aproximadamente 1 sondeo por minuto. Con el tiempo, esta velocidad se reduce a aproximadamente 1 encuesta cada 5 minutos. Si necesita sondeos más frecuentes o necesita tener más control sobre la estrategia de sondeo, puede utilizar la integración eks:call para consultar el estado del trabajo.

La integracióneks:runJob es específica de los trabajos de Kubernetes batch/v1. Para obtener más información, consulte Trabajos en la documentación de Kubernetes. Si quiere gestionar otros recursos de Kubernetes, incluidos los recursos personalizados, utilice la integración del servicio eks:call. Puede usar Step Functions para crear bucles de sondeo, como se ilustra en el proyecto de muestra Encuesta sobre el estado del trabajo (Lambda,) AWS Batch.

Entre los parámetros admitidos se incluyen:

  • ClusterName: el nombre del clúster de Amazon EKS al que desea llamar.

    • Type: String

    • Obligatorio: sí

  • CertificateAuthority: los datos de certificados codificados en Base64 necesarios para comunicarse con el clúster. Puede obtener este valor en la consola de Amazon EKS o mediante la DescribeClusterAPI de Amazon EKS.

    • Type: String

    • Obligatorio: sí

  • Endpoint: el punto de conexión del servidor de la API de Kubernetes. Puede obtener este valor en la consola de Amazon EKS o mediante la DescribeClusterAPI de Amazon EKS.

    • Type: String

    • Obligatorio: sí

  • Namespace: el espacio de nombres en el que se ejecutará el trabajo. Si no se proporciona, se utiliza el espacio de nombres default.

    • Type: String

    • Obligatorio: no

  • Job: la definición del trabajo de Kubernetes. Consulte Trabajos en la documentación de Kubernetes.

    • Type: JSON o String

    • Obligatorio: sí

  • LogOptions: un conjunto de opciones para controlar la recuperación opcional de registros. Solo se aplica si se utiliza el patrón de integración del servicio Ejecutar un trabajo (.sync) para esperar a que finalice el trabajo.

    • Type: JSON

    • Obligatorio: no

    • Los registros se incluyen en la respuesta, debajo de la clave logs. Es posible que haya varios pods en la tarea, cada uno con varios contenedores.

      { 
  ...
  "logs": { 
    "pods": { 
      "pod1": { 
        "containers": { 
          "container1": { 
            "log": <log> 
          },
          ...
        }
      },
      ...
    }
  }

    • La recuperación de registros se realiza en la medida de lo posible. Si se produce un error al recuperar un registro, en lugar del campo log aparecerán los campos error y cause.

  • LogOptions.RetrieveLogs: habilite la recuperación del registro una vez finalizado el trabajo. De forma predeterminada, los registros no se recuperan.

    • Type: Boolean

    • Obligatorio: no

  • LogOptions.RawLogs: si RawLogs se establece en true, los registros se devolverán como cadenas brutas sin intentar analizarlos para convertirlos en JSON. De forma predeterminada, los registros se deserializan en JSON si es posible. En algunos casos, este análisis puede introducir cambios no deseados, como limitar la precisión de los números que contienen muchos dígitos.

    • Type: Boolean

    • Obligatorio: no

  • LogOptions.LogParameters: la API Leer registro de Kubernetes admite parámetros de consulta para controlar la recuperación de registros. Por ejemplo, puede usar tailLines o limitBytes para limitar el tamaño de los registros recuperados y permanecer dentro de la cuota de tamaño de datos de Step Functions. Para obtener más información, consulte sección Leer registro de la referencia de la API de Kubernetes.

    • Type: Mapa de String a List of Strings

    • Obligatorio: no

    • Ejemplo:

      "LogParameters": {
  "tailLines": [ "6" ]
}

En el siguiente ejemplo se incluye un estado Task que ejecuta un trabajo, espera a que se complete y, posteriormente, recupera los registros del trabajo:

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

La integración del servicio eks:call le permite usar la API de Kubernetes para leer y escribir objetos de recursos de Kubernetes a través de un punto de conexión de la API de Kubernetes.

El servidor de la API de Kubernetes debe conceder permisos al rol de IAM que utiliza la máquina de estado. Para obtener más información, consulte Permisos.

Para obtener más información sobre estas operaciones disponibles, consulte la Referencia de la API de Kubernetes.

Entre los parámetros admitidos para Call se incluyen:

  • ClusterName: el nombre del clúster de Amazon EKS al que desea llamar.

    • Type: cadena

    • Obligatorio: sí

  • CertificateAuthority: los datos de certificados codificados en Base64 necesarios para comunicarse con el clúster. Puede obtener este valor en la consola de Amazon EKS o mediante la DescribeClusterAPI de Amazon EKS.

    • Type: String

    • Obligatorio: sí

  • Endpoint: el punto de conexión del servidor de la API de Kubernetes. Puede encontrar este valor en la consola de Amazon EKS o mediante la DescribeCluster API de Amazon EKS.

    • Type: String

    • Obligatorio: sí

  • Method: el método HTTP de su solicitud. Puede ser uno de los siguientes: GET, POST, PUT, DELETE, HEAD o PATCH.

    • Type: String

    • Obligatorio: sí

  • Path: la ruta HTTP de la operación de la API de REST de Kubernetes.

    • Type: String

    • Obligatorio: sí

  • QueryParameters: los parámetros de consulta HTTP de la operación de la API de REST de Kubernetes.

    • Type: Mapa de String a List of Strings

    • Obligatorio: no

    • Ejemplo:

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

  • RequestBody: el cuerpo del mensaje HTTP de la operación de la API de REST de Kubernetes.

    • Type: JSON o String

    • Obligatorio: no

El ejemplo siguiente incluye un estado Task que utiliza eks:call para enumerar los pods que pertenecen al trabajo 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
    }
  }
}

El ejemplo siguiente incluye un estado Task que utiliza eks:call para eliminar el trabajo example-job y establece la propagationPolicy para garantizar que también se eliminan los pods del trabajo.

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

API de Amazon EKS compatibles

Las API y la sintaxis de Amazon EKS compatibles incluyen:

El ejemplo siguiente incluye una Task que crea un clúster de 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
    }
  }
}

El ejemplo siguiente incluye un estado Task que elimina un clúster de Amazon EKS.

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

El ejemplo siguiente incluye un estado Task que crea un perfil de 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
    }
  }
}

El ejemplo siguiente incluye un estado Task que elimina un perfil de Fargate.

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

El ejemplo siguiente incluye un estado Task que crea un grupo de nodos.

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

El ejemplo siguiente incluye un estado Task que elimina un grupo de nodos.

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

Permisos

Cuando se crea un clúster de Amazon EKS mediante la integración del servicio eks:createCluster, el rol de IAM se añade a la tabla de autorización de RBAC de Kubernetes como administrador, con permisos system:masters. Inicialmente, solo esa entidad de IAM puede realizar llamadas al servidor de la API de Kubernetes. Por ejemplo, no se podrá usar kubectl para interactuar con el servidor de API de Kubernetes, a menos que se asuma el mismo rol que su máquina de estado de Step Functions o si configura Kubernetes para conceder permisos a entidades de IAM adicionales. Para obtener más información, consulte Administración de usuarios o roles de IAM para su clúster en la Guía del usuario de Amazon EKS.

Puede añadir permisos para entidades de IAM adicionales, como usuarios o roles, añadiéndolas al aws-auth ConfigMap en el espacio de nombres kube-system. Si va a crear el clúster a partir de Step Functions, utilice la integración del servicio eks:call.

El ejemplo siguiente incluye un estado Task que crea un aws-auth ConfigMap y otorga un permiso system:masters al usuario arn:aws:iam::123456789012:user/my-user y al rol de 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
    }
  }
nota

Puede que se vea el ARN de un rol de IAM en un formato que incluya la ruta /service-role/, como arn:aws:iam::123456789012:role/service-role/my-role. Este token de ruta service-role no debe incluirse al enumerar el rol en aws-auth.

Cuando el clúster se crea por primera vez, aws-auth ConfigMap no existirá, sino que se agregará automáticamente si crea un perfil de Fargate. Puede recuperar el valor actual de aws-auth, añadir los permisos adicionales y PUT una nueva versión. Por lo general, es más sencillo crear aws-auth antes que el perfil de Fargate.

Si el clúster se creó fuera de Step Functions, puede configurar kubectl para que se comunique con su servidor de API de Kubernetes. A continuación, se crea un nuevo aws-auth ConfigMap mediante kubectl apply -f aws-auth.yaml o se edita uno que ya exista mediante kubectl edit -n kube-system configmap/aws-auth. Para obtener más información, consulte:

Si el rol de IAM no tiene permisos suficientes en Kubernetes, las integraciones de servicios eks:call o eks:runJob generarán el siguiente error:

Error:
EKS.401

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