Algumas considerações ao usar referências dinâmicas Especificar referências dinâmicas em modelos de pilha Parâmetros do SSM Parâmetros de string segura SSM Segredos do Secrets Manager

Usar referências dinâmicas para especificar valores de modelos

Referências dinâmicas fornecem uma maneira compacta e poderosa para você especificar valores externos que são armazenados e gerenciados em outros serviços, como o Repositório de parâmetros do Systems Manager e o AWS Secrets Manager, em seus modelos de pilha. Quando você usa uma referência dinâmica, p CloudFormation recupera o valor da referência especificada quando necessário durante operações de pilha e conjunto de alterações.

Atualmente, o CloudFormation oferece suporte para aos seguintes padrões de referência dinâmica:

ssm, para valores de texto não criptografado armazenados no Repositório de parâmetros do AWS Systems Manager.
ssm-secure, para strings seguras armazenadas no Repositório de parâmetros do AWS Systems Manager.
secretsmanager, para segredos inteiros ou valores secretos específicos armazenados no AWS Secrets Manager.

Algumas considerações ao usar referências dinâmicas

Veja a seguir algumas considerações que você deve levar em conta ao utilizar referências dinâmicas:

Importante

É altamente recomendável evitar referências dinâmicas, ou dados confidenciais, nas propriedades do recurso que fazem parte do identificador primário de um recurso.

Quando um parâmetro de referência dinâmica está incluído em uma propriedade que forma um identificador de recurso primário, o CloudFormation pode utilizar o valor de texto sem formatação real no identificador do recurso primário. Esse ID de recurso pode aparecer em quaisquer saídas ou destinos derivados.

Para determinar quais propriedades de recursos compreendem o identificador primário de um tipo de recurso, consulte a documentação de referência de recursos desse recurso. Na seção Return values (Valores de retorno), o valor de retorno da função Ref representa as propriedades do recurso que compõem o identificador primário do tipo de recurso.

Você pode incluir até 60 referências dinâmicas em um modelo de pilha.
Para transformações, como AWS::Include e AWS::Serverless , o AWS CloudFormation não resolve referências dinâmicas antes de invocar qualquer transformação. Em vez disso, o AWS CloudFormation transmite a string literal da referência dinâmica para a transformação. Referências dinâmicas (incluindo aquelas inseridas no modelo processado como resultado de uma transformação) são resolvidas quando você executa o conjunto de alterações usando esse modelo.
Referências dinâmicas para valores seguros, como ssm-secure e secretsmanager, não são compatíveis atualmente com recursos personalizados.

nota

Não crie uma referência dinâmica com barra invertida (\) como o valor final. O AWS CloudFormation não pode resolver essas referências, o que resulta em falha no recurso.

Especificar referências dinâmicas em modelos de pilha

Referências dinâmicas aderem ao seguinte padrão:

'{{resolve:service-name:reference-key}}' ou '{{resolve:ssm:[a-zA-Z0-9_.\-/]+(:\d+)?}}'.

service-name

Especifica o serviço no qual o valor é armazenado e gerenciado.

Obrigatório.

Atualmente, os valores válidos incluem:

ssm: parâmetro de tempo sem formatação do Repositório de parâmetros do Systems Manager.
ssm-secure: parâmetro de string segura do Repositório de parâmetros do Systems Manager.

nota
Atualmente, os parâmetros SecureString não têm compatibilidade com Systems Manager nas regiões cn-north-1 e cn-northwest-1.

Para obter mais informações, consulte o Armazenamento de parâmetros do AWS Systems Manager, no Guia do usuário do AWS Systems Manager.
secretsmanager: segredo do Secrets Manager.

reference-key

A chave de referência. Dependendo do tipo de referência dinâmica, a chave de referência pode ser composta por segmentos múltiplos.

Obrigatório.

Parâmetros do SSM

Use a referência dinâmica ssm para incluir valores armazenados no Repositório de parâmetros do Systems Manager do tipo String ou StringList em seus modelos.

Padrão de referência

