# View service history using Amazon ECS service deployments Service deployments provide a comprehensive view of your deployments. Service deployments provide the following information about the service: + The currently deployed workload configuration (the source service revision) + The workload configuration being deployed (the target service revision) + The deployment status + The number of failed tasks the circuit break detected + The CloudWatch alarms that are in alarm + When the service deployment started and completed + The details of a rollback if one occurred For information about the service deployment properties, see [Properties included in an Amazon ECS service deployment](service-deployment-property.md). Service deployments are read-only and each have a unique ID. There are three service deployment stages: | Stage | Definition | Associated states | | --- | --- | --- | | Pending | A service deployment has been created, but has not started | PENDING | | Ongoing | A service deployment is in-progress | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-deployment.html) | | Completed | A service deployment has finished (successfully or unsuccessfully) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-deployment.html) | You use service deployments to understand the lifecycle of your service and to determine if there are any actions you need to take. For example, if a rollback happened, you might need to investigate the service deployment and looking at service events. You can view the most recent 90-day history for deployments created on or after October 25, 2024 by using the console, API, and the AWS CLI. You can stop a deployment that has not completed. For more information, see [Stopping Amazon ECS service deployments](stop-service-deployment.md). ## Service deployment lifecycle Amazon ECS creates a new service deployment automatically when any of the following actions happen: + A user creates a service. + A user updates the service and uses the force new deployment option. + A user updates one or more service properties that require a deployment. While a deployment is ongoing, Amazon ECS updates the following service deployment properties to reflect the service deployment’s progress: + The state + The number of running tasks The number of running tasks indicated in the service revision might not equal the actual number of running task. This number represents the number of tasks running when the deployment completed. For example, if you launched tasks independent of the service deployment, those tasks are not included in the running task count for the service revision. + Circuit breaker failure detection: + The number of tasks that have failed to start + CloudWatch alarm failure detection + The alarms that are active + Rollback information: + The start time + The reason for the rollback + The ARN of the service revision used for the rollback + The status reason Amazon ECS deletes the service deployment when you delete a service. ## Service deployment states A service deployment starts in `PENDING` state. The following illustration shows the service deployment states that can happen after the `PENDING` state: `IN_PROGRESS`, `ROLLBACK_REQUESTED`, `SUCCESSFUL`, `STOP_REQUESTED`, `ROLLBACK_IN_PROGRESSS`, `ROLLBACK_FAILED`, `ROLLBACK_SUCCESSFUL`, and `STOPPED`. ![\[Service deployment STOP_REQUESTED, SUCCESSFUL, and ROLLBACK_IN_PROGRESS states that can happen after the IN_PROGRESS state.\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/images/service-deployment-states.png) The following information provides details about service deployment states: + `PENDING` - The service deployment has been created, but has not started. The state can move to `IN_PROGRESS`, `ROLLBACK_REQUESTED`, `STOP_REQUESTED`, or `STOPPED`. + `IN_PROGRESS` - The service deployment is ongoing. The state can move to `SUCCESSFUL`, `STOP_REQUESTED`, `ROLLBACK_REQUESTED`, `ROLLBACK_IN_PROGRESS`, and `STOPPED`. + `STOP_REQUESTED` - The service deployment state moves to `STOP_REQUESTED` when any of the following happen: + A user starts a new service deployment. + The rollback option is not in use for the failure detection mechanism (the circuit breaker or alarm-based) and the service does not reach the `SUCCESSFUL` state. The state moves to `STOPPED`. + `ROLLBACK_REQUESTED` - The service deployment state moves to `ROLLBACK_REQUESTED` when a user request a rollback through the console, API, or CLI. The state can move to `SUCCESSFUL`, `ROLLBACK_IN_PROGRESS`, and `STOPPED`. + `SUCCESSFUL` - The service deployment state moves to `SUCCESSFUL` when the service deployment successfully completes. + `ROLLBACK_IN_PROGRESS` - The service deployment state moves to `ROLLBACK_IN_PROGRESS` when the rollback option is in use for the failure detection mechanism (the circuit breaker or alarm-based) and the service fails. The state moves to `ROLLBACK_SUCCESSFUL`, or `ROLLBACK_FAILED`. # Properties included in an Amazon ECS service deployment The following properties are included in a service deployment. | Property | Description | | --- | --- | | Service deployment ARN | The ARN of the service deployment. | | Service ARN | The ARN of the service for this service deployment. | | Cluster ARN | The ARN for the cluster that hosts the service. | | Service deployment creation time | The time the service deployment was created. | | Service deployment start time | The time the service deployment started. | | Service deployment finish time | The time the service deployment finished. | | Service deployment stopped time | The time the service deployment stopped. | | Service deployment update time | The time that the service deployment was last updated. | | Source service revisions | The currently running service revisions. For information about the included properties, see [Properties included in an Amazon ECS service revision](service-revision-property.md). | | Deployment configuration | The deployment parameters including the circuit breaker configuration, the alarms that determine.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-deployment-property.html) | | Target service revision | The service revision to deploy. After the deployment completes successfully, the target service revision is the running service revision. | | Service deployment status | The service deployment state.The valid values are PENDING, SUCCESSFUL, STOPPED, STOP\$1REQUESTED, STOP\$1IN\$1PROGRESS, IN\$1PROGRESS, ROLLBACK\$1IN\$1PROGRESS, ROLLBACK\$1SUCCESSFUL, and ROLLBACK\$1FAILED. | | Service deployment status information | Information about why the service deployment is in the current status. For example, the circuit breaker detected a failure. | | Rollback information | The rollback options the service deployment uses when the deployment fails. | | Service deployment circuit breaker options | The circuit breaker that determines a service deployment failed. | | CloudWatch alarms for the service deployment | The CloudWatch alarms that determine when a service deployment fails. | # Permissions required for viewing Amazon ECS service deployments When you follow the best practice of granting least privilege, you need to add additional permissions in order to view service deployments in the console. You need access to the following actions: + ListServiceDeployments + DescribeServiceDeployments + DescribeServiceRevisions You need access to the following resources: + Service + Service deployment + Service revision The following example policy contains the required permissions, and limits the actions to a specified service. Replace the `account`, `cluster-name`, and `service-name` with your values. ------ #### [ JSON ] **** ``` { "Statement": [ { "Effect": "Allow", "Action": [ "ecs:ListServiceDeployments", "ecs:DescribeServiceDeployments", "ecs:DescribeServiceRevisions" ], "Resource": [ "arn:aws:ecs:us-east-1:123456789012:service/cluster-name/service-name", "arn:aws:ecs:us-east-1:123456789012:service-deployment/cluster-name/service-name/*", "arn:aws:ecs:us-east-1:123456789012:service-revision/cluster-name/service-name/*" ] } ] } ``` ------ # Viewing Amazon ECS service deployments You can see the most recent 90-day history for deployments created on or after October 25, 2024. The service deployments can be in any of the following states: + In-progress + Pending + Completed You can use this information to determine if you need to update how the service is being deployed, or the service revision. For information about the included properties, see [Properties included in an Amazon ECS service deployment](service-deployment-property.md). Before you begin, configure the required permissions for viewing service deployments. For more information, see [Permissions required for viewing Amazon ECS service deployments](service-deployment-permissions.md). ------ #### [ Amazon ECS Console ] 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. On the **Clusters** page, choose the cluster. 1. On the cluster details page, in the **Services** section, choose the service. The service details page displays. 1. On the service details page, choose **Deployments**. 1. Choose the service deployment to view. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/view-service-deployment.html) The service deployment details page appears. 1. (Optional) Compare service revisions to view the differences. Under **Service revisions**, choose **Compare revisions**, and then select 2 revisions to compare. The service revisions are displayed side-by-side with the differences highlighted. ------ #### [ AWS CLI ] 1. Run `list-service-deployments` to retrieve the service deployment ARN. Replace the variables with your values. ``` aws ecs list-service-deployments --cluster cluster-name --service service-name ``` Note the serviceDeploymentArn for the deployment you want to view. ``` { "serviceDeployments": [ { "serviceDeploymentArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/example/sd-example/NCWGC2ZR-taawPAYrIaU5", "serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/example/sd-example", "clusterArn": "arn:aws:ecs:us-west-2:123456789012:cluster/example", "targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/example/sd-example/4980306466373577095", "status": "SUCCESSFUL" } ] } ``` 1. Run `describe-service-deployments`. Use the `serviceDeploymentArn` that was returned from `list-service-deployments`. Replace the variables with your values. ``` aws ecs describe-service-deployments --service-deployment-arns arn:aws:ecs:region:123456789012:service-deployment/cluster-name/service-name/NCWGC2ZR-taawPAYrIaU5 ``` ------ ## Next steps You can view the details for service revisions in the deployment. For more information, see [Viewing Amazon ECS service revision details](view-service-revision.md)