CloudFormation IaC ファイルのパラメータフィルター

AWS CloudFormation IaC ファイル内のAWS Proton パラメータを参照するときは、フィルターと呼ばれる Jinja 修飾子を使用して、レンダリングされたテンプレートに挿入される前にパラメータ値を検証、フィルタリング、フォーマットできます。コンポーネントの作成とアタッチは開発者が行いますが、サービスインスタンステンプレートでコンポーネント出力を使用する管理者はその存在と有効性を検証することがあるため、フィルター検証機能はコンポーネント出力パラメータを参照するときに特に便利です。ただし、フィルターは、どの Jinja IaC ファイルでも使用できます。

以下のセクションでは、使用可能なパラメータフィルターについて説明および定義し、これらのフィルターのほとんどを examples. AWS Proton defines で示します。default フィルターは Jinja の組み込みフィルターです。

Amazon ECS タスク用の環境プロパティをフォーマットする

宣言

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

説明

このフィルターは、Amazon Elastic Container Service (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

説明

このフィルターは、 AWS Lambda 関数定義の Propertiesセクションの Environment プロパティで使用される出力のリストをフォーマットします。

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 ポリシー ARN を抽出して IAM ロールに含める

宣言

dict → proton_cfn_iam_policy_arns → YAML list

説明

このフィルターは、 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

説明

これは汎用フィルターです。これを使用してパラメータ値の安全性を検証します。フィルターは、値が正規表現 ^[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

存在しない参照にはデフォルト値を指定します。

説明

名前空間参照が存在しない場合、default フィルターはデフォルト値を提供します。デフォルト値を使えば、参照するパラメータが欠落していても問題なくレンダリングできる堅牢なテンプレートを作成できます。

例

サービスインスタンスに直接定義された (デフォルト) コンポーネントがアタッチされていない場合や、アタッチされたコンポーネントに test という名前の出力がない場合、サービステンプレート内の次の参照によってテンプレートのレンダリングが失敗します。

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

この問題を回避するには、default フィルターを追加してください。

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