API AWS ParallelCluster

Qu'est-ce que AWS ParallelCluster l'API ?

AWS ParallelClusterL'API est une application sans serveur qui, une fois déployée sur votre ordinateurCompte AWS, fournit un accès programmatique aux AWS ParallelCluster fonctionnalités via une API.

AWS ParallelClusterL'API est distribuée sous la forme d'un AWS CloudFormationmodèle autonome qui inclut un point de terminaison Amazon API Gateway, qui expose les AWS ParallelCluster fonctionnalités, et une AWS Lambdafonction, qui prend en charge le traitement des fonctionnalités invoquées.

L'image suivante montre un schéma d'architecture de haut niveau de l'infrastructure d'AWS ParallelClusterAPI.

AWS ParallelClusterDocumentation de l'API

Le fichier de spécification OpenAPI décrivant l'AWS ParallelClusterAPI peut être téléchargé à l'adresse suivante :

https://<REGION>-aws-parallelcluster.s3.<REGION>.amazonaws.com/parallelcluster/<VERSION>/api/ParallelCluster.openapi.yaml

À partir du fichier de spécification OpenAPI, vous pouvez générer de la documentation pour l'AWS ParallelClusterAPI en utilisant l'un des nombreux outils disponibles tels que Swagger UI ou Redoc.

Comment déployer une AWS ParallelCluster API

Pour déployer AWS ParallelCluster l'API, vous devez être administrateur duCompte AWS.

Le modèle utilisé pour déployer l'API est disponible à l'adresse URL suivante :

https://<REGION>-aws-parallelcluster.s3.<REGION>.amazonaws.com/parallelcluster/<VERSION>/api/parallelcluster-api.yaml

où se <REGION> trouve l'Région AWSendroit où l'API doit être déployée et quelle <VERSION> est la AWS ParallelCluster version (par exemple 3.7.0).

AWS Lambdatraite les fonctionnalités invoquées par l'API en utilisant une interface de couche Lambda avec le. AWS ParallelClusterAPI de bibliothèque Python

Avertissement

Tout utilisateur duCompte AWS, qui dispose d'un accès privilégié aux AWS Lambda services Amazon API Gateway, hérite automatiquement des autorisations nécessaires pour administrer les ressources de AWS ParallelCluster l'API.

Déployez avec AWS CLI

Configurez les AWS informations d'identification à utiliser avec la CLI si ce n'est déjà fait.

$ aws configure

Exécutez les commandes suivantes pour déployer l'API :

$ REGION=<region>
$ API_STACK_NAME=<stack-name>  # This can be any name
$ VERSION=3.7.0
$ aws cloudformation create-stack \
    --region ${REGION} \
    --stack-name ${API_STACK_NAME} \
    --template-url https://${REGION}-aws-parallelcluster.s3.${REGION}.amazonaws.com/parallelcluster/${VERSION}/api/parallelcluster-api.yaml \
    --capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND
$ aws cloudformation wait stack-create-complete --stack-name ${API_STACK_NAME} --region ${REGION}

Personnalisez votre déploiement

Vous pouvez personnaliser le déploiement de l'API en utilisant les AWS CloudFormation paramètres exposés par le modèle. Pour configurer la valeur d'un paramètre lors du déploiement via la CLI, l'option suivante peut être utilisée : --parameters ParameterKey=KeyName,ParameterValue=Value

Les paramètres suivants sont facultatifs :

• Région : utilisez le Region paramètre pour spécifier si l'API est capable de contrôler les ressources dans toutes Régions AWS (par défaut) ou dans une seuleRégion AWS. Définissez cette valeur sur Région AWS l'API sur laquelle l'API est déployée afin de restreindre l'accès.

• ParallelClusterFunctionRole- Cela remplace le rôle IAM attribué à la AWS Lambda fonction AWS ParallelCluster implémentant les fonctionnalités. Le paramètre accepte l'ARN d'un rôle IAM. Ce rôle doit être configuré pour être utilisé AWS Lambda en tant que principal IAM.

• CustomDomainName,CustomDomainCertificate, CustomDomainHostedZoneId - Utilisez ces paramètres pour définir un domaine personnalisé pour le point de terminaison Amazon API Gateway. CustomDomainNameest le nom du domaine à utiliser, CustomDomainCertificate l'ARN d'un certificat AWS géré pour ce nom de domaine et CustomDomainHostedZoneId l'ID de la zone hébergée Amazon Route 53 dans laquelle vous souhaitez créer des enregistrements.

  Avertissement

  Vous pouvez configurer des paramètres de domaine personnalisés pour appliquer une version minimale du protocole TLS (Transport Layer Security) pour l'API. Pour plus d'informations, consultez Choisir une version minimale de TLS pour un domaine personnalisé dans API Gateway.

