Sintaxe de Conditions de modelo do CloudFormation - AWS CloudFormation
SintaxeComo as condições funcionamFunções intrínsecas da condiçãoUsar a chave ConditionExemplos

Sintaxe de Conditions de modelo do CloudFormation

A seção Conditions opcional contém instruções que definem as circunstâncias nas quais entidades são criadas ou configuradas. Por exemplo, é possível criar uma condição e associá-la a um recurso ou uma saída para que o CloudFormation crie o recurso ou a saída se a condição for true. Da mesma forma, é possível associar uma condição a uma propriedade para que o CloudFormation defina a propriedade como um valor específico se a condição for true. Se a condição for false, o CloudFormation definirá a propriedade para um valor alternativo que você especificar.

Você poderá usar as condições quando quiser reutilizar um modelo para criar recursos em contextos diferentes, como ambientes de teste versus de produção. Por exemplo, no modelo, você pode adicionar um parâmetro de entrada EnvironmentType que aceita prod ou test como entradas. Para o ambiente de prod, você pode incluir instâncias do EC2 com determinados recursos. No entanto, para o ambiente de test, você deve usar recursos reduzidos para economizar. Essa definição de condição permite que você defina quais recursos são criados e como eles são configurados para cada tipo de ambiente.

Sintaxe

A seção Conditions consiste no nome da chave Conditions. Cada declaração de condição inclui um ID lógico e uma ou mais funções intrínsecas.

JSON

