Utilisation d'Amazon SNS pour créer des ressources personnalisées

Ressources personnalisées soutenues par Amazon SNS

La rubrique suivante explique comment configurer une ressource personnalisée avec un jeton de service qui indique la rubrique Amazon SNS à laquelle les demandes sont CloudFormation envoyées. Vous apprenez également la séquence des événements et des messages envoyés et reçus à la suite de la création, de la mise à jour et de la suppression d'une pile de ressources personnalisée.

Les ressources personnalisées et Amazon SNS vous permettent d'activer des scénarios, tels que l'ajout de nouvelles ressources à une pile et l'injection de données dynamiques dans une pile. Par exemple, lorsque vous créez une pile, vous CloudFormation pouvez envoyer une Create demande à un sujet surveillé par une application exécutée sur une instance Amazon EC2. La notification Amazon SNS incite l'application à exécuter les tâches d'allocation supplémentaires, telles que la récupération d'un groupe d'adresses IP Elastic autorisées. Une fois cela fait, l'application envoie une réponse (et toutes les données de sortie) qui indique CloudFormation de poursuivre l'opération de pile.

Lorsque vous spécifiez une rubrique Amazon SNS comme cible d'une ressource personnalisée, CloudFormation vous envoyez des messages à la rubrique SNS spécifiée pendant les opérations de stack impliquant la ressource personnalisée. Pour traiter ces messages et effectuer les actions nécessaires, vous devez disposer d'un point de terminaison compatible abonné à la rubrique SNS.

Pour une présentation des ressources personnalisées et de leur fonctionnement, voirRessources personnalisées. Pour plus d'informations sur Amazon SNS et son fonctionnement, consultez le guide du développeur Amazon Simple Notification Service.

Étape 1 : Création de la pile

Le développeur du modèle crée une CloudFormation pile contenant une ressource personnalisée.

Dans l'exemple de modèle ci-dessous, nous utilisons le nom du type de ressource personnalisé Custom::SeleniumTester pour la ressource personnalisée avec un ID logiqueMySeleniumTest. Le nom des types de ressources personnalisées doit être alphanumérique et ne doit pas dépasser 60 caractères.

Le type de ressource personnalisé est déclaré avec un jeton de service, des propriétés facultatives spécifiques au fournisseur et des Fn::GetAtt attributs facultatifs définis par le fournisseur de ressources personnalisées. Ces propriétés et ces attributs peuvent être utilisés pour transmettre les informations du template developer au custom resource provider, et vice versa. Le jeton de service spécifie une rubrique Amazon SNS configurée par le fournisseur de ressources.
```
{
   "AWSTemplateFormatVersion" : "2010-09-09",
   "Resources" : {
      "MySeleniumTest" : {
         "Type": "Custom::SeleniumTester",
         "Version" : "1.0",
         "Properties" : {
            "ServiceToken": "arn:aws:sns:us-west-2:123456789012:CRTest",
            "seleniumTester" : "SeleniumTest()",
            "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ],
            "frequencyOfTestsPerHour" : [ "3", "2", "4" ]
         }
      }
   },
   "Outputs" : {
      "topItem" : {
         "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] }
      },
      "numRespondents" : {
         "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] }
      }
   }
}
```
Note
Les noms et les valeurs des données accessibles avec Fn::GetAtt sont renvoyés par le fournisseur de ressources personnalisées lors de la réponse du fournisseur à CloudFormation. Si le custom resource provider est un tiers, le template developer doit obtenir les noms de ces valeurs de retour auprès du custom resource provider.
CloudFormation envoie une Amazon SNS notification au fournisseur de ressources "RequestType" : "Create" contenant des informations sur la pile, les propriétés de ressources personnalisées du modèle de pile et une URL S3 pour la réponse.

La rubrique SNS qui est utilisée pour envoyer la notification est intégrée dans la propriété ServiceToken du modèle. Pour éviter les valeurs codées en dur, un template developer peut utiliser un paramètre de modèle de sorte que la valeur soit entrée lors du lancement de la pile.

L'exemple suivant présente une requête de création de ressource personnalisée (Create), qui inclut un nom de type de ressource personnalisée, Custom::SeleniumTester, créé avec la valeur LogicalResourceId MySeleniumTester :
```
{
   "RequestType" : "Create",
   "ResponseURL" : "http://pre-signed-S3-url-for-response",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
   "RequestId" : "unique id for this create request",
   "ResourceType" : "Custom::SeleniumTester",
   "LogicalResourceId" : "MySeleniumTester",
   "ResourceProperties" : {
      "seleniumTester" : "SeleniumTest()",
      "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ],
      "frequencyOfTestsPerHour" : [ "3", "2", "4" ]
   }
}
```
Pour des informations détaillées sur l'objet de demande pour les Create demandes, consultez la Création rubrique.
Le custom resource provider traite les données envoyées par le template developer et détermine si la demande Create a réussi. Le fournisseur de ressources utilise ensuite l'URL S3 envoyée par CloudFormation pour envoyer une réponse de l'un SUCCESS ou de l'autreFAILED.

