Fn::GetStackOutput

A função intrínseca Fn::GetStackOutput retorna o valor de uma saída proveniente de outra pilha. Ao contrário de Fn::ImportValue, essa função não exige que a pilha referenciada exporte explicitamente o valor de saída. Ela também é compatível com referências entre contas e entre regiões

Use essa função quando precisar referenciar saídas de pilhas em contas ou regiões da AWS, ou quando quiser referenciar saídas sem gerenciar exportações explícitas.

Declaração

{
  "Fn::GetStackOutput": {
    "StackName": "stack-name",
    "OutputName": "output-name",
    "Region": "region",
    "RoleArn": "role-arn"
  }
}

Fn::GetStackOutput:
  StackName: stack-name
  OutputName: output-name
  Region: region
  RoleArn: role-arn

!GetStackOutput
  StackName: stack-name
  OutputName: output-name
  Region: region
  RoleArn: role-arn

# Do not use
!GetStackOutput
  StackName: !Ref MyStackNameParam
  OutputName: VpcId

# Use this instead
Fn::GetStackOutput:
  StackName: !Ref MyStackNameParam
  OutputName: VpcId

Parâmetros

Valor de retorno

O valor da saída especificada proveniente da pilha referenciada.

Exemplos

Mesma conta, mesma região

O exemplo a seguir faz referência à saída VpcId proveniente de uma pilha nomeada ProducerStack na mesma conta e região. Como não há a especificação de Region ou RoleArn, o CloudFormation usa a região e o perfil de execução da pilha atual.

{
  "Fn::GetStackOutput": {
    "StackName": "ProducerStack",
    "OutputName": "VpcId"
  }
}

Fn::GetStackOutput:
  StackName: ProducerStack
  OutputName: VpcId

Mesma conta, região diferente

O exemplo a seguir faz referência à saída VpcId proveniente do ProducerStack implantado em us-west-2, enquanto a pilha consumidora está em uma região diferente. O parâmetro Region direciona o CloudFormation a pesquisar o valor referenciado em us-west-2.

{
  "Fn::GetStackOutput": {
    "StackName": "ProducerStack",
    "OutputName": "VpcId",
    "Region": "us-west-2"
  }
}

Fn::GetStackOutput:
  StackName: ProducerStack
  OutputName: VpcId
  Region: us-west-2

Entre contas

O exemplo a seguir faz referência à saída VpcId de ProducerStack na conta 111111111111. A pilha consumidora está na conta 222222222222. O RoleArn especifica um perfil na conta 111111111111 com permissões cloudformation:DescribeStacks, que precisa ser assumido pelo perfil de execução da pilha consumidora.

{
  "Fn::GetStackOutput": {
    "StackName": "ProducerStack",
    "OutputName": "VpcId",
    "RoleArn": "arn:aws:iam::111111111111:role/GetStackOutputRole"
  }
}

Fn::GetStackOutput:
  StackName: ProducerStack
  OutputName: VpcId
  RoleArn: arn:aws:iam::111111111111:role/GetStackOutputRole

Entre contas e entre regiões

O exemplo a seguir faz referência a uma saída proveniente de uma pilha em uma conta diferente e em uma região diferente. Os parâmetros RoleArn e Region são especificados.

{
  "Fn::GetStackOutput": {
    "StackName": "ProducerStack",
    "OutputName": "VpcId",
    "RoleArn": "arn:aws:iam::111111111111:role/GetStackOutputRole",
    "Region": "us-west-2"
  }
}

Fn::GetStackOutput:
  StackName: ProducerStack
  OutputName: VpcId
  RoleArn: arn:aws:iam::111111111111:role/GetStackOutputRole
  Region: us-west-2

Configuração de perfil do IAM

Ao usar o parâmetro RoleArn para referências entre contas, o perfil do IAM precisa ter permissão para descrever as pilhas na conta que contém a pilha referenciada:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudformation:DescribeStacks"
      ],
      "Resource": "*"
    }
  ]
}

O perfil precisa ter uma política de confiança que conceda permissões AssumeRole ao perfil de execução da pilha consumidora:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::222222222222:role/CloudFormationExecutionRole"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Funções compatíveis

As funções a seguir podem ser usadas nos valores dos parâmetros de Fn::GetStackOutput (p. ex., para construir StackName ou RoleArn). O valor dessas funções não depende de um recurso.

A própria função Fn::GetStackOutput pode ser usada nas seguintes posições do modelo:

Veja Limitações conhecidas abaixo para conhecer as posições que ainda não são compatíveis.

Por exemplo, você pode usar Ref para transmitir um valor de parâmetro como o nome da pilha:

Parameters:
  SourceStackName:
    Type: String

Resources:
  MyResource:
    Type: AWS::EC2::Instance
    Properties:
      SubnetId:
        Fn::GetStackOutput:
          StackName: !Ref SourceStackName
          OutputName: SubnetId

Limitações conhecidas

Os seguintes padrões de uso não são compatíveis nesta versão. Todos retornam o erro InternalFailure. A compatibilidade com esses padrões será adicionada em uma futura atualização.

Use Fn::GetStackOutput diretamente como um valor de propriedade de recurso ou envolva-o dentro de Fn::Join, Fn::If ou Fn::Select.

Tratamento de erros

O CloudFormation valida referências Fn::GetStackOutput durante as operações de criação ou atualização da pilha. Veja a seguir os erros comuns que você pode encontrar:

Referências entre us-east-1 e regiões opcionais

Talvez você encontre um erro ao implementar uma referência entre a região us-east-1 e uma região opcional. Para evitar esses erros, siga este guia para atualizar a compatibilidade do token para o endpoint STS global.

Como usar Fn::GetStackOutput com o AWS Cloud Development Kit (AWS CDK)

O AWS Cloud Development Kit (AWS CDK) (CDK) oferece suporte a Fn::GetStackOutput com o método Fn.getStackOutput(). Agora o CDK pode usar Fn::GetStackOutput nativamente em vez de gerar recursos personalizados com parâmetros do SSM quando você tiver referências entre regiões ou contas entre pilhas do CDK. Isso simplifica os modelos sintetizados e elimina a necessidade da solução alternativa anterior com crossRegionReferences.

Para obter mais informações, consulte a Referência de API do CDK.

Comparação com Fn::ImportValue

Use Fn::ImportValue quando precisar de uma integridade referencial forte na mesma conta e região. Use Fn::GetStackOutput quando precisar de referências entre contas ou regiões, ou quando quiser evitar o gerenciamento de exportações explícitas.

Práticas recomendadas