• EnableIamAdminAccess- Par défaut, les opérations de l'AWS ParallelClusterAPI de traitement des AWS Lambda fonctions sont configurées avec un rôle IAM qui empêche tout accès IAM privilégié ()EnableIamAdminAccess=false. Cela rend l'API incapable de traiter les opérations qui nécessitent la création de rôles ou de politiques IAM. De ce fait, la création de clusters ou d'images personnalisées n'est réussie que lorsque des rôles IAM sont fournis en entrée dans le cadre de la configuration des ressources.

  Lorsque cette EnableIamAdminAccess option est définie true sur l'AWS ParallelClusterAPI, des autorisations sont accordées pour gérer la création des rôles IAM nécessaires au déploiement de clusters ou à la génération d'AMI personnalisées.

  Avertissement

  La définition de ce paramètre sur true accorde des privilèges d'administrateur IAM aux AWS ParallelCluster opérations de traitement des AWS Lambda fonctions.

  Reportez-vous à AWS ParallelCluster exemples de politiques utilisateur pour la gestion des ressources IAM pour plus de détails sur les fonctionnalités qui peuvent être déverrouillées lors de l'activation de ce mode.

• PermissionsBoundaryPolicy- Ce paramètre facultatif accepte un ARN de politique IAM existant qui sera défini comme limite d'autorisations pour tous les rôles IAM créés par l'infrastructure API PC et comme condition des autorisations IAM administratives afin que seuls les rôles dotés de cette politique puissent être créés par l'API PC.

  Reportez-vous à Mode PermissionsBoundary pour plus de détails sur les restrictions imposées par ce mode.

• CreateApiUserRole- Par défaut, le déploiement de l'AWS ParallelClusterAPI inclut la création d'un rôle IAM défini comme le seul rôle autorisé à appeler l'API. Le point de terminaison Amazon API Gateway est configuré avec une politique basée sur les ressources pour accorder l'autorisation d'appel uniquement à l'utilisateur créé. Pour modifier cela, définissez CreateApiUserRole=false puis accordez l'accès à l'API aux utilisateurs IAM sélectionnés. Pour plus d'informations, consultez la section Contrôler l'accès pour appeler une API dans le manuel Amazon API Gateway Developer Guide.

  Avertissement

  Lorsque l'CreateApiUserRole=trueaccès au point de terminaison de l'API n'est pas limité par les politiques de ressources d'Amazon API Gateway, tous les rôles IAM disposant d'execute-api:Invokeautorisations illimitées peuvent accéder aux fonctionnalités. AWS ParallelCluster Pour plus d'informations, consultez la section Contrôle de l'accès à une API à l'aide des politiques de ressources d'API Gateway dans le Guide du développeur d'API Gateway.

  Avertissement

  ParallelClusterApiUserRoleIl est autorisé à appeler toutes les opérations AWS ParallelCluster d'API. Pour restreindre l'accès à un sous-ensemble de ressources d'API, consultez la méthode Control who can call an API Gateway API gateway avec des politiques IAM dans le guide du développeur d'API Gateway.

• IAM RoleAndPolicyPrefix - Ce paramètre facultatif accepte une chaîne de 10 caractères maximum qui sera utilisée comme préfixe pour les rôles IAM et les politiques créés dans le cadre de l'infrastructure d'API PC.

Mettre à jour l'API

Mise à niveau vers une AWS ParallelCluster version plus récente

Option 1 : supprimez l'API existante en supprimant la AWS CloudFormation pile correspondante et en déployant la nouvelle API comme indiqué ci-dessus.

Option 2 : mettez à jour l'API existante en exécutant les commandes suivantes :

$ REGION=<region>
$ API_STACK_NAME=<stack-name>  # This needs to correspond to the existing API stack name
$ VERSION=3.7.0
$ aws cloudformation update-stack \
    --region ${REGION} \
    --stack-name ${API_STACK_NAME} \
    --template-url https://${REGION}-aws-parallelcluster.s3.${REGION}.amazonaws.com/parallelcluster/${VERSION}/api/parallelcluster-api.yaml \
    --capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND
$ aws cloudformation wait stack-update-complete --stack-name ${API_STACK_NAME} --region ${REGION}

Invocation de AWS ParallelCluster l'API

Le point de terminaison AWS ParallelCluster Amazon API Gateway est configuré avec un type AWS_IAM d'autorisation et nécessite que toutes les demandes soient signées au format SigV4 avec des informations d'identification IAM valides (référence API : envoi de requêtes http).

Lorsqu'elles sont déployées avec les paramètres par défaut, les autorisations d'appel d'API ne sont accordées qu'à l'utilisateur IAM par défaut créé avec l'API.

Pour récupérer l'ARN de l'utilisateur IAM par défaut, exécutez :

$ REGION=<region>
$ API_STACK_NAME=<stack-name>
$ aws cloudformation describe-stacks --region ${REGION} --stack-name ${API_STACK_NAME} --query "Stacks[0].Outputs[?OutputKey=='ParallelClusterApiUserRole'].OutputValue" --output text

Pour obtenir des informations d'identification temporaires pour l'utilisateur IAM par défaut, exécutez la AssumeRole commande STS.

Vous pouvez récupérer le point de terminaison de l'AWS ParallelClusterAPI en exécutant la commande suivante :