Selon le type de réponse, différents champs de réponse seront attendus par CloudFormation. Pour plus d'informations sur les champs de réponse pour un type de demande particulier, consultez la documentation relative à ce type de demande dans la Types de demandes de ressource personnalisée section.

En réponse à une demande de création ou de mise à jour, le custom resource provider peut renvoyer des éléments de données dans le champ Data de la réponse. Il s'agit de paires nom-valeur, où les noms correspondent aux attributs Fn::GetAtt utilisés avec la ressource personnalisée dans le modèle de la pile. Les valeurs sont les données qui sont renvoyées quand le template developer appelle Fn::GetAtt au niveau de la ressource avec le nom d'attribut.

Voici un exemple de réponse de ressource personnalisée :
```
{
   "Status" : "SUCCESS",
   "PhysicalResourceId" : "Tester1",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
   "RequestId" : "unique id for this create request",
   "LogicalResourceId" : "MySeleniumTester",
   "Data" : {
      "resultsPage" : "http://www.myexampledomain/test-results/guid",
      "lastUpdate" : "2012-11-14T03:30Z"
   }
}
```
Pour des informations détaillées sur l'objet de réponse pour les Create demandes, consultez la Création rubrique.

Les champs StackId, RequestId et LogicalResourceId doivent être copiés mot pour mot à partir de la demande.
CloudFormation déclare le statut de la pile comme CREATE_COMPLETE ouCREATE_FAILED. Si la pile a été créée avec succès, le template developer peut utiliser les valeurs de sortie de la ressource personnalisée créée en y accédant avec Fn::GetAtt.

Par exemple, le modèle de ressource personnalisée utilisé à titre d'illustration a eu recours à Fn::GetAtt pour copier les sorties des ressources dans les sorties de la pile :
```
"Outputs" : {
   "topItem" : {
      "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] }
   },
   "numRespondents" : {
      "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] }
   }
}
```

Étape 2 : Mises à jour d'une pile

Pour mettre à jour une pile existante, vous devez soumettre un modèle qui spécifie les mises à jour des propriétés des ressources de la pile, comme indiqué dans l'exemple ci-dessous. CloudFormationmet à jour uniquement les ressources dont les modifications sont spécifiées dans le modèle. Pour plus d'informations sur la mise à jour des piles, consultez AWS CloudFormation mises à jour des piles.

Vous pouvez mettre à jour les ressources personnalisées qui nécessitent un remplacement de la ressource physique sous-jacente. Lorsque vous mettez à jour une ressource personnalisée dans un CloudFormation modèle, CloudFormation envoie une demande de mise à jour à cette ressource personnalisée. Si une ressource personnalisée nécessite un remplacement, la nouvelle ressource personnalisée doit envoyer une réponse avec le nouvel ID physique. Lorsqu'il CloudFormation reçoit la réponse, il compare PhysicalResourceId les anciennes et les nouvelles ressources personnalisées. S'ils sont différents, CloudFormation reconnaît la mise à jour comme un remplacement et envoie une demande de suppression à l'ancienne ressource, comme indiqué dansÉtape 3 : Suppression d'une pile.

Note

Si vous n'avez pas apporté de modifications à la ressource personnalisée, vous CloudFormation ne lui enverrez pas de demandes lors d'une mise à jour de la pile.

Le template developer lance une mise à jour de la pile qui contient une ressource personnalisée. Pendant une mise à jour, le template developer peut spécifier de nouvelles propriétés dans le modèle de la pile.

Voici un exemple de mise à jour (Update) apportée au modèle de la pile à l'aide d'un type de ressource personnalisée :


{
   "AWSTemplateFormatVersion" : "2010-09-09",
   "Resources" : {
      "MySeleniumTest" : {
         "Type": "Custom::SeleniumTester",
         "Version" : "1.0",
         "Properties" : {
            "ServiceToken": "arn:aws:sns:us-west-2:123456789012:CRTest",
            "seleniumTester" : "SeleniumTest()",
            "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com",
               "http://mynewsite.com" ],
            "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ]
         }
      }
   },
   "Outputs" : {
      "topItem" : {
         "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] }
      },
      "numRespondents" : {
         "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] }
      }
   }
}

CloudFormation envoie une Amazon SNS notification au fournisseur de ressources contenant des informations similaires à celles de l'Createappel, sauf que le OldResourceProperties champ contient les anciennes propriétés des ressources et ResourceProperties contient les propriétés des ressources mises à jour (le cas échéant). "RequestType" : "Update"

Voici un exemple de requête Update :


