Referência personalizada de solicitações e respostas de recursos do CloudFormation - AWS CloudFormation
Configuração do modeloObjeto de solicitaçãoObjeto da resposta

Referência personalizada de solicitações e respostas de recursos do CloudFormation

O CloudFormation gerencia recursos personalizados por meio de um protocolo de solicitação-resposta que se comunica com seu provedor de recursos personalizados. Cada solicitação inclui um tipo de solicitação (Create, Update ou Delete) e segue esse fluxo de trabalho de alto nível:

  1. Um desenvolvedor de modelos define um recurso personalizado com um ServiceToken e ServiceTimeout no modelo e inicia uma operação de pilha.

  2. O CloudFormation envia uma solicitação JSON ao provedor de recursos personalizados por meio do SNS ou do Lambda.

  3. O provedor de recursos personalizados processa a solicitação e retorna uma resposta JSON para um URL pré-assinado do bucket do Amazon S3 antes que o período de tempo limite expire.

  4. O CloudFormation lê a resposta e prossegue para a operação da pilha. Se nenhuma resposta for recebida antes do tempo limite terminar, a solicitação será considerada malsucedida e a operação de pilha falhará.

Para obter mais informações, consulte Como os recursos personalizados funcionam.

Esta seção descreve a estrutura, os parâmetros e as respostas esperadas para cada tipo de solicitação.

nota

O tamanho total do corpo da resposta não pode exceder 4096 bytes.

Configuração do modelo

Ao definir um recurso personalizado em um modelo, o desenvolvedor do modelo usa AWS::CloudFormation::CustomResource com as seguintes propriedades:

ServiceToken

Um ARN de tópico do Amazon SNS ou um ARN de função do Lambda da mesma região que a pilha.

Obrigatório: Sim

Tipo: string

ServiceTimeout

O tempo máximo, em segundos, antes que a operação de um recurso personalizado atinja o tempo limite. Esse valor deve estar entre 1 e 3600. Padrão: 3600 segundos (1 hora).

Obrigatório: não

Tipo: string

São compatíveis propriedades adicionais de recursos. As propriedades do recurso serão incluídas como ResourceProperties na solicitação. O provedor de recursos personalizados deve determinar quais propriedades são válidas e seus valores aceitáveis.

Objeto de solicitação

Create

Quando o desenvolvedor de modelos cria uma pilha que contém um recurso personalizado, o CloudFormation envia uma solicitação com RequestType definido como Create.

Crie solicitações que contenha os seguintes campos:

RequestType

Create.

Obrigatório: Sim

Tipo: string

RequestId

Um ID exclusivo para a solicitação.

Combinar StackId com RequestId forma um valor que é possível utilizar para identificar exclusivamente uma solicitação em um recurso personalizado específico.

Obrigatório: Sim

Tipo: string

StackId

O nome do recurso da Amazon (ARN) que identifica a pilha que contém o recurso personalizado.

Combinar StackId com RequestId forma um valor que é possível utilizar para identificar exclusivamente uma solicitação em um recurso personalizado específico.

Obrigatório: Sim

Tipo: string

ResponseURL

O URL de resposta identifica um bucket do S3 pré-assinado que recebe respostas do provedor de recursos personalizados para o CloudFormation.

Obrigatório: Sim

Tipo: string

ResourceType

O tipo de recurso escolhido pelo desenvolvedor do modelo do recurso personalizado no modelo do CloudFormation. Os nomes de tipos de recursos personalizados podem incluir até 60 caracteres, incluindo alfanuméricos e os seguintes caracteres: _@-.

Obrigatório: Sim

Tipo: string

LogicalResourceId

O nome do modelo escolhido pelo desenvolvedor (ID lógico) do recurso personalizado no modelo do CloudFormation.

Obrigatório: Sim

Tipo: string

ResourceProperties

Esse campo apresenta o conteúdo do objeto Properties enviado pelo desenvolvedor de modelos. Seu conteúdo é definido pelo provedor de recursos personalizados.

Obrigatório: não

Tipo: objeto JSON

Exemplo

