CloudFormation riferimento personalizzato alla richiesta e alla risposta delle risorse - AWS CloudFormation
Configurazione del modelloOggetto RequestOggetto Response

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

CloudFormation riferimento personalizzato alla richiesta e alla risposta delle risorse

CloudFormation gestisce le risorse personalizzate tramite un protocollo di richiesta-risposta che comunica con il fornitore di risorse personalizzato. Ogni richiesta include un tipo di richiesta (CreateUpdate, oDelete) e segue questo flusso di lavoro di alto livello:

  1. Uno sviluppatore di modelli definisce una risorsa personalizzata con un ServiceToken e ServiceTimeout nel modello e avvia un'operazione di stack.

  2. CloudFormation invia una richiesta JSON al provider di risorse personalizzato tramite SNS o Lambda.

  3. Il provider di risorse personalizzato elabora la richiesta e restituisce una risposta JSON a un URL del bucket Amazon S3 predefinito prima della scadenza del periodo di timeout.

  4. CloudFormation legge la risposta e procede con l'operazione stack. Se non viene ricevuta alcuna risposta prima della fine del periodo di timeout, la richiesta viene considerata non riuscita e l'operazione di stack ha esito negativo.

Per ulteriori informazioni, consulta Funzionamento delle risorse personalizzate.

Questa sezione descrive la struttura, i parametri e le risposte previste per ogni tipo di richiesta.

Nota

La dimensione totale del corpo della risposta non può superare 4096 byte.

Configurazione del modello

Quando definisce una risorsa personalizzata in un modello, lo sviluppatore del modello utilizza AWS::CloudFormation::CustomResourcele seguenti proprietà:

ServiceToken

ARN dell'argomento Amazon SNS o ARN della funzione Lambda della stessa regione dello stack.

Campo obbligatorio: sì

▬Tipo: stringa

ServiceTimeout

Il tempo massimo, in secondi, prima del timeout di un'operazione su una risorsa personalizzata. Deve essere un valore compreso tra 1 e 3600. Impostazione predefinita: 3600 secondi (1 ora).

Required: No

▬Tipo: stringa

Sono supportate proprietà aggiuntive delle risorse. Le proprietà delle risorse verranno incluse come ResourceProperties nella richiesta. Il fornitore di risorse personalizzate deve determinare quali proprietà sono valide e i relativi valori accettabili.

Oggetto Request

Create

Quando lo sviluppatore del modello crea uno stack contenente una risorsa personalizzata, CloudFormation invia una richiesta con RequestType set toCreate.

Le richieste di creazione contengono i seguenti campi:

RequestType

Create.

Campo obbligatorio: sì

▬Tipo: stringa

RequestId

Un ID univoco per la richiesta.

La combinazione di StackId con RequestId costituisce un valore che puoi utilizzare per identificare in modo univoco una richiesta in una particolare risorsa personalizzata.

Campo obbligatorio: sì

▬Tipo: stringa

StackId

Il nome della risorsa Amazon (ARN) che identifica lo stack che contiene la risorsa personalizzata.

La combinazione di StackId con RequestId costituisce un valore che puoi utilizzare per identificare in modo univoco una richiesta in una particolare risorsa personalizzata.

Campo obbligatorio: sì

▬Tipo: stringa

ResponseURL

L'URL di risposta identifica un bucket S3 predefinito che riceve risposte dal fornitore di risorse personalizzato a. CloudFormation

Campo obbligatorio: sì

▬Tipo: stringa

ResourceType

Il tipo di risorsa scelta dallo sviluppatore del modello della risorsa personalizzata nel modello CloudFormation . I nomi dei tipi di risorsa personalizzata possono contenere fino a 60 caratteri e possono includere caratteri alfanumerici, oltre ai caratteri seguenti: _@-.

Campo obbligatorio: sì

▬Tipo: stringa

LogicalResourceId

Il nome (ID logico) scelto dallo sviluppatore del modello della risorsa personalizzata nel modello CloudFormation .

Campo obbligatorio: sì

▬Tipo: stringa

ResourceProperties

Questo campo contiene il contenuto dell’oggetto Properties inviato dallo sviluppatore del modello. I suoi contenuti vengono definiti dal provider di risorse personalizzate.

Required: No

Tipo: JSON object

Esempio

{
   "RequestType" : "Create",
   "RequestId" : "unique-request-id",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id",
   "ResponseURL" : "pre-signed-url-for-create-response",
   "ResourceType" : "Custom::MyCustomResourceType",
   "LogicalResourceId" : "resource-logical-id",
   "ResourceProperties" : {
      "key1" : "string",
      "key2" : [ "list" ],
      "key3" : { "key4" : "map" }
   }
}
Update