Para Parâmetros SSM, o segmento reference-key é composto do nome do parâmetro e do número da versão. Use o seguinte padrão:

'{{resolve:ssm:parameter-name:version}}'

Sua referência deve aderir ao seguinte padrão de expressão regular para parameter-name e version:

'{{resolve:ssm:[a-zA-Z0-9_.-/]+:\\d+}}'

parameter-name

O nome do parâmetro no Repositório de parâmetros do Systems Manager. O nome do parâmetro faz distinção entre maiúsculas e minúsculas.

Obrigatório.

versão

Um número inteiro que especifica a versão do parâmetro a ser usada. Se você não especificar a versão exata, o CloudFormation usará a versão mais recente do parâmetro sempre que você criar ou atualizar a pilha. Para obter mais informações, consulte Trabalhar com versões de parâmetros, no Guia do usuário do AWS Systems Manager

Opcional.

Exemplo

O exemplo a seguir usa uma referência dinâmica ssm para definir o controle de acesso para um bucket do S3 a um valor de parâmetro armazenado no Repositório de parâmetros do Systems Manager. Conforme especificado, CloudFormation usará a versão 2 do parâmetro S3AccessControl para operações de pilha e conjunto de alterações.

JSON


  "MyS3Bucket": {
    "Type": "AWS::S3::Bucket",
    "Properties": {
      "AccessControl": "{{resolve:ssm:S3AccessControl:2}}"
    }
  }

YAML


  MyS3Bucket:
    Type: 'AWS::S3::Bucket'
    Properties:
      AccessControl: '{{resolve:ssm:S3AccessControl:2}}'

Para especificar um parâmetro armazenado no Repositório de parâmetros do Systems Manager, você deve ter acesso para chamar GetParameters para o parâmetro especificado. Para obter mais informações, consulte Controlar o acesso a parâmetros do Systems Manager, no Guia do usuário do AWS Systems Manager.

Considerações adicionais a notar ao usar o padrão de referência dinâmica ssm:

No momento, o CloudFormation não é compatível com o acesso a parâmetros SSM entre contas.
Para recursos personalizados, o CloudFormation resolve referências dinâmicas ssm antes de enviar a solicitação ao recurso personalizado. Para obter mais informações, consulte Recursos personalizados.
O CloudFormation não oferece suporte ao uso de rótulos de parâmetro ou de parâmetros públicos em referências dinâmicas.

Um rótulo de parâmetro é um alias definido pelo usuário para ajudar você a gerenciar diferentes versões de um parâmetro. Para obter mais informações, consulte Rotular parâmetros, no Guia do usuário do AWS Systems Manager.

Um parâmetro público é um parâmetro fornecido por um produto da AWS para uso com esse produto e armazenado no repositório de parâmetros do AWS Systems Manager. Para obter um exemplo de parâmetros públicos, consulte Recuperar os metadados de AMI otimizados para o Amazon ECS no Amazon Elastic Container Service Developer Guide.
Atualmente, o CloudFormation não oferece suporte à detecção de desvio em referências dinâmicas. Para referências dinâmicas ssm em que você não especificou a versão do parâmetro, recomendamos que, se você atualizar a versão do parâmetro no SSM, você também execute uma operação de atualização de pilha em todas as pilhas que incluam a referência dinâmica ssm a fim de obter a versão mais recente do parâmetro.
Para verificar qual versão de uma referência dinâmica ssm será usada em uma operação de pilha, crie um conjunto de alterações para a operação de pilha. Em seguida, revise o modelo processado na guia Template (Modelo).
Os parâmetros do SSM sem uma versão não têm suporte no Bloco de parâmetros, use Tipos de parâmetros do SSM em vez disso. Se você utilizar parâmetros do SSM, deverá especificar uma versão do parâmetro do Systems Manager para o AWS CloudFormation usar.

Parâmetros de string segura SSM

