Filtros de parámetros para archivos CloudFormation IaC

Al hacer referencia a AWS Proton los parámetros de los archivos AWS CloudFormation IaC, puede utilizar los modificadores de Jinja, conocidos como filtros, para validar, filtrar y formatear los valores de los parámetros antes de insertarlos en la plantilla renderizada. Las validaciones de filtros son especialmente útiles cuando se hace referencia a los parámetros de salida de los componentes, ya que los desarrolladores se encargan de crear y conectar los componentes, y un administrador que utilice las salidas de los componentes en una plantilla de instancia de servicio podría querer comprobar su existencia y validez. Sin embargo, puede utilizar filtros en cualquier archivo IaC de Jinja.

En las siguientes secciones se describen y definen los filtros de parámetros disponibles y se proporcionan ejemplos. AWS Proton define la mayoría de estos filtros. El default filtro es un filtro integrado por Jinja.

Formatear las propiedades del entorno para las tareas de Amazon ECS

Declaración

dict → proton_cfn_ecs_task_definition_formatted_env_vars (raw: boolean = True) → YAML list of dicts

Descripción

Este filtro da formato a una lista de salidas que se van a utilizar en una propiedad del entorno en la ContainerDefinition sección de una definición de tarea de Amazon Elastic Container Service (Amazon ECS).

rawFalseConfigúrelo para validar también el valor del parámetro. En este caso, el valor debe coincidir con la expresión regular^[a-zA-Z0-9_-]*$. Si el valor no pasa esta validación, se produce un error en la representación de la plantilla.

Ejemplo

Con la siguiente plantilla de componentes personalizados:

Resources:
  # ...
Outputs:
  Output1:
    Description: "Example component output 1"
    Value: hello
  Output2:
    Description: "Example component output 2"
    Value: world

Y la siguiente plantilla de servicio:

Resources:
  TaskDefinition:
    Type: AWS::ECS::TaskDefinition
    Properties:
      # ...
      ContainerDefinitions:
        - Name: MyServiceName
          # ...
          Environment:
            {{ service_instance.components.default.outputs
              | proton_cfn_ecs_task_definition_formatted_env_vars }}

La plantilla de servicio renderizada es la siguiente:

Resources:
  TaskDefinition:
    Type: AWS::ECS::TaskDefinition
    Properties:
      # ...
      ContainerDefinitions:
        - Name: MyServiceName
          # ...
          Environment:
            - Name: Output1
              Value: hello
            - Name: Output2
              Value: world

Propiedades del entorno de formato para funciones Lambda

Declaración

dict → proton_cfn_lambda_function_formatted_env_vars (raw: boolean = True) → YAML dict

Descripción

Este filtro formatea una lista de salidas que se utilizarán en una propiedad de entorno en la Properties sección de la definición de una AWS Lambda función.

rawFalseConfigúrelo en para validar también el valor del parámetro. En este caso, el valor debe coincidir con la expresión regular^[a-zA-Z0-9_-]*$. Si el valor no pasa esta validación, se produce un error en la representación de la plantilla.

Ejemplo

Con la siguiente plantilla de componentes personalizados:

Resources:
  # ...
Outputs:
  Output1:
    Description: "Example component output 1"
    Value: hello
  Output2:
    Description: "Example component output 2"
    Value: world

Y la siguiente plantilla de servicio:

Resources:
  Lambda:
    Type: AWS::Lambda::Function
    Properties:
      Environment:
        Variables:
          {{ service_instance.components.default.outputs
            | proton_cfn_lambda_function_formatted_env_vars }}

La plantilla de servicio renderizada es la siguiente:

Resources:
  Lambda:
    Type: AWS::Lambda::Function
    Properties:
      Environment:
        Variables:
          Output1: hello
          Output2: world

Extraiga los ARN de las políticas de IAM para incluirlos en las funciones de IAM

Declaración

dict → proton_cfn_iam_policy_arns → YAML list

Descripción

Este filtro formatea una lista de resultados que se van a utilizar en una ManagedPolicyArns propiedad en la Properties sección de una definición de rol AWS Identity and Access Management (IAM). El filtro utiliza la expresión regular ^arn:[a-zA-Z-]+:iam::\d{12}:policy/ para extraer los ARN de política de IAM válidos de la lista de parámetros de salida. Puede utilizar este filtro para añadir las políticas de los valores de los parámetros de salida a una definición de función de IAM en una plantilla de servicio.