{
   "RequestType" : "Update",
   "ResponseURL" : "http://pre-signed-S3-url-for-response",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
   "RequestId" : "uniqueid for this update request",
   "LogicalResourceId" : "MySeleniumTester",
   "ResourceType" : "Custom::SeleniumTester",  
   "PhysicalResourceId" : "Tester1",
   "ResourceProperties" : {
      "seleniumTester" : "SeleniumTest()",
      "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com",
         "http://mynewsite.com" ],
      "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ]
   },
   "OldResourceProperties" : {
      "seleniumTester" : "SeleniumTest()",
      "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ],
      "frequencyOfTestsPerHour" : [ "3", "2", "4" ]
   }
}

Pour des informations détaillées sur l'objet de demande pour les Update demandes, consultez la Mettre à jour rubrique.

Le fournisseur de ressources personnalisées traite les données envoyées par CloudFormation. La ressource personnalisée effectue la mise à jour et envoie une réponse à l'URL S3 SUCCESS ou FAILED à cette adresse. CloudFormation compare ensuite les PhysicalResourceIDs anciennes et les nouvelles ressources personnalisées. S'ils sont différents, CloudFormation reconnaît que la mise à jour doit être remplacée et envoie une demande de suppression à l'ancienne ressource. L'exemple suivant présente la réponse du custom resource provider à une demande Update.
```
{
   "Status" : "SUCCESS",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
   "RequestId" : "uniqueid for this update request",
   "LogicalResourceId" : "MySeleniumTester",
   "PhysicalResourceId" : "Tester2"
}
```
Pour des informations détaillées sur l'objet de réponse pour les Update demandes, consultez la Mettre à jour rubrique.

Les champs StackId, RequestId et LogicalResourceId doivent être copiés mot pour mot à partir de la demande.
CloudFormation déclare le statut de la pile comme UPDATE_COMPLETE ouUPDATE_FAILED. En cas d'échec de la mise à jour, la pile est restaurée. Si la pile a bien été mise à jour, le template developer peut accéder aux nouvelles valeurs de sortie de la ressource personnalisée créée avec Fn::GetAtt.

Étape 3 : Suppression d'une pile

Le développeur du modèle supprime une pile contenant une ressource personnalisée. CloudFormationobtient les propriétés actuelles spécifiées dans le modèle de pile ainsi que la rubrique SNS, et prépare une demande au fournisseur de ressources personnalisées.
CloudFormation envoie une Amazon SNS notification au fournisseur de ressources "RequestType" : "Delete" contenant des informations actuelles sur la pile, les propriétés de ressources personnalisées du modèle de pile et une URL S3 pour la réponse.

Chaque fois que vous supprimez une pile ou effectuez une mise à jour qui supprime ou remplace la ressource personnalisée CloudFormation , PhysicalResourceId comparez les anciennes et les nouvelles ressources personnalisées. S'ils sont différents, CloudFormation reconnaît la mise à jour comme un remplacement et envoie une demande de suppression pour l'ancienne ressource (OldPhysicalResource), comme illustré dans l'exemple de Delete demande suivant.
```
{
   "RequestType" : "Delete",
   "ResponseURL" : "http://pre-signed-S3-url-for-response",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
   "RequestId" : "unique id for this delete request",
   "ResourceType" : "Custom::SeleniumTester",
   "LogicalResourceId" : "MySeleniumTester",
   "PhysicalResourceId" : "Tester1",
   "ResourceProperties" : {
      "seleniumTester" : "SeleniumTest()",
      "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com",
         "http://mynewsite.com" ],
      "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ]
   }
}
```
Pour des informations détaillées sur l'objet de demande pour les Delete demandes, consultez la Suppression rubrique.

DescribeStackResource, DescribeStackResources, et ListStackResources affiche le nom défini par l'utilisateur, s'il a été spécifié.
Le fournisseur de ressources personnalisées traite les données envoyées par CloudFormation et détermine si la Delete demande a abouti. Le fournisseur de ressources utilise ensuite l'URL S3 envoyée par CloudFormation pour envoyer une réponse de l'un SUCCESS ou de l'autreFAILED. Pour supprimer une pile avec une ressource personnalisée, le custom resource provider doit répondre avec succès à une demande de suppression.

Voici un exemple de réponse du custom resource provider à une demande Delete :
```
{
   "Status" : "SUCCESS",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
   "RequestId" : "unique id for this delete request",
   "LogicalResourceId" : "MySeleniumTester",
   "PhysicalResourceId" : "Tester1"
}
```
Pour des informations détaillées sur l'objet de réponse pour les Delete demandes, consultez la Suppression rubrique.

Les champs StackId, RequestId et LogicalResourceId doivent être copiés mot pour mot à partir de la demande.
CloudFormation déclare le statut de la pile comme DELETE_COMPLETE ouDELETE_FAILED.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Ressources personnalisées

Ressources personnalisées soutenues par Lambda