Quando lo sviluppatore del modello apporta modifiche alle proprietà di una risorsa personalizzata all'interno del modello e aggiorna lo stack, CloudFormation invia una richiesta al fornitore di risorse personalizzate con set to. RequestType Update Questo significa che il codice della risorsa personalizzata non deve rilevare le modifiche nelle risorse perché sa che le proprietà sono state modificate quando il tipo di richiesta è Update.

Le richieste di aggiornamento contengono i seguenti campi:

RequestType

Update.

Campo obbligatorio: sì

▬Tipo: stringa

RequestId

Un ID univoco per la richiesta.

La combinazione di StackId con RequestId costituisce un valore che puoi utilizzare per identificare in modo univoco una richiesta in una particolare risorsa personalizzata.

Campo obbligatorio: sì

▬Tipo: stringa

StackId

Il nome della risorsa Amazon (ARN) che identifica lo stack che contiene la risorsa personalizzata.

La combinazione di StackId con RequestId costituisce un valore che puoi utilizzare per identificare in modo univoco una richiesta in una particolare risorsa personalizzata.

Campo obbligatorio: sì

▬Tipo: stringa

ResponseURL

L'URL di risposta identifica un bucket S3 predefinito che riceve risposte dal provider di risorse personalizzato a. CloudFormation

Campo obbligatorio: sì

▬Tipo: stringa

ResourceType

Il tipo di risorsa scelta dallo sviluppatore del modello della risorsa personalizzata nel modello CloudFormation . I nomi dei tipi di risorsa personalizzata possono contenere fino a 60 caratteri e possono includere caratteri alfanumerici, oltre ai caratteri seguenti: _@-. Non puoi modificare il tipo durante un aggiornamento.

Campo obbligatorio: sì

▬Tipo: stringa

LogicalResourceId

Il nome (ID logico) scelto dallo sviluppatore del modello della risorsa personalizzata nel modello CloudFormation .

Campo obbligatorio: sì

▬Tipo: stringa

PhysicalResourceId

Un ID fisico personalizzato definito dal provider di risorse che è unico per quel provider.

Campo obbligatorio: sì

▬Tipo: stringa

ResourceProperties

Questo campo contiene il contenuto dell’oggetto Properties inviato dallo sviluppatore del modello. I suoi contenuti vengono definiti dal provider di risorse personalizzate.

Required: No

Tipo: JSON object

OldResourceProperties

Usato solo per le richieste Update. I valori della proprietà della risorsa dichiarati precedentemente dal template developer nel modello CloudFormation .

Campo obbligatorio: sì

Tipo: JSON object

Esempio

{
   "RequestType" : "Update",
   "RequestId" : "unique-request-id",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id",
   "ResponseURL" : "pre-signed-url-for-update-response",
   "ResourceType" : "Custom::MyCustomResourceType",
   "LogicalResourceId" : "resource-logical-id",
   "PhysicalResourceId" : "provider-defined-physical-id",
   "ResourceProperties" : {
      "key1" : "new-string",
      "key2" : [ "new-list" ],
      "key3" : { "key4" : "new-map" }
   },
   "OldResourceProperties" : {
      "key1" : "string",
      "key2" : [ "list" ],
      "key3" : { "key4" : "map" }
   }
}
Delete

Quando lo sviluppatore del modello elimina lo stack o rimuove la risorsa personalizzata dal modello e quindi aggiorna lo stack, CloudFormation invia una richiesta con set to. RequestType Delete

Le richieste di eliminazione contengono i seguenti campi:

RequestType

Delete.

Campo obbligatorio: sì

▬Tipo: stringa

RequestId

Un ID univoco per la richiesta.

Campo obbligatorio: sì

▬Tipo: stringa

StackId

Il nome della risorsa Amazon (ARN) che identifica lo stack che contiene la risorsa personalizzata.

Campo obbligatorio: sì

▬Tipo: stringa

ResponseURL

L'URL di risposta identifica un bucket S3 predefinito che riceve risposte dal provider di risorse personalizzato a. CloudFormation

Campo obbligatorio: sì

▬Tipo: stringa

ResourceType

Il tipo di risorsa scelta dallo sviluppatore del modello della risorsa personalizzata nel modello CloudFormation . I nomi dei tipi di risorsa personalizzata possono contenere fino a 60 caratteri e possono includere caratteri alfanumerici, oltre ai caratteri seguenti: _@-.

Campo obbligatorio: sì

▬Tipo: stringa

LogicalResourceId

Il nome (ID logico) scelto dallo sviluppatore del modello della risorsa personalizzata nel modello CloudFormation .

Campo obbligatorio: sì

▬Tipo: stringa

PhysicalResourceId

Un ID fisico personalizzato definito dal provider di risorse che è unico per quel provider.

Campo obbligatorio: sì

▬Tipo: stringa

ResourceProperties

Questo campo contiene il contenuto dell’oggetto Properties inviato dallo sviluppatore del modello. I suoi contenuti vengono definiti dal provider di risorse personalizzate.

