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 templates To add your template bundle to your AWS Proton template library, create a template minor version and register it with AWS Proton. When creating the template, provide the name of the Amazon S3 bucket and path for your template bundle. After templates are published, they can be selected by platform team members and developers. After they're selected, AWS Proton uses the template to create and provision infrastructure and applications. As an administrator, you can create and register an environment template with AWS Proton. This environment template can then be used to deploy multiple environments. For example, it can be used to deploy "dev," "staging," and "prod" environments. The "dev" environment might include a VPC with private subnets and a restrictive access policy to all resources. Environment outputs can be used as inputs for services. You can create and register environment templates to create two different types of environments. Both you and developers can use AWS Proton to deploy services to both types. + Register and publish a *standard* environment template that AWS Proton uses to create a *standard* environment that provisions and manages the environment infrastructure. + Register and publish a *customer managed* environment template that AWS Proton uses to create a customer managed environment that connects to your existing provisioned infrastructure. AWS Proton *doesn't* manage your existing provisioned infrastructure. You can create and register service templates with AWS Proton to deploy services to environments. An AWS Proton environment must be created before a service can be deployed to it. The following list describes how you create and manage templates with AWS Proton. + (Optional) Prepare an IAM role to control developer access to AWS Proton API calls and AWS Proton IAM service roles. For more information, see [IAM Roles](ag-environment-roles.md). + Compose a template bundle. For more information, see [Template bundles](ag-template-authoring.md#ag-template-bundles). + Create and register a template with AWS Proton after the template bundle is composed, compressed, and saved in an Amazon S3 bucket. You can do this either in the console or by using the AWS CLI. + Test and use the template to create and manage AWS Proton provisioned resources after it's registered with AWS Proton. + Create and manage major and minor versions of the template throughout the life of the template. You can manage template versions manually or with template sync configurations: + Use the AWS Proton console and AWS CLI to create a new minor or major version. + [Create a template sync configuration](create-template-sync.md) that lets AWS Proton automatically create a new minor or major version when it detects a change to your template bundle in a repository that you define. For additional information, see the [https://docs.aws.amazon.com/proton/latest/APIReference/Welcome.html](https://docs.aws.amazon.com/proton/latest/APIReference/Welcome.html). **Topics** + [Versioned templates](ag-template-versions.md) + [Register and publish templates](template-create.md) + [View template data](template-view.md) + [Update a template](template-update.md) + [Delete templates](template-delete.md) + [Template sync configurations](ag-template-sync-configs.md) + [Service sync configurations](ag-service-sync-configs.md) # Versioned templates As an administrator or a member of a platform team, you define, create, and manage a library of versioned templates that are used to provision infrastructure resources. There are two types of template versions—minor versions and major versions. + *Minor versions* – Changes to the template that have a backward compatible schema. These changes don't require the developer to provide new information when updating to the new template version. When you attempt to make a minor version change, AWS Proton makes a best-effort attempt to determine whether the schema of the new version is backward compatible with the previous minor versions of the template. If the new schema isn't backward compatible, AWS Proton fails the registration of the new minor version. **Note** Compatibility is determined solely based on schema. AWS Proton doesn't check if the template bundle infrastructure as code (IaC) file is backward compatible with the previous minor versions. For example, AWS Proton doesn't check if the new IaC file causes breaking changes for the applications that are running on the infrastructure provisioned by a previous minor version of the template. + *Major versions* – Changes to the template that may not be not backward compatible. These changes typically require new inputs from the developer and often involve template schema changes. You may sometimes choose to designate a backward compatible change as a major version based on your team’s operational model. The way AWS Proton determines if a template version request is for a minor or major version depends on the way template changes are tracked: + When you explicitly make a request to create a new template version, you request a major version by specifying a major version number, and you request a minor version by not specifying a major version number. + When you use [template sync](ag-template-sync-configs.md) (and therefore you don't make explicit template version requests), AWS Proton attempts to create new minor versions for template changes that occur in the existing YAML file. AWS Proton creates a major version when you create a new directory for the new template change (for example, move from v1 to v2). **Note** A new minor version registration based on template sync still fails if AWS Proton determines that the change isn't backward compatible. When you publish a new version of a template, it becomes the **Recommended** version if it's the highest major and minor version. New AWS Proton resources are created using the new recommended version, and AWS Proton prompts administrators to use the new version and to update existing AWS Proton resources that are using an outdated version. # Register and publish templates You can register and publish environment and service templates with AWS Proton, as described in the following sections. You can create a new version of a template with the console or AWS CLI. Alternatively, you can use the console or AWS CLI to create a template and configure a [configure a template sync](ag-template-sync-configs.md) for it. This configuration lets AWS Proton sync from template bundles located in registered git repositories that you have defined. Whenever a commit is pushed to your repository that changes one of your template bundles, a new minor or major version of your template is created, if the version doesn’t already exist. To learn more about template sync configuration prerequisites and requirements, see [Template sync configurations](ag-template-sync-configs.md). ## Register and publish environment templates You can register and publish the following types of environment templates. + Register and publish a *standard* environment template that AWS Proton uses to deploy and manage environment infrastructure. + Register and publish a *customer managed* environment template that AWS Proton uses to connect to your existing provisioned infrastructure that you manage. AWS Proton *doesn't* manage your existing provisioned infrastructure. **Important** As an administrator, ensure that your provisioned and managed infrastructure and all output parameters are compatible with associated *customer managed* environment templates. AWS Proton can't account for changes on your behalf because these changes aren't visible to AWS Proton. Inconsistencies result in failures. You can use the console or the AWS CLI to register and publish an environment template. ------ #### [ AWS Management Console ] **Use the console to register and publish a new environment template.** 1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environment templates**. 1. Choose **Create environment template**. 1. In the **Create environment template** page, in the **Template options** section, choose one of the two available template options. + **Create a template for provisioning new environments**. + **Create a template to use provisioned infrastructure that you manage**. 1. If you chose **Create a template for provisioning new environments**, in the **Template bundle source** section, choose one of the three available template bundle source options. To learn more about requirements and prerequisites for syncing templates, see [Template sync configurations](ag-template-sync-configs.md). + **Use one of our sample template bundles**. + **Use your own template bundle**. + **[Sync templates from Git](ag-template-sync-configs.md)**. 1. **Provide a path to a template bundle.** 1. If you chose **Use one of our sample template bundles**: In the **Sample template bundle** section, select a sample template bundle. 1. If you chose **Sync templates from Git**, in the **Source code** section: 1. Select the repository for your template sync configuration. 1. Enter the name of the repository branch to sync from. 1. (Optional) Enter name of a directory to limit the search for your template bundle. 1. Otherwise, in the **S3 bundle location** section, provide a path to your template bundle. 1. In the **Template details** section. 1. Enter a **Template name**. 1. (Optional) Enter a **Template display name**. 1. (Optional) Enter a **Template description** for the environment template. 1. (Optional) Check the check box for **Customize encryption settings (advanced)** in the **Encryption settings** section to provide your own encryption key. 1. (Optional) In the **Tags** section, choose **Add new tag** and enter a key and value to create a customer managed tag. 1. Choose **Create Environment template**. You're now on a new page that displays the status and details for your new environment template. These details include a list of AWS and customer managed tags. AWS Proton automatically generates AWS managed tags for you when you create AWS Proton resources. For more information, see [AWS Proton resources and tagging](resources.md). 1. The status of a new environment template status starts in the **Draft** state. You and others with `proton:CreateEnvironment` permissions can view and access it. Follow the next step to make the template available to others. 1. In the **Template versions** section, choose the radio button to the left of the minor version of the template you just created (1.0). As an alternative, you can choose **Publish** in the info alert and skip the next step. 1. In the **Template versions** section, choose **Publish**. 1. The template status changes to **Published**. Because it's the latest version of the template, it's the **Recommended** version. 1. In the navigation pane, select **Environment templates** to view a list of your environment templates and details. **Use the console to register new major and minor versions of an environment template.** For more information, see [Versioned templates](ag-template-versions.md). 1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environment Templates**. 1. In the list of environment templates, choose the name of the environment template that you want to create a major or minor version for. 1. In the environment template detail view, choose **Create new version** in the **Template versions** section. 1. In the **Create a new environment template version** page, in the **Template bundle source** section, choose one of the two available template bundle source options. + **Use one of our sample template bundles**. + **Use your own template bundle**. 1. Provide a path to the selected template bundle. + If you chose **Use one of our sample template bundles**, in the **Sample template bundle** section, select a sample template bundle. + If you chose **Use your own template bundle**, in the **S3 bundle location** section, choose the path to your template bundle. 1. In the **Template details** section. 1. (Optional) Enter a **Template display name**. 1. (Optional) Enter a **Template description** for the service template. 1. In the **Template details** section, choose one of the following options. + To create a minor version, keep the check box **Check to create a new major version** empty. + To create a major version, check the check box **Check to create a new major version**. 1. Continue through the console steps to create the new minor or major version and choose **Create new version**. ------ #### [ AWS CLI ] **Use the CLI to register and publish a new environment template as shown in the following steps.** 1. Create a *standard* OR *customer managed* environment template by specifying the region, name, display name (optional), and description (optional). 1. Create a *standard* environment template. Run the following command: ``` $ aws proton create-environment-template \ --name "simple-env" \ --display-name "Fargate" \ --description "VPC with public access" ``` Response: ``` { "environmentTemplate": { "arn": "arn:aws:proton:region-id:123456789012:environment-template/simple-env", "createdAt": "2020-11-11T23:02:45.336000+00:00", "description": "VPC with public access", "displayName": "VPC", "lastModifiedAt": "2020-11-11T23:02:45.336000+00:00", "name": "simple-env" } } ``` 1. Create a *customer managed* environment template by adding the `provisioning` parameter with value `CUSTOMER_MANAGED`. Run the following command: ``` $ aws proton create-environment-template \ --name "simple-env" \ --display-name "Fargate" \ --description "VPC with public access" \ --provisioning "CUSTOMER_MANAGED" ``` Response: ``` { "environmentTemplate": { "arn": "arn:aws:proton:region-id:123456789012:environment-template/simple-env", "createdAt": "2020-11-11T23:02:45.336000+00:00", "description": "VPC with public access", "displayName": "VPC", "lastModifiedAt": "2020-11-11T23:02:45.336000+00:00", "name": "simple-env", "provisioning": "CUSTOMER_MANAGED" } } ``` 1. **Create a minor version 0 of major version 1 of the environment template** This and the remaining steps are the same for both the *standard* and *customer managed* environment templates. Include the template name, major version, and the S3 bucket name and key for the bucket that contains your environment template bundle. Run the following command: ``` $ aws proton create-environment-template-version \ --template-name "simple-env" \ --description "Version 1" \ --source s3="{bucket=your_s3_bucket, key=your_s3_key}" ``` Response: ``` { "environmentTemplateVersion": { "arn": "arn:aws:proton:region-id:123456789012:environment-template/simple-env:1.0", "createdAt": "2020-11-11T23:02:47.763000+00:00", "description": "Version 1", "lastModifiedAt": "2020-11-11T23:02:47.763000+00:00", "majorVersion": "1", "minorVersion": "0", "status": "REGISTRATION_IN_PROGRESS", "templateName": "simple-env" } } ``` 1. Use the get command to check the registrations status. Run the following command: ``` $ aws proton get-environment-template-version \ --template-name "simple-env" \ --major-version "1" \ --minor-version "0" ``` Response: ``` { "environment": { "arn": "arn:aws:proton:region-id:123456789012:environment-template/simple-env:1.0", "createdAt": "2020-11-11T23:02:47.763000+00:00", "description": "Version 1", "lastModifiedAt": "2020-11-11T23:02:47.763000+00:00", "majorVersion": "1", "minorVersion": "0", "recommendedMinorVersion": "0", "schema": "schema:\n format:\n openapi: \"3.0.0\"\n environment_input_type: \"MyEnvironmentInputType\"\n types:\n MyEnvironmentInputType:\n type: object\n description: \"Input properties for my environment\"\n properties:\n my_sample_input:\n type: string\n description: \"This is a sample input\"\n default: \"hello world\"\n my_other_sample_input:\n type: string\n description: \"Another sample input\"\n required:\n - my_other_sample_input\n", "status": "DRAFT", "statusMessage": "", "templateName": "simple-env" } } ``` 1. Publish of minor version 0 of major version 1 of the environment template by providing the template name and the major and minor version. This version is the `Recommended` version. Run the following command: ``` $ aws proton update-environment-template-version \ --template-name "simple-env" \ --major-version "1" \ --minor-version "0" \ --status "PUBLISHED" ``` Response: ``` { "environmentTemplateVersion": { "arn": "arn:aws:proton:region-id:123456789012:environment-template/simple-env:1.0", "createdAt": "2020-11-11T23:02:47.763000+00:00", "description": "Version 1", "lastModifiedAt": "2020-11-11T23:02:54.610000+00:00", "majorVersion": "1", "minorVersion": "0", "recommendedMinorVersion": "0", "schema": "schema:\n format:\n openapi: \"3.0.0\"\n environment_input_type: \"MyEnvironmentInputType\"\n types:\n MyEnvironmentInputType:\n type: object\n description: \"Input properties for my environment\"\n properties:\n my_sample_input:\n type: string\n description: \"This is a sample input\"\n default: \"hello world\"\n my_other_sample_input:\n type: string\n description: \"Another sample input\"\n required:\n - my_other_sample_input\n", "status": "PUBLISHED", "statusMessage": "", "templateName": "simple-env" } } ``` After creating a new template using the AWS CLI, you can view a list of AWS and customer managed tags. AWS Proton automatically generates AWS managed tags for you. You can also modify and create customer managed tags using the AWS CLI. For more information, see [AWS Proton resources and tagging](resources.md). Run the following command: ``` $ aws proton list-tags-for-resource \ --resource-arn "arn:aws:proton:region-id:123456789012:environment-template/simple-env" ``` ------ ## Register and publish service templates When you create a service template version, you specify a list of compatible environment templates. That way, when developers select a service template, they have options for which environment to deploy their service to. Before creating a service from a service template or before publishing a service template, confirm that environments are deployed from the listed compatible environment templates. You *can't* update a service to the new major version if it's deployed to an environment that was built from a removed compatible environment template. To add or remove compatible environment templates for a service template version, you create a new major version of it. You can use the console or the AWS CLI to register and publish a service template. ------ #### [ AWS Management Console ] **Use the console to register and publish a new service template.** 1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Service templates**. 1. Choose **Create service template**. 1. In the **Create service template** page, in the **Template bundle source** section, choose one of the available template options. + **Use your own template bundle**. + **Sync templates from Git**. 1. **Provide a path to a template bundle.** 1. If you chose **Sync templates from Git**, in the **Source code repository** section: 1. Select the repository for your template sync configuration. 1. Enter the name of the repository branch to sync from. 1. (Optional) Enter name of a directory to limit the search for your template bundle. 1. Otherwise, in the **S3 bundle location** section, provide a path to your template bundle. 1. In the **Template details** section. 1. Enter a **Template name**. 1. (Optional) Enter a **Template display name**. 1. (Optional) Enter a **Template description** for the service template. 1. In the **Compatible environment templates** section, choose from a list of compatible environment templates. 1. (Optional) In the **Encryption settings** section, choose **Customize encryption settings (advanced)** to provide your own encryption key. 1. (Optional) In the **Pipeline** section: If you aren't including a service pipeline definition in your service template, uncheck the **Pipeline - optional** check box at the bottom of the page. You *can't* change this after the service template is created. For more information, see [Template bundles](ag-template-authoring.md#ag-template-bundles). 1. (Optional) In the **Supported component sources** section, for **Component sources**, choose **Directly defined** to enable attachment of directly defined components to your service instances. 1. (Optional) In the **Tags** section, choose **Add new tag** and enter a key and value to create a customer managed tag. 1. Choose **Create a service template**. You're now on a new page that displays the status and details for your new service template. These details include a list of AWS and customer managed tags. AWS Proton automatically generates AWS managed tags for you when you create AWS Proton resources. For more information, see [AWS Proton resources and tagging](resources.md). 1. The status of a new service template status starts in the **Draft** state. You and others with `proton:CreateService` permissions can view and access it. Follow the next step to make the template available to others. 1. In the **Template versions** section, choose the radio button to the left of the minor version of the template you just created (1.0). As an alternative, you can choose **Publish** in the info alert and skip the next step. 1. In the **Template versions** section, choose **Publish**. 1. The template status changes to **Published**. Because it's the latest version of the template, it's the **Recommended** version. 1. In the navigation pane, select **Service templates** to view a list of your service templates and details. **Use the console to register new major and minor versions of a service template.** For more information, see [Versioned templates](ag-template-versions.md). 1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Service Templates**. 1. In the list of service templates, choose the name of the service template that you want to create a major or minor version for. 1. In the service template detail view, choose **Create new version** in the **Template versions** section. 1. In the **Create a new service template version** page, in the **Bundle source** section, select **Use your own template bundle**. 1. In the **S3 bundle location** section, choose the path to your template bundle. 1. In the **Template details** section. 1. (Optional) Enter a **Template display name**. 1. (Optional) Enter a **Template description** for the service template. 1. In the **Template details** section, choose one of the following options. + To create a minor version, keep the check box **Check to create a new major version** empty. + To create a major version, check the check box **Check to create a new major version**. 1. Continue through the console steps to create the new minor or major version and choose **Create new version**. ------ #### [ AWS CLI ] To create service template that deploys a service without a service pipeline, add the parameter and value `--pipeline-provisioning "CUSTOMER_MANAGED"` to the `create-service-template` command. Configure your template bundles as described in [Template bundles](ag-template-authoring.md#ag-template-bundles) creation and [Schema requirements for service template bundles](ag-schema.md#schema-req-svc). **Note** You can't modify `pipelineProvisioning` after the service template is created. 1. **Use the CLI to register and publish a new service template, with or without a service pipeline, as shown in the following steps.** 1. **Create a service template with a service pipeline using the CLI.** Specify the name, display name (optional), and description (optional). Run the following command: ``` $ aws proton create-service-template \ --name "fargate-service" \ --display-name "Fargate" \ --description "Fargate-based Service" ``` Response: ``` { "serviceTemplate": { "arn": "arn:aws:proton:region-id:123456789012:service-template/fargate-service", "createdAt": "2020-11-11T23:02:55.551000+00:00", "description": "Fargate-based Service", "displayName": "Fargate", "lastModifiedAt": "2020-11-11T23:02:55.551000+00:00", "name": "fargate-service" } } ``` 1. **Create a service template without a service pipeline.** Add `--pipeline-provisioning`. Run the folllowing command: ``` $ aws proton create-service-template \ --name "fargate-service" \ --display-name "Fargate" \ --description "Fargate-based Service" \ --pipeline-provisioning "CUSTOMER_MANAGED" ``` Response: ``` { "serviceTemplate": { "arn": "arn:aws:proton:region-id:123456789012:service-template/fargate-service", "createdAt": "2020-11-11T23:02:55.551000+00:00", "description": "Fargate-based Service", "displayName": "Fargate", "lastModifiedAt": "2020-11-11T23:02:55.551000+00:00", "name": "fargate-service", "pipelineProvisioning": "CUSTOMER_MANAGED" } } ``` 1. **Create a minor version 0 of major version 1 of the service template.** Include the template name, compatible environment templates, major version, and the S3 bucket name and key for the bucket that contains your service template bundle. Run the following command: ``` $ aws proton create-service-template-version \ --template-name "fargate-service" \ --description "Version 1" \ --source s3="{bucket=your_s3_bucket, key=your_s3_key}" \ --compatible-environment-templates '[{"templateName":"simple-env","majorVersion":"1"}]' ``` Response: ``` { "serviceTemplateMinorVersion": { "arn": "arn:aws:proton:region-id:123456789012:service-template/fargate-service:1.0", "compatibleEnvironmentTemplates": [ { "majorVersion": "1", "templateName": "simple-env" } ], "createdAt": "2020-11-11T23:02:57.912000+00:00", "description": "Version 1", "lastModifiedAt": "2020-11-11T23:02:57.912000+00:00", "majorVersion": "1", "minorVersion": "0", "status": "REGISTRATION_IN_PROGRESS", "templateName": "fargate-service" } } ``` 1. Use the *get* command to check the registrations status. Run the folllowing command: ``` $ aws proton get-service-template-version \ --template-name "fargate-service" \ --major-version "1" \ --minor-version "0" ``` Response: ``` { "serviceTemplateMinorVersion": { "arn": "arn:aws:proton:us-east-1:123456789012:service-template/fargate-service:1.0", "compatibleEnvironmentTemplates": [ { "majorVersion": "1", "templateName": "simple-env" } ], "createdAt": "2020-11-11T23:02:57.912000+00:00", "description": "Version 1", "lastModifiedAt": "2020-11-11T23:02:57.912000+00:00", "majorVersion": "1", "minorVersion": "0", "schema": "schema:\n format:\n openapi: \"3.0.0\"\n pipeline_input_type: \"MyPipelineInputType\"\n service_input_type: \"MyServiceInstanceInputType\"\n\n types:\n MyPipelineInputType:\n type: object\n description: \"Pipeline input properties\"\n required:\n - my_sample_pipeline_required_input\n properties:\n my_sample_pipeline_optional_input:\n type: string\n description: \"This is a sample input\"\n default: \"hello world\"\n my_sample_pipeline_required_input:\n type: string\n description: \"Another sample input\"\n\n MyServiceInstanceInputType:\n type: object\n description: \"Service instance input properties\"\n required:\n - my_sample_service_instance_required_input\n properties:\n my_sample_service_instance_optional_input:\n type: string\n description: \"This is a sample input\"\n default: \"hello world\"\n my_sample_service_instance_required_input:\n type: string\n description: \"Another sample input\"", "status": "DRAFT", "statusMessage": "", "templateName": "fargate-service" } } ``` 1. Publish the service template by using the update command to change the status to `"PUBLISHED"`. Run the following command: ``` $ aws proton update-service-template-version \ --template-name "fargate-service" \ --description "Version 1" \ --major-version "1" \ --minor-version "0" \ --status "PUBLISHED" ``` Response: ``` { "serviceTemplateVersion": { "arn": "arn:aws:proton:region-id:123456789012:service-template/fargate-service:1.0", "compatibleEnvironmentTemplates": [ { "majorVersion": "1", "templateName": "simple-env" } ], "createdAt": "2020-11-11T23:02:57.912000+00:00", "description": "Version 1", "lastModifiedAt": "2020-11-11T23:02:57.912000+00:00", "majorVersion": "1", "minorVersion": "0", "recommendedMinorVersion": "0", "schema": "schema:\n format:\n openapi: \"3.0.0\"\n pipeline_input_type: \"MyPipelineInputType\"\n service_input_type: \"MyServiceInstanceInputType\"\n\n types:\n MyPipelineInputType:\n type: object\n description: \"Pipeline input properties\"\n required:\n - my_sample_pipeline_required_input\n properties:\n my_sample_pipeline_optional_input:\n type: string\n description: \"This is a sample input\"\n default: \"hello pipeline\"\n my_sample_pipeline_required_input:\n type: string\n description: \"Another sample input\"\n\n MyServiceInstanceInputType:\n type: object\n description: \"Service instance input properties\"\n required:\n - my_sample_service_instance_required_input\n properties:\n my_sample_service_instance_optional_input:\n type: string\n description: \"This is a sample input\"\n default: \"hello world\"\n my_sample_service_instance_required_input:\n type: string\n description: \"Another sample input\"\n", "status": "PUBLISHED", "statusMessage": "", "templateName": "fargate-service" } } ``` 1. Check that AWS Proton has published version 1.0 by using the get command to retrieve service template detail data. Run the following command: ``` $ aws proton get-service-template-version \ --template-name "fargate-service" \ --major-version "1" \ --minor-version "0" ``` Response: ``` { "serviceTemplateMinorVersion": { "arn": "arn:aws:proton:us-east-1:123456789012:service-template/fargate-service:1.0", "compatibleEnvironmentTemplates": [ { "majorVersion": "1", "templateName": "simple-env" } ], "createdAt": "2020-11-11T23:02:57.912000+00:00", "description": "Version 1", "lastModifiedAt": "2020-11-11T23:03:04.767000+00:00", "majorVersion": "1", "minorVersion": "0", "schema": "schema:\n format:\n openapi: \"3.0.0\"\n pipeline_input_type: \"MyPipelineInputType\"\n service_input_type: \"MyServiceInstanceInputType\"\n\n types:\n MyPipelineInputType:\n type: object\n description: \"Pipeline input properties\"\n required:\n - my_sample_pipeline_required_input\n properties:\n my_sample_pipeline_optional_input:\n type: string\n description: \"This is a sample input\"\n default: \"hello world\"\n my_sample_pipeline_required_input:\n type: string\n description: \"Another sample input\"\n\n MyServiceInstanceInputType:\n type: object\n description: \"Service instance input properties\"\n required:\n - my_sample_service_instance_required_input\n properties:\n my_sample_service_instance_optional_input:\n type: string\n description: \"This is a sample input\"\n default: \"hello world\"\n my_sample_service_instance_required_input:\n type: string\n description: \"Another sample input\"", "status": "PUBLISHED", "statusMessage": "", "templateName": "fargate-service" } } ``` ------ # View template data You can view lists of templates with details and view individual templates with detail data by using the [AWS Proton console](https://console.aws.amazon.com//proton/) and AWS CLI. *Customer managed* environment template data includes the `provisioned` parameter with the value `CUSTOMER_MANAGED`. If a service template *doesn't* include a service pipeline, the service template data includes the `pipelineProvisioning` parameter with the value `CUSTOMER_MANAGED`. For more information, see [Register and publish templates](template-create.md). You can use the console or the AWS CLI to list and view template data. ------ #### [ AWS Management Console ] **Use the console to list and view templates.** 1. To view a list of templates, choose **(Environment or Service) templates**. 1. To view detail data choose the name of a template. View the detail data of the template, a list of the major and minor versions of the template, a list of the AWS Proton resources that were deployed using template versions and template tags. The recommended major version and minor version is labeled as **Recommended**. ------ #### [ AWS CLI ] **Use the AWS CLI to list and view templates.** Run the following command: ``` $ aws proton get-environment-template-version \ --template-name "simple-env" \ --major-version "1" \ --minor-version "0" ``` Response: ``` { "environmentTemplateVersion": { "arn": "arn:aws:proton:region-id:123456789012:environment-template/simple-env:1.0", "createdAt": "2020-11-10T18:35:08.293000+00:00", "description": "Version 1", "lastModifiedAt": "2020-11-10T18:35:11.162000+00:00", "majorVersion": "1", "minorVersion": "0", "recommendedMinorVersion": "0", "schema": "schema:\n format:\n openapi: \"3.0.0\"\n environment_input_type: \"MyEnvironmentInputType\"\n types:\n MyEnvironmentInputType:\n type: object\n description: \"Input properties for my environment\"\n properties:\n my_sample_input:\n type: string\n description: \"This is a sample input\"\n default: \"hello world\"\n my_other_sample_input:\n type: string\n description: \"Another sample input\"\n required:\n - my_other_sample_input\n", "status": "DRAFT", "statusMessage": "", "templateName": "simple-env" } } ``` Run the following command: ``` $ aws proton list-environment-templates ``` Response: ``` { "templates": [ { "arn": "arn:aws:proton:region-id:123456789012:environment-template/simple-env-3", "createdAt": "2020-11-10T18:35:05.763000+00:00", "description": "VPC with Public Access", "displayName": "VPC", "lastModifiedAt": "2020-11-10T18:35:05.763000+00:00", "name": "simple-env-3", "recommendedVersion": "1.0" }, { "arn": "arn:aws:proton:region-id:123456789012:environment-template/simple-env-1", "createdAt": "2020-11-10T00:14:06.881000+00:00", "description": "Some SSM Parameters", "displayName": "simple-env-1", "lastModifiedAt": "2020-11-10T00:14:06.881000+00:00", "name": "simple-env-1", "recommendedVersion": "1.0" } ] } ``` View a minor version of a service template. Run the following command: ``` $ aws proton get-service-template-version \ --template-name "fargate-service" \ --major-version "1" \ --minor-version "0" ``` Response: ``` { "serviceTemplateMinorVersion": { "arn": "arn:aws:proton:us-east-1:123456789012:service-template/fargate-service:1.0", "compatibleEnvironmentTemplates": [ { "majorVersion": "1", "templateName": "simple-env" } ], "createdAt": "2020-11-11T23:02:57.912000+00:00", "description": "Version 1", "lastModifiedAt": "2020-11-11T23:02:57.912000+00:00", "majorVersion": "1", "minorVersion": "0", "schema": "schema:\n format:\n openapi: \"3.0.0\"\n pipeline_input_type: \"MyPipelineInputType\"\n service_input_type: \"MyServiceInstanceInputType\"\n\n types:\n MyPipelineInputType:\n type: object\n description: \"Pipeline input properties\"\n required:\n - my_sample_pipeline_required_input\n properties:\n my_sample_pipeline_optional_input:\n type: string\n description: \"This is a sample input\"\n default: \"hello world\"\n my_sample_pipeline_required_input:\n type: string\n description: \"Another sample input\"\n\n MyServiceInstanceInputType:\n type: object\n description: \"Service instance input properties\"\n required:\n - my_sample_service_instance_required_input\n properties:\n my_sample_service_instance_optional_input:\n type: string\n description: \"This is a sample input\"\n default: \"hello world\"\n my_sample_service_instance_required_input:\n type: string\n description: \"Another sample input\"", "status": "DRAFT", "statusMessage": "", "templateName": "fargate-service" } } ``` View a service template without a service pipeline as shown in the next example command and response. Run the following command: ``` $ aws proton get-service-template \ --name "simple-svc-template-cli" ``` Response: ``` { "serviceTemplate": { "arn": "arn:aws:proton:region-id:123456789012:service-template/simple-svc-template-cli", "createdAt": "2021-02-18T15:38:57.949000+00:00", "displayName": "simple-svc-template-cli", "lastModifiedAt": "2021-02-18T15:38:57.949000+00:00", "status": "DRAFT", "name": "simple-svc-template-cli", "pipelineProvisioning": "CUSTOMER_MANAGED" } } ``` ------ # Update a template You can update a template as described in the following list. + Edit the `description` or `display name` of a template when you use either the console or AWS CLI. You *can't* edit the `name` of a template. + Update the status of a template minor version when you use either the console or AWS CLI. You can only change the status from `DRAFT` to `PUBLISHED`. + Edit the display name and description of a minor or major version of a template when you use the AWS CLI. ------ #### [ AWS Management Console ] Edit a template description and display name using the console as described in the following steps. **In the list of templates.** 1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **(Environment or Service) Templates**. 1. In the list of templates, choose the radio button to the left of the template that you want to update the description or display name for. 1. Choose **Actions** and then **Edit**. 1. In the **Edit (environment or service) template** page, in the **Template details** section, enter your edits in the form and choose **Save changes**. Change the status of a minor version of a template using the console to publish a template as described in the following. You can only change the status from `DRAFT` to `PUBLISHED`. **In the (environment or service) template detail page.** 1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **(Environment or Service) templates**. 1. In the list of templates, choose the name of the template that you want to update the status of a minor version from **Draft** to **Published**. 1. In the (environment or service) template detail page, in the **Template versions** section, select the radio button to the left of the minor version that you want to publish. 1. Choose **Publish** in the **Template versions** section. The status changes from **Draft** to **Published**. ------ #### [ AWS CLI ] The following example command and response shows how you can edit the description of an environment template. Run the following command. ``` $ aws proton update-environment-template \ --name "simple-env" \ --description "A single VPC with public access" ``` Response: ``` { "environmentTemplate": { "arn": "arn:aws:proton:region-id:123456789012:environment-template/simple-env", "createdAt": "2020-11-28T22:02:10.651000+00:00", "description": "A single VPC with public access", "displayName": "simple-env", "lastModifiedAt": "2020-11-29T16:11:18.956000+00:00", "majorVersion": "1", "minorVersion": "0", "recommendedMinorVersion": "0", "schema": "schema:\n format:\n openapi: \"3.0.0\"\n environment_input_type: \"MyEnvironmentInputType\"\n types:\n MyEnvironmentInputType:\n type: object\n description: \"Input properties for my environment\"\n properties:\n my_sample_input:\n type: string\n description: \"This is a sample input\"\n default: \"hello world\"\n my_other_sample_input:\n type: string\n description: \"Another sample input\"\n required:\n - my_other_sample_input\n", "status": "PUBLISHED", "statusMessage": "", "templateName": "simple-env" } } ``` You can also use the AWS CLI to update service templates. See [Register and publish service templates](template-create.md#svc-template-v1), step 5, for an example of updating the status of a minor version of a service template. ------ # Delete templates Templates can be deleted using the console and AWS CLI. You can delete a minor version of an environment template if there are no environments deployed to that version. You can delete a minor version of a service template if there are no service instances or pipelines deployed to that version. Your pipeline can be deployed to a different template version than your service instance. For example, if your service instance is updated to version 1.1 from 1.0 and your pipeline is still deployed to version 1.0, you can’t delete service template 1.0. ------ #### [ AWS Management Console ] You can use the console to delete the entire template or individual minor and major versions of a template. Use the console to delete templates as follows. **Note** When you delete the entire template, you also delete the major and minor versions of the template. **In the list of (environment or service) templates.** 1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **(Environment or Service) Templates**. 1. In the list of templates, select the radio button to the left of the template you want to delete. You can only delete an entire template if there are no AWS Proton resources deployed to its versions. 1. Choose **Actions** and then **Delete** to delete the entire template. 1. A modal prompts you to confirm the delete action. 1. Follow the instructions and choose **Yes, delete**. **In the (environment or service) template detail page.** 1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **(Environment or Service) Templates**. 1. In the list of templates, choose the name of the template that you want to entirely delete or delete individual major or minor versions of it. 1. **To delete the entire template.** You can only delete an entire template if there are no AWS Proton resources deployed to its versions. 1. Choose **Delete**, top right corner of page. 1. A modal prompts you to confirm the delete action. 1. Follow the instructions and choose **Yes, delete**. 1. **To delete major or minor versions of a template.** You can only delete a minor version of a template if there are no AWS Proton resources deployed to that version. 1. In the **Template versions** section, select the radio button to the left of the version that you want to delete. 1. Choose **Delete** in the **Template versions** section. 1. A modal prompts you to confirm the delete action. 1. Follow the instructions and choose **Yes, delete**. ------ #### [ AWS CLI ] AWS CLI template delete operations *don't* include the deletion of other versions of a template. When using the AWS CLI, delete templates with the following conditions. + Delete an entire template if no minor or major versions of the template exist. + Delete a major version when you delete the last remaining minor version. + Delete a minor version of a template if there are no AWS Proton resources deployed to that version. + Delete the recommended minor version of a template if no other minor versions of the template exist and there are no AWS Proton resources deployed to that version. **The following example commands and responses show how to use the AWS CLI to delete templates.** Run the following command: ``` $ aws proton delete-environment-template-version \ --template-name "simple-env" \ --major-version "1" \ --minor-version "0" ``` Response: ``` { "environmentTemplateVersion": { "arn": "arn:aws:proton:region-id:123456789012:environment-template/simple-env:1.0", "createdAt": "2020-11-11T23:02:47.763000+00:00", "description": "Version 1", "lastModifiedAt": "2020-11-11T23:02:54.610000+00:00", "majorVersion": "1", "minorVersion": "0", "status": "PUBLISHED", "statusMessage": "", "templateName": "simple-env" } } ``` Run the following command: ``` $ aws proton delete-environment-template \ --name "simple-env" ``` Response: ``` { "environmentTemplate": { "arn": "arn:aws:proton:region-id:123456789012:environment-template/simple-env", "createdAt": "2020-11-11T23:02:45.336000+00:00", "description": "VPC with Public Access", "displayName": "VPC", "lastModifiedAt": "2020-11-12T00:23:22.339000+00:00", "name": "simple-env", "recommendedVersion": "1.0" } } ``` Run the following command: ``` $ aws proton delete-service-template-version \ --template-name "fargate-service" \ --major-version "1" \ --minor-version "0" ``` Response: ``` { "serviceTemplateVersion": { "arn": "arn:aws:proton:region-id:123456789012:service-template/fargate-service:1.0", "compatibleEnvironmentTemplates": [{"majorVersion": "1", "templateName": "simple-env"}], "createdAt": "2020-11-28T22:07:05.798000+00:00", "lastModifiedAt": "2020-11-28T22:19:05.368000+00:00", "majorVersion": "1", "minorVersion": "0", "status": "PUBLISHED", "statusMessage": "", "templateName": "fargate-service" } } ``` ------ # Template sync configurations Learn how to configure a template to let AWS Proton sync from template bundles located in registered git repositories that you define. When a commit is pushed to your repository, AWS Proton checks for changes to your repository template bundles. If it detects a template bundle change, a new minor or major version of its template is created, if the version doesn’t already exist. AWS Proton currently supports GitHub, GitHub Enterprise, and BitBucket. ## Pushing a commit to a synced template bundle When you push a commit to a branch that's being tracked by one of your templates, AWS Proton clones your repository and determines what templates it needs to sync. It scans the files in your directory to find directories matching the convention of `{template-name}/{major-version}/`. After AWS Proton determines which templates and major versions are associated with your repository and branch, it starts trying to sync all of those templates in parallel. During each sync to a particular template, AWS Proton first checks to see if the contents of the template directory changed since the last successful sync. If the contents didn't change, AWS Proton skips registering a duplicate bundle. This ensures that a new template minor version is created if the content of the template bundle changes. If the contents of the template bundle changed, the bundle is registered with AWS Proton. After the template bundle is registered, AWS Proton monitors the registration status until the registration is complete. Only one sync can occur to a particular template minor and major version at a single given time. Any commits that might have been pushed while a sync was in progress are batched. The batched commits are synced after the previous sync attempt is complete. ## Syncing service templates AWS Proton can sync both environment and service templates from your git repository. To sync your service templates you add an additional file named `.template-registration.yaml` to each major version directory in your template bundle. This file contains additional details that AWS Proton needs when it creates a service template version for you following a commit: *compatible environments* and *supported component sources*. The file's full path is `service-template-name/major-version/.template-registration.yaml`. For more information, see [Syncing service templates](create-template-sync.md#create-template-sync-service-templates). ## Template sync configuration considerations Review the following considerations for using template sync configurations. + Repositories must be no larger than 250 MB. + To configure template sync, first link the repository to AWS Proton. For more information, see [Create a link to your repository](ag-create-repo.md). + When a new template version is created from a synced template, it's in the `DRAFT` state. + A new minor version of a template is created if one of the following is true: + The template bundle contents are different from those of the last synced template minor version. + The last previously synced template minor version was deleted. + Syncing can’t be paused. + Both new minor or major versions are automatically synced. + New top-level templates can’t be created by template sync configurations. + You can’t sync to one template from multiple repositories with a template sync configuration. + You can’t use tags instead of branches. + When you [create a service template](template-create.md#svc-template-v1), you specify compatible environment templates. + You can create an environment template and add it as a compatible environment for your service template in the same commit. + Syncs to a single template major version are run one at a time. During a sync, if any new commits are detected, they're batched and applied at the end of active sync. Syncs to different template major versions happen in parallel. + If you change the branch your templates are syncing from, any ongoing syncs from the old branch first complete. Then syncing begins from the new branch. + If you change the repository your templates sync from, any ongoing syncs from the old repository might fail or run to completion. It depends on which stage of the sync they're in. For more information, see the [https://docs.aws.amazon.com/proton/latest/APIReference/Welcome.html](https://docs.aws.amazon.com/proton/latest/APIReference/Welcome.html). **Topics** + [Pushing a commit to a synced template bundle](#ag-commits) + [Syncing service templates](#syncing-service-templates) + [Template sync configuration considerations](#sync-considerations) + [Create a template sync configuration](create-template-sync.md) + [View template sync configuration details](view-template-sync.md) + [Edit a template sync configuration](update-template-sync.md) + [Delete a template sync configuration](delete-template-sync.md) # Create a template sync configuration Learn how to create a template sync configuration with AWS Proton. **Create a template sync configuration prerequisites:** + You've [linked a repository](ag-create-repo.md) with AWS Proton. + A [template bundle](ag-template-authoring.md#ag-template-bundles) is located in your repository. **The repository link consists of the following:** + An CodeConnections connection that gives AWS Proton permission to access your repository and subscribe to its notifications. + A [service linked role](using-service-linked-roles.md). When you link your repository, the service linked role is created for you. Before you create your first template sync configuration, push a template bundle to your repository as shown in the following directory layout. ``` /templates/ # subdirectory (optional) /templates/my-env-template/ # template name /templates/my-env-template/v1/ # template version /templates/my-env-template/v1/infrastructure/ # template bundle /templates/my-env-template/v1/schema/ ``` After you create your first template sync configuration, new template versions are automatically created when you push a commit that adds an updated template bundle under a new version (for example, under `/my-env-template/v2/`). ``` /templates/ # subdirectory (optional) /templates/my-env-template/ # template name /templates/my-env-template/v1/ # template version /templates/my-env-template/v1/infrastructure/ # template bundle /templates/my-env-template/v1/schema/ /templates/my-env-template/v2/ /templates/my-env-template/v2/infrastructure/ /templates/my-env-template/v2/schema/ ``` You can include new template bundle versions for one or more sync configured templates in a single commit. AWS Proton creates a new template version for each new template bundle version that was included in the commit. After you created the template sync configuration, you can still manually create new versions of the template in the console or with the AWS CLI by uploading template bundles from an S3 bucket. Template syncing only works in one direction: from your repository to AWS Proton. Manually created template versions *aren’t* synced. After you set up a template sync configuration, AWS Proton listens for changes to your repository. Whenever a change is pushed, it looks for any directory that has the same name as your template. It then looks inside that directory for any directories that look like major versions. AWS Proton registers the template bundle to the corresponding template major version. The new versions are always in the `DRAFT` state. You can [publish the new versions](template-create.md) with the console or AWS CLI. For example, suppose you have a template that's called `my-env-template` configured to sync from `my-repo/templates` on branch `main` with the following layout. ``` /code /code/service.go README.md /templates/ /templates/my-env-template/ /templates/my-env-template/v1/ /templates/my-env-template/v1/infrastructure/ /templates/my-env-template/v1/schema/ /templates/my-env-template/v2/ /templates/my-env-template/v2/infrastructure/ /templates/my-env-template/v2/schema/ ``` AWS Proton syncs the contents of `/templates/my-env-template/v1/` to `my-env-template:1` and the contents of `/templates/my-env-template/v2/` to `my-env-template:2`. If they don’t already exist, it creates these major versions. AWS Proton found the first directory that matched the template name. You can limit the directories AWS Proton searches by specifying a `subdirectoryPath` when you create or edit a template sync configuration. For example, you can specify `/production-templates/` for `subdirectoryPath`. You can create a template sync configuration using the console or CLI. ------ #### [ AWS Management Console ] **Create a template and template sync configuration using the console.** 1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Environment templates**. 1. Choose **Create environment template**. 1. In the **Create environment template** page, in the **Template options** section, choose **Create a template for provisioning new environments**. 1. In the **Template bundle source** section, choose **Sync templates from Git**. 1. In the **Source code repository** section: 1. For **Repository**, select the linked repository that contains your template bundle. 1. For **Branch**, select a repository branch to sync from. 1. (Optional) For **Template bundle directory**, enter the name of a directory to scope down the search for your template bundle. 1. In the **Template details** section. 1. Enter a **Template name**. 1. (Optional) Enter a **Template display name**. 1. (Optional) Enter a **Template description** for the environment template. 1. (Optional) Check the checkbox for **Customize encryption settings (advanced)** in the **Encryption settings** section to provide your own encryption key. 1. (Optional) In the **Tags** section, choose **Add new tag** and enter a key and value to create a customer managed tag. 1. Choose **Create Environment template**. You're now on a new page that displays the status and details for your new environment template. These details include a list of AWS managed and customer managed tags. AWS Proton automatically generates AWS managed tags for you when you create AWS Proton resources. For more information, see [AWS Proton resources and tagging](resources.md). 1. In the template detail page, choose the **Sync** tab to view template sync configuration detail data. 1. Choose the **Template versions** tab to view template versions with status details. 1. The status of a new environment template status starts in the **Draft** state. You and others with `proton:CreateEnvironment` permissions can view and access it. Follow the next step to make the template available to others. 1. In the **Template versions** section, choose the radio button to the left of the minor version of the template that you just created (1.0). As an alternative, you can choose **Publish** in the info alert and skip the next step. 1. In the **Template versions** section, choose **Publish**. 1. The template status changes to **Published**. It's the latest and **Recommended** version of the template. 1. In the navigation pane, select **Environment templates** to view a list of your environment templates and details. The procedure for creating a service template and template sync configuration is similar. ------ #### [ AWS CLI ] **Create a template and template sync configuration using the AWS CLI.** 1. **Create a template. In this example, an environment template is created.** Run the following command. ``` $ aws proton create-environment-template \ --name "env-template" ``` The response is as follows. ``` { "environmentTemplate": { "arn": "arn:aws:proton:us-east-1:123456789012:environment-template/env-template", "createdAt": "2021-11-07T23:32:43.045000+00:00", "displayName": "env-template", "lastModifiedAt": "2021-11-07T23:32:43.045000+00:00", "name": "env-template", "status": "DRAFT", "templateName": "env-template" } } ``` 1. **Create your template sync configuration with AWS CLI by providing the following:** + The template that you want to sync to. After you have created the template sync configuration, you can still create new versions from it manually in the console or with the AWS CLI. + The template name. + The template type. + The linked repository that you want to sync from. + The linked repository provider. + The branch where the template bundle is located. + (Optional) The path to the directory containing your template bundle. By default, AWS Proton looks for the first directory that matches your template name. Run the following command. ``` $ aws proton create-template-sync-config \ --template-name "env-template" \ --template-type "ENVIRONMENT" \ --repository-name "myrepos/templates" \ --repository-provider "GITHUB" \ --branch "main" \ --subdirectory "env-template/" ``` The response is as follows. ``` { "templateSyncConfigDetails": { "branch": "main", "repositoryName": "myrepos/templates", "repositoryProvider": "GITHUB", "subdirectory": "templates", "templateName": "env-template", "templateType": "ENVIRONMENT" } } ``` 1. **To publish your template version, see [Register and publish templates](template-create.md).** ------ ## Syncing service templates The preceding examples show how you can sync environment templates. Service templates are similar. To sync service templates you add an additional file named `.template-registration.yaml` to each major version directory in your template bundle. This file contains additional details that AWS Proton needs when it creates a service template version for you following a commit. When you explicitly create a service template version using the AWS Proton console or API, you provide these details as inputs, and this file replaces these inputs for template sync. ``` ./templates/ # subdirectory (optional) /templates/my-svc-template/ # service template name /templates/my-svc-template/v1/ # service template version /templates/my-svc-template/v1/.template-registration.yaml # service template version properties /templates/my-svc-template/v1/instance_infrastructure/ # template bundle /templates/my-svc-template/v1/schema/ ``` The `.template-registration.yaml` file contains the following details: + **Compatible environments** [required] – Environments based on these environment templates and major versions are compatible with services based on this service template version. + **Supported component sources** [optional] – Components using these sources are compatible with services based on this service template version. If not specified, components can't be attached to these services. For more information about components, see [AWS Proton components](ag-components.md). The file's YAML syntax is as follows: ``` compatible_environments: - env-templ-name:major-version - ... supported_component_sources: - DIRECTLY_DEFINED ``` Specify one or more environment template / major version combinations. Specifying `supported_component_sources` is optional, and the only supported value is `DIRECTLY_DEFINED`. **Example .template-registration.yaml** In this example, the service template version is compatible with major versions 1 and 2 of the `my-env-template` environment template. It's also compatible with the major versions 1 and 3 of the `another-env-template` environment template. The file doesn't specify `supported_component_sources`, so components can't be attached to services based on this service template version. ``` compatible_environments: - my-env-template:1 - my-env-template:2 - another-env-template:1 - another-env-template:3 ``` **Note** Previously, AWS Proton defined a different file, `.compatible-envs`, for specifying compatible environments. AWS Proton still supports that file and its format for backward compatibility. We don't recommend using it anymore, because it isn't extensible and can't support newer features like components. # View template sync configuration details View template sync configuration detail data using the console or CLI. ------ #### [ AWS Management Console ] **Use the console to view template sync configuration details.** 1. In the navigation pane, choose **(Environment or Service) templates**. 1. To view detail data, choose the name of a template that you created a template sync configuration for. 1. In the detail page for the template, select the **Sync** tab to view the template sync configuration detail data. ------ #### [ AWS CLI ] **Use the AWS CLI to view a synced template.** Run the following command. ``` $ aws proton get-template-sync-config \ --template-name "svc-template" \ --template-type "SERVICE" ``` The response is as follows. ``` { "templateSyncConfigDetails": { "branch": "main", "repositoryProvider": "GITHUB", "repositoryName": "myrepos/myrepo", "subdirectory": "svc-template", "templateName": "svc-template", "templateType": "SERVICE" } } ``` **Use the AWS CLI to get template sync status.** For `template-version`, enter the template major version. Run the following command. ``` $ aws proton get-template-sync-status \ --template-name "env-template" \ --template-type "ENVIRONMENT" \ --template-version "1" ``` ------ # Edit a template sync configuration You can edit any of the template sync configuration parameters except `template-name` and `template-type`. Learn to edit a template sync configuration using the console or CLI. ------ #### [ AWS Management Console ] Edit a template sync configuration branch using the console. **In the list of templates.** 1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **(Environment or Service) Templates**. 1. In the list of templates, choose the name of the template with the template sync configuration that you want to edit. 1. In the template detail page, choose the **Template sync** tab. 1. In the **Template sync details** section, choose **Edit**. 1. In the **Edit** page, in the **Source code repository** section, for **Branch**, select a branch, and then choose **Save configuration**. ------ #### [ AWS CLI ] **The following example command and response shows how you can edit a template sync configuration `branch` using the CLI.** Run the following command. ``` $ aws proton update-template-sync-config \ --template-name "env-template" \ --template-type "ENVIRONMENT" \ --repository-provider "GITHUB" \ --repository-name "myrepos/templates" \ --branch "fargate" \ --subdirectory "env-template" ``` The response is as follows. ``` { "templateSyncConfigDetails": { "branch": "fargate", "repositoryProvider": "GITHUB", "repositoryName": "myrepos/myrepo", "subdirectory": "templates", "templateName": "env-template", "templateType": "ENVIRONMENT" } } ``` You can similarly use the AWS CLI to update synced service templates. ------ # Delete a template sync configuration Delete a template sync configuration using the console or CLI. ------ #### [ AWS Management Console ] **Delete a template sync configuration using the console.** 1. In the template details page, choose the **Sync** tab. 1. In the **Sync details** section, choose **Disconnect**. ------ #### [ AWS CLI ] **The following example commands and responses show how to use the AWS CLI to delete synced template configurations.** Run the following command. ``` $ aws proton delete-template-sync-config \ --template-name "env-template" \ --template-type "ENVIRONMENT" ``` The response is as follows. ``` { "templateSyncConfig": { "templateName": "env-template", "templateType": "ENVIRONMENT" } } ``` ------ # Service sync configurations With service sync, you can configure and deploy your AWS Proton services using Git. You can use service sync to manage initial deployments and updates to your AWS Proton service with a configuration defined in a Git repository. Through Git, you can use features like version tracking and pull requests to configure, manage, and deploy your services. Service sync combines AWS Proton and Git to help you provision standardized infrastructure that is defined and managed through AWS Proton templates. It manages service definitions in your Git repository and reduces tool switching. Compared to using Git alone, the standardization of templates and deployment in AWS Proton helps you spend less time managing your infrastructure. AWS Proton also provides higher transparency and auditability for both developers and platform teams. ## AWS Proton OPS file The `proton-ops` file defines where AWS Proton finds the spec file that's used to update your service instance. It also defines what order to update service instances in and when to promote changes from one instance to another. The `proton-ops` file supports syncing a service instance using the spec file, or multiple spec files, found in your linked repository. You can do this by defining a sync block in the `proton-ops` file, like in the following example. **Example ./configuration/proton-ops.yaml:** ``` sync: services: frontend-svc: alpha: branch: dev spec: ./frontend-svc/test/frontend-spec.yaml beta: branch: dev spec: ./frontend-svc/test/frontend-spec.yaml gamma: branch: pre-prod spec: ./frontend-svc/pre-prod/frontend-spec.yaml prod-one: branch: prod spec: ./frontend-svc/prod/frontend-spec-second.yaml prod-two: branch: prod spec: ./frontend-svc/prod/frontend-spec-second.yaml prod-three: branch: prod spec: ./frontend-svc/prod/frontend-spec-second.yaml ``` In the preceding example, `frontend-svc` is the service name, and `alpha`, `beta`, `gamma`, `prod-one`, `prod-two`, and `prod-three` are the instances. The `spec` file can be all of the instances or a subset of the instances that are defined within the `proton-ops` file. However, at minimum, it must have the instance defined within the branch and the spec it's syncing from. If instances aren't defined in the `proton-ops` file, with the specific branch and `spec` file location, service sync won't create or update those instances. The following examples show what the `spec` files look like. Remember, the `proton-ops` file is synced from these `spec` files. **Example `./frontend-svc/test/frontend-spec.yaml`:** ``` proton: "ServiceSpec" instances: - name: "alpha" environment: "frontend-env" spec: port: 80 desired_count: 1 task_size: "x-small" image: "public.ecr.aws/z9d2n7e1/nginx:1.21.0" - name: "beta" environment: "frontend-env" spec: port: 80 desired_count: 1 task_size: "x-small" image: "public.ecr.aws/z9d2n7e1/nginx:1.21.0" ``` **Example `./frontend-svc/pre-prod/frontend-spec.yaml`:** ``` proton: "ServiceSpec" instances: - name: "gamma" environment: "frontend-env" spec: port: 80 desired_count: 1 task_size: "x-small" image: "public.ecr.aws/z9d2n7e1/nginx:1.21.0" ``` **Example `./frontend-svc/prod/frontend-spec-second.yaml`:** ``` proton: "ServiceSpec" instances: - name: "prod-one" environment: "frontend-env" spec: port: 80 desired_count: 1 task_size: "x-small" image: "public.ecr.aws/z9d2n7e1/nginx:1.21.0" - name: "prod-two" environment: "frontend-env" spec: port: 80 desired_count: 1 task_size: "x-small" image: "public.ecr.aws/z9d2n7e1/nginx:1.21.0" - name: "prod-three" environment: "frontend-env" spec: port: 80 desired_count: 1 task_size: "x-small" image: "public.ecr.aws/z9d2n7e1/nginx:1.21.0" ``` If an instance doesn't sync, and there's a continuing issue when trying to sync it, calling the [https://docs.aws.amazon.com//proton/latest/APIReference/API_GetServiceInstanceSyncStatus.html](https://docs.aws.amazon.com//proton/latest/APIReference/API_GetServiceInstanceSyncStatus.html) API may help in resolving the issue. **Note** Customers using service sync are still restricted by AWS Proton limits. **Blockers** By syncing your service using AWS Proton service sync, you can update your service spec and create and update service instances from your Git repository. However, there may be moments where you need to update a service or instance manually through the AWS Management Console or AWS CLI. AWS Proton helps avoid overwriting any manual changes you make through the AWS Management Console or AWS CLI, such as updating a service instance or deleting a service instance. To achieve this, AWS Proton automatically creates a service sync blocker by disabling service sync when it detects a manual change. To get all the blockers associated with a service, you must do the following in order for each `serviceInstance` associated to the service: + Call the `getServiceSyncBlockerSummary` API with only the `serviceName`. + Call the `getServiceSyncBlockerSummary` API with the `serviceName` and `serviceInstanceName`. This returns a list of the most recent blockers and the status associated with them. If any blockers are marked **ACTIVE**, you must resolve them by calling the `UpdateServiceSyncBlocker` API with the `blockerId` and `resolvedReason` for each one. If you manually update or create a service instance, AWS Proton creates a service sync blocker on the service instance. AWS Proton continues to sync all other service instances, but disables the syncing of this service instance until the blocker is resolved. If you delete a service instance from a service, AWS Proton creates a service sync blocker on the service. This prevents AWS Proton from syncing any of the service instances until the blocker has been resolved. After you have all the active blockers, you must resolve them by calling the `UpdateServiceSyncBlocker` API with the `blockerId` and `resolvedReason` for each of the active blockers. Using the AWS Management Console, you can determine if a service sync is disabled by navigating to AWS Proton and choosing the **Service Sync** tab. If the service or service instances are blocked, an **Enable** button appears. To enable service sync, choose **Enable**. **Topics** + [AWS Proton OPS file](#service-sync-ops) + [Create a service sync configuration](create-service-sync.md) + [View configuration details for a service sync](get-service-sync.md) + [Edit a service sync configuration](update-service-sync.md) + [Delete a service sync configuration](delete-service-sync.md) # Create a service sync configuration You can create a service sync configuration using the console or AWS CLI. ------ #### [ AWS Management Console ] 1. On the **Choose a service template** page, select a template and choose **Configure**. 1. On the **Configure service** page, in the **Service details** section, enter a new **Service name**. 1. (Optional) Enter a description for the service. 1. In the **Application source code repository** section, choose **Choose a linked Git repository** to select a repository you've already linked with AWS Proton. If you don't already have a linked repository, choose **Link another Git repository** and follow the instructions in [Create a link to your repository](https://docs.aws.amazon.com//proton/latest/userguide/ag-create-repo.html). 1. For **Repository**, choose the name of your source code repository from the list. 1. For **Branch**, choose the name of the repository branch for your source code from the list. 1. (Optional) In the **Tags** section, choose **Add new tag** and enter a key and value to create a customer managed tag. 1. Choose **Next**. 1. On the **Configure service instances** page, in the **Service definition source** section, select **Sync your service from Git**. 1. In the **Service definition files** section, if you want AWS Proton to create your `proton-ops` file, select **I want AWS Proton to create the files**. With this option, AWS Proton creates the `spec` and `proton-ops` file in the locations you specify. Select **I am providing my own files** to create your own OPS file. 1. In the **Service definition repository** section, choose **Choose a linked Git repository** to select a repository you've already linked with AWS Proton. 1. For **Repository name**, choose the name of your source code repository from the list. 1. For **`proton-ops` file branch**, choose the name of your branch from the list where AWS Proton will put your OPS and spec file. 1. In the **Service instances** section, each field is automatically filled based on the values in the `proton-ops` file. 1. Choose **Next** and review your inputs. 1. Choose **Create**. ------ #### [ AWS CLI ] **Create a service sync configuration using the AWS CLI** + Run the following command. ``` $ aws proton create-service-sync-config \ --resource "service-arn" \ --repository-provider "GITHUB" \ --repository "example/proton-sync-service" \ --ops-file-branch "main" \ --proton-ops-file "./configuration/custom-proton-ops.yaml" (optional) ``` The response is as follows. ``` { "serviceSyncConfig": { "branch": "main", "filePath": "./configuration/custom-proton-ops.yaml", "repositoryName": "example/proton-sync-service", "repositoryProvider": "GITHUB", "serviceName": "service name" } } ``` ------ # View configuration details for a service sync You can view the configuration details data for a service sync using the console or AWS CLI. ------ #### [ AWS Management Console ] **Use the console to view configuration details for a service sync** 1. In the navigation pane, choose **Services**. 1. To view detail data, choose the name of a service that you created a service sync configuration for. 1. In the detail page for the service, select the **Service sync** tab to view the configuration detail data for the service sync. ------ #### [ AWS CLI ] **Use the AWS CLI to get a synced service.** Run the following command. ``` $ aws proton get-service-sync-config \ --service-name "service name" ``` The response is as follows. ``` { "serviceSyncConfig": { "branch": "main", "filePath": "./configuration/custom-proton-ops.yaml", "repositoryName": "example/proton-sync-service", "repositoryProvider": "GITHUB", "serviceName": "service name" } } ``` **Use the AWS CLI to get the service sync status.** Run the following command. ``` $ aws proton get-service-sync-status \ --service-name "service name" ``` ------ # Edit a service sync configuration You can edit a service sync configuration using the console or AWS CLI. ------ #### [ AWS Management Console ] Edit a service sync configuration using the console. 1. In the navigation pane, choose **Services**. 1. To view detail data, choose the name of a service that you created a service sync configuration for. 1. On the service detail page, choose the **Service sync** tab. 1. In the **Service sync** section, choose **Edit**. 1. On the **Edit** page, update the information you want to edit and then choose **Save**. ------ #### [ AWS CLI ] **The following example command and response shows how you can edit a service sync configuration using the AWS CLI.** Run the following command. ``` $ aws proton update-service-sync-config \ --service-name "service name" \ --repository-provider "GITHUB" \ --repository "example/proton-sync-service" \ --ops-file-branch "main" \ --ops-file "./configuration/custom-proton-ops.yaml" ``` The response is as follows. ``` { "serviceSyncConfig": { "branch": "main", "filePath": "./configuration/custom-proton-ops.yaml", "repositoryName": "example/proton-sync-service", "repositoryProvider": "GITHUB", "serviceName": "service name" } } ``` ------ # Delete a service sync configuration You can delete a service sync configuration using the console or AWS CLI. ------ #### [ AWS Management Console ] **Delete a service sync configuration using the console** 1. On the service details page, choose the **Service sync** tab. 1. In the **Service sync details** section, choose **Disconnect** to disconnect your repository. After your repository is disconnected, we no longer sync the service from that repository. ------ #### [ AWS CLI ] **The following example commands and responses show how to use the AWS CLI to delete service synced configurations.** Run the following command. ``` $ aws proton delete-service-sync-config \ --service-name "service name" ``` The response is as follows. ``` { "serviceSyncConfig": { "branch": "main", "filePath": "./configuration/custom-proton-ops.yaml", "repositoryName": "example/proton-sync-service", "repositoryProvider": "GITHUB", "serviceName": "service name" } } ``` **Note** Service sync doesn't delete service instances. It only deletes the configuration. ------