Use o padrão de referência dinâmica ssm-secure para especificar parâmetros do tipo SecureString do AWS Systems Manager nos seus modelos. Para referências dinâmicas ssm-secure, o AWS CloudFormation nunca armazena o valor real do parâmetro. O AWS CloudFormation acessa o valor do parâmetro durante operações de criação e atualização de pilhas e conjuntos de alterações. Atualmente, parâmetros de strings seguras só podem ser usados para propriedades de recursos que oferecem suporte ao padrão de referência dinâmica ssm-secure.

Um parâmetro de string segura representa quaisquer dados confidenciais que precisem ser armazenados e consultados com segurança. Ou seja, dados que não deseja que os usuários alterem ou referenciem em texto não criptografado, como senhas ou chaves de licença. Para obter mais informações sobre strings seguras, consulte Usar parâmetros de strings seguras, no Guia do usuário do AWS Systems Manager.

Os valores dos parâmetros de strings seguras não são armazenados no CloudFormation, nem são retornados em nenhum resultado de chamadas de API.

Padrão de referência

Para referências dinâmicas ssm-secure, o segmento reference-key é composto pelo nome do parâmetro e pelo número da versão. Use o seguinte padrão:

'{{resolve:ssm-secure:parameter-name:version}}'

Sua referência deve aderir ao seguinte padrão de expressão regular para parameter-name e version:

'{{resolve:ssm-secure:[a-zA-Z0-9_.-/]+:\\d+}}'

parameter-name

O nome do parâmetro no Repositório de parâmetros do Systems Manager. O nome do parâmetro faz distinção entre maiúsculas e minúsculas.

Obrigatório.

versão

Um número inteiro que especifica a versão do parâmetro a ser usada. Se você não especificar a versão exata, o AWS CloudFormation usará a versão mais recente do parâmetro sempre que você criar ou atualizar a pilha. Para obter mais informações, consulte Trabalhar com versões de parâmetros, no Guia do usuário do AWS Systems Manager

Opcional.

Exemplo

O exemplo a seguir usa uma referência dinâmica ssm-secure para definir a senha de um usuário IAM como uma string segura armazenada no Repositório de parâmetros do Systems Manager. Conforme especificado, CloudFormation usará a versão 10 do parâmetro IAMUserPassword para operações de pilha e conjunto de alterações.

JSON


  "MyIAMUser": {
    "Type": "AWS::IAM::User",
    "Properties": {
      "UserName": "MyUserName",
      "LoginProfile": {
        "Password": "{{resolve:ssm-secure:IAMUserPassword:10}}"
      }
    }
  }

YAML


  MyIAMUser:
    Type: AWS::IAM::User
    Properties:
      UserName: 'MyUserName'
      LoginProfile:
        Password: '{{resolve:ssm-secure:IAMUserPassword:10}}'

Considerações adicionais a notar ao usar o padrão de referência dinâmica ssm-secure:

O CloudFormation não retorna o valor real do parâmetro para strings seguras em nenhuma chamada de API, mas retorna a referência dinâmica literal.
O CloudFormation armazena a referência dinâmica literal, que contém o nome do parâmetro de texto simples da string segura.
Para conjuntos de alterações, o CloudFormation compara a string de referência dinâmica literal. Ele não resolve e compara os valores reais de referências ssm-secure.
Referências dinâmicas para valores seguros, como ssm-secure e secretsmanager, não são compatíveis atualmente com recursos personalizados.
Nos casos em que o CloudFormation tiver que reverter uma atualização de pilha, essa operação de reversão falhará se a versão anteriormente especificada de um parâmetro de string segura não estiver mais disponível. Nesses casos, siga um destes procedimentos:
- Use CONTINUE_UPDATE_ROLLBACK para ignorar o recurso.
- Recrie o parâmetro de string segura no Repositório de parâmetros do Systems Manager e atualize-o até que a versão do parâmetro atinja a versão usada no modelo. Em seguida, use CONTINUE_UPDATE_ROLLBACK sem ignorar o recurso.
No momento, o AWS CloudFormation não é compatível com o acesso a parâmetros SSM entre contas.
O CloudFormation não oferece suporte ao uso de rótulos de parâmetro ou de parâmetros públicos em referências dinâmicas.

