End of support notice: On October 7, 2026, AWS will end support for AWS Proton. After October 7, 2026, you will no longer be able to access the AWS Proton console or AWS Proton resources. Your deployed infrastructure will remain intact. For more information, see [AWS Proton Service Deprecation and Migration Guide](https://docs.aws.amazon.com/proton/latest/userguide/proton-end-of-support.html). # AWS Proton components Components are a type of AWS Proton resource. They add flexibility to service templates. Components provide platform teams with a mechanism to extend core infrastructure patterns, and define safeguards that empower developers to manage aspects of their application infrastructure. In AWS Proton administrators define standard infrastructure that is used across development teams and applications. However, development teams might need to include additional resources for their specific use cases, like Amazon Simple Queue Service (Amazon SQS) queues or Amazon DynamoDB tables. These application-specific resources might change frequently, particularly during early application development. Maintaining these frequent changes in administrator authored templates might be hard to manage and scale—administrators would need to maintain many more templates without real administrator added value. The alternative—letting application developers author templates for their applications—isn't ideal either, because it takes away administrators' ability to standardize the main architecture components, like AWS Fargate tasks. This is where components come in. With a component, a developer can add supplemental resources to their application, above and beyond what administrators defined in environment and service templates. The developer then attaches the component to a service instance. AWS Proton provisions infrastructure resources defined by the component just like it provisions resources for environments and service instances. A component can read service instance inputs and provide outputs to the service instance, for a fully integrated experience. For example, if the component adds an Amazon Simple Storage Service (Amazon S3) bucket for use by a service instance, the component template can take the environment and service instance names into account for naming the bucket. When AWS Proton renders the service template to provision a service instance, the service instance can refer to the bucket and use it. The components that AWS Proton currently supports are *directly defined components*. You pass the Infrastructure as Code (IaC) file that defines the component's infrastructure directly to the AWS Proton API or console. This is different than an environment or service, where you define IaC in a template bundle and register the bundle as a template resource, then use a template resource to create the environment or service. **Note** Directly defined components allow developers to define extra infrastructure and provision it. AWS Proton provisions all directly defined components running in the same environment using the same AWS Identity and Access Management (IAM) role. An administrator can control what developers can do with components in two ways: + *Supported component sources* – An administrator can allow the attachment of components to service instances based on a property of AWS Proton service template versions. By default, developers can't attach components to service instances. For more information about this property, see the [supportedComponentSources](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateServiceTemplateVersion.html#proton-CreateServiceTemplateVersion-request-supportedComponentSources) parameter of the [CreateServiceTemplateVersion](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateServiceTemplateVersion.html) API action in the *AWS Proton API Reference*. **Note** When you use template sync, AWS Proton creates service template versions implicitly when you commit changes to a service template bundle in a repository. In this case, instead of specifying supported component sources during service template version creation, you specify this property in a file associated with each service template major version. For more information, see [Syncing service templates](create-template-sync.md#create-template-sync-service-templates). + *Component roles* – An administrator can assign a component role to an environment. AWS Proton assumes this role when it provisions infrastructure defined by directly defined component in the environment. Therefore, the component role scopes down the infrastructure that developers can add using directly defined components in the environment. In the absence of the component role, developers can't create directly defined components in the environment. For more information about assigning a component role, see the [componentRoleArn](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateEnvironment.html#proton-CreateEnvironment-request-componentRoleArn) parameter of the [CreateEnvironment](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateEnvironment.html) API action in the *AWS Proton API Reference*. **Note** Component roles aren't used in [Self-managed provisioning](ag-works-prov-methods.md#ag-works-prov-methods-self) environments. **Topics** + [How do components compare to other AWS Proton resources?](#ag-components.compare) + [Components in the AWS Proton console](#ag-components.console) + [Components in the AWS Proton API and AWS CLI](#ag-components.api) + [Component frequently asked questions](#ag-components.faq) + [Component states](ag-components-states.md) + [Component infrastructure as code files](ag-components-iac.md) + [Component CloudFormation example](ag-components-example-cfn.md) ## How do components compare to other AWS Proton resources? In many ways, components are similar to other AWS Proton resources. Their infrastructure is defined in an [IaC template file](ag-components-iac.md), authored in either CloudFormation YAML or Terraform HCL format. AWS Proton can provision component infrastructure using either [AWS-managed provisioning](ag-works-prov-methods.md#ag-works-prov-methods-direct) or [self-managed provisioning](ag-works-prov-methods.md#ag-works-prov-methods-self). Components are, however, different from other AWS Proton resources in a few ways: + *Detached state* – Components are designed to be attached to service instances and to extend their infrastructure, but can also be in a *detached* state, in which they aren't attached to any service instance. For more information about component states, see [Component states](ag-components-states.md). + *No schema* – Components don't have an associated schema like [template bundles](ag-template-authoring.md#ag-template-bundles) have. Component inputs are defined by a service. A component can consume inputs when it is attached to a service instance. + *No customer-managed components* – AWS Proton always provisions component infrastructure for you. There isn't a *bring your own resources* version of components. For more information about customer-managed environments, see [Create an environment](ag-create-env.md). + *No template resource* – Directly defined components don't have an associated template resource similar to environment and service templates. You provide an IaC template file directly to the component. Similarly, you directly provide a manifest that defines the template language and rendering engine for provisioning the component's infrastructure. You author the template file and the manifest in a way similar to authoring a [template bundle](ag-template-authoring.md#ag-template-bundles). However, with directly defined components, there's no requirement to store IaC files as bundles in particular locations, and you don't create a template resource in AWS Proton out of IaC files. + *No CodeBuild-based provisioning* – You can't provision directly defined components using your own custom provisioning script, known as *CodeBuild-based provisioning*. For more information, see [How CodeBuild provisioning works](ag-works-prov-methods.md#ag-works-prov-methods-codebuild). ## Components in the AWS Proton console Use the AWS Proton console to create, update, view, and use AWS Proton components. The following console pages are related to components. We include direct links to top level console pages. + [Components](https://console.aws.amazon.com//proton/#/components) – View the list of components in your AWS account. You can create new components, and update or delete existing components. Choose a component name on the list to view its details page. Similar lists exist also on the **Environment details** and **Service instance details** pages. These lists show only the components associated with the resource that is being viewed. When you create a component from one of these lists, AWS Proton pre-selects the associated environment on the **Create component** page. + **Component details** – To view the component details page, choose a component name on the [Components](https://console.aws.amazon.com//proton/#/components) list. On the details page, view the component details and status, and update or delete the component. View and manage lists of outputs (for example, provisioned resource ARNs), provisioned CloudFormation stacks, and assigned tags. + [Create component](https://console.aws.amazon.com//proton/#/components/create) – Create a component. Enter the component name and description, choose the associated resources, specify the component source IaC file, and assign tags. + **Update component** – To update a component, select the component on the [Components](https://console.aws.amazon.com//proton/#/components) list, and then, on the **Actions** menu, choose **Update component**. Alternatively, on the **Component details** pages, choose **Update**. You can update most of the component's details. You can't update the component name. And you can choose whether or not to redeploy the component after a successful update. + **Configure environment** – When you create or update an environment, you can specify a **Component role**. This role controls the ability to run directly defined components in the environment and provides permissions for provisioning them. + **Create new service template version** – When you create a service template version, you can specify **Supported component sources** for the template version. This controls the ability to attach components to service instances of services based on this template version. ## Components in the AWS Proton API and AWS CLI Use the AWS Proton API or the AWS CLI to create, update, view, and use AWS Proton components. The following API actions directly manage AWS Proton component resources. + [CreateComponent](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateComponent.html) – Create an AWS Proton component. + [DeleteComponent](https://docs.aws.amazon.com/proton/latest/APIReference/API_DeleteComponent.html) – Delete an AWS Proton component. + [GetComponent](https://docs.aws.amazon.com/proton/latest/APIReference/API_GetComponent.html) – Get detailed data for a component. + [ListComponentOutputs](https://docs.aws.amazon.com/proton/latest/APIReference/API_ListComponentOutputs.html) – Get a list of component Infrastructure as Code (IaC) outputs. + [ListComponentProvisionedResources](https://docs.aws.amazon.com/proton/latest/APIReference/API_ListComponentProvisionedResources.html) – List provisioned resources for a component with details. + [ListComponents](https://docs.aws.amazon.com/proton/latest/APIReference/API_ListComponents.html) – List components with summary data. You can filter the result list by environment, service, or a single service instance. The following API actions of other AWS Proton resources have some functionality related to components. + [CreateEnvironment](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateEnvironment.html), [UpdateEnvironment](https://docs.aws.amazon.com/proton/latest/APIReference/API_UpdateEnvironment.html) – Use `componentRoleArn` to specify the Amazon Resource Name (ARN) of the IAM service role that AWS Proton uses when provisioning directly defined components in this environment. It determines the scope of infrastructure that a directly defined component can provision. + [CreateServiceTemplateVersion](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateServiceTemplateVersion.html) – Use `supportedComponentSources` to specify supported component sources. Components with supported sources can be attached to service instances based on this service template version. ## Component frequently asked questions **What is the lifecycle of a component?** Components can be in an *attached* or *detached* state. They are designed to be attached to a service instance and enhance its infrastructure most of the time. Detached components are in a transitional state that enables you to delete a component or attach it to another service instance in a controlled and safe way. For more information, see [Component states](ag-components-states.md). **Why can't I delete my attached components?** *Solution:* To delete an attached component, update the component to detach it from the service instance, validate service instance stability, and then delete the component. *Why is this required?* Attached components provide extra infrastructure that your application needs to perform its runtime functions. The service instance might be using component outputs to detect and use resources of this infrastructure. Deleting the component, thereby removing its infrastructure resources, could be disruptive to the attached service instance. As an added safety measure, AWS Proton requires that you update the component and detach it from its service instance before you can delete it. You can then validate your service instance to ensure that it continues to deploy and function properly. If you detect an issue, you can quickly reattach the component to the service instance, then work to fix the issue. When you're confident that your service instance is clear of any dependency on the component, you can safely delete the component. **Why can't I change a component's attached service instance directly?** *Solution:* To change attachment, update the component to detach it from the service instance, validate component and service instance stability, then attach the component to the new service instance. *Why is this required?* A component is designed to be attached to a service instance. Your component might use service instance inputs for infrastructure resource naming and configuration. Changing the attached service instance could be disruptive to the component (in addition to possible disruption to the service instance, as described in the previous FAQ, [Why can't I delete my attached components?](#ag-components.faq.delete)). For example, it might cause renaming, and possibly even replacement, of resources defined in the component's IaC template. As an added safety measure, AWS Proton requires that you update the component and detach it from its service instance before you can attach it to another service instance. You can then validate the stability of both the component and the service instance before attaching the component to the new service instance. # Component states AWS Proton components can be in two fundamentally different states: + *Attached* – The component is attached to a service instance. It defines infrastructure that supports the runtime functionality of the service instance. The component extends the infrastructure defined in environment and service templates with developer-defined infrastructure. A typical component is in the attached state throughout most of the useful part of its lifecycle. + *Detached* – The component is associated with an AWS Proton environment, and isn't attached to any service instance in the environment. This is a transitional state for extending the lifetime of a component beyond a single service instance. The following table provides a top level comparison of the different component states. | | Attached | Detached | | --- | --- | --- | | **State's main purpose** | To extend the infrastructure of a service instance. | To maintain the component's infrastructure between service instance attachments. | | **Associated with** | A service instance and an environment | An environment | | **Key specific properties** | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/proton/latest/userguide/ag-components-states.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/proton/latest/userguide/ag-components-states.html) | | **Can be deleted** | ![\[No\]](http://docs.aws.amazon.com/proton/latest/userguide/images/icon-no.png) No | ![\[Yes\]](http://docs.aws.amazon.com/proton/latest/userguide/images/icon-yes.png) Yes | | **Can be updated to another service instance** | ![\[No\]](http://docs.aws.amazon.com/proton/latest/userguide/images/icon-no.png) No | ![\[Yes\]](http://docs.aws.amazon.com/proton/latest/userguide/images/icon-yes.png) Yes | | **Can read inputs** | ![\[Yes\]](http://docs.aws.amazon.com/proton/latest/userguide/images/icon-yes.png) Yes | ![\[No\]](http://docs.aws.amazon.com/proton/latest/userguide/images/icon-no.png) No | A component's main purpose is to be attached to a service instance and extend its infrastructure with additional resources. An attached component can read inputs from the service instance according to the spec. You can't directly delete the component or attach it to a different service instance. You can't delete its service instance or the related service and environment, either. To do any of these things, update the component to detach it from its service instance first. To maintain the component's infrastructure beyond the lifetime of a single service instance, you update the component and detach it from its service instance by removing the service and service instance names. This detached state is a transitional state. The component has no inputs. Its infrastructure stays provisioned and you can update it. You can delete resources that the component was associated with when it was attached (service instance, service). You can delete the component or update it to be attached to a service instance again. # Component infrastructure as code files Component infrastructure as code (IaC) files are similar to those for other AWS Proton resources. Learn here about some details that are specific to components. For complete information about authoring IaC files for AWS Proton, see [Authoring templates and creating bundles for AWS Proton](ag-template-authoring.md). ## Using parameters with components The AWS Proton parameter namespace includes some parameters that a service IaC file can reference to get an associated component's name and outputs. The namespace also includes parameters that a component IaC file can reference to get inputs, outputs, and resource values from the environment, service, and service instance that the component is associated with. A components doesn't have inputs of its own—it gets its inputs from the service instance it's attached to. A component can also read environment outputs. For more information about using parameters in component and associated service IaC files, see [Component CloudFormation IaC file parameter details and examples](comp-parameters.md). For general information about AWS Proton parameters and a complete reference of the parameter namespace, see [AWS Proton parameters](parameters.md). ## Authoring robust IaC files As an administrator, when you create a service template version, you can decide if you want to allow service instances created from the template version to have attached components. See the [supportedComponentSources](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateServiceTemplateVersion.html#proton-CreateServiceTemplateVersion-request-supportedComponentSources) parameter of the [CreateServiceTemplateVersion](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateServiceTemplateVersion.html) API action in the *AWS Proton API Reference*. However, for any future service instance, the person who creates the instance, decides whether or not to attach a component to it, and (in the case of directly defined components) authors the component IaC is typically a different person—a developer using your service template. Therefore, you can't guarantee that a component would be attached to a service instance. You also can't guarantee the existence of specific component output names or the validity and safety of the values of these outputs. AWS Proton and the Jinja syntax help you work around these issues and author robust service templates that render without failure in the following ways: + *AWS Proton parameter filters* – When you refer to component output properties, you can use *parameter filters*—modifiers that validate, filter, and format parameter values. For more information and examples, see [Parameter filters for CloudFormation IaC files](parameter-filters.md). + *Single property default* – When you refer to a single resource or output property of a component, you can guarantee that rendering your service template won't fail by using the `default` filter, with or without a default value. If the component, or a specific output parameter you're referring to, doesn't exist, the default value (or an empty string, if you haven't specified a default value) is rendered instead, and rendering succeeds. For more information, see [Provide default values for nonexistent references](parameter-filters.md#parameter-filters.proton.default). Examples: + `{{ service_instance.components.default.name | default("") }}` + `{{ service_instance.components.default.outputs.my-output | default("17") }}` **Note** Do not confuse the `.default` part of the namespace, which designates directly defined components, with the `default` filter, which provides a default value when referenced property doesn't exist. + *Entire object reference* – When you refer to the entire component, or to the collection of a component's outputs, AWS Proton returns an empty object, `{}`, and therefore guarantees that rendering your service template won't fail. You don't have to use any filter. Be sure to make the reference in a context that can take an empty object, or use an `{{ if .. }}` condition to test for an empty object. Examples: + `{{ service_instance.components.default }}` + `{{ service_instance.components.default.outputs }}` # Component CloudFormation example Here is a complete example of an AWS Proton directly defined component and how you can use it in an AWS Proton service. The component provisions an Amazon Simple Storage Service (Amazon S3) bucket and related access policy. The service instance can refer to this bucket and use it. 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 components based on this component template, to provision Amazon S3 buckets for different service instances and functional needs. The example covers authoring the various required CloudFormation infrastructure as code (IaC) files and creating a required AWS Identity and Access Management (IAM) role. The example groups steps by the owning people roles. ## Administrator steps **To enable developers to use components with a service** 1. Create an AWS Identity and Access Management (IAM) role that scopes down the resources that directly defined components running in your environment can provision. AWS Proton assumes this role later to provision directly defined components in the environment. For this example, use the following policy: **Example directly defined component role** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "cloudformation:CancelUpdateStack", "cloudformation:CreateChangeSet", "cloudformation:DeleteChangeSet", "cloudformation:DescribeStacks", "cloudformation:ContinueUpdateRollback", "cloudformation:DetectStackResourceDrift", "cloudformation:DescribeStackResourceDrifts", "cloudformation:DescribeStackEvents", "cloudformation:CreateStack", "cloudformation:DeleteStack", "cloudformation:UpdateStack", "cloudformation:DescribeChangeSet", "cloudformation:ExecuteChangeSet", "cloudformation:ListChangeSets", "cloudformation:ListStackResources" ], "Resource": "arn:aws:cloudformation:*:123456789012:stack/AWSProton-*" }, { "Effect": "Allow", "Action": [ "s3:CreateBucket", "s3:DeleteBucket", "s3:GetBucket*", "iam:CreatePolicy", "iam:DeletePolicy", "iam:GetPolicy", "iam:ListPolicyVersions", "iam:DeletePolicyVersion" ], "Resource": "*", "Condition": { "ForAnyValue:StringEquals": { "aws:CalledVia": "cloudformation.amazonaws.com" } } } ] } ``` ------ 1. Provide the role you created in the previous step when you create or update the environment. In the AWS Proton console, specify a **Component role** on the **Configure environment** page. If you're using the AWS Proton API or AWS CLI, specify the `componentRoleArn` of the [CreateEnvironment](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateEnvironment.html) or [UpdateEnvironment](https://docs.aws.amazon.com/proton/latest/APIReference/API_UpdateEnvironment.html) API actions. 1. Create a service template that refers to a directly defined component attached to the service instance. The example shows how to write a robust service template that doesn't break if a component isn't attached to the service instance. **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: # ... ``` 1. Create a new service template minor version that declares directly defined components as supported. + **Template bundle in Amazon S3** – In the AWS Proton console, when you create a service template version, for **Supported component sources**, choose **Directly defined**. If you're using the AWS Proton API or AWS CLI, specify `DIRECTLY_DEFINED` in the `supportedComponentSources` parameter of the [CreateServiceTemplateVersion](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateServiceTemplateVersion.html) or [UpdateServiceTemplateVersion](https://docs.aws.amazon.com/proton/latest/APIReference/API_UpdateServiceTemplateVersion.html) API actions. + **Template sync** – Commit a change to your service template bundle repository, where you specify `DIRECTLY_DEFINED` as an item of `supported_component_sources:` in the `.template-registration.yaml` file in the major version directory. For more information about this file, see [Syncing service templates](create-template-sync.md#create-template-sync-service-templates). 1. Publish the new service template minor version. For more information, see [Register and publish templates](template-create.md). 1. Be sure to allow the `proton:CreateComponent` in the IAM role of developers that use this service template. ## Developer steps **To use a directly defined component with a service instance** 1. Create a service that uses the service template version that the administrator created with component support. Alternatively, update one of your existing service instances to use the latest template version. 1. Write a component IaC template file that provisions an Amazon S3 bucket and a related access policy and exposes these resources as outputs. **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 ``` 1. If you're using the AWS Proton API or AWS CLI, write a manifest file for the component. **Example directly defined component manifest** ``` infrastructure: templates: - file: "cloudformation.yaml" rendering_engine: jinja template_language: cloudformation ``` 1. Create a directly defined component. AWS Proton assumes the component role that the administrator defined to provision the component. In the AWS Proton console, on the [Components](https://console.aws.amazon.com//proton/#/components) page, choose **Create component**. For **Component settings**, enter a **Component name** and an optional **Component description**. For **Component attachment**, choose **Attach the component to a service instance.** Select your environment, service, and service instance. For **Component source**, choose **CloudFormation**, and then choose the component IaC file. **Note** You don't need to provide a manifest—the console creates one for you. If you're using the AWS Proton API or AWS CLI, use the [CreateComponent](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateComponent.html) API action. Set a component `name` and optional `description`. Set `environmentName`, `serviceName`, and `serviceInstanceName`. Set `templateSource` and `manifest` to the paths of the files you created. **Note** Specifying an environment name is optional when you specify service and service instance names. The combination of these two is unique in your AWS account, and AWS Proton can determine the environment from the service instance. 1. Update your service instance to redeploy it. AWS Proton uses outputs from your component in the rendered service instance template, to enable your application to use the Amazon S3 bucket that the component provisioned.