Required: No

Tipo: JSON object

Esempio

{
   "RequestType" : "Delete",
   "RequestId" : "unique-request-id",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id",
   "ResponseURL" : "pre-signed-url-for-delete-response",
   "ResourceType" : "Custom::MyCustomResourceType",
   "LogicalResourceId" : "resource-logical-id",
   "PhysicalResourceId" : "provider-defined-physical-id",
   "ResourceProperties" : {
      "key1" : "string",
      "key2" : [ "list" ],
      "key3" : { "key4" : "map" }
   }
}

Oggetto Response

Il provider di risorse personalizzato invia una risposta all'URL prefirmato per tutti i tipi di richiesta. Se il provider di risorse personalizzato non invia una risposta, CloudFormation attende il timeout dell'operazione.

La risposta deve essere un oggetto JSON con i seguenti campi:

Status

Deve essere SUCCESS o FAILED.

Campo obbligatorio: sì

▬Tipo: stringa

RequestId

Un ID univoco per la richiesta. Copia questo valore esattamente come appare nella richiesta.

Campo obbligatorio: sì

▬Tipo: stringa

StackId

Il nome della risorsa Amazon (ARN) che identifica lo stack che contiene la risorsa personalizzata. Copia questo valore esattamente come appare nella richiesta.

Campo obbligatorio: sì

▬Tipo: stringa

LogicalResourceId

Il nome (ID logico) scelto dallo sviluppatore del modello della risorsa personalizzata nel modello CloudFormation . Copia questo valore esattamente come appare nella richiesta.

Campo obbligatorio: sì

▬Tipo: stringa

PhysicalResourceId

Questo valore deve essere un identificativo univoco per il fornitore di risorse personalizzate e può avere una dimensione massima di 1 KB. Il valore deve essere una stringa non vuota e deve essere identico per tutte le risposte per la stessa risorsa.

Quando si aggiornano risorse personalizzate, il valore restituito per PhysicalResourceId determina il comportamento di aggiornamento. Se il valore rimane lo stesso, lo CloudFormation considera un aggiornamento normale. Se il valore cambia, CloudFormation interpreta l'aggiornamento come sostitutivo e invia una richiesta di eliminazione alla vecchia risorsa. Per ulteriori informazioni, consulta AWS::CloudFormation::CustomResource.

Campo obbligatorio: sì

▬Tipo: stringa

Reason

Descrive il motivo di una risposta con esito negativo.

Necessario se Status è FAILED. Altrimenti, è facoltativo.

Required: Conditional

▬Tipo: stringa

NoEcho

Indica se nascondere o meno l’output della risorsa personalizzata quando viene recuperata utilizzando la funzione Fn::GetAtt. Se impostato su true, tutti i valori restituiti vengono nascosti con degli asterischi (*****), ad eccezione di quelli archiviati nella sezione del modello Metadata. CloudFormation non trasforma, modifica o omette le informazioni incluse nella sezione Metadata. Il valore predefinito è false.

Per ulteriori informazioni sull’utilizzo di NoEcho per mascherare le informazioni sensibili, consulta la best practice Non incorporare le credenziali nei modelli.

Disponibile solo per Update risposte Create e risposte. Non è supportata per Delete le risposte.

Required: No

Tipo: Booleano

Data

Le coppie nome-valore definite dal provider di risorse personalizzate da inviare con la risposta. Puoi accedere ai valori forniti qui in base al nome nel modello con Fn::GetAtt.

Disponibile solo per Update risposte Create e risposte. Non è supportata per Delete le risposte.

Importante

Se le coppie nome-valore contengono informazioni riservate, è necessario utilizzare il campo NoEcho per mascherare l’output della risorsa personalizzata. Altrimenti, i valori sono visibili attraverso i valori delle proprietà di APIs quella superficie (ad esempioDescribeStackEvents).

Required: No

Tipo: JSON object

Esempi di risposte di successo

Createe Update risposta

{
   "Status": "SUCCESS",
   "RequestId": "unique-request-id",
   "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/name/id",
   "LogicalResourceId": "resource-logical-id", 
   "PhysicalResourceId": "provider-defined-physical-id",
   "NoEcho": true,
   "Data": {
      "key1": "value1",
      "key2": "value2"
   }
}

Risposta Delete

{
   "Status": "SUCCESS",
   "RequestId": "unique-request-id",
   "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/name/id",
   "LogicalResourceId": "resource-logical-id", 
   "PhysicalResourceId": "provider-defined-physical-id"
}

Esempio di risposta fallita

{
   "Status": "FAILED",
   "RequestId": "unique-request-id",
   "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/name/id",
   "LogicalResourceId": "resource-logical-id",
   "PhysicalResourceId": "provider-defined-physical-id",
   "Reason": "Required failure reason string"
}