Ejemplo

Con la siguiente plantilla de componentes personalizados:

Resources:
  # ...
  ExamplePolicy1:
    Type: AWS::IAM::ManagedPolicy
    Properties:
      # ...
  ExamplePolicy2:
    Type: AWS::IAM::ManagedPolicy
    Properties:
      # ...

  # ...

Outputs:
  Output1:
    Description: "Example component output 1"
    Value: hello
  Output2:
    Description: "Example component output 2"
    Value: world
  PolicyArn1:
    Description: "ARN of policy 1"
    Value: !Ref ExamplePolicy1
  PolicyArn2:
    Description: "ARN of policy 2"
    Value: !Ref ExamplePolicy2

Y la siguiente plantilla de servicio:

Resources: 

  # ...

  TaskRole:
    Type: AWS::IAM::Role
    Properties:
      # ...
      ManagedPolicyArns:
        - !Ref BaseTaskRoleManagedPolicy
        {{ service_instance.components.default.outputs
            | proton_cfn_iam_policy_arns }}

  # Basic permissions for the task
  BaseTaskRoleManagedPolicy:
    Type: AWS::IAM::ManagedPolicy
    Properties:
      # ...

La plantilla de servicio renderizada es la siguiente:

Resources: 

  # ...

  TaskRole:
    Type: AWS::IAM::Role
    Properties:
      # ...
      ManagedPolicyArns:
        - !Ref BaseTaskRoleManagedPolicy
        - arn:aws:iam::123456789012:policy/cfn-generated-policy-name-1
        - arn:aws:iam::123456789012:policy/cfn-generated-policy-name-2

  # Basic permissions for the task
  BaseTaskRoleManagedPolicy:
    Type: AWS::IAM::ManagedPolicy
    Properties:
      # ...

Desinfecte los valores de las propiedades

Declaración

string → proton_cfn_sanitize → string

Descripción

Se trata de un filtro de uso general. Utilícelo para validar la seguridad del valor de un parámetro. El filtro valida que el valor coincide con la expresión regular ^[a-zA-Z0-9_-]*$ o que es un nombre de recurso de Amazon (ARN) válido. Si el valor no pasa esta validación, se produce un error en la representación de la plantilla.

Ejemplo

Con la siguiente plantilla de componentes personalizados:

Resources:
  # ...
Outputs:
  Output1:
    Description: "Example of valid output"
    Value: "This-is_valid_37"
  Output2:
    Description: "Example incorrect output"
    Value: "this::is::incorrect"
  SomeArn:
    Description: "Example ARN"
    Value: arn:aws:some-service::123456789012:some-resource/resource-name

• La siguiente referencia en una plantilla de servicio:

  # ...
    {{ service_instance.components.default.outputs.Output1
      | proton_cfn_sanitize }}

  Se representa de la siguiente manera:

  # ...
    This-is_valid_37

• La siguiente referencia en una plantilla de servicio:

  # ...
    {{ service_instance.components.default.outputs.Output2
      | proton_cfn_sanitize }}

  Resultados con el siguiente error de representación:

  Illegal character(s) detected in "this::is::incorrect". Must match regex ^[a-zA-Z0-9_-]*$ or be a valid ARN

• La siguiente referencia en una plantilla de servicio:

  # ...
    {{ service_instance.components.default.outputs.SomeArn
      | proton_cfn_sanitize }}

  Se representa de la siguiente manera:

  # ...
    arn:aws:some-service::123456789012:some-resource/resource-name

Provisión de valores predeterminados para referencias inexistentes

Descripción

El default filtro proporciona un valor predeterminado cuando no existe una referencia a un espacio de nombres. Úselo para escribir plantillas sólidas que puedan renderizarse sin errores incluso cuando falte el parámetro al que hace referencia.

Ejemplo

La siguiente referencia en una plantilla de servicio provoca un error en la representación de la plantilla si la instancia de servicio no tiene un componente adjunto definido directamente (predeterminado) o si el componente adjunto no tiene un nombre de salidatest.

# ...
  {{ service_instance.components.default.outputs.test }}

Para evitar este problema, agrega el default filtro.

# ...
  {{ service_instance.components.default.outputs.test | default("[optional-value]") }}