CloudFormation IaC 檔案的參數篩選器

當您在 AWS CloudFormation IaC 文件中引用AWS Proton 參數時，可以使用稱為過濾器的 Jinja 修飾符來驗證，過濾和格式化參數值，然後將參數值插入渲染的模板中。篩選器驗證在參照元件輸出參數時特別有用，因為元件建立和附件是由開發人員完成的，而在服務執行個體範本中使用元件輸出的管理員可能想要驗證其存在性和有效性。但是，您可以在任何 Jinja IaC 文件中使用過濾器。

以下各節說明和定義可用的參數篩選器，並提供範例。 AWS Proton 定義了大部分的篩選器。該default過濾器是 Jinja 內置過濾器。

格式化 Amazon ECS 任務的環境屬性

宣言

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

Description

此篩選器會格式化 Amazon 彈性容器服務 (Amazon ECS) 任務定義ContainerDefinition區段中環境屬性中要使用的輸出清單。

設定raw為False以同時驗證參數值。在這種情況下，需要該值才能匹配正則表達式^[a-zA-Z0-9_-]*$。如果該值失敗此驗證，則模板渲染失敗。

範例

使用以下自定義組件模板：

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

以下服務模板：

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

呈現的服務模板如下：

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

格式化 Lambda 函數的環境屬性

宣言

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

Description

此篩選器會格式化 AWS Lambda 函數定義Properties區段中 Envi stance 屬性中要使用的輸出清單。

設定raw為False以同時驗證參數值。在這種情況下，需要該值才能匹配正則表達式^[a-zA-Z0-9_-]*$。如果該值失敗此驗證，則模板渲染失敗。

範例

使用以下自定義組件模板：

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

以下服務模板：

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

呈現的服務模板如下：

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

擷取要包含在 IAM 角色中的 IAM 政策 ARN

宣言

dict → proton_cfn_iam_policy_arns → YAML list

Description

此篩選器會格式化要在 AWS Identity and Access Management (IAM) 角色定義Properties區段中ManagedPolicyArns 屬性中使用的輸出清單。篩選器會使用規則運算式^arn:[a-zA-Z-]+:iam::\d{12}:policy/，從輸出參數清單中擷取有效的 IAM 政策 ARN。您可以使用此篩選器，將輸出參數值中的政策附加到服務範本中的 IAM 角色定義。

範例

使用以下自定義組件模板：

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

以下服務模板：

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:
      # ...

呈現的服務模板如下：

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:
      # ...

清理屬性值

宣言

string → proton_cfn_sanitize → string

Description

這是一個通用的過濾器。使用它來驗證參數值的安全性。篩選器會驗證值是否符合規則運算式，^[a-zA-Z0-9_-]*$或是有效的 Amazon 資源名稱 (ARN)。如果該值失敗此驗證，則模板渲染失敗。

範例

使用以下自定義組件模板：

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

• 服務範本中的下列參考資料：

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

  呈現如下：

  # ...
    This-is_valid_37

• 服務範本中的下列參考資料：

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

  具有以下渲染錯誤的結果：

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

• 服務範本中的下列參考資料：

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

  呈現如下：

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

為不存在的參照提供預設值

Description

當命名空間參考不存在時，default篩選器會提供預設值。使用它來編寫強大的模板，即使您引用的參數丟失也可以渲染而不會失敗。

範例

如果服務實例沒有附加的直接定義（默認）組件，或者連接的組件沒有名為的輸出，則服務模板中的以下引用會導致模板渲染失敗test。

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

若要避免此問題，請新增default篩選器。

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