"Conditions": {
  "LogicalConditionName1": {
    "Intrinsic function": ...[
  },

  "LogicalConditionName2": {
    "Intrinsic function": ...
  }
}

YAML

Conditions:
  LogicalConditionName1:
    Intrinsic function:
      ...

  LogicalConditionName2:
    Intrinsic function:
      ...

Como as condições funcionam

Para usar as condições, siga estas etapas:

  1. Adicionar uma definição de parâmetro: defina as entradas que as condições avaliarão na seção Parameters do seu modelo. As condições são avaliadas como true ou false com base nos valores dos parâmetros de entrada. Observe que os pseudoparâmetros estão disponíveis automaticamente e não exigem definição explícita na seção Parameters. Para obter mais informações sobre pseudoparâmetros, consulte Obter valores da AWS usando pseudoparâmetros.

  2. Adicionar uma definição de condição: defina condições na seção Conditions usando funções intrínsecas como Fn::If ou Fn::Equals. Essas condições determinam quando o CloudFormation cria os recursos associados. As condições podem ser baseadas em:

    • Valores de parâmetros de entrada ou pseudoparâmetros

    • Outras condições

    • Valores de mapeamento

    No entanto, você não pode fazer referência a IDs lógicos de recursos ou seus atributos em condições.

  3. Associar condições a recursos ou saídas: referencie condições em recursos ou saídas usando a chave Condition e o ID lógico de uma condição. Opcionalmente, use Fn::If em outras partes do modelo (como valores de propriedades) para definir valores com base em uma condição. Para obter mais informações, consulte Usar a chave Condition.

O CloudFormation avalia as condições ao criar ou atualizar uma pilha. O CloudFormation cria entidades que são associadas a uma condição verdadeira e ignora entidades que são associadas a uma condição falsa. O CloudFormation também reavalia essas condições em cada atualização de pilha antes de modificar qualquer recurso. As entidades que permanecem associadas a uma condição true são atualizadas, enquanto as que se tornam associadas a uma condição false são excluídas.

Importante

Durante uma atualização de pilha, você não pode atualizar as condições por si só. Você pode atualizar condições apenas ao incluir alterações que adicionam, modificam ou excluem recursos.

Funções intrínsecas da condição

Você pode usar as seguintes funções intrínsecas para definir condições:

nota

Fn::If só tem suporte no atributo de metadados, no atributo de atualização de política e em valores de propriedade nas seções Resources e Outputs de um modelo.

Usar a chave Condition

Depois que uma condição é definida, é possível aplicá-la em vários lugares no modelo, como Resources e Outputs, usando a chave Condition. A chave Condition faz referência ao nome lógico de uma condição e retorna o resultado avaliado da condição especificada.

Associar condições a recursos

Para criar recursos condicionalmente, adicione a chave Condition e o ID lógico da condição como um atributo ao recurso. O CloudFormation cria o recurso somente quando a condição é avaliada como verdadeira.

JSON

"NewVolume" : {
  "Type" : "AWS::EC2::Volume",
  "Condition" : "IsProduction",
  "Properties" : {
     "Size" : "100",
     "AvailabilityZone" : { "Fn::GetAtt" : [ "EC2Instance", "AvailabilityZone" ]}
  }
}

YAML

NewVolume:
  Type: AWS::EC2::Volume
  Condition: IsProduction
  Properties:
    Size: 100
    AvailabilityZone: !GetAtt EC2Instance.AvailabilityZone

Associar condições a saídas

Também é possível associar condições a saídas. O CloudFormation cria a saída somente quando a condição associada é avaliada como verdadeira.

JSON

"Outputs" : {
  "VolumeId" : {
    "Condition" : "IsProduction",
    "Value" : { "Ref" : "NewVolume" }
  }
}

YAML

Outputs:
  VolumeId:
    Condition: IsProduction
    Value: !Ref NewVolume

Fazer referência a condições em outras condições

Ao definir condições na seção Conditions, você pode fazer referência a outras condições usando a chave Condition. Isso permite que você crie uma lógica condicional mais complexa combinando várias condições.

No exemplo a seguir, a condição IsProdAndFeatureEnabled será avaliada como verdadeira somente se as condições IsProduction e IsFeatureEnabled forem avaliadas como verdadeiras.

JSON

"Conditions": {
  "IsProduction" : {"Fn::Equals" : [{"Ref" : "Environment"}, "prod"]},
  "IsFeatureEnabled" : { "Fn::Equals" : [{"Ref" : "FeatureFlag"}, "enabled"]},
  "IsProdAndFeatureEnabled" : {
    "Fn::And" : [
      {"Condition" : "IsProduction"},
      {"Condition" : "IsFeatureEnabled"}
    ]
  }
}

YAML

Conditions:
  IsProduction:
    !Equals [!Ref Environment, "prod"]
  IsFeatureEnabled:
    !Equals [!Ref FeatureFlag, "enabled"]
  IsProdAndFeatureEnabled: !And
    - !Condition IsProduction
    - !Condition IsFeatureEnabled

Retorne condicionalmente valores de propriedade usando Fn::If

Para um controle mais granular, é possível usar a função intrínseca Fn::If para retornar condicionalmente um dos dois valores de propriedade em recursos ou saídas. Essa função avalia uma condição e retorna um valor se a condição é verdadeira e outro valor se a condição é falsa.

Valores condicionais da propriedade

O exemplo a seguir demonstra a definição de um tipo de instância do EC2 com base em uma condição do ambiente. Se a condição IsProduction for verdadeira, o tipo de instância será definido como c5.xlarge. Caso contrário, ele será definido como t3.small.

JSON
"Properties" : {
  "InstanceType" : {
    "Fn::If" : [
      "IsProduction",
      "c5.xlarge",
      "t3.small"
    ]
  }
}
YAML
Properties:
  InstanceType: !If
    - IsProduction
    - c5.xlarge
    - t3.small

Remoção condicional de propriedades

Também é possível usar o pseudoparâmetro AWS::NoValue como um valor de retorno para remover a propriedade correspondente quando uma condição é falsa.

JSON
"DBSnapshotIdentifier" : {
  "Fn::If" : [
    "UseDBSnapshot",
    {"Ref" : "DBSnapshotName"},
    {"Ref" : "AWS::NoValue"}
  ]
}
YAML
DBSnapshotIdentifier: !If
  - UseDBSnapshot
  - !Ref DBSnapshotName
  - !Ref "AWS::NoValue"

Exemplos

Criação de recursos com base no ambiente

Os exemplos a seguir provisionam uma instância do EC2 e criam e anexam condicionalmente um novo volume do EBS somente se o tipo de ambiente for prod. Se o ambiente for test, eles simplesmente criam a instância do EC2 sem o volume adicional.

JSON

{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Parameters": {
        "EnvType": {
            "Description": "Environment type",
            "Default": "test",
            "Type": "String",
            "AllowedValues": [
                "prod",
                "test"
            ],
            "ConstraintDescription": "must specify prod or test"
        }
    },
    "Conditions": {
        "IsProduction": {
            "Fn::Equals": [
                {
                    "Ref": "EnvType"
                },
                "prod"
            ]
        }
    },
    "Resources": {
        "EC2Instance": {
            "Type": "AWS::EC2::Instance",
            "Properties": {
                "ImageId": "ami-1234567890abcdef0",
                "InstanceType": "c5.xlarge"
            }
        },
        "MountPoint": {
            "Type": "AWS::EC2::VolumeAttachment",
            "Condition": "IsProduction",
            "Properties": {
                "InstanceId": {
                    "Ref": "EC2Instance"
                },
                "VolumeId": {
                    "Ref": "NewVolume"
                },
                "Device": "/dev/sdh"
            }
        },
        "NewVolume": {
            "Type": "AWS::EC2::Volume",
            "Condition": "IsProduction",
            "Properties": {
                "Size": 100,
                "AvailabilityZone": {
                    "Fn::GetAtt": [
                        "EC2Instance",
                        "AvailabilityZone"
                    ]
                }
            }
        }
    }
}

