# 指定 Amazon ECS 部署时的 Amazon EBS 卷配置
将 `configuredAtLaunch` 参数设置为 `true` 注册任务定义后，您可以在运行独立任务或创建或更新服务时在部署时配置 Amazon EBS 卷。有关使用 `configuredAtLaunch` 参数将卷配置推迟到启动时间的更多信息，请参阅[在 Amazon ECS 任务定义中将卷配置推迟到启动时间](specify-ebs-config.md)。
要配置卷，您可以使用 Amazon ECS API，也可以将 JSON 文件作为以下 AWS CLI 命令的输入传递：
+ 运行独立 ECS 任务的 `[run-task](https://docs.aws.amazon.com/cli/latest/reference/ecs/run-task.html)`。
+ 在特定的容器实例中运行独立 ECS 任务的 `[start-task](https://docs.aws.amazon.com/cli/latest/reference/ecs/start-task.html)`。此命令不适用于 Fargate 任务。
+ 创建新的 ECS 服务的 `[create-service](https://docs.aws.amazon.com/cli/latest/reference/ecs/create-service.html)`。
+ 更新现有服务的 `[update-service](https://docs.aws.amazon.com/cli/latest/reference/ecs/update-service.html)`。
**注意**
要使任务中的容器写入已装载的 Amazon EBS 卷，该容器必须具有适当的文件系统权限。当您在容器定义中指定非根用户时，Amazon ECS 会自动为卷配置基于组的权限，以允许指定的用户读取和写入该卷。如果未指定用户，则容器以根用户身份运行，并拥有对卷的完全访问权限。
您也可以使用 AWS 管理控制台 来配置 Amazon EBS 卷。有关更多信息，请参阅 [将应用程序作为 Amazon ECS 任务运行](standalone-task-create.md)、[创建 Amazon ECS 滚动更新部署](create-service-console-v2.md) 和 [更新 Amazon ECS 服务](update-service-console-v2.md)。
以下 JSON 代码段显示可在部署时配置的 Amazon EBS 卷的所有参数。要使用这些参数进行卷配置，请将 `user input placeholders` 替换为您自己的信息。有关这些参数的更多信息，请参阅[卷配置](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service_definition_parameters.html#sd-volumeConfigurations)。
```
"volumeConfigurations": [
{
"name": "ebs-volume",
"managedEBSVolume": {
"encrypted": true,
"kmsKeyId": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"volumeType": "gp3",
"sizeInGiB": 10,
"snapshotId": "snap-12345",
"volumeInitializationRate":100,
"iops": 3000,
"throughput": 125,
"tagSpecifications": [
{
"resourceType": "volume",
"tags": [
{
"key": "key1",
"value": "value1"
}
],
"propagateTags": "NONE"
}
],
"roleArn": "arn:aws:iam::1111222333:role/ecsInfrastructureRole",
"terminationPolicy": {
"deleteOnTermination": true//can't be configured for service-managed tasks, always true
},
"filesystemType": "ext4"
}
}
]
```
**重要**
确保您在配置中指定的 `volumeName` 与您在任务定义中指定的 `volumeName` 相同。
有关检查卷附加状态的信息，请参阅[排查 Amazon ECS 任务挂载 Amazon EBS 卷的问题](troubleshoot-ebs-volumes.md)。有关 EBS 卷附加所需的 Amazon ECS 基础设施 AWS Identity and Access Management（IAM）角色的信息，请参阅[Amazon ECS 基础设施 IAM 角色](infrastructure_IAM_role.md)。
以下是显示 Amazon EBS 卷配置的 JSON 代码段示例。这些示例可以通过将代码段保存在 JSON 文件中并将文件作为 AWS CLI 命令的参数（使用 `--cli-input-json file://filename` 参数）传递来使用。将 `user input placeholders` 替换为您自己的信息。
## 为独立任务配置卷
以下代码段显示配置 Amazon EBS 卷以附加到独立任务的语法。以下 JSON 代码段显示配置 `volumeType`、`sizeInGiB`、`encrypted` 和 `kmsKeyId` 设置的语法。JSON 文件中指定的配置用于创建 EBS 卷并将其附加到独立任务。
```
{
"cluster": "mycluster",
"taskDefinition": "mytaskdef",
"volumeConfigurations": [
{
"name": "datadir",
"managedEBSVolume": {
"volumeType": "gp3",
"sizeInGiB": 100,
"roleArn":"arn:aws:iam::1111222333:role/ecsInfrastructureRole",
"encrypted": true,
"kmsKeyId": "arn:aws:kms:region:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
}
]
}
```
## 在创建服务时配置卷
以下代码段显示配置 Amazon EBS 卷以附加到服务管理的任务的语法。卷来自使用 `snapshotId` 参数指定的快照，速率为 200 MiB/s。JSON 文件中指定的配置用于创建 EBS 卷并将其附加到服务管理的每个任务。
```
{
"cluster": "mycluster",
"taskDefinition": "mytaskdef",
"serviceName": "mysvc",
"desiredCount": 2,
"volumeConfigurations": [
{
"name": "myEbsVolume",
"managedEBSVolume": {
"roleArn":"arn:aws:iam::1111222333:role/ecsInfrastructureRole",
"snapshotId": "snap-12345",
"volumeInitializationRate": 200
}
}
]
}
```
## 在更新服务时配置卷
以下 JSON 代码段显示更新以前未将 Amazon EBS 卷配置为附加到任务的服务的语法。您必须提供任务定义修订的 ARN，其 `configuredAtLaunch` 被设置为 `true`。以下 JSON 代码段显示配置 `volumeType`、`sizeInGiB`、`throughput` 和 `iops` 以及 `filesystemType` 设置的语法。此配置用于创建 EBS 卷并将其附加到服务管理的每个任务。
```
{
"cluster": "mycluster",
"taskDefinition": "mytaskdef",
"service": "mysvc",
"desiredCount": 2,
"volumeConfigurations": [
{
"name": "myEbsVolume",
"managedEBSVolume": {
"roleArn":"arn:aws:iam::1111222333:role/ecsInfrastructureRole",
"volumeType": "gp3",
"sizeInGiB": 100,
"iops": 3000,
"throughput": 125,
"filesystemType": "ext4"
}
}
]
}
```
### 将服务配置为不再利用 Amazon EBS 卷
以下 JSON 代码段显示更新服务以不再利用 Amazon EBS 卷的语法。您必须提供 `configuredAtLaunch` 被设置为 `false` 的任务定义的 ARN，或者不带 `configuredAtLaunch` 参数的任务定义。您还必须提供一个空的 `volumeConfigurations` 对象。
```
{
"cluster": "mycluster",
"taskDefinition": "mytaskdef",
"service": "mysvc",
"desiredCount": 2,
"volumeConfigurations": []
}
```
## Amazon EBS 卷的终止策略
当 Amazon ECS 任务终止时，Amazon ECS 使用 `deleteOnTermination` 值来确定是否应删除与已终止的任务关联的 Amazon EBS 卷。默认情况下，任务终止时，将会删除附加到任务的 EBS 卷。对于独立任务，您可以更改此设置，改为在任务终止时保留卷。
**注意**
附加到由服务管理的任务的卷不会被保留，并且总是会在任务终止时被删除。
## 标记 Amazon EBS 卷
您可以使用 `tagSpecifications` 对象标记 Amazon EBS 卷。使用该对象，您可以提供自己的标签，并从任务定义或服务中设置标签的传播，具体取决于卷是附加到一项独立任务还是附加到服务中的某项任务。可以附加到一个卷上的最大标签数为 50。
**重要**
Amazon ECS 会自动将保留的 `AmazonECSCreated` 和 `AmazonECSManaged` 标签附加到 Amazon EBS 卷中。这意味着您可以控制最多将 48 个其他标签附加到卷的情况。这些附加标签可以是用户定义的、ECS 管理的或传播的标签。
如果您想向卷中添加 Amazon ECS 托管的标签，则必须在 `UpdateService`、`CreateService`、`RunTask` 或 `StartTask` 调用中将 `enableECSManagedTags` 设置为 `true`。如果您启用 Amazon ECS 管理的标签，Amazon ECS 将使用集群和服务信息（`aws:ecs:clusterName` 和 `aws:ecs:serviceName`）自动标记卷。有关标记 Amazon ECS 源的更多信息，请参阅[标记 Amazon ECS 资源](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-using-tags.html)。
以下 JSON 代码段显示使用用户定义的标签标记附加到服务中每个任务的每个 Amazon EBS 卷的语法。要使用此示例创建服务，请将 `user input placeholders` 替换为您自己的信息。
```
{
"cluster": "mycluster",
"taskDefinition": "mytaskdef",
"serviceName": "mysvc",
"desiredCount": 2,
"enableECSManagedTags": true,
"volumeConfigurations": [
{
"name": "datadir",
"managedEBSVolume": {
"volumeType": "gp3",
"sizeInGiB": 100,
"tagSpecifications": [
{
"resourceType": "volume",
"tags": [
{
"key": "key1",
"value": "value1"
}
],
"propagateTags": "NONE"
}
],
"roleArn":"arn:aws:iam:1111222333:role/ecsInfrastructureRole",
"encrypted": true,
"kmsKeyId": "arn:aws:kms:region:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
}
]
}
```
**重要**
您必须指定 `volume` 资源类型来标记 Amazon EBS 卷。