Component CloudFormation IaC file parameter details and examples

You can define and reference parameters in your component infrastructure as code (IaC) files. For a detailed description of AWS Proton parameters, parameter types, the parameter namespace, and how to use parameters in your IaC files, see AWS Proton parameters. For more information about components, see AWS Proton components.

Define component output parameters

You can define output parameters in your component IaC files. You can then refer to these outputs in service IaC files.

Note

You can't define inputs for component IaC files. Attached components can get inputs from the service instance that they are attached to. Detached components don't have inputs.

Read parameter values in component IaC files

You can read parameters related to the component and to other resources in component IaC files. You read a parameter value by referencing the parameter's name in the AWS Proton parameter namespace.

• Input parameters – Read an attached service instance input value by referencing service_instance.inputs.input-name.

• Resource parameters – Read AWS Proton resource parameters by referencing names such as component.name, service.name, service_instance.name, and environment.name.

• Output parameters – Read environment outputs by referencing environment.outputs.output-name.

Example component and service IaC files with parameters

The following example shows a component that provisions an Amazon Simple Storage Service (Amazon S3) bucket and related access policy and exposes the Amazon Resource Names (ARNs) of both resources as component outputs. A service IaC template adds the component outputs as container environment variables of an Amazon Elastic Container Service (Amazon ECS) task to make the outputs available to code running in the container, and adds the bucket access policy to the task's role. The bucket name is based on the names of the environment, service, service instance, and component, meaning that the bucket is coupled with a specific instance of the component template extending a specific service instance. Developers can create multiple custom components based on this component template, to provision Amazon S3 buckets for different service instances and functional needs.

The example shows how you use Jinja {{ ... }} syntax to refer to component and other resource parameters in your service IaC file. You can use {% if ... %} statements to add blocks of statements only when a component is attached to the service instance. The proton_cfn_* keywords are filters that you can use to sanitize and format output parameter values. For more information about filters, see Parameter filters for CloudFormation IaC files.

As an administrator, you author the service IaC template file.

Example service CloudFormation IaC file using a component

# service/instance_infrastructure/cloudformation.yaml

Resources: 
  TaskDefinition:
    Type: AWS::ECS::TaskDefinition
    Properties:
      TaskRoleArn: !Ref TaskRole
      ContainerDefinitions:
        - Name: '{{service_instance.name}}'
          # ...
          {% if service_instance.components.default.outputs | length > 0 %}
          Environment:
            {{ service_instance.components.default.outputs |
                proton_cfn_ecs_task_definition_formatted_env_vars }}
          {% endif %}

  # ...

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

As a developer, you author the component IaC template file.

Example component CloudFormation IaC file

# cloudformation.yaml

# A component that defines an S3 bucket and a policy for accessing the bucket.
Resources:
  S3Bucket:
    Type: 'AWS::S3::Bucket'
    Properties:
      BucketName: '{{environment.name}}-{{service.name}}-{{service_instance.name}}-{{component.name}}'
  S3BucketAccessPolicy:
    Type: AWS::IAM::ManagedPolicy
    Properties:
      PolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Action:
              - 's3:Get*'
              - 's3:List*'
              - 's3:PutObject'
            Resource: !GetAtt S3Bucket.Arn
Outputs:
  BucketName:
    Description: "Bucket to access"
    Value: !GetAtt S3Bucket.Arn
  BucketAccessPolicyArn:
    Value: !Ref S3BucketAccessPolicy

When AWS Proton renders an AWS CloudFormation template for your service instance and replaces all parameters with actual values, the template might look like the following file.

Example service instance CloudFormation rendered IaC file

Resources: 
  TaskDefinition:
    Type: AWS::ECS::TaskDefinition
    Properties:
      TaskRoleArn: !Ref TaskRole
      ContainerDefinitions:
        - Name: '{{service_instance.name}}'
          # ...
          Environment:
            - Name: BucketName
              Value: arn:aws:s3:us-east-1:123456789012:environment_name-service_name-service_instance_name-component_name
            - Name: BucketAccessPolicyArn
              Value: arn:aws:iam::123456789012:policy/cfn-generated-policy-name
  # ...

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

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