YAML

AWSTemplateFormatVersion: 2010-09-09
Parameters:
  EnvType:
    Description: Environment type
    Default: test
    Type: String
    AllowedValues:
      - prod
      - test
    ConstraintDescription: must specify prod or test
Conditions:
  IsProduction: !Equals
    - !Ref EnvType
    - prod
Resources:
  EC2Instance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: ami-1234567890abcdef0
      InstanceType: c5.xlarge
  MountPoint:
    Type: AWS::EC2::VolumeAttachment
    Condition: IsProduction
    Properties:
      InstanceId: !Ref EC2Instance
      VolumeId: !Ref NewVolume
      Device: /dev/sdh
  NewVolume:
    Type: AWS::EC2::Volume
    Condition: IsProduction
    Properties:
      Size: 100
      AvailabilityZone: !GetAtt
        - EC2Instance
        - AvailabilityZone

Provisionamento de recursos com várias condições

Os exemplos a seguir criarão condicionalmente um bucket do S3 se um nome de bucket for fornecido, e anexarão uma política de bucket somente quando o ambiente estiver definido como prod. Se nenhum nome de bucket for fornecido ou se o ambiente for de test, nenhum recurso será criado.

JSON

{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Parameters": {
        "EnvType": {
            "Type": "String",
            "AllowedValues": [
                "prod",
                "test"
            ]
        },
        "BucketName": {
            "Default": "",
            "Type": "String"
        }
    },
    "Conditions": {
        "IsProduction": {
            "Fn::Equals": [
                {
                    "Ref": "EnvType"
                },
                "prod"
            ]
        },
        "CreateBucket": {
            "Fn::Not": [
                {
                    "Fn::Equals": [
                        {
                            "Ref": "BucketName"
                        },
                        ""
                    ]
                }
            ]
        },
        "CreateBucketPolicy": {
            "Fn::And": [
                {
                    "Condition": "IsProduction"
                },
                {
                    "Condition": "CreateBucket"
                }
            ]
        }
    },
    "Resources": {
        "Bucket": {
            "Type": "AWS::S3::Bucket",
            "Condition": "CreateBucket",
            "Properties": {
                "BucketName": {
                    "Ref": "BucketName"
                }
            }
        },
        "Policy": {
            "Type": "AWS::S3::BucketPolicy",
            "Condition": "CreateBucketPolicy",
            "Properties": {
                "Bucket": {
                    "Ref": "Bucket"
                },
                "PolicyDocument": { ... }
            }
        }
    }
}

YAML

AWSTemplateFormatVersion: 2010-09-09
Parameters:
  EnvType:
    Type: String
    AllowedValues:
      - prod
      - test
  BucketName:
    Default: ''
    Type: String
Conditions:
  IsProduction: !Equals
    - !Ref EnvType
    - prod
  CreateBucket: !Not
    - !Equals
      - !Ref BucketName
      - ''
  CreateBucketPolicy: !And
    - !Condition IsProduction
    - !Condition CreateBucket
Resources:
  Bucket:
    Type: AWS::S3::Bucket
    Condition: CreateBucket
    Properties:
      BucketName: !Ref BucketName
  Policy:
    Type: AWS::S3::BucketPolicy
    Condition: CreateBucketPolicy
    Properties:
      Bucket: !Ref Bucket
      PolicyDocument: ...

Neste exemplo, a condição CreateBucketPolicy demonstra como fazer referência a outras condições usando a chave Condition. A política é criada somente quando as condições IsProduction e CreateBucket são avaliadas como verdadeiras.

nota

Para exemplos mais complexos do uso de condições, consulte o tópico atributo Condition no Guia de referência de modelos do AWS CloudFormation.