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

# Getting started with AWS Proton
Getting started

Before getting started, get [set up](ag-setting-up.md) to use AWS Proton and verify you have met the [Getting started prerequisites](getting-started-prerequisites.md).

**Get started with AWS Proton by choosing one or more of the following paths:**
+ Follow a guided [example console or CLI workflow](ag-admin-workflow.md) through documentation links.
+ Run through a guided [example console workflow](ag-getting-started-console.md).
+ Run through a guided [example AWS CLI workflow](ag-getting-started-cli.md).



**Topics**
+ [

# Prerequisites
](getting-started-prerequisites.md)
+ [

# Getting started workflow
](ag-admin-workflow.md)
+ [

# Getting started with the AWS Management Console
](ag-getting-started-console.md)
+ [

# Getting started with the AWS CLI
](ag-getting-started-cli.md)
+ [

# The AWS Proton template library
](ag-getting-started-templates.md)

# Prerequisites


Before you start using AWS Proton, make sure that the following prerequisites are met. For more information, see [Setting up](ag-setting-up.md).
+ You have an IAM account with administrator permissions. For more information, see [Setting up with IAM](ag-setting-up-iam.md).
+ You have the AWS Proton service role and the AWS Proton pipeline service role are attached to your account. For more information, see [Setting up AWS Proton service roles](ag-setting-up-iam.md#setting-up-cicd) and [Service roles for AWS Proton](security_iam_service-with-iam.md#security_iam_service-with-iam-roles-service).
+ You have an AWS CodeStar connection. For more information, see [Setting up an AWS CodeStar connection](setting-up-for-service.md#setting-up-vcontrol).
+ You're familiar with creating CloudFormation templates and Jinja parameterization. For more information, see [What is CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)* in the CloudFormation User Guide * and [Jinja website](https://palletsprojects.com/projects/jinja).
+ You have working knowledge of AWS infrastructure services.
+ You're logged into your AWS account.

# Getting started workflow


Learn to create template bundles, create and register templates, and create environments and services by following the example steps and links.

Before starting, verify that you created an [AWS Proton service role](ag-setting-up-iam.md#setting-up-cicd).

If your service template includes an AWS Proton service pipeline, verify that you created an [AWS CodeStar connection](setting-up-for-service.md#setting-up-vcontrol) and a [AWS Proton pipeline service role](ag-setting-up-iam.md#setting-up-cicd).

For more information, see [The AWS Proton service API Reference](https://docs.aws.amazon.com/proton/latest/APIReference/Welcome.html).

**Example: Getting started workflow**

1. Refer to the diagram in [How AWS Proton works](ag-works.md) for a high-level view of AWS Proton inputs and outputs.

1. [Create an environment bundle and a service template bundle](ag-template-authoring.md#ag-template-bundles).

   1. Identify [input parameters](parameters.md).

   1. Create a [schema file](ag-schema.md).

   1. Create [infrastructure as code (IaC) files](ag-infrastructure-tmp-files.md).

   1. To [wrap up your template bundle](ag-wrap-up.md), create a manifest file and organize your IaC files, manifest files, and schema file in directories.

   1. Make your [template bundle](ag-wrap-up.md) accessible to AWS Proton.

1. [Create and register an environment template version](template-create.md) with AWS Proton.

   When you use the console to create and register a template, a template version is automatically created.

   When you use the AWS CLI to create and register a template:

   1. Create an environment template.

   1. Create an environment template version.

   For more information, see [CreateEnvironmentTemplate](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateEnvironmentTemplate.html) and [CreateEnvironmentTemplateVersion](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateEnvironmentTemplateVersion.html) in the *AWS Proton API reference*.

1. [Publish your environment template](template-update.md) to make it available for use.

   For more information, see [UpdateEnvironmentTemplateVersion](https://docs.aws.amazon.com/proton/latest/APIReference/API_UpdateEnvironmentTemplateVersion.html) in the *AWS Proton API reference*.

1. To [create an environment](ag-create-env.md), select a published environment template version and provide values for required inputs.

   For more information, see [CreateEnvironment](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateEnvironment.html) in the *AWS Proton API reference*.

1. [Create and register a service template version](template-create.md) with AWS Proton.

   When you use the console to create and register a template, a template version is automatically created.

   When you use the AWS CLI to create and register a template:

   1. Create a service template.

   1. Create a service template version.

   For more information, see [CreateServiceTemplate](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateServiceTemplate.html) and [CreateServiceTemplateVersion](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateServiceTemplateVersion.html) in the *AWS Proton API reference*.

1. [Publish your service template](template-update.md) to make it available for use.

   For more information, see [UpdateServiceTemplateVersion](https://docs.aws.amazon.com/proton/latest/APIReference/API_UpdateServiceTemplateVersion.html) in the *AWS Proton API reference*.

1. To [create a service](ag-create-svc.md), select a published service template version and provide values for required inputs.

   For more information, see [CreateService](https://docs.aws.amazon.com/proton/latest/APIReference/API_CreateService.html) in the *AWS Proton API reference*.

# Getting started with the AWS Management Console
Getting started with the console

**Get started with AWS Proton**
+ Create and view an environment template.
+ Create, view, and publish a service template that uses the environment template that you just created.
+ Create an environment and service (optional).
+ Delete the service template, environment template, environment and service, if created.

## Step 1: Open the AWS Proton console

+ Open the [AWS Proton console](https://console.aws.amazon.com//proton/)

## Step 2: Prepare to use the example templates


1. Create a Codestar Connection to Github and name the connection my-proton-connection.

1. Navigate to [https://github.com/aws-samples/aws-proton-cloudformation-sample-templates](https://github.com/aws-samples/aws-proton-cloudformation-sample-templates)

1. Create a fork of the repository in your Github account. 

## Step 3: Create an environment template


In the navigation pane, choose **Environment templates**.

1. In the **Environment templates** page, 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 a template bundle from Git**.

1. In the **Template definition repository** section, select **Choose a linked Git repository**.

1. Select **my-proton-connection** from the **Repository list**.

1. Select **main** from the **Branch list**.

1. In the **Proton environment template details** section.

   1. Enter the template name as **fargate-env**.

   1. Enter the environment template display name as **My Fargate Environment**.

   1. (Optional) Enter a description for the environment template.

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 banner 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**.

   A new page displays a list of your environment templates along with template details.

## Step 4: Create a service template


**Create a service template.**

1. In the navigation pane, choose **Service templates**.

1. In the **Service templates** page, choose **Create Service template**.

1. In the **Create service template** page, in the **Template bundle source** section, choose **Sync a template bundle from Git**.

1. In the **Template ** section, select **Choose a linked Git repository**.

1. Select **my-proton-connection** from the **Repository list**.

1. Select **main** from the **Branch list**.

1. In the **Proton service template details** section.

   1. Enter the service template name as **backend-fargate-svc**.

   1. Enter the service template display name as **My Fargate Service**.

   1. (Optional) Enter a description for the service template.

1. In the **Compatible environment templates** section.

   1. Check the check-box to the left of the environment template **My Fargate Environment** to select the compatible environment template for the new service template.

1. For **Encryption settings**, keep the defaults.

1. In the **Pipeline definition** section.

   1. Keep the **This template includes a CI/CD pipeline** button selected.

1. Choose **Create service template**.

   You're now on a new page that displays the status and details for your new service template, including a list of AWS and customer managed tags.

1. The status of a new service template status starts in the **Draft** state. Only administrators can view and access it. To make the service template available for use by developers, follow the next step.

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 banner and skip the next step.

1. In the **Template versions** section, choose **Publish**.

1. The template status changes to **Published**.

   The first minor version of your service template is published and available for use by developers. Because it's the latest version of the template, it's the **Recommended** version.

1. In the navigation pane, choose **Service templates**.

   A new page displays a list of your service templates and details.

## Step 5: Create an environment


In the navigation pane, choose **Environments**.

1. Choose **Create environment**.

1. In the **Choose an environment template** page, select the template that you just created. It's named **My Fargate Environment**. Then, choose **Configure**.

1. In the **Configure environment** page, in the **Provisioning** section, choose **Provision through AWS Proton**.

1. In the **Deployment account** section, select **This AWS account**.

1. In **Environment Settings**, enter the environment name as **my-fargate-environment**.

1. In the **Environment roles** section, select **New service role** or, if you have already created an AWS Proton service role, select **Existing service role**.

   1. Select **New service role** to create a new role.

      1. Enter the **Environment role name** as **MyProtonServiceRole**.

      1. Check the check box to agree to create an AWS Proton service role with administrative privileges for your account.

   1. Select **Existing service role** to use an existing role.

      1. Select your role in the **Environment role name** drop down field.

1. Choose **Next**.

1. On the **Configure custom settings** page, use the defaults.

1. Choose **Next** and review your inputs.

1. Choose **Create**.

   View the environment details and status, as well as the AWS managed tags and customer managed tags for your environment.

1. In the navigation pane, choose **Environments**.

   A new page displays a list of your environments along with the status and other environment details.

## Step 6: Optional - Create a service and deploy an application


1. Open the [AWS Proton console](https://console.aws.amazon.com//proton/).

1. In the navigation pane, choose **Services**.

1. In the **Services** page, choose **Create service**.

1. In the **Choose a service template** page, select the **My Fargate Service** template by choosing the radio button at the top-right corner of the template card.

1. Choose **Configure** at the lower right corner of the page.

1. In the **Configure service** page, in the **Service settings** section, enter the service name **my-service**.

1. (Optional) Enter a description for the service.

1. 

**In the **Service repository settings** section:**

   1. For **CodeStar connection**, choose your connection from the list.

   1. For **Repository name**, choose the name of your source code repository from the list.

   1. For **Branch name**, choose the name of your source code repository branch 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. Then choose **Next**.

1. In the **Configure custom settings** page, in the **Service instances** section, in the **New instance** section, follow the next steps to provide custom values for your service instance parameters.

   1. Enter the instance name **my-app-service**.

   1. Choose the environment **my-fargate-environment** for your service instance.

   1. Keep the defaults for the remaining instance parameters.

   1. Keep the defaults for **Pipeline inputs**.

   1. Choose **Next** and review your inputs.

   1. Choose **Create** and view your service status and details.

1. In the service details page, view the status of your service instance and pipeline by choosing the **Overview** and **Pipeline** tabs. On these pages you can also view AWS and customer managed tags. AWS Proton automatically creates AWS managed tags for you. Choose **Manage tags** to create and modify customer managed tags. For more information about tagging, see [AWS Proton resources and tagging](resources.md).

1. After the service is **Active**, in the **Overview** tab, in the **Service Instances** section, choose the name of your service instance, **my-app-service**.

   You are now on the service instance detail page.

1. To view your application, in the **Outputs** section, copy the **ServiceEndpoint** link to your browser.

   You see an AWS Proton graphic in the web page.

1. After the service is created, in the navigation pane, choose **Services** to view a list of your services.

## Step 7: Clean up.


1. Open the [AWS Proton console](https://console.aws.amazon.com//proton/).

1. 

**Delete a service (if you created one)**

   1. In the navigation pane, choose **Services**.

   1. In the **Services** page, choose the service name **my-service**.

      You're now on the service detail page for **my-service**.

   1. In the upper right-hand corner of the page, choose **Actions** and then **Delete**.

   1. A modal prompts you to confirm the delete action.

   1. Follow the instructions and choose **Yes, delete**.

1. 

**Delete an environment**

   1. In the navigation pane, choose **Environments**.

   1. In the **Environments** page, select the radio button the left of the environment that you just created.

   1. Choose **Actions**, then **Delete**.

   1. A modal prompts you to confirm the delete action.

   1. Follow the instructions and choose **Yes, delete**.

1. 

**Delete a service template**

   1. In the navigation pane, choose **Service templates**.

   1. In the **Service templates** page, select the radio button to the left of service template **my-svc-template**.

   1. Choose **Actions**, then **Delete**.

   1. A modal prompts you to confirm the delete action.

   1. Follow the instructions and choose **Yes, delete**. This deletes the service template and all of its versions.

1. 

**Delete an environment template**

   1. In the navigation pane, choose **Environment templates**.

   1. In the **Environment templates** page, select the radio button to the left of **my-env-template**.

   1. Choose **Actions**, then **Delete**.

   1. A modal prompts you to confirm the delete action.

   1. Follow the instructions and choose **Yes, delete**. This deletes the environment template and all of its versions.

1. 

**Delete your Codestar Connection**

# Getting started with the AWS CLI
Getting started with the CLI

To get started with AWS Proton using the AWS CLI, follow this tutorial. The tutorial demonstrates a public facing load-balanced AWS Proton service based on AWS Fargate. The tutorial also provisions a CI/CD pipeline that deploys a static website with a displayed image.

Before you start, be sure you are set up correctly. For details, see [Prerequisites](getting-started-prerequisites.md).

## Step 1: Register an environment template
1. Register an environment template

In this step, as an administrator, you register an example environment template, which contains an Amazon Elastic Container Service (Amazon ECS) cluster and an Amazon Virtual Private Cloud (Amazon VPC) with two public/private subnets.

**To register an environment template**

1. Fork the [AWS Proton Sample CloudFormation Templates](https://github.com/aws-samples/aws-proton-cloudformation-sample-templates/) repository into your GitHub account or organization. This repository includes the environment and service templates that we use in this tutorial.

   Then, register your forked repository with AWS Proton. For more information, see [Create a link to your repository](ag-create-repo.md).

1. Create an environment template.

   The environment template resource tracks environment template versions.

   ```
   $ aws proton create-environment-template \
     --name "fargate-env" \
     --display-name "Public VPC Fargate" \
     --description "VPC with public access and ECS cluster"
   ```

1. Create a template sync configuration.

   AWS Proton sets up a sync relationship between your repository and your environment template. It then creates template version 1.0 in `DRAFT` status.

   ```
   $ aws proton create-template-sync-config \
     --template-name "fargate-env" \
     --template-type "ENVIRONMENT" \
     --repository-name "your-forked-repo" \
     --repository-provider "GITHUB" \
     --branch "your-branch" \
     --subdirectory "environment-templates/fargate-env"
   ```

1. Wait for the environment template version to be successfully registered.

   When this command returns with an exit status of `0`, version registration is complete. This is useful in scripts to ensure you can successfully run the command in the next step.

   ```
   $ aws proton wait environment-template-version-registered \
     --template-name "fargate-env" \
     --major-version "1" \
     --minor-version "0"
   ```

1. Publish the environment template version to make it available for environment creation.

   ```
   $ aws proton update-environment-template-version \
     --template-name "fargate-env" \
     --major-version "1" \
     --minor-version "0" \
     --status "PUBLISHED"
   ```

## Step 2: Register a service template
2. Register a service template

In this step, as an administrator, you register an example service template, which contains all the resources required to provision an Amazon ECS Fargate service behind a load balancer and a CI/CD pipeline that uses AWS CodePipeline.

**To register a service template**

1. Create a service template.

   The service template resource tracks service template versions.

   ```
   $ aws proton create-service-template \
     --name "load-balanced-fargate-svc" \
     --display-name "Load balanced Fargate service" \
     --description "Fargate service with an application load balancer"
   ```

1. Create a template sync configuration.

   AWS Proton sets up a sync relationship between your repository and your service template. It then creates template version 1.0 in `DRAFT` status.

   ```
   $ aws proton create-template-sync-config \
     --template-name "load-balanced-fargate-svc" \
     --template-type "SERVICE" \
     --repository-name "your-forked-repo" \
     --repository-provider "GITHUB" \
     --branch "your-branch" \
     --subdirectory "service-templates/load-balanced-fargate-svc"
   ```

1. Wait for the service template version to be successfully registered.

   When this command returns with an exit status of `0`, version registration is complete. This is useful in scripts to ensure you can successfully run the command in the next step.

   ```
   $ aws proton wait service-template-version-registered \
     --template-name "load-balanced-fargate-svc" \
     --major-version "1" \
     --minor-version "0"
   ```

1. Publish the service template version to make it available for service creation.

   ```
   $ aws proton update-service-template-version \
     --template-name "load-balanced-fargate-svc" \
     --major-version "1" \
     --minor-version "0" \
     --status "PUBLISHED"
   ```

## Step 3: Deploy an environment
3. Deploy an environment

In this step, as an administrator, you instantiate an AWS Proton environment from the environment template.

**To deploy an environment**

1. Get an example spec file for the environment template that you registered.

   You can download the file `environment-templates/fargate-env/spec/spec.yaml` from the template example repository. Alternatively, you can fetch the entire repository locally and run the **create-environment** command from the `environment-templates/fargate-env` directory.

1. Create an environment.

   AWS Proton reads input values from your environment spec, combines them with your environment template, and provisions environment resources in your AWS account using your AWS Proton service role.

   ```
   $ aws proton create-environment \
     --name "fargate-env-prod" \
     --template-name "fargate-env" \
     --template-major-version 1 \
     --proton-service-role-arn "arn:aws:iam::123456789012:role/AWSProtonServiceRole" \
     --spec "file://spec/spec.yaml"
   ```

1. Wait for the environment to successfully deploy.

   ```
   $ aws proton wait environment-deployed --name "fargate-env-prod"
   ```

## Step 4: Deploy a service [application developer]
4. Deploy a service

In the previous steps, an administrator registered and published a service template and deployed an environment. As an application developer, you can now create an AWS Proton service and deploy it into the AWS Proton environment

**To deploy a service**

1. Get an example spec file for the service template that the administrator registered.

   You can download the file `service-templates/load-balanced-fargate-svc/spec/spec.yaml` from the template example repository. Alternatively, you can fetch the entire repository locally and run the **create-service** command from the `service-templates/load-balanced-fargate-svc` directory.

1. Fork the [AWS Proton Sample Services](https://github.com/aws-samples/aws-proton-sample-services/) repository into your GitHub account or organization. This repository includes the application source code that we use in this tutorial.

1. Create a service.

   AWS Proton reads input values from your service spec, combines them with your service template, and provisions service resources in your AWS account in the environment that is specified in the spec. An AWS CodePipeline pipeline deploys your application code from the repository that you specify in the command.

   ```
   $ aws proton create-service \
     --name "static-website" \
     --repository-connection-arn \
       "arn:aws:codestar-connections:us-east-1:123456789012:connection/your-codestar-connection-id" \
     --repository-id "your-GitHub-account/aws-proton-sample-services" \
     --branch-name "main" \
     --template-major-version 1 \
     --template-name "load-balanced-fargate-svc" \
     --spec "file://spec/spec.yaml"
   ```

1. Wait for the service to successfully deploy.

   ```
   $ aws proton wait service-created --name "static-website"
   ```

1. Retrieve outputs and view your new website.

   Run the following command:

   ```
   $ aws proton list-service-instance-outputs \
     --service-name "static-website" \
     --service-instance-name load-balanced-fargate-svc-prod
   ```

   The command's output should be similar to the following:

   ```
   {
       "outputs": [
           {
               "key": "ServiceURL",
               "valueString": "http://your-service-endpoint.us-east-1.elb.amazonaws.com"
           }
       ]
   }
   ```

   The value of the `ServiceURL` instance output is the endpoint to your new service website. Use your browser to navigate to it. You should see the following graphic on a static page:  
![\[A web browser showing the static image site resulting from the getting started CLI procedure\]](http://docs.aws.amazon.com/proton/latest/userguide/images/getting-started-static-site.png)

## Step 5: Clean up (optional)
5. Clean up

In this step, when you're done exploring the AWS resources that you created as part of this tutorial, and to save on costs associated with these resources, you delete them.

**To delete tutorial resources**

1. To delete the service, run the following command:

   ```
   $ aws proton delete-service --name "static-website"
   ```

1. To delete the environment, run the following command:

   ```
   $ aws proton delete-environment --name "fargate-env-prod"
   ```

1. To delete the service template, run the following commands:

   ```
   $ aws proton delete-template-sync-config \
     --template-name "load-balanced-fargate-svc" \
     --template-type "SERVICE"
   $ aws proton delete-service-template --name "load-balanced-fargate-svc"
   ```

1. To delete the environment template, run the following commands:

   ```
   $ aws proton delete-template-sync-config \
     --template-name "fargate-env" \
     --template-type "ENVIRONMENT"
   $ aws proton delete-environment-template --name "fargate-env"
   ```

# The AWS Proton template library
Template library

The AWS Proton team maintains a library of template examples on GitHub. The library includes examples of infrastructure as code (IaC) files for many common environment and application infrastructure scenarios.

The template library is stored in two GitHub repositories:
+ [aws-proton-cloudformation-sample-templates](https://github.com/aws-samples/aws-proton-cloudformation-sample-templates/) – Examples of template bundles that use *AWS CloudFormation* with Jinja as their IaC language. You can use these examples for [AWS-managed provisioning](ag-works-prov-methods.md#ag-works-prov-methods-direct) environments.
+ [aws-proton-terraform-sample-templates](https://github.com/aws-samples/aws-proton-terraform-sample-templates/) – Examples of template bundles that use *Terraform* as their IaC language. You can use these examples for [Self-managed provisioning](ag-works-prov-methods.md#ag-works-prov-methods-self) environments.

Each one of these repositories has a `README` file with full information about the repository's content and structure. Each example has information about the use case that the template covers, the example's architecture, and the input parameters that the template takes.

You can use the templates in this library directly by forking one of the library's repositories into your GitHub account. Alternatively, use these examples as a starting point for developing your environment and service templates.