{
   "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 o desenvolvedor de modelos faz alterações nas propriedades de uma pilha que contém um recurso personalizado e atualiza a pilha, o CloudFormation envia uma solicitação ao provedor de recursos personalizados com RequestType definido como Update. Isso significa que o código do recurso personalizado não precisa detectar as alterações nos recursos, pois sabe que as propriedades foram alteradas quando o tipo de solicitação é Update.

Atualize solicitações que contenham os seguintes campos:

RequestType

Update.

Obrigatório: Sim

Tipo: string

RequestId

Um ID exclusivo para a solicitação.

Combinar StackId com RequestId forma um valor que é possível utilizar para identificar exclusivamente uma solicitação em um recurso personalizado específico.

Obrigatório: Sim

Tipo: string

StackId

O nome do recurso da Amazon (ARN) que identifica a pilha que contém o recurso personalizado.

Combinar StackId com RequestId forma um valor que é possível utilizar para identificar exclusivamente uma solicitação em um recurso personalizado específico.

Obrigatório: Sim

Tipo: string

ResponseURL

O URL de resposta identifica um bucket do S3 pré-assinado que recebe respostas do provedor de recursos personalizados para o CloudFormation.

Obrigatório: Sim

Tipo: string

ResourceType

O tipo de recurso escolhido pelo desenvolvedor do modelo do recurso personalizado no modelo do CloudFormation. Os nomes de tipos de recursos personalizados podem incluir até 60 caracteres, incluindo alfanuméricos e os seguintes caracteres: _@-. Não é possível alterar o tipo durante uma atualização.

Obrigatório: Sim

Tipo: string

LogicalResourceId

O nome do modelo escolhido pelo desenvolvedor (ID lógico) do recurso personalizado no modelo do CloudFormation.

Obrigatório: Sim

Tipo: string

PhysicalResourceId

Um ID físico definido por um provedor de recursos personalizados exclusivo para esse provedor.

Obrigatório: Sim

Tipo: string

ResourceProperties

Esse campo apresenta o conteúdo do objeto Properties enviado pelo desenvolvedor de modelos. Seu conteúdo é definido pelo provedor de recursos personalizados.

Obrigatório: não

Tipo: objeto JSON

OldResourceProperties

Usado apenas para solicitações Update. Os valores da propriedade do recurso que foram declarados anteriormente pelo desenvolvedor do modelo no modelo do CloudFormation.

Obrigatório: sim

Tipo: objeto JSON

Exemplo

{
   "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 o desenvolvedor de modelos exclui uma pilha ou remove um recurso personalizado do modelo, e depois atualiza a pilha, o CloudFormation envia uma solicitação com RequestType definido como Delete.

Exclua solicitações que contenha os seguintes campos:

RequestType

Delete.

Obrigatório: Sim

Tipo: string

RequestId

Um ID exclusivo para a solicitação.

Obrigatório: Sim

Tipo: string

StackId

O nome do recurso da Amazon (ARN) que identifica a pilha que contém o recurso personalizado.

Obrigatório: Sim

Tipo: string

ResponseURL

O URL de resposta identifica um bucket do S3 pré-assinado que recebe respostas do provedor de recursos personalizados para o CloudFormation.

Obrigatório: Sim

Tipo: string

ResourceType

O tipo de recurso escolhido pelo desenvolvedor do modelo do recurso personalizado no modelo do CloudFormation. Os nomes de tipos de recursos personalizados podem incluir até 60 caracteres, incluindo alfanuméricos e os seguintes caracteres: _@-.

Obrigatório: Sim

Tipo: string

LogicalResourceId

O nome do modelo escolhido pelo desenvolvedor (ID lógico) do recurso personalizado no modelo do CloudFormation.

Obrigatório: Sim

Tipo: string

PhysicalResourceId

Um ID físico definido por um provedor de recursos personalizados exclusivo para esse provedor.

Obrigatório: Sim

Tipo: string

ResourceProperties

Esse campo apresenta o conteúdo do objeto Properties enviado pelo desenvolvedor de modelos. Seu conteúdo é definido pelo provedor de recursos personalizados.

Obrigatório: não

Tipo: objeto JSON

Exemplo

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

Objeto da resposta

O provedor de recursos personalizados envia uma resposta para o URL pré-assinado para todos os tipos de solicitação. Se o provedor de recursos personalizados não enviar uma resposta, o CloudFormation vai esperar até que a operação atinja o tempo limite.

A resposta deve ser um objeto JSON com os seguintes campos:

Status

Deve ser SUCCESS ou FAILED.

Obrigatório: Sim

Tipo: string

RequestId

Um ID exclusivo para a solicitação. Copie esse valor exatamente como ele aparece na solicitação.

Obrigatório: Sim

Tipo: string

StackId

O nome do recurso da Amazon (ARN) que identifica a pilha que contém o recurso personalizado. Copie esse valor exatamente como ele aparece na solicitação.

Obrigatório: Sim

Tipo: string

LogicalResourceId

O nome do modelo escolhido pelo desenvolvedor (ID lógico) do recurso personalizado no modelo do CloudFormation. Copie esse valor exatamente como ele aparece na solicitação.

Obrigatório: Sim

Tipo: string

PhysicalResourceId

Esse valor deve ser um identificador exclusivo do fornecedor de recursos personalizados e pode ter até 1 KB de tamanho. O valor deve ser uma string não vazia e deve ser idêntico para todas as respostas do mesmo recurso.

Ao atualizar recursos personalizados, o valor retornado de PhysicalResourceId determina o comportamento da atualização. Se o valor retornado permanecer o mesmo, o CloudFormation vai considerar a atualização normal. Se o valor mudar, o CloudFormation vai interpretar a atualização como uma substituição e enviará uma solicitação de exclusão para o recurso antigo. Para obter mais informações, consulte AWS::CloudFormation::CustomResource.

Obrigatório: Sim

Tipo: string

Reason

Descreve o motivo de uma resposta de falha.

Obrigatório se Status for FAILED. Caso contrário, será opcional.

Obrigatório: Condicional

Tipo: string

NoEcho

Indica se é necessário mascarar a saída do recurso personalizado quando ela for recuperada usando a função Fn::GetAtt. Se definido como true, todos os valores retornados serão mascarados com asteriscos (*****), exceto os armazenados na seção Metadata do modelo. O CloudFormation não transforma, modifica nem edita nenhuma informação incluída na seção Metadata. O valor padrão é false.

Para obter mais informações sobre como usar NoEcho para mascarar informações confidenciais, consulte a prática recomendada Não incorporar credenciais em seus modelos.

Disponível somente para respostas Create e Update. Não é compatível com respostas Delete.

Obrigatório: não

Tipo: booliano

Data

Os pares de nome/valor definidos pelo provedor de recursos personalizados a serem enviados com a resposta. É possível acessar os valores fornecidos aqui pelo nome no modelo com Fn::GetAtt.

Disponível somente para respostas Create e Update. Não é compatível com respostas Delete.

Importante

Se os pares de nome/valor contiverem informações confidenciais, você deverá utilizar o campo NoEcho para mascarar a saída do recurso personalizado. Caso contrário, os valores estarão visíveis por meio de APIs que exibem valores de propriedades (como DescribeStackEvents).

Obrigatório: não

Tipo: objeto JSON

Exemplos de respostas de sucesso

Resposta Create e Update

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

DeleteResposta do 

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

Exemplo de resposta com falha

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