Um rótulo de parâmetro é um alias definido pelo usuário para ajudar você a gerenciar diferentes versões de um parâmetro. Para obter mais informações, consulte Rotular parâmetros, no Guia do usuário do AWS Systems Manager.

Um parâmetro público é um parâmetro fornecido por um produto da AWS para uso com esse produto e armazenado no repositório de parâmetros do AWS Systems Manager. Para obter um exemplo de parâmetros públicos, consulte Recuperar os metadados de AMI otimizados para o Amazon ECS no Amazon Elastic Container Service Developer Guide.

Recursos que oferecem suporte a padrões de parâmetros dinâmicos para strings seguras

Recursos que oferecem suporte ao padrão de referência dinâmica ssm-secure incluem atualmente:

Recurso	Tipo de propriedade	Propriedades
AWS::DirectoryService::MicrosoftAD		`Password`
AWS::DirectoryService::SimpleAD		`Password`
AWS::ElastiCache::ReplicationGroup		`AuthToken`
AWS::IAM::User	LoginProfile	`Password`
AWS::KinesisFirehose::DeliveryStream	RedshiftDestinationConfiguration	`Password`
AWS::OpsWorks::App	Origem	`Password`
AWS::OpsWorks::Stack	CustomCookbooksSource	`Password`
AWS::OpsWorks::Stack	RdsDbInstances	`DbPassword`
AWS::RDS::DBCluster		`MasterUserPassword`
AWS::RDS::DBInstance		`MasterUserPassword`
AWS::Redshift::Cluster		`MasterUserPassword`

Segredos do Secrets Manager

Use a referência dinâmica secretsmanager para recuperar todos os segredos ou valores secretos armazenados no Secrets Manager para uso em modelos. Segredos podem ser credenciais de banco de dados, senhas, chaves de API de terceiros e até mesmo texto arbitrário. Usando o Secrets Manager, você pode armazenar e controlar o acesso a esses segredos centralmente, para que você possa substituir credenciais codificadas no seu código (incluindo senhas) por uma chamada de API para o Secrets Manager recuperar o segredo de forma programática. Para obter mais informações, consulte O que é o AWS Secrets Manager? no Guia do usuário do AWS Secrets Manager.

Considerações importantes ao usar referências dinâmicas para segredos do Secrets Manager

É necessário levar em conta as importantes considerações de segurança a seguir ao usar referências dinâmicas para especificar segredos do Secrets Manager em seus modelos de pilha:

A referência dinâmica secretsmanager pode ser usada em todas as propriedades de recursos. Usar a referência dinâmica secretsmanager indica que nem o Secrets Manager, nem o CloudFormation deve registrar ou persistir qualquer valor secreto resolvido. No entanto, o valor secreto pode aparecer no serviço cujo recurso está sendo usado. Revise seu uso para evitar o vazamento de dados secretos.
Atualizar um segredo no Secrets Manager não atualiza automaticamente o segredo no CloudFormation. Para que o CloudFormation atualize uma referência dinâmica secretsmanager, é necessário executar uma atualização de pilha que atualize o recurso que contenha a referência dinâmica, atualizando a propriedade do recurso que contenha a referência dinâmica secretsmanager ou atualizando alguma outra propriedade do recurso.

Por exemplo, suponha que no modelo você especifique a propriedade MasterPassword de um recurso AWS::RDS::DBInstance para ser uma referência dinâmica secretsmanager e crie uma pilha a partir do modelo. Mais tarde, atualize o valor do segredo no Secrets Manager, mas não atualize o recurso AWS::RDS::DBInstance no modelo. Nesse caso, mesmo se você executar uma atualização de pilha, o valor do segredo na propriedade MasterPassword não será atualizado e permanecerá com o valor do segredo anterior.

Além disso, considere usar o Secrets Manager para alternar o segredo automaticamente para um serviço ou banco de dados protegido. Para obter mais informações, consulte Alternar segredos do AWS Secrets Manager.
Referências dinâmicas para valores seguros, como secretsmanager, atualmente não têm suporte em recursos personalizados.

