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 services
Services

An AWS Proton service is an instantiation of a service template, normally including several service instances and a pipeline. An AWS Proton service instance is an instantiation of a service template in a specific [environment](ag-environments.md). A service template is a complete definition of the infrastructure and optional service pipeline for an AWS Proton service.

After you deploy your service instances, you can update them by source code pushes that prompt the CI/CD pipeline or by updating the service to new versions of its service template. AWS Proton prompts you when new versions of its service template become available so you can update your services to a new version. When your service is updated, AWS Proton re-deploys the service and service instances.

This chapter shows how to manage services by using create, view, update and delete operations. 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**
+ [

# Create a service
](ag-create-svc.md)
+ [

# View service data
](ag-svc-view.md)
+ [

# Edit a service
](ag-svc-update.md)
+ [

# Delete a service
](ag-svc-delete.md)
+ [

# View service instance data
](ag-svc-instance-view.md)
+ [

# Update a service instance
](ag-svc-instance-update.md)
+ [

# Update a service pipeline
](ag-svc-pipeline-update.md)

# Create a service
Create

To deploy an application with AWS Proton, as a developer, you create a service and provide the following inputs.

1. The name of an AWS Proton service template that's published by the platform team.

1. A name for the service.

1. The number of service instances that you want to deploy.

1. A selection of environments that you want to use.

1. A connection to your code repository if you're using a service template that includes a service pipeline (optional).

## What's in a service?


When you create an AWS Proton service, you can choose from two different types of service templates:
+ A service template that includes a service pipeline (default).
+ A service template that *doesn't* include a service pipeline.

You must create at least one service instance when you create your service.

A service instance and optional pipeline are associated with a service. You can only create or delete a pipeline within the context of service *create* and *delete* actions. To learn how to add and remove instances from a service, see [Edit a service](ag-svc-update.md).

**Note**  
Your environment is configured for either AWS- or self-managed provisioning. AWS Proton provisions services in an environment using the same provisioning method as the environment uses. The developer creating or updating service instances doesn't see the difference and their experience is the same in both case.  
For more information about provisioning methods, see [How AWS Proton provisions infrastructure](ag-works-prov-methods.md).

## Service templates


Both major and minor versions of service templates are available. When you use the console, you select the latest `Recommended` major and minor version of the service template. When you use the AWS CLI and you specify only the major version of the service template, you implicitly specify its latest `Recommended` minor version.

The following describes the difference between major and minor template versions and their use.
+ New versions of a template become `Recommended` as soon as they're approved by a member of the platform team. This means that new services are created using that version, and you're prompted to update existing services to the new version.
+ Through AWS Proton, the platform team can automatically update service instances to a new minor version of a service template. Minor versions must be backward compatible. 
+ Because major versions require you to provide new inputs as part of the update process, you need to update your service to a major version of its service template. Major versions *aren't* backward compatible.

## Create a service


The following procedures show how to use the AWS Proton console or AWS CLI to create a service with or without a service pipeline.

------
#### [ AWS Management Console ]

**Create a service as shown in the following console steps.**

1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Services**.

1. Choose **Create service**.

1. In the **Choose a service template** page, select a template and choose **Configure**.

   When you *don't* want to use an enabled pipeline, choose a template marked with *Excludes pipeline* for your service.

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

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 ID**, 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.

1. Choose **Next**.

1. In the **Configure custom settings** page, in the **Service instances** section, in the **New instance** section. You must enter values for the `required` parameters. You can enter values for the `optional` parameters or use the defaults when given.

1. In the **Pipeline inputs** section, you must enter values for the `required` parameters. You can enter values for the `optional` parameters or use the defaults when given.

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

1. Choose **Create**.

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

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

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

------
#### [ AWS CLI ]

When you use the AWS CLI, you specify service inputs in a YAML formatted `spec` file, `.aws-proton/service.yaml`, located in your source code directory.

You can use the CLI `get-service-template-minor-version` command to view the schema required and optional parameters that you provide values for in your spec file.

If you want to use a service template that has `pipelineProvisioning: "CUSTOMER_MANAGED"`, *don’t* include the `pipeline:` section in your spec and *don’t* include `-repository-connection-arn`, `-repository-id`, and `-branch-name` parameters in your `create-service` command.

**Create a service with a service pipeline as shown in the following CLI steps.**

