Create a template sync configuration - AWS Proton
Syncing service templates

Create a template sync configuration

Learn how to create a template sync configuration with AWS Proton.

Create a template sync configuration prerequisites:

The repository registration consists of the following:

  • An AWS CodeStar connections connection that gives AWS Proton permission to access your repository and subscribe to its notifications.

  • A service linked role. When you register 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 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, choose Environment templates.

  2. Choose Create environment template.

  3. In the Create environment template page, in the Template options section, choose Create a template for provisioning new environments.

  4. In the Template bundle source section, choose Sync templates from Git.

  5. In the Source code repository section:

    1. For Repository, select the repository that contains your template bundle.

    2. For Branch, select a repository branch to sync from.

    3. (Optional) For Template bundle directory, enter the name of a directory to scope down the search for your template bundle.

  6. In the Template details section.

    1. Enter a Template name.

    2. (Optional) Enter a Template display name.

    3. (Optional) Enter a Template description for the environment template.

  7. (Optional) Check the checkbox for Customize encryption settings (advanced) in the Encryption settings section to provide your own encryption key.

  8. (Optional) In the Tags section, choose Add new tag and enter a key and value to create a customer managed tag.

  9. 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.

  10. In the template detail page, choose the Sync tab to view template sync configuration detail data.

  11. Choose the Template versions tab to view template versions with status details.

  12. 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.

  13. 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.

  14. In the Template versions section, choose Publish.

  15. The template status changes to Published. It's the latest and Recommended version of the template.

  16. 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-2: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"
    }
}

  2. 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 repository that you want to sync from.

    • The repository provider type.

    • 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"
    }
}

  3. To publish your template version, see Register and publish templates.

Syncing service templates

The preceding examples show how you can sync environment templates. Service templates are similar. However, they also require an additional file that's called the .compatible-envs file. This file contains a line-separated list of environment templates and major versions that are compatible with the service template. 

./templates/                                      # subdirectory (optional)
 /templates/my-svc-template/                      # service template name
 /templates/my-svc-template/v1/                   # service template version
 /templates/my-svc-template/v1/.compatible-envs   # service template's compatible envs file
 /templates/my-svc-template/v1/infrastructure/    # template bundle
 /templates/my-svc-template/v1/schema/

The .compatible-envs file contains the names and major versions of the environment templates that are compatible with this service template.

my-env-template:1
my-env-template:2

This file indicates that the major version 1 of the my-svc-template service template is compatible with major versions 1 and 2 of the my-env-template environment template.