$ REGION=<region>
$ API_STACK_NAME=<stack-name>
$ aws cloudformation describe-stacks --region ${REGION} --stack-name ${API_STACK_NAME} --query "Stacks[0].Outputs[?OutputKey=='ParallelClusterApiInvokeUrl'].OutputValue" --output text

L'AWS ParallelClusterAPI peut être invoquée par n'importe quel client HTTP conforme aux spécifications OpenAPI disponibles ici :

https://<REGION>-aws-parallelcluster.s3.<REGION>.amazonaws.com/parallelcluster/<VERSION>/api/ParallelCluster.openapi.yaml

Les demandes doivent être signées au format SigV4, comme indiqué ici.

À l'heure actuelle, nous ne proposons aucune implémentation client API officielle. Cependant, les clients d'API peuvent être facilement générés à partir du modèle OpenAPI à l'aide d'OpenAPI Generator. Une fois le client généré, la signature SigV4 doit être ajoutée si elle n'est pas fournie par défaut.

Une implémentation de référence pour un client d'API Python se trouve dans le AWS ParallelClusterréférentiel. Pour en savoir plus sur l'utilisation du client API Python, consultez le Utilisation de l'API AWS ParallelCluster didacticiel.

Pour mettre en œuvre des mécanismes de contrôle d'accès plus avancés, tels qu'Amazon Cognito ou Lambda Authorizers, ou pour protéger davantage l'API avec AWS WAF des clés d'API, consultez la documentation Amazon API Gateway.

Avertissement

Un utilisateur IAM autorisé à invoquer l'AWS ParallelClusterAPI peut contrôler indirectement toutes les AWS ressources gérées par AWS ParallelCluster leCompte AWS. Cela inclut la création de AWS ressources que l'utilisateur ne peut pas contrôler directement en raison des restrictions de la politique IAM de l'utilisateur. Par exemple, la création d'un AWS ParallelCluster cluster, en fonction de sa configuration, peut inclure le déploiement d'instances Amazon EC2, d'Amazon Route 53, de systèmes de fichiers Amazon Elastic File System, de systèmes de fichiers Amazon FSx, de rôles IAM et de ressources provenant d'autres Services AWS applications sur AWS ParallelCluster lesquelles l'utilisateur n'a peut-être aucun contrôle direct.

Avertissement

Lors de la création d'un cluster avec des paramètres AdditionalIamPolicies spécifiés dans la configuration, les politiques supplémentaires doivent correspondre à l'un des modèles suivants :

- !Sub arn:${AWS::Partition}:iam::${AWS::AccountId}:policy/parallelcluster*
- !Sub arn:${AWS::Partition}:iam::${AWS::AccountId}:policy/parallelcluster/*
- !Sub arn:${AWS::Partition}:iam::aws:policy/CloudWatchAgentServerPolicy
- !Sub arn:${AWS::Partition}:iam::aws:policy/AmazonSSMManagedInstanceCore
- !Sub arn:${AWS::Partition}:iam::aws:policy/AWSBatchFullAccess
- !Sub arn:${AWS::Partition}:iam::aws:policy/AmazonS3ReadOnlyAccess
- !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AWSBatchServiceRole
- !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AmazonEC2ContainerServiceforEC2Role
- !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
- !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AmazonEC2SpotFleetTaggingRole
- !Sub arn:${AWS::Partition}:iam::aws:policy/EC2InstanceProfileForImageBuilder
- !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

Si vous avez besoin d'autres politiques supplémentaires, vous pouvez effectuer l'une des opérations suivantes :

• Modifiez le DefaultParallelClusterIamAdminPolicy dans :

  https://<REGION>-aws-parallelcluster.s3.<REGION>.amazonaws.com/parallelcluster/<VERSION>/api/parallelcluster-api.yaml

  Ajoutez la politique dans la ArnLike/iam:PolicyARN section.

• Omettez de spécifier des politiques AdditionalIamPolicies dans le fichier de configuration et ajoutez manuellement des politiques au rôle d'AWS ParallelClusterinstance créé dans le cluster.

Accès aux journaux et aux métriques de l'API

Les journaux d'API sont publiés sur Amazon CloudWatch avec une durée de conservation de 30 jours. Pour récupérer le LogGroup nom associé à un déploiement d'API, exécutez la commande suivante :

$ REGION=<region>
$ API_STACK_NAME=<stack-name>
$ aws cloudformation describe-stacks --region ${REGION} --stack-name ${API_STACK_NAME} --query "Stacks[0].Outputs[?OutputKey=='ParallelClusterLambdaLogGroup'].OutputValue" --output text

Les métriques Lambda, les journaux et les journaux de AWS X-Raysuivi sont également accessibles via la console Lambda. Pour récupérer l'ARN de la fonction Lambda associée à un déploiement d'API, exécutez la commande suivante :

$ REGION=<region>
$ API_STACK_NAME=<stack-name>
$ aws cloudformation describe-stacks --region ${REGION} --stack-name ${API_STACK_NAME} --query "Stacks[0].Outputs[?OutputKey=='ParallelClusterLambdaArn'].OutputValue" --output text