1. **Set up the [service role](security_iam_service-role-policy-examples.md#codepipeline-proton-svc-role) for the pipeline as shown in the following CLI example command.**

   Command:

   ```
   $ aws proton update-account-settings \
           --pipeline-service-role-arn "arn:aws:iam::123456789012:role/AWSProtonServiceRole"
   ```

1. The following listing shows an example spec, based on the service template schema, that includes the service pipeline and instance inputs.

   Spec:

   ```
   proton: ServiceSpec
   
   pipeline:
     my_sample_pipeline_required_input: "hello"
     my_sample_pipeline_optional_input: "bye"
   
   instances:
     - name: "acme-network-dev"
       environment: "ENV_NAME"
       spec:
         my_sample_service_instance_required_input: "hi"
         my_sample_service_instance_optional_input: "ho"
   ```

   **Create a service with a pipeline as shown in the following CLI example command and response.**

   Command:

   ```
   $ aws proton create-service \
           --name "MySimpleService" \
           --branch-name "mainline" \
           --template-major-version "1" \
           --template-name "fargate-service" \
           --repository-connection-arn "arn:aws:codestar-connections:region-id:123456789012:connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" \
           --repository-id "myorg/myapp" \
           --spec "file://spec.yaml"
   ```

   Response:

   ```
   {
       "service": {
           "arn": "arn:aws:proton:region-id:123456789012:service/MySimpleService",
           "createdAt": "2020-11-18T19:50:27.460000+00:00",
           "lastModifiedAt": "2020-11-18T19:50:27.460000+00:00",
           "name": "MySimpleService",
           "repositoryConnectionArn": "arn:aws:codestar-connections:region-id:123456789012:connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
           "repositoryId": "myorg/myapp",
           "status": "CREATE_IN_PROGRESS",
           "templateName": "fargate-service"
       }
   }
   ```

**Create a service without a service pipeline as shown in the following CLI example command and response.**

The following shows an example spec that *doesn't* include service pipeline inputs.

Spec:

```
proton: ServiceSpec

instances:
  - name: "acme-network-dev"
    environment: "ENV_NAME"
    spec:
      my_sample_service_instance_required_input: "hi"
      my_sample_service_instance_optional_input: "ho"
```

**To create a service *without* a provisioned service pipeline, you provide the path to a `spec.yaml` and you *don't* include repository parameters as shown in the following CLI example command and response.**

Command:

```
$ aws proton create-service \
        --name "MySimpleServiceNoPipeline" \
        --template-major-version "1" \
        --template-name "fargate-service" \
        --spec "file://spec-no-pipeline.yaml"
```

Response:

```
{
    "service": {
        "arn": "arn:aws:proton:region-id:123456789012:service/MySimpleServiceNoPipeline",
        "createdAt": "2020-11-18T19:50:27.460000+00:00",
        "lastModifiedAt": "2020-11-18T19:50:27.460000+00:00",
        "name": "MySimpleServiceNoPipeline",
        "status": "CREATE_IN_PROGRESS",
        "templateName": "fargate-service-no-pipeline"
    }
}
```

------

# View service data
View

You can view and list service detail data using the AWS Proton console or the AWS CLI.

------
#### [ AWS Management Console ]

**List and view service details using the [AWS Proton console](https://console.aws.amazon.com//proton/) as shown in the following steps.**

1. To view a list of your services, choose **Services** in the navigation pane.

1. To view detail data, choose the name of a service.

   View your service detail data.

------
#### [ AWS CLI ]

**View the details of a service with a service pipeline as shown in the following CLI example command and response.**

Command:

```
$ aws proton get-service \
    --name "simple-svc"
```

Response:

```
{
    "service": {
        "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc",
        "branchName": "mainline",
        "createdAt": "2020-11-28T22:40:50.512000+00:00",
        "lastModifiedAt": "2020-11-28T22:44:51.207000+00:00",
        "name": "simple-svc",
        "pipeline": {
            "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc/pipeline/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
            "createdAt": "2020-11-28T22:40:50.512000+00:00",
            "deploymentStatus": "SUCCEEDED",
            "lastDeploymentAttemptedAt": "2020-11-28T22:40:50.512000+00:00",
            "lastDeploymentSucceededAt": "2020-11-28T22:40:50.512000+00:00",
            "spec": "proton: ServiceSpec\npipeline:\n  my_sample_pipeline_required_input: hello\n  my_sample_pipeline_optional_input: bye\ninstances:\n- name: instance-svc-simple\n  environment: my-simple-env\n  spec:\n    my_sample_service_instance_required_input: hi\n    my_sample_service_instance_optional_input: ho\n",
            "templateMajorVersion": "1",
            "templateMinorVersion": "1",
            "templateName": "svc-simple"
        },
        "repositoryConnectionArn": "arn:aws:codestar-connections:region-id:123456789012:connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
        "repositoryId": "myorg/myapp",
        "spec": "proton: ServiceSpec\npipeline:\n  my_sample_pipeline_required_input: hello\n  my_sample_pipeline_optional_input: bye\ninstances:\n- name: instance-svc-simple\n  environment: my-simple-env\n  spec:\n    my_sample_service_instance_required_input: hi\n    my_sample_service_instance_optional_input: ho\n",
        "status": "ACTIVE",
        "templateName": "svc-simple"
    }
}
```

**View the details of a service without a service pipeline as shown in the following CLI example command and response.**

Command:

```
$ aws proton get-service \
    --name "simple-svc-no-pipeline"
```

Response:

```
{
    "service": {
        "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc-without-pipeline",
        "createdAt": "2020-11-28T22:40:50.512000+00:00",
        "lastModifiedAt": "2020-11-28T22:44:51.207000+00:00",
        "name": "simple-svc-without-pipeline",
        "spec": "proton: ServiceSpec\ninstances:\n- name: instance-svc-simple\n  environment: my-simple-env\n  spec:\n    my_sample_service_instance_required_input: hi\n    my_sample_service_instance_optional_input: ho\n",
        "status": "ACTIVE",
        "templateName": "svc-simple-no-pipeline"
    }
}
```

------

# Edit a service
Edit

You can make the following edits to an AWS Proton service.
+ Edit the service description.
+ Edit a service by adding and removing service instances.

## Edit service description
Edit service description

You can use the console or the AWS CLI to edit a service description.

------
#### [ AWS Management Console ]

**Edit a service using the console as described in the following steps.**

**In the list of services.**

1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Services**.

1. In the list of services, choose the radio button to the left of the service that you want to update.

1. Choose **Edit**.

1. In the **Configure service** page, fill out the form and choose **Next**.

1. In the **Configure custom settings** page, choose **Next**.

1. Review your edits and choose **Save changes**.

**In the service detail page.**

1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Services**.

1. In the list of services, choose the name of the service that you want to edit.

1. In the service detail page, choose **Edit**.

1. In the **Configure service** page, fill out the form and choose **Next**.

1. In the **Configure custom settings** page, fill out the form and choose **Next**.

1. Review your edits and choose **Save changes**.

------
#### [ AWS CLI ]

**Edit a description as shown in the following CLI example command and response.**

Command:

```
$ aws proton update-service \
    --name "MySimpleService" \
    --description "Edit by updating description"
```

Response:

```
{
    "service": {
        "arn": "arn:aws:proton:region-id:123456789012:service/MySimpleService",
        "branchName": "main",
        "createdAt": "2021-03-12T22:39:42.318000+00:00",
        "description": "Edit by updating description",
        "lastModifiedAt": "2021-03-12T22:44:21.975000+00:00",
        "name": "MySimpleService",
        "repositoryConnectionArn": "arn:aws:codestar-connections:region-id:123456789012:connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "repositoryId": "my-repository/myorg-myapp",
        "status": "ACTIVE",
        "templateName": "fargate-service"
    }
}
```

------

## Edit a service to add or remove service instances
Add or remove service instances

For an AWS Proton service, you can add or delete service instances by submitting an edited spec. The following conditions must be met for a successful request:
+ Your service and pipeline aren't already being edited or deleted when you submit the edit request.
+ Your edited spec doesn't include edits that modify the service pipeline or edits to existing service instances that *aren't* to be deleted.
+ Your edited spec doesn't remove any existing service instance that has an attached component. To delete such a service instance, you should first update the component to detach it from its service instance. For more information about components, see [AWS Proton components](ag-components.md).

Deletion-failed instances are service instances in the `DELETE_FAILED` state. When you request a service edit, AWS Proton attempts to remove the deletion-failed instances for you, as part of the edit process. If any of your service instances failed to delete, there might still be resources that are associated with the instances, even though they aren't visible from the console or AWS CLI. Check your deletion-failed instance infrastructure resources and clean them up so that AWS Proton can remove them for you.

For the quota of service instances for a service, see [AWS Proton quotas](ag-limits.md). You also must maintain at least 1 service instance for your service after it's created. During the update process, AWS Proton makes a count of the existing service instances and the instances to be added or removed. Deletion-failed instances are included in this count and you must account for them when you edit your `spec`.

### Use the console or AWS CLI to add or remove service instances


------
#### [ AWS Management Console ]

**Edit your service to add or remove service instances using the console.**

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

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

1. Select the service that you want to edit.

1. Choose **Edit**.

1. (Optional) On the **Configure service** page, edit the service name or description, and then choose **Next**.

1. On the **Configure custom settings** page, choose **Delete** to delete a service instance and choose **Add new instance** to add a service instance and fill out the form.

1. Choose **Next**.

1. Review your update and choose **Save changes**.

1. A modal asks you to verify deletion of service instances. Follow the instructions and choose **Yes, delete**.

1. On the service detail page, view the status details for your service.

------
#### [ AWS CLI ]

**Add and delete service instances with an edited `spec` as shown in the following AWS CLI example commands and responses.**

When you use the CLI, your `spec` must *exclude* the service instances to delete and *include* both the service instances to add and the existing service instances that you *haven't* marked for deletion.

The following listing shows the example `spec` before the edit and a list of the service instances deployed by the spec. This spec was used in the previous example for editing a service description.

Spec:

```
proton: ServiceSpec

pipeline:
  my_sample_pipeline_optional_input: "abc"
  my_sample_pipeline_required_input: "123"

instances:
  - name: "my-instance"
    environment: "simple-env"
    spec:
      my_sample_service_instance_optional_input: "def"
      my_sample_service_instance_required_input: "456"
  - name: "my-other-instance"
    environment: "simple-env"
    spec:
      my_sample_service_instance_required_input: "789"
```

The following example CLI `list-service-instances` command and response shows the active instances prior to adding or deleting a service instance.

Command:

```
$ aws proton list-service-instances \
    --service-name "MySimpleService"
```

Response:

```
{
    "serviceInstances": [
        {
            "arn": "arn:aws:proton:region-id:123456789012:service/MySimpleService/service-instance/my-other-instance",
            "createdAt": "2021-03-12T22:39:42.318000+00:00",
            "deploymentStatus": "SUCCEEDED",
            "environmentName": "simple-env",
            "lastDeploymentAttemptedAt": "2021-03-12T22:39:43.109000+00:00",
            "lastDeploymentSucceededAt": "2021-03-12T22:39:43.109000+00:00",
            "name": "my-other-instance",
            "serviceName": "example-svc",
            "templateMajorVersion": "1",
            "templateMinorVersion": "0",
            "templateName": "fargate-service"
        },
        {
            "arn": "arn:aws:proton:region-id:123456789012:service/MySimpleService/service-instance/my-instance",
            "createdAt": "2021-03-12T22:39:42.318000+00:00",
            "deploymentStatus": "SUCCEEDED",
            "environmentName": "simple-env",
            "lastDeploymentAttemptedAt": "2021-03-12T22:39:43.160000+00:00",
            "lastDeploymentSucceededAt": "2021-03-12T22:39:43.160000+00:00",
            "name": "my-instance",
            "serviceName": "example-svc",
            "serviceTemplateArn": "arn:aws:proton:region-id:123456789012:service-template/fargate-service",
            "templateMajorVersion": "1",
            "templateMinorVersion": "0",
            "templateName": "fargate-service"
        }
    ]
}
```

The following listing shows the example edited `spec` used to delete and add an instance. The existing instance named `my-instance` is removed and a new instance named `yet-another-instance` is added.

Spec:

```
proton: ServiceSpec

pipeline:
  my_sample_pipeline_optional_input: "abc"
  my_sample_pipeline_required_input: "123"

instances:
  - name: "my-other-instance"
    environment: "simple-env"
    spec:
      my_sample_service_instance_required_input: "789"
  - name: "yet-another-instance"
    environment: "simple-env"
    spec:
      my_sample_service_instance_required_input: "789"
```

You can use `"${Proton::CURRENT_VAL}"` to indicate which parameter values to preserve from the original `spec`, if the values exist in the `spec`. Use `get-service` to view the original `spec` for a service, as described in [View service data](ag-svc-view.md).

The following listing shows how you can use `"${Proton::CURRENT_VAL}"` to ensure that your `spec` *doesn't* include parameter values changes for the existing services instances to remain.

Spec:

```
proton: ServiceSpec

pipeline:
  my_sample_pipeline_optional_input: "${Proton::CURRENT_VAL}"
  my_sample_pipeline_required_input: "${Proton::CURRENT_VAL}"

instances:
  - name: "my-other-instance"
    environment: "simple-env"
    spec:
      my_sample_service_instance_required_input: "${Proton::CURRENT_VAL}"
  - name: "yet-another-instance"
    environment: "simple-env"
    spec:
      my_sample_service_instance_required_input: "789"
```

The next listing shows the CLI command and response to edit the service.

Command:

```
$ aws proton update-service 
    --name "MySimpleService" \
    --description "Edit by adding and deleting a service instance" \
    --spec "file://spec.yaml"
```

Response:

```
{
    "service": {
        "arn": "arn:aws:proton:region-id:123456789012:service/MySimpleService",
        "branchName": "main",
        "createdAt": "2021-03-12T22:39:42.318000+00:00",
        "description": "Edit by adding and deleting a service instance",
        "lastModifiedAt": "2021-03-12T22:55:48.169000+00:00",
        "name": "MySimpleService",
        "repositoryConnectionArn": "arn:aws:codestar-connections:region-id:123456789012:connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "repositoryId": "my-repository/myorg-myapp",
        "status": "UPDATE_IN_PROGRESS",
        "templateName": "fargate-service"
    }
}
```

The following `list-service-instances` command and response confirms that the existing instance named `my-instance` is removed and a new instance named `yet-another-instance` is added.

Command:

```
$ aws proton list-service-instances \
    --service-name "MySimpleService"
```

Response:

```
{
    "serviceInstances": [
        {
            "arn": "arn:aws:proton:region-id:123456789012:service/MySimpleService/service-instance/yet-another-instance",
            "createdAt": "2021-03-12T22:39:42.318000+00:00",
            "deploymentStatus": "SUCCEEDED",
            "environmentName": "simple-env",
            "lastDeploymentAttemptedAt": "2021-03-12T22:56:01.565000+00:00",
            "lastDeploymentSucceededAt": "2021-03-12T22:56:01.565000+00:00",
            "name": "yet-another-instance",
            "serviceName": "MySimpleService",
            "templateMajorVersion": "1",
            "templateMinorVersion": "0",
            "templateName": "fargate-service"
        },
        {
            "arn": "arn:aws:proton:region-id:123456789012:service/MySimpleService/service-instance/my-other-instance",
            "createdAt": "2021-03-12T22:39:42.318000+00:00",
            "deploymentStatus": "SUCCEEDED",
            "environmentName": "simple-env",
            "lastDeploymentAttemptedAt": "2021-03-12T22:39:43.109000+00:00",
            "lastDeploymentSucceededAt": "2021-03-12T22:39:43.109000+00:00",
            "name": "my-other-instance",
            "serviceName": "MySimpleService",
            "templateMajorVersion": "1",
            "templateMinorVersion": "0",
            "templateName": "fargate-service"
        }
    ]
}
```

------

### What happens when you add or remove service instances


After you submit a service edit to delete and add service instances, AWS Proton takes the following actions.
+ Sets the service to `UPDATE_IN_PROGRESS`.
+ If the service has a pipeline, sets its status to `IN_PROGRESS` and blocks pipeline actions.
+ Sets any service instances that are to be deleted to `DELETE_IN_PROGRESS`.
+ Blocks service actions.
+ Blocks actions on service instances that are marked for deletion.
+ Creates new service instances.
+ Deletes instances that you listed for deletion.
+ Attempts to remove deletion-failed instances.
+ After additions and deletions are complete, re-provisions the service pipeline (if there is one), sets your service to `ACTIVE` and enables service and pipeline actions.

AWS Proton attempts to re-mediate failure modes as follows.
+ If one or more service instances *failed to be created*, AWS Proton tries to de-provision all of the newly created service instances and reverts the `spec` to the previous state. It *doesn't* delete any service instances and it *doesn't* modify the pipeline in any way.
+ If one or more service instances *failed to be deleted*, AWS Proton re-provisions the pipeline without the deleted instances. The `spec` is updated to include the added instances and to exclude the instances that were marked for deletion.
+ If the *pipeline fails provisioning*, a rollback *isn't* attempted and both the service and pipeline reflect a failed update state.

### Tagging and service edits


When you add service instances as part of your service edit, AWS managed tags propagate to and are automatically created for the new instances and provisioned resources. If you create new tags, those tags are only applied to the new instances. Existing service customer managed tags also propagate to the new instances. For more information, see [AWS Proton resources and tagging](resources.md).

# Delete a service
Delete

You can delete an AWS Proton service, with its instances and pipeline, by using the AWS Proton console or the AWS CLI.

You can't delete a service that has any service instance with an attached component. To delete such a service, you should first update all attached components to detach them from their service instances. For more information about components, see [AWS Proton components](ag-components.md).

------
#### [ AWS Management Console ]

**Delete a service using the console as described in the following steps.**

**In the service detail page.**

1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Services**.

1. In the list of services, choose the name of the service that you want to delete.

1. On the service detail page, choose **Actions** and then **Delete**.

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

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

------
#### [ AWS CLI ]

**Delete a service as shown in the following CLI example command and response.**

Command:

```
$ aws proton delete-service \
    --name "simple-svc"
```

Response:

```
{
    "service": {
        "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc",
        "branchName": "mainline",
        "createdAt": "2020-11-28T22:40:50.512000+00:00",
        "description": "Edit by updating description",
        "lastModifiedAt": "2020-11-29T00:30:39.248000+00:00",
        "name": "simple-svc",
        "repositoryConnectionArn": "arn:aws:codestar-connections:region-id:123456789012:connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "repositoryId": "myorg/myapp",
        "status": "DELETE_IN_PROGRESS",
        "templateName": "fargate-service"
    }
}
```

------

# View service instance data
View instances

Learn to view AWS Proton service instance detail data. You can use the console or the AWS CLI.

A service instance belongs to a service. You can only create or delete an instance within the context of service [edit](ag-svc-update.md), [create](ag-create-svc.md) and [delete](ag-svc-delete.md) actions. To learn how to add and remove instances from a service, see [Edit a service](ag-svc-update.md).

------
#### [ AWS Management Console ]

**List and view service instance details using the [AWS Proton console](https://console.aws.amazon.com//proton/) as shown in the following steps.**

1. To view a list of your service instances, choose **Services instances** in the navigation pane.

1. To view detail data, choose the name of a service instance.

   View your service instance detail data.

------
#### [ AWS CLI ]

**List and view service instance details as shown in the following CLI example commands and responses.**

Command:

```
$ aws proton list-service-instances
```

Response:

```
{
    "serviceInstances": [
        {
            "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc/service-instance/instance-one",
            "createdAt": "2020-11-28T22:40:50.512000+00:00",
            "deploymentStatus": "SUCCEEDED",
            "environmentArn": "arn:aws:proton:region-id:123456789012:environment/simple-env",
            "lastDeploymentAttemptedAt": "2020-11-28T22:40:50.512000+00:00",
            "lastDeploymentSucceededAt": "2020-11-28T22:40:50.512000+00:00",
            "name": "instance-one",
            "serviceName": "simple-svc",
            "templateMajorVersion": "1",
            "templateMinorVersion": "0",
            "templateName": "fargate-service"
        }
    ]
}
```

Command:

```
$ aws proton get-service-instance \
    --name "instance-one" \
    --service-name "simple-svc"
```

Response:

```
{
    "serviceInstance": {
        "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc/service-instance/instance-one",
        "createdAt": "2020-11-28T22:40:50.512000+00:00",
        "deploymentStatus": "SUCCEEDED",
        "environmentName": "simple-env",
        "lastDeploymentAttemptedAt": "2020-11-28T22:40:50.512000+00:00",
        "lastDeploymentSucceededAt": "2020-11-28T22:40:50.512000+00:00",
        "name": "instance-one",
        "serviceName": "simple-svc",
        "spec": "proton: ServiceSpec\npipeline:\n  my_sample_pipeline_optional_input: hello world\n  my_sample_pipeline_required_input: pipeline up\ninstances:\n- name: instance-one\n  environment: my-simple-env\n  spec:\n    my_sample_service_instance_optional_input: Ola\n    my_sample_service_instance_required_input: Ciao\n",
        "templateMajorVersion": "1",
        "templateMinorVersion": "0",
        "templateName": "svc-simple"
    }
}
```

------

# Update a service instance
Update instance

Learn to update an AWS Proton service instance and cancel the update.

A service instance belongs to a service. You can only create or delete an instance within the context of service [edit](ag-svc-update.md), [create](ag-create-svc.md) and [delete](ag-svc-delete.md) actions. To learn how to add and remove instances from a service, see [Edit a service](ag-svc-update.md).

There are four modes for updating a service instance as described in the following list. When using the AWS CLI, the `deployment-type` field defines the mode. When using the console, these modes map to the **Edit** and the **Update to latest minor version** and **Update to latest major version** actions that drop down from **Actions** in the service instance detail page.

  
`NONE`  
In this mode, a deployment *doesn't* occur. Only the requested metadata parameters are updated.

  
`CURRENT_VERSION`  
In this mode, the service instance is deployed and updated with the new spec that you provide. Only requested parameters are updated. *Don’t* include minor or major version parameters when you use this `deployment-type`.

  
`MINOR_VERSION`  
In this mode, the service instance is deployed and updated with the published, recommended (latest) minor version of the current major version in use by default. You can also specify a different minor version of the current major version in use.

  
`MAJOR_VERSION`  
In this mode, the service instance is deployed and updated with the published, recommended (latest) major and minor version of the current template by default. You can also specify a different major version that is higher than the major version in use and a minor version (optional).

You can attempt to cancel a service instance update deployment if the `deploymentStatus` is `IN_PROGRESS`. AWS Proton attempts to cancel the deployment. Successful cancellation *isn’t* guaranteed.

When you cancel an update deployment, AWS Proton attempts to cancel the deployment as listed in the following steps.
+ Sets the deployment state to `CANCELLING`.
+ Stops the deployment in process and deletes any new resources that were created by the deployment when `IN_PROGRESS`.
+ Sets the deployment state to `CANCELLED`.
+ Reverts the state of the resource to what it was before the deployment was started.

For more information on cancelling a service instance deployment, see [CancelServiceInstanceDeployment](https://docs.aws.amazon.com/proton/latest/APIReference/API_CancelServiceInstanceDeployment.html) in the *AWS Proton API Reference*.

**Use the console or AWS CLI to make updates or cancel update deployments.**

------
#### [ AWS Management Console ]

**Update a service instance using the console by following these steps.**

1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Service instances** in the navigation pane.

1. In the list of service instances, choose the name of the service instance that you want to update.

1. Choose **Actions** and then choose one of the update options, **Edit** to update spec or **Actions** and then **Update to latest minor version**, or **Update to latest major version**.

1. Fill out each form and choose **Next** until you reach the **Review** page.

1. Review your edits and choose **Update**.

------
#### [ AWS CLI ]

**Update a service instance to a new minor version as shown in the CLI example commands and responses.**

When you update your service instance with a modified `spec`, you can use `"${Proton::CURRENT_VAL}"` to indicate which parameter values to preserve from the original `spec`, if the values exist in the `spec`. Use `get-service` to view the original `spec` for a service instance, as described in [View service data](ag-svc-view.md).

The following example shows how you can use `"${Proton::CURRENT_VAL}"` in a `spec`.

Spec:

```
proton: ServiceSpec

pipeline:
  my_sample_pipeline_optional_input: "${Proton::CURRENT_VAL}"
  my_sample_pipeline_required_input: "${Proton::CURRENT_VAL}"

instances:
  - name: "my-instance"
    environment: "simple-env"
    spec:
      my_sample_service_instance_optional_input: "${Proton::CURRENT_VAL}"
      my_sample_service_instance_required_input: "${Proton::CURRENT_VAL}"
  - name: "my-other-instance"
    environment: "simple-env"
    spec:
      my_sample_service_instance_required_input: "789"
```

Command: to update

```
$ aws proton update-service-instance \
    --name "instance-one" \
    --service-name "simple-svc" \
    --spec "file://service-spec.yaml" \
    --template-major-version "1" \
    --template-minor-version "1" \
    --deployment-type "MINOR_VERSION"
```

Response:

```
{
    "serviceInstance": {
        "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc/service-instance/instance-one",
        "createdAt": "2021-04-02T21:29:59.962000+00:00",
        "deploymentStatus": "IN_PROGRESS",
        "environmentName": "arn:aws:proton:region-id:123456789012:environment/simple-env",
        "lastDeploymentAttemptedAt": "2021-04-02T21:38:00.823000+00:00",
        "lastDeploymentSucceededAt": "2021-04-02T21:29:59.962000+00:00",
        "name": "instance-one",
        "serviceName": "simple-svc",
        "templateMajorVersion": "1",
        "templateMinorVersion": "0",
        "templateName": "svc-simple"
    }
}
```

Command: to get and confirm status

```
$ aws proton get-service-instance \
    --name "instance-one" \
    --service-name "simple-svc"
```

Response:

```
{
    "serviceInstance": {
        "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc/service-instance/instance-one",
        "createdAt": "2021-04-02T21:29:59.962000+00:00",
        "deploymentStatus": "SUCCEEDED",
        "environmentName": "simple-env",
        "lastDeploymentAttemptedAt": "2021-04-02T21:38:00.823000+00:00",
        "lastDeploymentSucceededAt": "2021-04-02T21:38:00.823000+00:00",
        "name": "instance-one",
        "serviceName": "simple-svc",
        "spec": "proton: ServiceSpec\n\npipeline:\n  my_sample_pipeline_optional_input: \"abc\"\n  my_sample_pipeline_required_input: \"123\"\n\ninstances:\n  - name: \"instance-one\"\n    environment: \"simple-env\"\n    spec:\n      my_sample_service_instance_optional_input: \"def\"\n      my_sample_service_instance_required_input: \"456\"\n  - name: \"my-other-instance\"\n    environment: \"kls-simple-env\"\n    spec:\n      my_sample_service_instance_required_input: \"789\"\n",
        "templateMajorVersion": "1",
        "templateMinorVersion": "1",
        "templateName": "svc-simple"
    }
}
```

------

------
#### [ AWS Management Console ]

**Cancel a service instance deployment using the console as shown in the following steps.**

1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Service instances** in the navigation pane.

1. In the list of service instances, choose the name of the service instance with the deployment update that you want to cancel.

1. If your update deployment status is **In progress**, in the service instance detail page, choose **Actions** and then **Cancel deployment**.

1. A modal asks you to confirm the cancellation. Choose **Cancel deployment**.

1. Your update deployment status is set to **Cancelling** and then **Cancelled** to complete the cancellation.

------
#### [ AWS CLI ]

**Cancel an IN\$1PROGRESS service instance deployment update to new minor version 2 as shown in the following CLI example commands and responses.**

A wait condition is included in the template used for this example so that the cancellation starts before the update deployment succeeds.

Command: to cancel

```
$ aws proton cancel-service-instance-deployment \
    --service-instance-name "instance-one" \
    --service-name "simple-svc"
```

Response:

```
{
    "serviceInstance": {
        "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc/service-instance/instance-one",
        "createdAt": "2021-04-02T21:29:59.962000+00:00",
        "deploymentStatus": "CANCELLING",
        "environmentName": "simple-env",
        "lastDeploymentAttemptedAt": "2021-04-02T21:45:15.406000+00:00",
        "lastDeploymentSucceededAt": "2021-04-02T21:38:00.823000+00:00",
        "name": "instance-one",
        "serviceName": "simple-svc",
        "spec": "proton: ServiceSpec\npipeline:\n  my_sample_pipeline_optional_input: abc\n  my_sample_pipeline_required_input: '123'\ninstances:\n- name: my-instance\n  environment: MySimpleEnv\n  spec:\n    my_sample_service_instance_optional_input: def\n    my_sample_service_instance_required_input: '456'\n- name: my-other-instance\n  environment: MySimpleEnv\n  spec:\n    my_sample_service_instance_required_input: '789'\n",
        "templateMajorVersion": "1",
        "templateMinorVersion": "1",
        "templateName": "svc-simple"
    }
}
```

Command: to get and confirm status

```
$ aws proton get-service-instance \
    --name "instance-one" \
    --service-name "simple-svc"
```

Response:

```
{
    "serviceInstance": {
        "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc/service-instance/instance-one",
        "createdAt": "2021-04-02T21:29:59.962000+00:00",
        "deploymentStatus": "CANCELLED",
        "deploymentStatusMessage": "User initiated cancellation.",
        "environmentName": "simple-env",
        "lastDeploymentAttemptedAt": "2021-04-02T21:45:15.406000+00:00",
        "lastDeploymentSucceededAt": "2021-04-02T21:38:00.823000+00:00",
        "name": "instance-one",
        "serviceName": "simple-svc",
        "spec": "proton: ServiceSpec\n\npipeline:\n  my_sample_pipeline_optional_input: \"abc\"\n  my_sample_pipeline_required_input: \"123\"\n\ninstances:\n  - name: \"instance-one\"\n    environment: \"simple-env\"\n    spec:\n      my_sample_service_instance_optional_input: \"def\"\n      my_sample_service_instance_required_input: \"456\"\n  - name: \"my-other-instance\"\n    environment: \"kls-simple-env\"\n    spec:\n      my_sample_service_instance_required_input: \"789\"\n",
        "templateMajorVersion": "1",
        "templateMinorVersion": "1",
        "templateName": "svc-simple"
    }
}
```

------

# Update a service pipeline
Update pipeline

Learn to update an AWS Proton service pipeline and cancel the update.

A service pipeline belongs to a service. You can only create or delete a pipeline within the context of service [create](ag-create-svc.md) and [delete](ag-svc-delete.md) actions.

There are four modes for updating a service pipeline as described in the following list. When using the AWS CLI, the `deployment-type` field defines the mode. When you use the console, these modes map to the **Edit pipeline** and **Update to recommended version**.

  
`NONE`  
In this mode, a deployment *doesn't* occur. Only the requested metadata parameters are updated.

  
`CURRENT_VERSION`  
In this mode, the service pipeline is deployed and updated with the new spec that you provide. Only requested parameters are updated. *Don’t* include minor or major version parameters when you use this `deployment-type`.

  
`MINOR_VERSION`  
In this mode, the service pipeline is deployed and updated with the published, recommended (latest) minor version of the current major version in use by default. You can also specify a different minor version of the current major version in use.

  
`MAJOR_VERSION`  
In this mode, the service pipeline is deployed and updated with the published, recommended (latest) major and minor version of the current template by default. You can also specify a different major version that is higher than the major version in use and a minor version (optional).

You can attempt to cancel a service pipeline update deployment if the `deploymentStatus` is `IN_PROGRESS`. AWS Proton attempts to cancel the deployment. Successful cancellation isn’t guaranteed.

When you cancel an update deployment, AWS Proton attempts to cancel the deployment as listed in the following steps.
+ Sets the deployment state to `CANCELLING`.
+ Stops the deployment in process and deletes any new resources that were created by the deployment when `IN_PROGRESS`.
+ Sets the deployment state to `CANCELLED`.
+ Reverts the state of the resource to what it was before the deployment was started.

For more information on cancelling a service pipeline deployment, see [CancelServicePipelineDeployment](https://docs.aws.amazon.com/proton/latest/APIReference/API_CancelServicePipelineDeployment.html) in the *AWS Proton API Reference*.

**Use the console or AWS CLI to make updates or cancel update deployments.**

------
#### [ AWS Management Console ]

**Update a service pipeline using the console as described in the following steps.**

1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Services**.

1. In the list of services, choose the name of the service that you want to update the pipeline for.

1. There are two tabs on the service detail page, **Overview** and **Pipeline**. Choose **Pipeline**.

1. If you want to update specs, choose **Edit Pipeline** and fill out each form and choose **Next** until you complete the final form and then choose **Update pipeline**.

   If you want to update to a new version and there's an **information icon** that indicates a new version is available at **Pipeline template**, choose the name of the new template version.

   1. Choose **Update to recommended version**.

   1. Fill out each form and choose **Next** until you complete the final form and choose **Update**.

------
#### [ AWS CLI ]

**Update a service pipeline to a new minor version as shown in the following CLI example commands and responses.**

When you update your service pipeline with a modified `spec`, you can use `"${Proton::CURRENT_VAL}"` to indicate which parameter values to preserve from the original `spec`, if the values exist in the `spec`. Use `get-service` to view the original `spec` for a service pipeline, as described in [View service data](ag-svc-view.md).

The following example shows how you can use `"${Proton::CURRENT_VAL}"` in a `spec`.

Spec:

```
proton: ServiceSpec

pipeline:
  my_sample_pipeline_optional_input: "${Proton::CURRENT_VAL}"
  my_sample_pipeline_required_input: "${Proton::CURRENT_VAL}"

instances:
  - name: "my-instance"
    environment: "simple-env"
    spec:
      my_sample_service_instance_optional_input: "${Proton::CURRENT_VAL}"
      my_sample_service_instance_required_input: "${Proton::CURRENT_VAL}"
  - name: "my-other-instance"
    environment: "simple-env"
    spec:
      my_sample_service_instance_required_input: "789"
```

Command: to update

```
$ aws proton update-service-pipeline \
    --service-name "simple-svc" \
    --spec "file://service-spec.yaml" \
    --template-major-version "1" \
    --template-minor-version "1" \
    --deployment-type "MINOR_VERSION"
```

Response:

```
{
    "pipeline": {
        "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc/pipeline/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "createdAt": "2021-04-02T21:29:59.962000+00:00",
        "deploymentStatus": "IN_PROGRESS",
        "lastDeploymentAttemptedAt": "2021-04-02T21:39:28.991000+00:00",
        "lastDeploymentSucceededAt": "2021-04-02T21:29:59.962000+00:00",
        "spec": "proton: ServiceSpec\n\npipeline:\n  my_sample_pipeline_optional_input: \"abc\"\n  my_sample_pipeline_required_input: \"123\"\n\ninstances:\n  - name: \"my-instance\"\n    environment: \"MySimpleEnv\"\n    spec:\n      my_sample_service_instance_optional_input: \"def\"\n      my_sample_service_instance_required_input: \"456\"\n  - name: \"my-other-instance\"\n    environment: \"MySimpleEnv\"\n    spec:\n      my_sample_service_instance_required_input: \"789\"\n",
        "templateMajorVersion": "1",
        "templateMinorVersion": "0",
        "templateName": "svc-simple"
    }
}
```

Command: to get and confirm status

```
$ aws proton get-service \
    --name "simple-svc"
```

Response:

```
{
    "service": {
        "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc",
        "branchName": "main",
        "createdAt": "2021-04-02T21:29:59.962000+00:00",
        "lastModifiedAt": "2021-04-02T21:30:54.364000+00:00",
        "name": "simple-svc",
        "pipeline": {
            "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc/pipeline",
            "createdAt": "2021-04-02T21:29:59.962000+00:00",
            "deploymentStatus": "SUCCEEDED",
            "lastDeploymentAttemptedAt": "2021-04-02T21:39:28.991000+00:00",
            "lastDeploymentSucceededAt": "2021-04-02T21:39:28.991000+00:00",
            "spec": "proton: ServiceSpec\n\npipeline:\n  my_sample_pipeline_optional_input: \"abc\"\n  my_sample_pipeline_required_input: \"123\"\n\ninstances:\n  - name: \"instance-one\"\n    environment: \"simple-env\"\n    spec:\n      my_sample_service_instance_optional_input: \"def\"\n      my_sample_service_instance_required_input: \"456\"\n  - name: \"my-other-instance\"\n    environment: \"simple-env\"\n    spec:\n      my_sample_service_instance_required_input: \"789\"\n",
            "templateMajorVersion": "1",
            "templateMinorVersion": "1",
            "templateName": "svc-simple"
        },
        "repositoryConnectionArn": "arn:aws:codestar-connections:region-id:123456789012:connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "repositoryId": "repo-name/myorg-myapp",
        "spec": "proton: ServiceSpec\n\npipeline:\n  my_sample_pipeline_optional_input: \"abc\"\n  my_sample_pipeline_required_input: \"123\"\n\ninstances:\n  - name: \"instance-one\"\n    environment: \"simple-env\"\n    spec:\n      my_sample_service_instance_optional_input: \"def\"\n      my_sample_service_instance_required_input: \"456\"\n  - name: \"my-other-instance\"\n    environment: \"simple-env\"\n    spec:\n      my_sample_service_instance_required_input: \"789\"\n",
        "status": "ACTIVE",
        "templateName": "svc-simple"
    }
}
```

------

------
#### [ AWS Management Console ]

**Cancel a service pipeline deployment using the console as shown in the following steps.**

1. In the [AWS Proton console](https://console.aws.amazon.com//proton/), choose **Services** in the navigation pane.

1. In the list of services, choose the name of the service that has the pipeline with the deployment update that you want to cancel.

1. In the service detail page, choose the **Pipeline** tab.

1. If your update deployment status is **In progress**, in the service pipeline detail page, choose **Cancel deployment**.

1. A modal asks you to confirm the cancellation. Choose **Cancel deployment**.

1. Your update deployment status is set to **Cancelling** and then **Cancelled** to complete the cancellation.

------
#### [ AWS CLI ]

**Cancel an IN\$1PROGRESS service pipeline deployment update to minor version 2 as shown in the following CLI example commands and responses.**

A wait condition is included in the template used for this example so that the cancellation starts before the update deployment succeeds.

Command: to cancel

```
$ aws proton cancel-service-pipeline-deployment \
    --service-name "simple-svc"
```

Response:

```
{
    "pipeline": {
        "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc/pipeline",
        "createdAt": "2021-04-02T21:29:59.962000+00:00",
        "deploymentStatus": "CANCELLING",
        "lastDeploymentAttemptedAt": "2021-04-02T22:02:45.095000+00:00",
        "lastDeploymentSucceededAt": "2021-04-02T21:39:28.991000+00:00",
        "templateMajorVersion": "1",
        "templateMinorVersion": "1",
        "templateName": "svc-simple"
    }
}
```

Command: to get and confirm status

```
$ aws proton get-service \
    --name "simple-svc"
```

Response:

```
{
    "service": {
        "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc",
        "branchName": "main",
        "createdAt": "2021-04-02T21:29:59.962000+00:00",
        "lastModifiedAt": "2021-04-02T21:30:54.364000+00:00",
        "name": "simple-svc",
        "pipeline": {
            "arn": "arn:aws:proton:region-id:123456789012:service/simple-svc/pipeline",
            "createdAt": "2021-04-02T21:29:59.962000+00:00",
            "deploymentStatus": "CANCELLED",
            "deploymentStatusMessage": "User initiated cancellation.",
            "lastDeploymentAttemptedAt": "2021-04-02T22:02:45.095000+00:00",
            "lastDeploymentSucceededAt": "2021-04-02T21:39:28.991000+00:00",
            "spec": "proton: ServiceSpec\n\npipeline:\n  my_sample_pipeline_optional_input: \"abc\"\n  my_sample_pipeline_required_input: \"123\"\n\ninstances:\n  - name: \"instance-one\"\n    environment: \"simple-env\"\n    spec:\n      my_sample_service_instance_optional_input: \"def\"\n      my_sample_service_instance_required_input: \"456\"\n  - name: \"my-other-instance\"\n    environment: \"simple-env\"\n    spec:\n      my_sample_service_instance_required_input: \"789\"\n",
            "templateMajorVersion": "1",
            "templateMinorVersion": "1",
            "templateName": "svc-simple"
        },
        "repositoryConnectionArn": "arn:aws:codestar-connections:region-id:123456789012:connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "repositoryId": "repo-name/myorg-myapp",
        "spec": "proton: ServiceSpec\n\npipeline:\n  my_sample_pipeline_optional_input: \"abc\"\n  my_sample_pipeline_required_input: \"123\"\n\ninstances:\n  - name: \"instance-one\"\n    environment: \"simple-env\"\n    spec:\n      my_sample_service_instance_optional_input: \"def\"\n      my_sample_service_instance_required_input: \"456\"\n  - name: \"my-other-instance\"\n    environment: \"simple-env\"\n    spec:\n      my_sample_service_instance_required_input: \"789\"\n",
        "status": "ACTIVE",
        "templateName": "svc-simple"
    }
}
```

------