Permissões obrigatórias

Para especificar um segredo armazenado no Secrets Manager, você deve ter acesso para chamar GetSecretValue para o segredo.

Padrão de referência

Para segredos do Secrets Manager, o segmento reference-key é composto de vários segmentos, incluindo o ID secreto, a chave do valor secreto, o estágio da versão e o ID da versão. Use o seguinte padrão:

{{resolve:secretsmanager:secret-id:secret-string:json-key:version-stage:version-id}}

secret-id

O nome ou ARN completo do segredo.

Para acessar um segredo na sua conta da AWS, você precisa especificar apenas o nome do segredo. Para acessar um segredo em outra conta da AWS, especifique o ARN completo do segredo.

Obrigatório.

secret-string

Atualmente, o único valor compatível é SecretString. O padrão é SecretString.

json-key

O nome da chave do par de chave-valor cujo valor você deseja recuperar. Se você não especificar um json-key, o CloudFormation recuperará todo o texto do segredo.

Esse segmento não pode incluir o caractere de dois pontos (:).

version-stage

O rótulo de preparação da versão do segredo a ser utilizada. O Secrets Manager usa rótulos de preparação para acompanhar diferentes versões durante o processo de alternância. Se você usar version-stage, não especifique version-id. Se você não especificar version-stage ou version-id, o padrão é a versão AWSCURRENT.

Esse segmento não pode incluir o caractere de dois pontos (:).

version-id

O identificador exclusivo da versão do segredo a usar. Se você especificar version-id, não especifique version-stage. Se você não especificar version-stage ou version-id, o padrão é a versão AWSCURRENT.

Esse segmento não pode incluir o caractere de dois pontos (:).

Exemplos

O exemplo a seguir usa os segmentos secret-name e json-key para recuperar os valores de nome de usuário e senha armazenados no segredo MyRDSSecret. Por padrão, a versão do segredo recuperada é a versão com o valor de estágio de versão de AWSCURRENT.

JSON


{
    "MyRDSInstance": {
        "Type": "AWS::RDS::DBInstance",
        "Properties": {
            "DBName": "MyRDSInstance",
            "AllocatedStorage": "20",
            "DBInstanceClass": "db.t2.micro",
            "Engine": "mysql",
            "MasterUsername": "{{resolve:secretsmanager:MyRDSSecret:SecretString:username}}",
            "MasterUserPassword": "{{resolve:secretsmanager:MyRDSSecret:SecretString:password}}"
        }
    }
}

YAML


  MyRDSInstance:
    Type: 'AWS::RDS::DBInstance'
    Properties:
      DBName: MyRDSInstance
      AllocatedStorage: '20'
      DBInstanceClass: db.t2.micro
      Engine: mysql
      MasterUsername: '{{resolve:secretsmanager:MyRDSSecret:SecretString:username}}'
      MasterUserPassword: '{{resolve:secretsmanager:MyRDSSecret:SecretString:password}}'

Especificar os segmentos a seguir recupera SecretString para MySecret.

'{{resolve:secretsmanager:MySecret}}' ou '{{resolve:secretsmanager:MySecret::::}}'

Especificar os segmentos a seguir recupera o valor password para MySecret.

'{{resolve:secretsmanager:MySecret:SecretString:password}}'

Especificar os segmentos a seguir recupera SecretString para MySecret que está em outra conta da AWS. Você deve especificar o ARN do segredo completo para acessar segredos em outra conta da AWS.

'{{resolve:secretsmanager:arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-a1b2c3}}'

Especificar os segmentos a seguir recupera o valor password para MySecret que está em outra conta da AWS. Você deve especificar o ARN do segredo completo para acessar segredos em outra conta da AWS.

'{{resolve:secretsmanager:arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-a1b2c3:SecretString:password}}'

Especificar os segmentos a seguir recupera o valor password para a versão AWSPREVIOUS de MySecret.

'{{resolve:secretsmanager:MySecret:SecretString:password:AWSPREVIOUS}}'

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Parâmetros

Regras