# Amazon ECS タスク定義のユースケース
<a name="use-cases"></a>

さまざまな AWS のサービスや機能のタスク定義を作成する方法を説明します。

ワークロードによっては、設定を要するいくつかのタスク定義パラメータがあります。また、EC2 では、そのワークロード用に設計された特定のインスタンスを選択する必要があります。

**Topics**
+ [GPU ワークロード向けの Amazon ECS タスク定義](ecs-gpu.md)
+ [動画トランスコーディングワークロードでの Amazon ECS タスク定義](ecs-vt1.md)
+ [AWS Neuron 機械学習ワークロードでの Amazon ECS タスク定義](ecs-inference.md)
+ [深層学習インスタンスでの Amazon ECS タスク定義](ecs-dl1.md)
+ [64 ビット ARM ワークロードでの Amazon ECS タスク定義](ecs-arm64.md)
+ [Amazon ECS ログを CloudWatch に送信する](using_awslogs.md)
+ [Amazon ECS ログを AWS サービスまたは AWS Partner に送信する](using_firelens.md)
+ [Amazon ECS での AWS 以外のコンテナイメージの使用](private-auth.md)
+ [コンテナ再起動ポリシーを使用して Amazon ECS タスク内の個々のコンテナを再起動する](container-restart-policy.md)
+ [Amazon ECS コンテナに機密データを渡す](specifying-sensitive-data.md)

# GPU ワークロード向けの Amazon ECS タスク定義
<a name="ecs-gpu"></a>

GPU 対応コンテナインスタンスを使用してクラスターを作成することで、GPU を使用するワークロードが Amazon ECS でサポートされます。p2、p3、p5、g3、g4、g5 のインスタンスタイプを使用する、Amazon EC2 GPU ベースのコンテナインスタンスでは、NVIDIA GPU へのアクセスが可能です。詳細については、「*Amazon EC2 インスタンスタイプガイド*」の「[Linux Accelerated Computing Instances](https://docs.aws.amazon.com/ec2/latest/instancetypes/ac.html)」を参照してください。

Amazon ECS には、事前設定された NVIDIA カーネルドライバーと Docker GPU ランタイムが付属する、GPU 最適化 AMI が用意されています。詳細については、「[Amazon ECS に最適化された Linux AMI](ecs-optimized_AMI.md)」を参照してください。

コンテナレベルのタスク配置のために、タスク定義でいくつかの GPU を指定できます。Amazon ECS は、使用が可能で GPU をサポートしているコンテナインスタンスをスケジュールし、物理的 GPU を適切なコンテナに固定して最適なパフォーマンスを実現します。

以下の Amazon EC2 GPU ベースのインスタンスタイプがサポートされています。詳細については、「[Amazon EC2 P2 インスタンス](https://aws.amazon.com/ec2/instance-types/p2/)」、「[Amazon EC2 P3 インスタンス](https://aws.amazon.com/ec2/instance-types/p3/)」、「[Amazon EC2 P4d インスタンス](https://aws.amazon.com/ec2/instance-types/p4/)」、「[Amazon EC2 P5 インスタンス](https://aws.amazon.com/ec2/instance-types/p5/)」、「[Amazon EC2 G3 インスタンス](https://aws.amazon.com/ec2/instance-types/g3/)」、「[Amazon EC2 G4 インスタンス](https://aws.amazon.com/ec2/instance-types/g4/)」、「[Amazon EC2 G5 インスタンス](https://aws.amazon.com/ec2/instance-types/g5/)」、「[Amazon EC2 G6 インスタンス](https://aws.amazon.com/ec2/instance-types/g6/)」、「[Amazon EC2 G6e Instances](https://aws.amazon.com/ec2/instance-types/g6e/)」を参照してください。


|  インスタンスタイプ  |  GPU  |  GPU メモリ (GiB)  |  vCPU  |  メモリ (GiB)  | 
| --- | --- | --- | --- | --- | 
|  p3.2xlarge  |  1  |  16  |  8  |  61  | 
|  p3.8xlarge  |  4  |  64  |  32  |  244  | 
|  p3.16xlarge  |  8  |  128  |  64  |  488  | 
|  p3dn.24xlarge  |  8  |  256  |  96  |  768  | 
|  p4d.24xlarge  | 8 | 320 | 96 | 1152 | 
| p5.48xlarge | 8 | 640 | 192 | 2048 | 
|  g3s.xlarge  |  1  |  8  |  4  |  30.5  | 
|  g3.4xlarge  |  1  |  8  |  16  |  122  | 
|  g3.8xlarge  |  2  |  16  |  32  |  244  | 
|  g3.16xlarge  |  4  |  32  |  64  |  488  | 
|  g4dn.xlarge  |  1  |  16  |  4  |  16  | 
|  g4dn.2xlarge  |  1  |  16  |  8  |  32  | 
|  g4dn.4xlarge  |  1  |  16  |  16  |  64  | 
|  g4dn.8xlarge  |  1  |  16  |  32  |  128  | 
|  g4dn.12xlarge  |  4  |  64  |  48  |  192  | 
|  g4dn.16xlarge  |  1  |  16  |  64  |  256  | 
|  g5.xlarge  |  1  |  24  |  4  |  16  | 
|  g5.2xlarge  |  1  |  24  |  8  |  32  | 
|  g5.4xlarge  |  1  |  24  |  16  |  64  | 
|  g5.8xlarge  |  1  |  24  |  32  |  128  | 
|  g5.16xlarge  |  1  |  24  |  64  |  256  | 
|  g5.12xlarge  |  4  |  96  |  48  |  192  | 
|  g5.24xlarge  |  4  |  96  |  96  |  384  | 
|  g5.48xlarge  |  8  |  192  |  192  |  768  | 
| g6.xlarge | 1 | 24 | 4 | 16 | 
| g6.2xlarge | 1 | 24 | 8 | 32 | 
| g6.4xlarge | 1 | 24 | 16 | 64 | 
| g6.8xlarge | 1 | 24 | 32 | 128 | 
| g6.16.xlarge | 1 | 24 | 64 | 256 | 
| g6.12xlarge | 4 | 96 | 48 | 192 | 
| g6.24xlarge | 4 | 96 | 96 | 384 | 
| g6.48xlarge | 8 | 192 | 192 | 768 | 
| g6.metal | 8 | 192 | 192 | 768 | 
| gr6.4xlarge | 1 | 24 | 16 | 128 | 
| g6e.xlarge | 1 | 48 | 4 | 32 | 
| g6e.2xlarge | 1 | 48 | 8 | 64 | 
| g6e.4xlarge | 1 | 48 | 16 | 128 | 
| g6e.8xlarge | 1 | 48 | 32 | 256 | 
| g6e16.xlarge | 1 | 48 | 64 | 512 | 
| g6e12.xlarge | 4 | 192 | 48 | 384 | 
| g6e24.xlarge | 4 | 192 | 96 | 768 | 
| g6e48.xlarge | 8 | 384 | 192 | 1536 | 
| gr6.8xlarge | 1 | 24 | 32 | 256 | 

AWS Systems Manager パラメータストア API をクエリすることで、Amazon ECS に最適化された AMI の Amazon マシンイメージ (AMI) ID を取得できます。このパラメータを使用することで、Amazon ECS 最適化 AMI ID を手動で検索する必要がなくなります。Systems Manager Parameter Store API の詳細については、[GetParameter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html) を参照してください。使用するユーザーには、Amazon ECS 最適化 AMI メタデータを取得するための `ssm:GetParameter` IAM 許可が必要です。

```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended --region us-east-1
```

# Amazon ECS マネージドインスタンスで GPU を使用する
<a name="managed-instances-gpu"></a>

Amazon ECS マネージドインスタンスは、次の Amazon EC2 インスタンスタイプを通じて、機械学習、高性能コンピューティング、ビデオ処理などのワークロードに対して GPU アクセラレーションコンピューティングをサポートしています。Amazon ECS マネージドインスタンスが対応するインスタンスタイプについて、詳しくは「[Amazon ECS マネージドインスタンスのインスタンスタイプ](managed-instances-instance-types.md)」を参照してください。

以下は、Amazon ECS マネージドインスタンスでサポートされている GPU ベースのインスタンスタイプのサブセットです。
+ `g4dn`: NVIDIA T4 GPUs を利用し、機械学習の推論、コンピュータビジョン、グラフィックを多用するアプリケーションに適しています。
+ `g5`: NVIDIA A10G GPUs を利用し、グラフィックスを多用するアプリケーションや機械学習ワークロードでより高いパフォーマンスを提供します。
+ `p3`: NVIDIA V100 GPUs を利用し、高性能コンピューティングと深層学習トレーニングに適しています。
+ `p4d`: NVIDIA A100 GPUs を利用し、機械学習トレーニングとハイパフォーマンスコンピューティングを支援します。

Amazon ECS マネージドインスタンスで GPU 対応インスタンスタイプを使用すると、NVIDIA ドライバーと CUDA ツールキットがインスタンスに事前にインストールされるため、GPU 対応ワークロードの実行が容易になります。

## GPU 対応インスタンスの選択
<a name="managed-instances-gpu-instance-selection"></a>

Amazon ECS マネージドインスタンスワークロードの GPU 対応インスタンスタイプを選択するには、キャパシティプロバイダーの起動テンプレートで `instanceRequirements` オブジェクトを使用します。次のスニペットは、GPU 対応インスタンスの選択に使用できる属性を示しています。

```
{
  "instanceRequirements": {
    "acceleratorTypes": "gpu",
    "acceleratorCount": 1,
    "acceleratorManufacturers": ["nvidia"]
  }
}
```

次のスニペットは、起動テンプレートで GPU 対応インスタンスタイプを指定するために使用できる属性を示しています。

```
{
  "instanceRequirements": {
    "allowedInstanceTypes": ["g4dn.xlarge", "p4de.24xlarge"]
  }
}
```

## GPU 対応コンテナイメージ
<a name="managed-instances-gpu-container-images"></a>

コンテナで GPUs を使用するには、必要な GPU ライブラリとツールを含むコンテナイメージを使用する必要があります。NVIDIA には、GPU ワークロードのベースとして使用できるいくつかの構築済みコンテナイメージが用意されています。
+ `nvidia:cuda`: GPU コンピューティング用の CUDA ツールキットを使用したベースイメージ。
+ `tensorflow/tensorflow:latest-gpu`: GPU 対応の TensorFlow。
+ `pytorch/pytorch:latest-cuda`: GPU 対応の PyTorch。

GPU を使用した Amazon ECS マネージドインスタンスのタスク定義サンプルは「[Amazon ECS タスク定義での GPU の指定](ecs-gpu-specifying.md)」を参照してください。

## 考慮事項
<a name="gpu-considerations"></a>

**注記**  
g2 インスタンスファミリータイプのサポートは廃止されました。  
p2 インスタンスファミリータイプは、バージョン `20230912` より前の Amazon ECS GPU 最適化 AMI でのみサポートされています。引き続き p2 インスタンスを使用する必要がある場合は、[P2 インスタンスが必要な場合の対処方法](#p2-instance) を参照してください。  
これら両方のインスタンスファミリータイプで NVIDIA/CUDA ドライバーをインプレース更新すると、GPU ワークロードに障害が発生する可能性があります。

Amazon ECS で GPU の使用を開始する前に、以下について検討することをお勧めします。
+ クラスターには、GPU 対応コンテナインスタンスと GPU 非対応コンテナインスタンスを混在させることができます。
+ GPU ワークロードは外部インスタンスでの実行が可能です。外部インスタンスをクラスターに登録するときは、`--enable-gpu` フラグがインストールスクリプトに含まれていることを確認してください。詳細については、「[Amazon ECS クラスターに外部インスタンスを登録する](ecs-anywhere-registration.md)」を参照してください。
+ エージェント設定ファイルで `ECS_ENABLE_GPU_SUPPORT` を `true` に設定する必要があります。詳細については、「[Amazon ECS コンテナエージェントの設定](ecs-agent-config.md)」を参照してください。
+ タスクの実行時またはサービスの作成時に、インスタンスタイプ属性を使用してタスク配置制約を設定することで、タスクが起動されるコンテナインスタンスを指定できます。これにより、リソースをより効果的に使用できます。詳細については、「[Amazon ECS がタスクをコンテナインスタンスに配置する方法](task-placement.md)」を参照してください。

  以下の例では、デフォルトクラスター内の `g4dn.xlarge` コンテナインスタンスでタスクを起動しています。

  ```
  aws ecs run-task --cluster default --task-definition ecs-gpu-task-def \
       --placement-constraints type=memberOf,expression="attribute:ecs.instance-type ==  g4dn.xlarge" --region us-east-2
  ```
+ Amazon ECS は、コンテナ定義で指定された GPU リソース要件が適用されるコンテナごとに、コンテナランタイムとして NVIDIA のコンテナランタイムが使用されるように設定します。
+ NVIDIA コンテナランタイムが適切に機能するためには、コンテナにいくつかの環境変数を設定する必要があります。これらの環境変数のリストについては、「[Docker を使用した特殊設定](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html?highlight=environment%20variable)」を参照してください。Amazon ECS は、`NVIDIA_VISIBLE_DEVICES`環境変数の値を Amazon ECS がコンテナに割り当てる GPU デバイス ID のリストに設定します。Amazon ECS は、これら以外の必須環境変数の設定は行いません。そのため、これらの必須変数がコンテナイメージで設定されていること、あるいはコンテナ定義内で設定されていることを確認する必要があります。
+ p5 インスタンスタイプファミリーは、バージョン `20230929` 以降の Amazon ECS GPU 最適化 AMI でサポートされています。
+ g4 インスタンスタイプファミリーは、バージョン `20230913` 以降の Amazon ECS GPU 最適化 AMI でサポートされています。詳細については、「[Amazon ECS に最適化された Linux AMI](ecs-optimized_AMI.md)」を参照してください。Amazon ECS コンソールのクラスター作成ワークフローではサポートされていません。これらのインスタンスタイプを使用するには、Amazon EC2 コンソール、AWS CLI、または API を使用して、手動でインスタンスをクラスターに登録する必要があります。
+ p4d.24xlarge インスタンスタイプは、CUDA 11 以降でのみ動作します。
+ Amazon ECS GPU 最適化 AMI は IPv6 が有効になっているため、`yum` を使用するとき問題が生じます。これは、以下のコマンドで IPv4 を使用するように `yum` を構成することで解決できます。

  ```
  echo "ip_resolve=4" >> /etc/yum.conf
  ```
+  NVIDIA/CUDA ベースのイメージを使用しないコンテナイメージをビルドする場合は、`NVIDIA_DRIVER_CAPABILITIES` コンテナランタイム変数に以下のいずれかの値を設定します。
  + `utility,compute`
  + `all`

  変数の設定方法については、NVIDIA の Web サイトの「[NVIDIA コンテナランタイムの制御](https://sarus.readthedocs.io/en/stable/user/custom-cuda-images.html#controlling-the-nvidia-container-runtime)」を参照してください。
+ Windows コンテナでは、GPU はサポートされません。

# Amazon ECS 向け GPU コンテナインスタンスの起動
<a name="gpu-launch"></a>

Amazon EC2 上で Amazon ECS の GPU インスタンスを使用するには、起動テンプレートとユーザーデータファイルを作成し、インスタンスを起動する必要があります。

これにより、GPU 用に設定されたタスク定義を使用するタスクを実行できます。

## 起動テンプレートを使用する
<a name="gpu-launch-template"></a>

起動テンプレートを作成します。
+ Amazon ECS に最適化された AMI 用の GPU AMI ID を使用する起動テンプレートを作成してください。起動テンプレートの作成方法について、詳しくは「*Amazon EC2 ユーザーガイド*」の「[Create a new launch template using parameters you define](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-launch-template.html#create-launch-template-define-parameters)」を参照してください。

  **[Amazon マシンイメージ]** には、前のステップの AMI ID を使用します。Systems Manager パラメータで AMI ID を指定する方法については、「*Amazon EC2 ユーザーガイド*」の「[Specify a Systems Manager parameter in a launch template](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-launch-template.html#use-an-ssm-parameter-instead-of-an-ami-id)」を参照してください。

  起動テンプレートの **[ユーザーデータ]** に以下を追加します。*cluster-name* をクラスターの名前に置き換えます。

  ```
  #!/bin/bash
  echo ECS_CLUSTER=cluster-name >> /etc/ecs/ecs.config;
  echo ECS_ENABLE_GPU_SUPPORT=true >> /etc/ecs/ecs.config
  ```

## AWS CLI の使用
<a name="gpu-launch-cli"></a>

AWS CLI を使用して、コンテナインスタンスを起動できます。

1. `userdata.toml` というファイルを作成します。このファイルは、インスタンスのユーザーデータに使用されます。*cluster-name* をクラスターの名前に置き換えます。

   ```
   #!/bin/bash
   echo ECS_CLUSTER=cluster-name >> /etc/ecs/ecs.config;
   echo ECS_ENABLE_GPU_SUPPORT=true >> /etc/ecs/ecs.config
   ```

1. 次のコマンドを実行して、GPU AMI ID を取得します。これは次のステップで使用します。

   ```
   aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended --region us-east-1
   ```

1. 次のコマンドを実行して、GPU インスタンスを起動します。次のパラメータを必ず置き換えてください。
   + *subnet* を、インスタンスを起動するプライベートまたはパブリックサブネットの ID に置き換えます。
   + *gpu\$1ami* を、前のステップの AMI ID に置き換えます。
   + *t3.large* を、使用するインスタンスタイプに置き換えます。
   + *region* を、リージョンコードに置き換えます。

   ```
   aws ec2 run-instances --key-name ecs-gpu-example \
      --subnet-id subnet \
      --image-id gpu_ami \
      --instance-type t3.large \
      --region region \
      --tag-specifications 'ResourceType=instance,Tags=[{Key=GPU,Value=example}]' \
      --user-data file://userdata.toml \
      --iam-instance-profile Name=ecsInstanceRole
   ```

1. 次のコマンドを実行して、コンテナインスタンスがクラスターに登録されていることを検証します。このコマンドを実行するときは、次のパラメータを必ず置き換えてください。
   + *cluster* を、自分のクラスター名に置き換えます。
   + *region* を、リージョンコードに置き換えます。

   ```
   aws ecs list-container-instances --cluster cluster-name --region region
   ```

# Amazon ECS タスク定義での GPU の指定
<a name="ecs-gpu-specifying"></a>

コンテナインスタンス上の GPU と Docker GPU ランタイムを利用するには、コンテナに必要な GPU の数をタスク定義内で必ず指定します。GPU をサポートするコンテナが配置されると、Amazon ECS コンテナエージェントは必要な数の物理 GPU を適切なコンテナに固定します。タスク内でコンテナ用に予約されている、すべての GPU の数は、タスクが起動されたコンテナインスタンスで使用できる GPU の数を超えることはできません。詳細については、「[コンソールを使用した Amazon ECS タスク定義の作成](create-task-definition.md)」を参照してください。

**重要**  
GPU 要件をタスク定義で指定していない場合、タスクではデフォルトの Docker ランタイムが使用されます。

タスク定義での GPU 要件の JSON 形式は以下のとおりです。

```
{
  "containerDefinitions": [
     {
        ...
        "resourceRequirements" : [
            {
               "type" : "GPU", 
               "value" : "2"
            }
        ],
     },
...
}
```

以下の例では、GPU 要件を指定する Docker コンテナの構文を示しています。このコンテナは 2 つの GPU を使用しており、`nvidia-smi` ユーティリティを実行した後に終了します。

```
{
  "containerDefinitions": [
    {
      "memory": 80,
      "essential": true,
      "name": "gpu",
      "image": "nvidia/cuda:11.0.3-base",
      "resourceRequirements": [
         {
           "type":"GPU",
           "value": "2"
         }
      ],
      "command": [
        "sh",
        "-c",
        "nvidia-smi"
      ],
      "cpu": 100
    }
  ],
  "family": "example-ecs-gpu"
}
```

次のタスク定義の例は、使用可能な GPU 数を出力する TensorFlow コンテナを示しています。タスクは Amazon ECS マネージドインスタンスで実行され、1 つの GPU が必要で、`g4dn.xlarge` インスタンスを使用します。

```
{
  "family": "tensorflow-gpu",
  "networkMode": "awsvpc",
  "executionRoleArn": "arn:aws:iam::account-id:role/ecsTaskExecutionRole",
  "containerDefinitions": [
    {
      "name": "tensorflow",
      "image": "tensorflow/tensorflow:latest-gpu",
      "essential": true,
      "command": [
        "python",
        "-c",
        "import tensorflow as tf; print('Num GPUs Available: ', len(tf.config.list_physical_devices('GPU')))"
      ],
      "resourceRequirements": [
        {
          "type": "GPU",
          "value": "1"
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/tensorflow-gpu",
          "awslogs-region": "region",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ],
  "requiresCompatibilities": [
    "MANAGED_INSTANCES"
  ],
  "cpu": "4096",
  "memory": "8192",
}
```

## GPU の共有
<a name="share-gpu"></a>

GPU を共有する場合は、以下を設定する必要があります。

1. タスク定義から GPU リソース要件を削除して、Amazon ECS が共有する必要がある GPU を予約しないようにします。

1. GPU を共有する場合は、次のユーザーデータをインスタンスに追加します。これにより、NVIDIA がコンテナインスタンスのデフォルトの Docker コンテナランタイムになり、すべての Amazon ECS コンテナが GPU を使用できるようになります。詳細については、「*Amazon EC2 ユーザーガイド*」の「[ユーザーデータ入力を使用して EC2 インスタンスを起動するときにコマンドを実行する](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html)」を参照してください。

   ```
   const userData = ec2.UserData.forLinux();
    userData.addCommands(
    'sudo rm /etc/sysconfig/docker',
    'echo DAEMON_MAXFILES=1048576 | sudo tee -a /etc/sysconfig/docker',
    'echo OPTIONS="--default-ulimit nofile=32768:65536 --default-runtime nvidia" | sudo tee -a /etc/sysconfig/docker',
    'echo DAEMON_PIDFILE_TIMEOUT=10 | sudo tee -a /etc/sysconfig/docker',
    'sudo systemctl restart docker',
   );
   ```

1. コンテナに `NVIDIA_VISIBLE_DEVICES` 環境変数を設定します。これを行うには、タスク定義内で環境変数を設定します。有効な値の詳細については、NVIDIA ドキュメントサイトの「[GPU 列挙](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html#gpu-enumeration)」を参照してください。

## P2 インスタンスが必要な場合の対処方法
<a name="p2-instance"></a>

P2 インスタンスを使用する必要がある場合、次のいずれかのオプションを使用してインスタンスを使用し続けることができます。

どちらのオプションでも、インスタンスユーザーデータを変更する必要があります。詳細については、「*Amazon EC2 ユーザーガイド*」の「[ユーザーデータ入力を使用して EC2 インスタンスを起動するときにコマンドを実行する](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html)」を参照してください。

**サポートされている最新の GPU 最適化 AMI を使用する**

GPU に最適化された AMI の `20230906` バージョンを使用して、インスタンスのユーザーデータに以下を追加できます。

cluster-name をクラスターの名前に置き換えます。

```
#!/bin/bash
echo "exclude=*nvidia* *cuda*" >> /etc/yum.conf
echo "ECS_CLUSTER=cluster-name" >> /etc/ecs/ecs.config
```

**GPU に最適化された最新の AMI を使用し、ユーザーデータを更新する**

以下をインスタンスのユーザーデータに追加します。これにより Nvidia 535/Cuda12.2 ドライバーがアンインストールされ、次に Nvidia 470/Cuda11.4 ドライバーがインストールされ、バージョンが修正されます。

```
#!/bin/bash
yum remove -y cuda-toolkit* nvidia-driver-latest-dkms*
tmpfile=$(mktemp)
cat >$tmpfile <<EOF
[amzn2-nvidia]
name=Amazon Linux 2 Nvidia repository
mirrorlist=\$awsproto://\$amazonlinux.\$awsregion.\$awsdomain/\$releasever/amzn2-nvidia/latest/\$basearch/mirror.list
priority=20
gpgcheck=1
gpgkey=https://developer.download.nvidia.com/compute/cuda/repos/rhel7/x86_64/7fa2af80.pub
enabled=1
exclude=libglvnd-*
EOF

mv $tmpfile /etc/yum.repos.d/amzn2-nvidia-tmp.repo
yum install -y system-release-nvidia cuda-toolkit-11-4 nvidia-driver-latest-dkms-470.182.03
yum install -y libnvidia-container-1.4.0 libnvidia-container-tools-1.4.0 nvidia-container-runtime-hook-1.4.0 docker-runtime-nvidia-1

echo "exclude=*nvidia* *cuda*" >> /etc/yum.conf
nvidia-smi
```

**P2 と互換性のある GPU に最適化された独自の AMI を作成する**

P2 インスタンスと互換性のある独自の Amazon ECS GPU 最適化 AMI を作成し、その AMI を使用して P2 インスタンスを起動できます。

1. 次のコマンドを実行して `amazon-ecs-ami repo` をクローンします。

   ```
   git clone https://github.com/aws/amazon-ecs-ami
   ```

1. 必要な Amazon ECS エージェントとソースの Amazon Linux AMI バージョンを `release.auto.pkrvars.hcl` または `overrides.auto.pkrvars.hcl` に設定します。

1. P2 と互換性のあるプライベート EC2 AMI を構築するには、次のコマンドを実行します。

   リージョンをインスタンスリージョンがあるリージョンに置き換えます。

   ```
   REGION=region make al2keplergpu
   ```

1. 以下のインスタンスユーザーデータを含む AMI を使用して Amazon ECS クラスターに接続します。

   cluster-name をクラスターの名前に置き換えます。

   ```
   #!/bin/bash
   echo "ECS_CLUSTER=cluster-name" >> /etc/ecs/ecs.config
   ```

# 動画トランスコーディングワークロードでの Amazon ECS タスク定義
<a name="ecs-vt1"></a>

Amazon ECS で動画トランスコーディングワークロードを使用するには、[Amazon EC2 VT1](https://aws.amazon.com/ec2/instance-types/vt1/) インスタンスを登録します。これらのインスタンスを登録した後は、事前レンダリングされたライブ動画のトランスコーディングワークロードを、Amazon ECS タスクとして実行できます。Amazon EC2 VT1 インスタンスは、Xilinx U30 メディアトランスコーディングカードを使用して、事前レンダリングされたライブ動画のトランスコーディングワークロードを高速化します。

**注記**  
Amazon ECS 以外のコンテナで動画トランスコーディングワークロードを実行する方法については、[Xilinx のドキュメント](https://xilinx.github.io/video-sdk/v1.5/container_setup.html#working-with-docker-vt1)を参照してください。

## 考慮事項
<a name="ecs-vt1-considerations"></a>

Amazon ECS で VT1 のデプロイを開始する前に、以下の点を考慮してください。
+ クラスターには、VT1 コンテナインスタンスと VT1 以外のインスタンスを混在させることができます。
+ アクセラレータ付きの AVC (H.264) および HEVC (H.265) コーデックを備えた、Xilinx U30 メディアトランスコーディングカードを使用する Linux アプリケーションが必要です。
**重要**  
他のコーデックを使用するアプリケーションでは、VT1 インスタンスのパフォーマンスが強化されていない場合があります。
+ U30 カードでは、トランスコーディングタスクを 1 つのみ実行できます。各カードには、2 つのデバイスが関連付けられています。VT1 インスタンスごとに、使用しているカードの数だけのトランスコーディングタスクを実行できます。
+ サービスの作成時、またはスタンドアロンタスクの実行時に、インスタンスタイプ属性を使用してタスク配置制約を設定することができます。これにより、指定したコンテナインスタンスでタスクが起動されることを保証します。また、リソースを効果的に使用し、動画トランスコーディングワークロードのタスクが VT1 インスタンスに配置されるようにすることができます。詳細については、「[Amazon ECS がタスクをコンテナインスタンスに配置する方法](task-placement.md)」を参照してください。

  次の例では、タスクが`default` クラスターの `vt1.3xlarge` インスタンス上で実行されます。

  ```
  aws ecs run-task \
       --cluster default \
       --task-definition vt1-3xlarge-xffmpeg-processor \
       --placement-constraints type=memberOf,expression="attribute:ecs.instance-type == vt1.3xlarge"
  ```
+ ホストコンテナインスタンス向けに用意された、特定の U30 カードを使用するようにコンテナを設定します。これを行うには、`linuxParameters` パラメータによりデバイスの詳細を指定します。詳細については、「[タスク定義の要件](#ecs-vt1-requirements)」を参照してください。

## VT1 AMI の使用
<a name="ecs-vt1-ami"></a>

Amazon ECS コンテナインスタンス用 Amazon EC2 上で AMI を実行するには、2 つのオプションがあります。1 番目のオプションは、AWS Marketplace にある Xilinx 公式 AMI を使用することです。2 番目のオプションは、サンプルのリポジトリを利用して、独自の AMI を構築することです。
+ [Xilinx は、AWS Marketplace に AMI を提供しています](https://aws.amazon.com/marketplace/pp/prodview-phvk6d4mq3hh6)。
+ Amazon ECS は、動画トランスコーディングワークロード用の AMI を構築するために使用できる、サンプルのリポジトリを提供しています。この AMI には Xilinx U30 ドライバー備わります。[GitHub](https://github.com/aws-samples/aws-vt-baseami-pipeline) で、Packer スクリプトを含むリポジトリを入手できます。Packer の詳細については、「[Packer documentation](https://developer.hashicorp.com/packer/docs)」(Packer ドキュメント) を参照してください。

## タスク定義の要件
<a name="ecs-vt1-requirements"></a>

Amazon ECS で動画トランスコーディングコンテナを実行するには、アクセラレータ付きの H.264/AVC および H.265/HEVC コーデックを使用する動画トランスコーディングアプリケーションが、タスク定義に含まれている必要があります。[Xilinx GitHub](https://xilinx.github.io/video-sdk/v1.5/container_setup.html#creating-a-docker-image-for-vt1-usage) の手順に従うことで、コンテナイメージを構築できます。

タスク定義は、インスタンスタイプに固有である必要があります。これらのインスタンスタイプは、3xlarge、6xlarge、および 24xlarge です。コンテナでは、ホストコンテナインスタンス向けに用意された、特定の Xilinx U30 デバイスの使用を設定する必要があります。これは、`linuxParameters` パラメータを使用して設定します。次の表に、各インスタンスタイプに固有のカードとデバイス SoC の詳細を示します。


| インスタンスタイプ | vCPU | RAM (GiB) | U30 アクセラレータカード | アドレス可能な XCU30 SoC デバイス | デバイスへのパス | 
| --- | --- | --- | --- | --- | --- | 
| vt1.3xlarge | 12 | 24 | 1 | 2 | /dev/dri/renderD128,/dev/dri/renderD129 | 
| vt1.6xlarge | 24 | 48 | 2 | 4 | /dev/dri/renderD128,/dev/dri/renderD129,/dev/dri/renderD130,/dev/dri/renderD131 | 
| vt1.24xlarge | 96 | 182 | 8 | 16 | /dev/dri/renderD128,/dev/dri/renderD129,/dev/dri/renderD130,/dev/dri/renderD131,/dev/dri/renderD132,/dev/dri/renderD133,/dev/dri/renderD134,/dev/dri/renderD135,/dev/dri/renderD136,/dev/dri/renderD137,/dev/dri/renderD138,/dev/dri/renderD139,/dev/dri/renderD140,/dev/dri/renderD141,/dev/dri/renderD142,/dev/dri/renderD143 | 

**重要**  
タスク定義に EC2 インスタンスにないデバイスがリストされている場合、タスクの実行は失敗します。タスクが失敗した場合は、`stoppedReason` にエラーメッセージ `CannotStartContainerError: Error response from daemon: error gathering device information while adding custom device "/dev/dri/renderD130": no such file or directory` が表示されます。

# Amazon ECS タスク定義での動画トランスコーディングの指定
<a name="task-def-video-transcode"></a>

次の例に、Amazon EC2 の Linux コンテナのタスク定義に使用される構文を示します。このタスク定義は、「[Xilinx documentation](https://xilinx.github.io/video-sdk/v1.5/container_setup.html#creating-a-docker-image-for-vt1-usage)」(Xilinx のドキュメント) で説明されている手順により構築されるコンテナイメージ用です。この例を使用する場合は、`image` を独自のイメージで置き換え、`/home/ec2-user` ディレクトリにあるインスタンスにビデオファイルをコピーします。

------
#### [ vt1.3xlarge ]

1. `vt1-3xlarge-ffmpeg-linux.json` と言う名前で、以下の内容が記述されたテキストファイルを作成します。

   ```
   {
       "family": "vt1-3xlarge-xffmpeg-processor",
       "requiresCompatibilities": ["EC2"],
       "placementConstraints": [
           {
               "type": "memberOf",
               "expression": "attribute:ecs.os-type == linux"
           },
           {
               "type": "memberOf",
               "expression": "attribute:ecs.instance-type == vt1.3xlarge"
           }
       ],
       "containerDefinitions": [
           {
               "entryPoint": [
                   "/bin/bash",
                   "-c"
               ],
               "command": ["/video/ecs_ffmpeg_wrapper.sh"],
               "linuxParameters": {
                   "devices": [
                       {
                           "containerPath": "/dev/dri/renderD128",
                           "hostPath": "/dev/dri/renderD128",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD129",
                           "hostPath": "/dev/dri/renderD129",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       }
                   ]
               },
               "mountPoints": [
                   {
                       "containerPath": "/video",
                       "sourceVolume": "video_file"
                   }
               ],
               "cpu": 0,
               "memory": 12000,
               "image": "0123456789012.dkr.ecr.us-west-2.amazonaws.com/aws/xilinx-xffmpeg",
               "essential": true,
               "name": "xilinix-xffmpeg"
           }
       ],
       "volumes": [
           {
               "name": "video_file",
               "host": {"sourcePath": "/home/ec2-user"}
           }
       ]
   }
   ```

1. タスク定義を登録します。

   ```
   aws ecs register-task-definition --family vt1-3xlarge-xffmpeg-processor --cli-input-json file://vt1-3xlarge-xffmpeg-linux.json --region us-east-1
   ```

------
#### [ vt1.6xlarge ]

1. `vt1-6xlarge-ffmpeg-linux.json` と言う名前で、以下の内容が記述されたテキストファイルを作成します。

   ```
   {
       "family": "vt1-6xlarge-xffmpeg-processor",
       "requiresCompatibilities": ["EC2"],
       "placementConstraints": [
           {
               "type": "memberOf",
               "expression": "attribute:ecs.os-type == linux"
           },
           {
               "type": "memberOf",
               "expression": "attribute:ecs.instance-type == vt1.6xlarge"
           }
       ],
       "containerDefinitions": [
           {
               "entryPoint": [
                   "/bin/bash",
                   "-c"
               ],
               "command": ["/video/ecs_ffmpeg_wrapper.sh"],
               "linuxParameters": {
                   "devices": [
                       {
                           "containerPath": "/dev/dri/renderD128",
                           "hostPath": "/dev/dri/renderD128",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD129",
                           "hostPath": "/dev/dri/renderD129",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD130",
                           "hostPath": "/dev/dri/renderD130",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD131",
                           "hostPath": "/dev/dri/renderD131",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       }
                   ]
               },
               "mountPoints": [
                   {
                       "containerPath": "/video",
                       "sourceVolume": "video_file"
                   }
               ],
               "cpu": 0,
               "memory": 12000,
               "image": "0123456789012.dkr.ecr.us-west-2.amazonaws.com/aws/xilinx-xffmpeg",
               "essential": true,
               "name": "xilinix-xffmpeg"
           }
       ],
       "volumes": [
           {
               "name": "video_file",
               "host": {"sourcePath": "/home/ec2-user"}
           }
       ]
   }
   ```

1. タスク定義を登録します。

   ```
   aws ecs register-task-definition --family vt1-6xlarge-xffmpeg-processor --cli-input-json file://vt1-6xlarge-xffmpeg-linux.json --region us-east-1
   ```

------
#### [ vt1.24xlarge ]

1. `vt1-24xlarge-ffmpeg-linux.json` と言う名前で、以下の内容が記述されたテキストファイルを作成します。

   ```
   {
       "family": "vt1-24xlarge-xffmpeg-processor",
       "requiresCompatibilities": ["EC2"],
       "placementConstraints": [
           {
               "type": "memberOf",
               "expression": "attribute:ecs.os-type == linux"
           },
           {
               "type": "memberOf",
               "expression": "attribute:ecs.instance-type == vt1.24xlarge"
           }
       ],
       "containerDefinitions": [
           {
               "entryPoint": [
                   "/bin/bash",
                   "-c"
               ],
               "command": ["/video/ecs_ffmpeg_wrapper.sh"],
               "linuxParameters": {
                   "devices": [
                       {
                           "containerPath": "/dev/dri/renderD128",
                           "hostPath": "/dev/dri/renderD128",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD129",
                           "hostPath": "/dev/dri/renderD129",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD130",
                           "hostPath": "/dev/dri/renderD130",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD131",
                           "hostPath": "/dev/dri/renderD131",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD132",
                           "hostPath": "/dev/dri/renderD132",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD133",
                           "hostPath": "/dev/dri/renderD133",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD134",
                           "hostPath": "/dev/dri/renderD134",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD135",
                           "hostPath": "/dev/dri/renderD135",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD136",
                           "hostPath": "/dev/dri/renderD136",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD137",
                           "hostPath": "/dev/dri/renderD137",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD138",
                           "hostPath": "/dev/dri/renderD138",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD139",
                           "hostPath": "/dev/dri/renderD139",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD140",
                           "hostPath": "/dev/dri/renderD140",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD141",
                           "hostPath": "/dev/dri/renderD141",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD142",
                           "hostPath": "/dev/dri/renderD142",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       },
                       {
                           "containerPath": "/dev/dri/renderD143",
                           "hostPath": "/dev/dri/renderD143",
                           "permissions": [
                               "read",
                               "write"
                           ]
                       }
                   ]
               },
               "mountPoints": [
                   {
                       "containerPath": "/video",
                       "sourceVolume": "video_file"
                   }
               ],
               "cpu": 0,
               "memory": 12000,
               "image": "0123456789012.dkr.ecr.us-west-2.amazonaws.com/aws/xilinx-xffmpeg",
               "essential": true,
               "name": "xilinix-xffmpeg"
           }
       ],
       "volumes": [
           {
               "name": "video_file",
               "host": {"sourcePath": "/home/ec2-user"}
           }
       ]
   }
   ```

1. タスク定義を登録します。

   ```
   aws ecs register-task-definition --family vt1-24xlarge-xffmpeg-processor --cli-input-json file://vt1-24xlarge-xffmpeg-linux.json --region us-east-1
   ```

------

# AWS Neuron 機械学習ワークロードでの Amazon ECS タスク定義
<a name="ecs-inference"></a>

機械学習ワークロード用のクラスターには、[Amazon EC2 Trn1](https://aws.amazon.com/ec2/instance-types/trn1/)、[Amazon EC2 Trn2](https://aws.amazon.com/ec2/instance-types/trn2/)、[Amazon EC2 Inf1](https://aws.amazon.com/ec2/instance-types/inf1/)、および [Amazon EC2 Inf2](https://aws.amazon.com/ec2/instance-types/inf2/) インスタンスを登録できます。

Amazon EC2 Trn1 および Trn2 インスタンスには、[AWS Trainium](https://aws.amazon.com/ai/machine-learning/trainium/) チップが搭載されています。これらのインスタンスは、クラウドでの機械学習用に高性能で低コストのトレーニングを提供します。Trn1 または Trn2 インスタンスで AWS Neuron を用いる機械学習フレームワークを使用して、機械学習推論モデルをトレーニングできます。その後、Inf1 インスタンスまたは Inf2 インスタンスでモデルを実行して、AWS Inferentia チップのアクセラレーションを使用できます。

Amazon EC2 Inf1 インスタンスと Inf2 インスタンスは、[AWS Inferentia](https://aws.amazon.com/ai/machine-learning/inferentia/) チップを搭載しています。これらは、クラウドで高性能かつ最低レベルのコストの推論を提供します。

機械学習モデルは、専用の Software Developer Kit (SDK) である [AWS Neuron](https://aws.amazon.com/ai/machine-learning/neuron/) を使用してコンテナにデプロイされます。この SDK は、AWS 機械学習チップの機械学習パフォーマンスを最適化するコンパイラ、ランタイム、およびプロファイリングツールからなります。 AWSNeuron は、TensorFlow、PyTorch、Apache MXNet などの一般的な機械学習フレームワークをサポートしています。

## 考慮事項
<a name="ecs-inference-considerations"></a>

Amazon ECS での Neuron のデプロイを開始する前に、以下の点を考慮してください。
+ クラスターには、Trn1、Trn2、Inf1、Inf2、およびその他インスタンスの組み合わせを含めることができます。
+ AWS Neuron をサポートする機械学習フレームワークを使用するコンテナ内に、Linux アプリケーションが必要です。
**重要**  
他のフレームワークを使用するアプリケーションでは、Trn1、Trn2、Inf1、Inf2 インスタンスでパフォーマンスが向上しない場合があります。
+ 各 [AWS Trainium](https://aws.amazon.com/ai/machine-learning/trainium/) または [AWS Inferentia](https://aws.amazon.com/ai/machine-learning/inferentia/) チップで実行できる推論または推論トレーニングのタスクは 1 つだけです。Inf1 の場合、各チップには 4 つの NeuronCore があります。Trn1、Trn2、および Inf2 の場合、各チップに 2 つの NeuronCore があります。Trn1、Trn2、Inf1、Inf2 インスタンスごとに、チップの数だけのタスクを実行できます。
+ サービスの作成時、またはスタンドアロンタスクの実行時にタスク配置制約を設定する場合は、インスタンスタイプ属性を使用します。これにより、指定したコンテナインスタンスでタスクが起動されることを保証します。そうすることで、全体的なリソース使用率を最適化し、推論ワークロードのタスクを確実に Trn1、Trn2、Inf1、Inf2 インスタンスに配置できます。詳細については、「[Amazon ECS がタスクをコンテナインスタンスに配置する方法](task-placement.md)」を参照してください。

  次の例では、`default` クラスターの `Inf1.xlarge` インスタンスでタスクが実行されます。

  ```
  aws ecs run-task \
       --cluster default \
       --task-definition ecs-inference-task-def \
       --placement-constraints type=memberOf,expression="attribute:ecs.instance-type == Inf1.xlarge"
  ```
+ Neuron リソース要件はタスク定義で定義できません。代わりに、ホストコンテナインスタンス向けに用意された、特定の AWS Trainium または AWS Inferentia チップを使用するようコンテナを設定します。これを行うには、`linuxParameters` パラメータを使用してデバイスの詳細を指定します。詳細については、「[タスク定義の要件](#ecs-inference-requirements)」を参照してください。

## Amazon ECS に最適化された Amazon Linux 2023 (Neuron) AMI の使用
<a name="ecs-inference-ami2023"></a>

Amazon ECS では、Amazon Linux 2023 ベースの Amazon ECS 最適化 AMI が、AWS Trainium および AWS Inferentia のワークロード用に用意されています。これには、Docker 用の AWS Neuron ドライバーとランタイムが付属しています。この AMI により、Amazon ECS 上で機械学習推論ワークロードの実行が容易になります。

Amazon EC2 の Trn1、Inf1、Inf2 インスタンスを起動する際は、Amazon ECS に最適化された Amazon Linux 2023 (Neuron) AMI を使用することをお勧めします。

現在の Amazon ECS に最適化された Amazon Linux 2023 (Neuron) AMI を取得するには、AWS CLI で次のコマンドを使用します。

```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2023/neuron/recommended
```

## タスク定義の要件
<a name="ecs-inference-requirements"></a>

Amazon ECS 上に Neuron をデプロイするには、TensorFlow の推論モデルを提供するビルド済みコンテナのコンテナ定義が、タスク定義の中に含まれている必要があります。この定義は、AWS Deep Learning Containers によって提供されます。このコンテナには、AWS Neuron ランタイムと TensorFlow Serving アプリケーションが含まれています。起動時に、このコンテナは Amazon S3 からモデルを取得し、保存されたモデルを使用して Neuron TensorFlow Serving を起動した後、予測リクエストのために待機します。次の例でのコンテナイメージでは、 TensorFlow 1.15 と Ubuntu 18.04 を使用しています。Neuron 用に最適化された事前構築済みの Deep Learning Containers の完全なリストは、GitHub に保持されます。詳細については、「[AWS Neuron TensorFlow Serving の使用](https://docs.aws.amazon.com/dlami/latest/devguide/tutorial-inferentia-tf-neuron-serving.html)」を参照してください。

```
763104351884.dkr.ecr.us-east-1.amazonaws.com/tensorflow-inference-neuron:1.15.4-neuron-py37-ubuntu18.04
```

または、独自の Neuron サイドカーコンテナイメージを構築することもできます。詳細は「*AWS Deep Learning AMIs デベロッパーガイド*」の「[チュートリアル: Neuron TensorFlow Serving](https://github.com/aws-neuron/aws-neuron-sdk/blob/master/frameworks/tensorflow/tensorflow-neuron/tutorials/tutorials-tensorflow-utilizing-neuron-capabilities.rst)」を参照してください。

タスク定義は、1 つのインスタンスタイプに固有である必要があります。コンテナでは、ホストコンテナインスタンス向けに用意された、固有の AWS Trainium または AWS Inferentia デバイスを使用するよう設定する必要があります。これは、`linuxParameters` パラメータを使用して設定します。タスク定義の例については、「[Amazon ECS タスク定義での AWS Neuron 機械学習の指定](ecs-inference-task-def.md)」を参照してください。次の表に、各インスタンスタイプに固有のチップの詳細を示します。


| インスタンスタイプ | vCPU | RAM (GiB) | AWS ML アクセラレーターチップ | デバイスへのパス | 
| --- | --- | --- | --- | --- | 
| trn1.2xlarge | 8 | 32 | 1 | /dev/neuron0 | 
| trn1.32xlarge | 128 | 512 | 16 |  /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3, /dev/neuron4, /dev/neuron5, /dev/neuron6, /dev/neuron7, /dev/neuron8, /dev/neuron9, /dev/neuron10, /dev/neuron11, /dev/neuron12, /dev/neuron13, /dev/neuron14, /dev/neuron15  | 
| trn2.48xlarge | 192 | 1536 | 16 |  /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3, /dev/neuron4, /dev/neuron5, /dev/neuron6, /dev/neuron7, /dev/neuron8, /dev/neuron9, /dev/neuron10, /dev/neuron11, /dev/neuron12, /dev/neuron13, /dev/neuron14, /dev/neuron15  | 
| inf1.xlarge | 4 | 8 | 1 | /dev/neuron0 | 
| inf1.2xlarge | 8 | 16 | 1 | /dev/neuron0 | 
| inf1.6xlarge | 24 | 48 | 4 | /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3 | 
| inf1.24xlarge | 96 | 192 | 16 |  /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3, /dev/neuron4, /dev/neuron5, /dev/neuron6, /dev/neuron7, /dev/neuron8, /dev/neuron9, /dev/neuron10, /dev/neuron11, /dev/neuron12, /dev/neuron13, /dev/neuron14, /dev/neuron15  | 
| inf2.xlarge | 8 | 16 | 1 | /dev/neuron0 | 
| inf2.8xlarge | 32 | 64 | 1 | /dev/neuron0 | 
| inf2.24xlarge | 96 | 384 | 6 | /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3, /dev/neuron4, /dev/neuron5,  | 
| inf2.48xlarge | 192 | 768 | 12 | /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3, /dev/neuron4, /dev/neuron5, /dev/neuron6, /dev/neuron7, /dev/neuron8, /dev/neuron9, /dev/neuron10, /dev/neuron11 | 

# Amazon ECS タスク定義での AWS Neuron 機械学習の指定
<a name="ecs-inference-task-def"></a>

次に、使用する構文を表示する `inf1.xlarge` 用の Linux タスク定義の例を示します。

```
{
    "family": "ecs-neuron",
    "requiresCompatibilities": ["EC2"],
    "placementConstraints": [
        {
            "type": "memberOf",
            "expression": "attribute:ecs.os-type == linux"
        },
        {
            "type": "memberOf",
            "expression": "attribute:ecs.instance-type == inf1.xlarge"
        }
    ],
    "executionRoleArn": "${YOUR_EXECUTION_ROLE}",
    "containerDefinitions": [
        {
            "entryPoint": [
                "/usr/local/bin/entrypoint.sh",
                "--port=8500",
                "--rest_api_port=9000",
                "--model_name=resnet50_neuron",
                "--model_base_path=s3://amzn-s3-demo-bucket/resnet50_neuron/"
            ],
            "portMappings": [
                {
                    "hostPort": 8500,
                    "protocol": "tcp",
                    "containerPort": 8500
                },
                {
                    "hostPort": 8501,
                    "protocol": "tcp",
                    "containerPort": 8501
                },
                {
                    "hostPort": 0,
                    "protocol": "tcp",
                    "containerPort": 80
                }
            ],
            "linuxParameters": {
                "devices": [
                    {
                        "containerPath": "/dev/neuron0",
                        "hostPath": "/dev/neuron0",
                        "permissions": [
                            "read",
                            "write"
                        ]
                    }
                ],
                "capabilities": {
                    "add": [
                        "IPC_LOCK"
                    ]
                }
            },
            "cpu": 0,
            "memoryReservation": 1000,
            "image": "763104351884.dkr.ecr.us-east-1.amazonaws.com/tensorflow-inference-neuron:1.15.4-neuron-py37-ubuntu18.04",
            "essential": true,
            "name": "resnet50"
        }
    ]
}
```

# 深層学習インスタンスでの Amazon ECS タスク定義
<a name="ecs-dl1"></a>

Amazon ECS で深層学習ワークロードを使用するには、[Amazon EC2 DL1](https://aws.amazon.com/ec2/instance-types/dl1/)インスタンスをクラスターに登録します。Amazon EC2 DL1 インスタンスには、Habana Labs (インテル子会社) の Gaudi アクセラレータを搭載しています。Habana Gaudiアクセラレータには、Habana SynapseAI SDK を使用して接続します。この SDK は、TensorFlow および PyTorch による、一般的な機械学習フレームワークをサポートしています。

## 考慮事項
<a name="ecs-dl1-considerations"></a>

Amazon ECS 上で DL1 のデプロイを開始する前に、以下の点を考慮してください。
+ クラスターには、DL1 コンテナインスタンスと DL1 以外のインスタンスを混在させることができます。
+ サービスの作成時、またはスタンドアロンタスクの実行時、特にタスク配置制約を設定する場合には、インスタンスタイプ属性を使用して、タスクが起動されるコンテナインスタンスを確定できます。これにより、リソースが効果的に使用され、深層学習ワークロードのタスクが DL1 インスタンス上に配置されることが保証されます。詳細については、「[Amazon ECS がタスクをコンテナインスタンスに配置する方法](task-placement.md)」を参照してください。

  次の例では、`default` クラスターの `dl1.24xlarge` インスタンスでタスクを実行します。

  ```
  aws ecs run-task \
       --cluster default \
       --task-definition ecs-dl1-task-def \
       --placement-constraints type=memberOf,expression="attribute:ecs.instance-type == dl1.24xlarge"
  ```

## DL1 AMI の使用
<a name="ecs-dl1-ami"></a>

Amazon ECS 向けの Amazon EC2 DL1 インスタンス上で AMI を実行するためには、以下の 3 つのオプションがあります。
+ Habana が[ここで](https://aws.amazon.com/marketplace/pp/prodview-h24gzbgqu75zq)提供している AWS Marketplace AMI。
+ Amazon Web Services によって提供される Habana 深層学習 AMI。これには、Amazon ECS コンテナエージェントは含まれないため、このエージェントを個別にインストールする必要があります。
+ [GitHub リポジトリ](https://github.com/aws-samples/aws-habana-baseami-pipeline)を通じて提供されるカスタム AMI をビルドするには、Packer を使用します。詳細については、「[the Packer documentation](https://developer.hashicorp.com/packer/docs)」(Packer ドキュメント) を参照してください。

# Amazon ECS タスク定義での深層学習の指定
<a name="ecs-dl1-requirements"></a>

Habana Gaudi アクセラレータ付きの深層学習コンテナを Amazon ECS で実行するには、AWS Deep Learning Containers が提供する Habana SynapseAI を使用して TensorFlow または PyTorch 向けに深層学習モデルを提供する、ビルド済みコンテナのコンテナ定義が、対象のタスク定義内に含まれている必要があります。

次のコンテナイメージには TensorFlow 2.7.0 と Ubuntu 20.04 が含まれています。Neuron 用に最適化された事前構築済みの深層学習コンテナの完全なリストは、GitHub で確認できます。詳細については、「[Habana Training Containers](https://github.com/aws/deep-learning-containers/blob/master/available_images.md#habana-training-containers)」(Habana トレーニングコンテナ) を参照してください。

```
763104351884.dkr.ecr.us-east-1.amazonaws.com/tensorflow-training-habana:2.7.0-hpu-py38-synapseai1.2.0-ubuntu20.04
```

以下の例で、Amazon EC2 の Linux コンテナのタスク定義で使用する構文を示します。この例で使用するイメージには、`vault.habana.ai/gaudi-docker/1.1.0/ubuntu20.04/habanalabs/tensorflow-installer-tf-cpu-2.6.0:1.1.0-614` から入手が可能な Habana Labs のシステム管理インターフェイスツール (HL-SMI) が含まれています。

```
{
    "family": "dl-test",
    "requiresCompatibilities": ["EC2"],
    "placementConstraints": [
        {
            "type": "memberOf",
            "expression": "attribute:ecs.os-type == linux"
        },
        {
            "type": "memberOf",
            "expression": "attribute:ecs.instance-type == dl1.24xlarge"
        }
    ],
    "networkMode": "host",
    "cpu": "10240",
    "memory": "1024",
    "containerDefinitions": [
        {
            "entryPoint": [
                "sh",
                "-c"
            ],
            "command": ["hl-smi"],
            "cpu": 8192,
            "environment": [
                {
                    "name": "HABANA_VISIBLE_DEVICES",
                    "value": "all"
                }
            ],
            "image": "vault.habana.ai/gaudi-docker/1.1.0/ubuntu20.04/habanalabs/tensorflow-installer-tf-cpu-2.6.0:1.1.0-614",
            "essential": true,
            "name": "tensorflow-installer-tf-hpu"
        }
    ]
}
```

# 64 ビット ARM ワークロードでの Amazon ECS タスク定義
<a name="ecs-arm64"></a>

Amazon ECS は 64 ビット ARM アプリケーションの使用をサポートしています。アプリケーションは、[AWS Graviton プロセッサ](https://aws.amazon.com/ec2/graviton/)搭載のプラットフォーム上で実行できます。この構成、さまざまなワークロードに適しています。対象となるのは、アプリケーションサーバー、マイクロサービス、ハイパフォーマンスコンピューティング、CPU ベースの機械学習推論、ビデオエンコーディング、電子回路設計オートメーション、ゲーム配信、オープンソースデータベース、インメモリーキャッシュなどのワークロードです。

## 考慮事項
<a name="ecs-arm64-considerations"></a>

64 ビット ARM アーキテクチャを使用するタスク定義のデプロイを開始する前に、次の点を考慮してください。
+ アプリケーションは、Fargate または EC2 を使用できます。
+ アプリケーションは Linux オペレーティングシステムのみで使用できます。
+ Fargate タイプの場合、アプリケーションは Fargate プラットフォームバージョン `1.4.0` 以降を使用する必要があります。
+ アプリケーションは、モニタリングに Fluent Bit または CloudWatch を使用できます。
+ Fargate の場合、次の AWS リージョンでは 64 ビット ARM のワークロードには対応していません。
  + 米国東部 (バージニア北部)、`use1-az3` アベイラビリティーゾーン
+  EC2 の場合、以下を参照して、使用したいインスタンスタイプが利用地域でサポートされていることを確認してください。
  + [Amazon EC2 M6g インスタンス](https://aws.amazon.com/ec2/instance-types/m6)
  +  [Amazon EC2 T4g インスタンス](https://aws.amazon.com/ec2/instance-types/t4/)
  +  [Amazon EC2 C6g インスタンス](https://aws.amazon.com/ec2/instance-types/c6g/)
  +  [Amazon EC2 R6gd インスタンス](https://aws.amazon.com/ec2/instance-types/r6/)
  +  [Amazon EC2 X2gd インスタンス](https://aws.amazon.com/ec2/instance-types/x2/)

  フィルターで Amazon EC2 の `describe-instance-type-offerings` コマンドを使用して、リージョンのインスタンスオファリングを表示することもできます。

  ```
  aws ec2 describe-instance-type-offerings --filters Name=instance-type,Values=instance-type --region region
  ```

  次の例では、米国東部 (バージニア北部) (us-east-1) リージョンで M6 インスタンスタイプが使用可能かどうかを確認します。

  ```
  aws ec2 describe-instance-type-offerings --filters "Name=instance-type,Values=m6*" --region us-east-1
  ```

  詳細については、「*Amazon EC2 コマンドラインリファレンス*」の「[インスタンスタイプオファリングの説明](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instance-type-offerings.html)」を参照してください。

# Amazon ECS タスク定義での ARM アーキテクチャの指定
<a name="ecs-arm-specifying"></a>

ARM アーキテクチャを使用するには、`cpuArchitecture` タスク定義パラメータに `ARM64` を指定します。

次の例では、タスク定義で ARM アーキテクチャが指定されています。JSON 形式にあります。

```
{
    "runtimePlatform": {
        "operatingSystemFamily": "LINUX",
        "cpuArchitecture": "ARM64"
    },
...
}
```

次の例に、「hello world」を表示する ARM アーキテクチャのタスク定義を示します。

```
{
 "family": "arm64-testapp",
 "networkMode": "awsvpc",
 "containerDefinitions": [
    {
        "name": "arm-container",
        "image": "public.ecr.aws/docker/library/busybox:latest",
        "cpu": 100,
        "memory": 100,
        "essential": true,
        "command": [ "echo hello world" ],
        "entryPoint": [ "sh", "-c" ]
    }
 ],
 "requiresCompatibilities": [ "EC2" ],
 "cpu": "256",
 "memory": "512",
 "runtimePlatform": {
        "operatingSystemFamily": "LINUX",
        "cpuArchitecture": "ARM64"
  },
 "executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole"
}
```

# Amazon ECS ログを CloudWatch に送信する
<a name="using_awslogs"></a>

タスクのコンテナを設定して CloudWatch Logs にログ情報を送信できます。タスクで Fargate を使用すると、コンテナからログを表示できます。EC2 を使用すると、コンテナからの異なるログを 1 か所で便利に表示できます。また、コンテナインスタンスのディスク容量をコンテナログが占有してしまうことも防止できます。

**注記**  
タスクのコンテナによってログ記録される情報のタイプは、`ENTRYPOINT` コマンドによって大きく異なります。デフォルトでは、キャプチャされるログには、コンテナをローカルに実行した場合に通常はインタラクティブターミナルに表示されるコマンド出力 (`STDOUT` および `STDERR` I/O ストリーム) が表示されます。`awslogs` ログドライバーは、これらのログを Docker から CloudWatch Logs に渡します。Docker ログの処理方法 (ファイルデータやストリームをキャプチャする別の方法) の詳細については、Docker ドキュメントの[コンテナまたはサービスのログを表示する](https://docs.docker.com/engine/logging/)を参照してください。

your Amazon ECS コンテナインスタンスから CloudWatch Logs にシステムログを送信するには、「*Amazon CloudWatch Logs ユーザーガイド*」の「[ログファイルをモニタリングする」](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/WhatIsCloudWatchLogs.html)と「[CloudWatch Logs クォータ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/cloudwatch_limits_cwl.html)」を参照してください。

## Fargate
<a name="enable_awslogs"></a>

タスクで Fargate を使用する場合、`awslogs` ログドライバーを有効化するには、必要な `logConfiguration` パラメータをタスク定義に追加する必要があります。詳細については、「[Amazon ECS タスク定義の例: CloudWatch にログをルーティングする](specify-log-config.md)」を参照してください。

Fargate の Windows コンテナでは、タスク定義パラメータに `& \ < > ^ |` などの特殊文字が含まれている場合は、次のいずれかのオプションを実行します。
+ パラメータ文字列全体を二重引用符で囲んだエスケープ (`\`) を追加する

  例

  ```
  "awslogs-multiline-pattern": "\"^[|DEBUG|INFO|WARNING|ERROR\"",
  ```
+ 各特殊文字の周囲にエスケープ (`^`) 文字を追加する

  例

  ```
  "awslogs-multiline-pattern": "^^[^|DEBUG^|INFO^|WARNING^|ERROR",
  ```

## EC2
<a name="ec2-considerations"></a>

タスクで EC2 を使用する場合、`awslogs` ログドライバーをオンにするには、Amazon ECS コンテナインスタンスに、コンテナエージェントのバージョン 1.9.0 以降が必要です。エージェントのバージョンの確認と最新バージョンへの更新については、「[Amazon ECS コンテナエージェントをアップデートする](ecs-agent-update.md)」を参照してください。

**注記**  
Amazon ECS に最適化された AMI か、もしくは少なくともバージョン `1.9.0-1` の `ecs-init` パッケージを含むカスタム AMI を使用する必要があります。カスタム AMI を使用する場合、**docker run** ステートメント内で以下の環境変数を使用するか、または環境変数ファイルを使用することにより、エージェントの起動時に Amazon EC2 インスタンス上で `awslogs` ロギングドライバーが使用可能となることを指定する必要があります。  

```
ECS_AVAILABLE_LOGGING_DRIVERS=["json-file","awslogs"]
```

Amazon ECS コンテナインスタンスでは、コンテナインスタンスで起動する IAM ロールに `logs:CreateLogStream` および `logs:PutLogEvents` アクセス許可も必要になります。Amazon ECS で `awslogs` ログドライバーのサポートを有効にする前に Amazon ECS コンテナインスタンスを作成した場合は、このアクセス許可の追加が必要となる場合があります。`ecsTaskExecutionRole` はタスクに割り当てられた時点で使用され、また、正しいアクセス許可が含まれている必要があります。タスクの実行ロールの詳細については、「[Amazon ECS タスク実行IAM ロール](task_execution_IAM_role.md)」を参照してください。コンテナインスタンスでコンテナインスタンス用の管理 IAM ポリシーを使用している場合、通常そのコンテナインスタンスには、適切なアクセス許可が付与されています。コンテナインスタンスのマネージド IAM ポリシーについては、「[Amazon ECS コンテナインスタンスの IAM ロール](instance_IAM_role.md)」を参照してください。

# Amazon ECS タスク定義の例: CloudWatch にログをルーティングする
<a name="specify-log-config"></a>

コンテナがログを CloudWatch に送信する前に、タスク定義でコンテナの `awslogs` ログドライバーを指定する必要があります。ログパラメータの詳細については、「[ストレージとログ記録](task_definition_parameters.md#container_definition_storage)」を参照してください

下にあるタスク定義 JSON には、各コンテナに指定された `logConfiguration` オブジェクトが含まれています。その 1 つは、`awslogs-wordpress` というロググループにログを送信する WordPress コンテナ用です。もう 1 つは、`awslogs-mysql` というロググループにログを送信する MySQL コンテナ用です。どちらのコンテナも `awslogs-example` ログストリームプレフィックスを使用します。

```
{
    "containerDefinitions": [
        {
            "name": "wordpress",
            "links": [
                "mysql"
            ],
            "image": "public.ecr.aws/docker/library/wordpress:latest",
            "essential": true,
            "portMappings": [
                {
                    "containerPort": 80,
                    "hostPort": 80
                }
            ],
            "logConfiguration": {
                "logDriver": "awslogs",
                "options": {
                    "awslogs-create-group": "true",
                    "awslogs-group": "awslogs-wordpress",
                    "awslogs-region": "us-west-2",
                    "awslogs-stream-prefix": "awslogs-example"
                }
            },
            "memory": 500,
            "cpu": 10
        },
        {
            "environment": [
                {
                    "name": "MYSQL_ROOT_PASSWORD",
                    "value": "password"
                }
            ],
            "name": "mysql",
            "image": "public.ecr.aws/docker/library/mysql:latest",
            "cpu": 10,
            "memory": 500,
            "essential": true,
            "logConfiguration": {
                "logDriver": "awslogs",
                "options": {
                    "awslogs-create-group": "true",
                    "awslogs-group": "awslogs-mysql",
                    "awslogs-region": "us-west-2",
                    "awslogs-stream-prefix": "awslogs-example",
                    "mode": "non-blocking", 
                    "max-buffer-size": "25m" 
                }
            }
        }
    ],
    "family": "awslogs-example"
}
```

## 次のステップ
<a name="specify-log-config-next-steps"></a>
+ CloudWatch AWS CLI または API を使用してロググループの保持ポリシーを設定できます (オプション)。詳細は「*AWS Command Line Interfaceリファレンス*」の「[put-retention-policy](https://docs.aws.amazon.com/cli/latest/reference/logs/put-retention-policy.html)」を参照してください。
+ `awslogs` ログドライバーを使用するタスク定義をコンテナ定義ログ設定に登録すると、タスク定義を使用してタスクを実行またはサービスを作成し、CloudWatch Logs へのログの送信を開始できます。詳細については、「[Amazon ECS タスクとしてのアプリケーションの実行](standalone-task-create.md)」および「[Amazon ECS のローリング更新デプロイの作成](create-service-console-v2.md)」を参照してください。

# Amazon ECS ログを AWS サービスまたは AWS Partner に送信する
<a name="using_firelens"></a>

FireLens for Amazon ECS では、タスク定義パラメータを使用してログを AWS サービスや AWS Partner Network (APN) の宛先にルーティングし、ログを保存および分析できます。AWS Partner Network は、プログラム、専門知識、リソースを活用して顧客向けサービスの構築、マーケティング、販売を行うパートナーのグローバルコミュニティです。詳細については、「[AWS Partner](https://aws.amazon.com/partners/work-with-partners/)」を参照してください。FireLens は [Fluentd](https://www.fluentd.org/) および [Fluent Bit](https://fluentbit.io/) と連携しています。Fluent Bit イメージ用に AWS を提供していますが、Fluentd や Fluent Bit のイメージはご用意いただいたものを使用することもできます。

デフォルトでは、Amazon ECS は、Firelens コンテナを使用するコンテナより前に Firelens コンテナを起動するようにコンテナの依存関係を設定します。また Firelens コンテナは、それを使用するすべてのコンテナが停止した後で停止します。

この機能を使用するには、タスク用の IAM ロールを作成し、AWS のサービスを使用するために必要なアクセス許可をタスクに付与する必要があります。例えば、コンテナから Firehose にログをルーティングする場合、タスクには `firehose:PutRecordBatch` API を呼び出すためのアクセス許可が必要です。詳細については、*IAM ユーザーガイド*の「[IAM ID アクセス許可の追加と削除](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)」を参照してください。

以下の場合は、タスクに Amazon ECS タスク実行ロールが必要になることもあります。詳細については、「[Amazon ECS タスク実行IAM ロール](task_execution_IAM_role.md)」を参照してください。
+ タスクが Fargate でホストされていて、Amazon ECR からコンテナイメージをプルしたり、ログ設定で AWS Secrets Manager の機密データを参照したりする場合は、タスク実行 IAM ロールを含める必要があります。
+ Amazon S3 でホストされているカスタム設定ファイルを使用する場合は、タスク実行 IAM ロールに `s3:GetObject` アクセス許可が含まれている必要があります。

FireLens for Amazon ECS を使用する際は、以下の点を考慮してください。
+ コンソール上でコンテナ名を簡単に区別できるよう、`my_service_` をログコンテナ名に追加することをおすすめします。
+ Amazon ECS はデフォルトで、アプリケーションコンテナと FireLens コンテナの間に開始コンテナ順序依存関係を追加します。アプリケーションコンテナと FireLens コンテナ間でコンテナ順序を指定すると、デフォルトの開始コンテナ順序が上書きされます。
+ FireLens for Amazon ECS は、Linux の AWS Fargate と Linux の Amazon EC2 の両方でホストされたタスクでサポートされます。Windows コンテナは FireLens をサポートしていません。

  Windows コンテナの集中ロギングを設定する方法については、「[Centralized logging for Windows containers on Amazon ECS using Fluent Bit](https://aws.amazon.com/blogs/containers/centralized-logging-for-windows-containers-on-amazon-ecs-using-fluent-bit/)」(Fluent Bit を使用した Amazon ECS での Windows コンテナの集中ロギング) を参照してください。
+ Amazon ECS の FireLens は、CloudFormation テンプレートを使用して設定できます。詳細については、*AWS CloudFormation ユーザーガイド*の「[AWS::ECS::TaskDefinition FirelensConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-taskdefinition-firelensconfiguration.html)」を参照してください。
+ FireLens はポート `24224` でリッスンするため、FireLens ログルーターがタスク外に到達できないようにするには、タスクが使用するセキュリティグループでポート `24224` でのインバウンドトラフィックを許可してはなりません。`awsvpc` ネットワークモードを使用するタスクの場合、これは、そのタスクに関連付けられたセキュリティグループです。`host` ネットワークモードを使用するタスクでは、そのタスクをホストする Amazon EC2 インスタンスに関連付けられているセキュリティグループです。`bridge` ネットワークモードを使用するタスクの場合、ポート `24224` を使用するポートマッピングを作成しないでください。
+ `bridge` ネットワークモードを使用するタスクの場合、FireLens 設定のコンテナは、それに依存するアプリケーションコンテナが開始する前に開始する必要があります。コンテナの開始順序を制御するには、タスク定義の依存関係条件を使用します。詳細については、「[コンテナの依存関係](task_definition_parameters.md#container_definition_dependson)」を参照してください。
**注記**  
FireLens 設定のコンテナ定義で依存関係条件パラメータを使用する場合は、各コンテナに `START` または `HEALTHY` 条件要件があることを確認してください。
+ デフォルトでは、FireLens はクラスターとタスクの定義名、およびクラスターの Amazon リソースネーム (ARN) をメタデータキーとして stdout/stderr コンテナログに追加します。メタデータ形式の例を次に示します。

  ```
  "ecs_cluster": "cluster-name",
  "ecs_task_arn": "arn:aws:ecs:region:111122223333:task/cluster-name/f2ad7dba413f45ddb4EXAMPLE",
  "ecs_task_definition": "task-def-name:revision",
  ```

  ログにメタデータを含めたくない場合は、タスク定義の「`firelensConfiguration`」セクションで `enable-ecs-log-metadata` を `false` に設定します。

  ```
  "firelensConfiguration":{
     "type":"fluentbit",
     "options":{
        "enable-ecs-log-metadata":"false",
        "config-file-type":"file",
        "config-file-value":"/extra.conf"
  }
  ```

非ルートユーザーとして実行するように FireLens コンテナを設定できます。以下の点を考慮してください。
+  非ルートユーザーとして実行するように FireLens コンテナを設定するには、次のいずれかの形式でユーザーを指定する必要があります。
  + `uid`
  + `uid:gid`
  + `uid:group`

  コンテナ定義について、詳細は「*Amazon Elastic Container Service API リファレンス*」の「[ContainerDefinition](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDefinition.html)」を参照してください。

  FireLens コンテナは UNIX ソケット経由でアプリケーションログを受け取ります。Amazon ECS エージェントは `uid` を使用してソケットディレクトリの所有権を FireLens コンテナに割り当てます。
+ 非ルートユーザーとして実行するための FireLens コンテナ設定は、Amazon ECS エージェントバージョン `1.96.0` 以降、および Amazon ECS 最適化 AMI のバージョン `v20250716` 以降でサポートされています。
+ FireLens コンテナのユーザーを指定する場合、`uid` は一意でなければならず、タスク内の他のコンテナまたはコンテナインスタンスに属する他のプロセスには使用されません。

Amazon S3 でホストするファイルや Amazon S3 内のファイルなど、Amazon ECS で複数の設定ファイルを使用する方法については、「[Init process for Fluent Bit on ECS, multi-config support](https://github.com/aws/aws-for-fluent-bit/tree/mainline/use_cases/init-process-for-fluent-bit)」を参照してください。

構成例については、「[Amazon ECS タスク定義の例: FireLens にログをルーティングする](firelens-taskdef.md)」を参照してください。

高スループットのログ有効化と設定について、詳細は「[高スループットの Amazon ECS ログの設定](firelens-docker-buffer-limit.md)」を参照してください。

# 高スループットの Amazon ECS ログの設定
<a name="firelens-docker-buffer-limit"></a>

ログスループットの高いシナリオでは、FireLens と Fluent Bit を組み合わせた `awsfirelens` ログドライバーを使用することをお勧めします。 Fluent Bit は、リソースを効率的に処理し、数百万のログレコードを処理できる軽量ログプロセッサです。ただし、大規模に最適なパフォーマンスを実現するには、その設定を調整する必要があります。

このセクションでは、システムの安定性を維持し、データ損失を回避しながら、高いログスループットを処理するための高度な Fluent Bit 最適化手法について説明します。

FireLens でカスタム設定ファイルを使用する方法については、「[カスタム設定ファイルを使用する](firelens-taskdef.md#firelens-taskdef-customconfig)」を参照してください。その他の例については、GitHub の「[Amazon ECS FireLens の例](https://github.com/aws-samples/amazon-ecs-firelens-examples)」を参照してください。

**注記**  
`workers` や `threaded` など、このセクションの一部の設定オプションでは、Fluent Bit バージョン 3 以降の AWS が必要です。使用可能なバージョンについては、「 [AWS for Fluent Bit リリース](https://github.com/aws/aws-for-fluent-bit/releases)」を参照してください。

## ファイルシステムのバッファリングを使用する
<a name="firelens-filesystem-buffering"></a>

デフォルトでは、 Fluent Bit はメモリ内のすべてのデータをバッファします。データが出力にフラッシュされるよりも速く取り込まれると、バッファが満杯になります。満杯になると、入力プラグインはバッファスペースが使用可能になるまで一時停止します。これにより、バックプレッシャーが発生し、アプリケーションの速度が低下する可能性があります。

高スループットのシナリオでは、ファイルシステムのバッファリングを使用することをお勧めします。Fluent Bit がバッファリングとストレージを管理する方法の詳細については、 Fluent Bit ドキュメントの「[バッファリングとストレージ](https://docs.fluentbit.io/manual/administration/buffering-and-storage)」を参照してください。

ファイルシステムのバッファリングには、次の利点があります。
+ **バッファ容量が大きい** — 通常、ディスクスペースはメモリよりも豊富です。
+ **永続性** – バッファされたデータは Fluent Bit 再起動後も保持されます。
+ **グレースフルデグラデーション** – 出力の失敗時に、メモリの枯渇を引き起こすのではなく、データがディスクに蓄積されます。

ファイルシステムのバッファリングを有効にするには、カスタム Fluent Bit 設定ファイルを指定します。次の例は、推奨される設定です。

```
[SERVICE]
    # Flush logs every 1 second
    Flush 1
    # Wait 120 seconds during shutdown to flush remaining logs
    Grace 120
    # Directory for filesystem buffering
    storage.path             /var/log/flb-storage/
    # Limit chunks stored 'up' in memory (reduce for memory-constrained environments)
    storage.max_chunks_up    32
    # Flush backlog chunks to destinations during shutdown (prevents log loss)
    storage.backlog.flush_on_shutdown On

[INPUT]
    Name forward
    unix_path /var/run/fluent.sock
    # Run input in separate thread to prevent blocking
    threaded true
    # Enable filesystem buffering for persistence
    storage.type filesystem

[OUTPUT]
    Name cloudwatch_logs
    Match *
    region us-west-2
    log_group_name /aws/ecs/my-app
    log_stream_name $(ecs_task_id)
    # Use multiple workers for parallel processing
    workers 2
    # Retry failed flushes up to 15 times
    retry_limit 15
    # Maximum disk space for buffered data for this output
    storage.total_limit_size 10G
```

主な設定パラメータ:

`storage.path`  
Fluent Bit がバッファされたチャンクをディスクに保存するディレクトリ。

`storage.backlog.flush_on_shutdown`  
有効にすると、Fluent Bit はシャットダウン中にすべてのバックログファイルシステムのチャンクを送信先にフラッシュしようとします。これにより、Fluent Bit が停止する前にデータ配信を確保できますが、シャットダウン時間が長くなる可能性があります。

`storage.max_chunks_up`  
メモリに残っているチャンクの数。デフォルトは 128 チャンクで、各チャンクは最大 4～5 MB を使用できるため、500 MB 以上のメモリを消費する可能性があります。メモリに制約のある環境では、この値を小さくします。たとえば、バッファリングに 50 MB 使用できる場合は、これを 8～10 チャンクに設定します。

`storage.type filesystem`  
入力プラグインのファイルシステムストレージを有効にします。名前にかかわらず、 Fluent Bit は `mmap` を使用してチャンクをメモリとディスクの両方にマッピングし、パフォーマンスを犠牲にすることなく永続性を提供します。

`threaded true`  
Fluent Bit のメインイベントループとは別に、独自のスレッドで入力を実行します。これにより、遅い入力がパイプライン全体をブロックすることを防ぎます。

## 出力設定の最適化
<a name="firelens-output-optimization"></a>

ネットワークの問題、サービスの停止、送信先スロットリングにより、ログの配信が妨げられる場合があります。適切な出力設定により、データ損失のない耐障害性を保証します。

出力フラッシュが失敗した場合、 Fluent Bit はオペレーションを再試行できます。次のパラメータは再試行動作を制御します。

`retry_limit`  
レコードを削除する前の最大再試行回数。デフォルトは 1 です。本番環境では、数分の停止に対応できるよう、エクスポネンシャルバックオフを用いた再試行数を 15 回以上に設定することをお勧めします。

`scheduler.base`  
再試行間の最小秒数。10 秒をお勧めします。

`scheduler.cap`  
エクスポネンシャルバックオフを使用する場合の再試行間の最大秒数。60 秒をお勧めします。

`workers`  
並列出力処理のスレッド数。複数のワーカーが同時フラッシュを許可し、多くのチャンクを処理する際のスループットを向上させます。

`[SERVICE]` セクションの `Grace` パラメータは、バッファされたデータをフラッシュするためにシャットダウン中に Fluent Bit が待機する時間を設定します。`Grace` 期間はコンテナの `stopTimeout` と調整する必要があります。`SIGKILL` を受信する前に Fluent Bit がフラッシュを完了できるように、`stopTimeout` が `Grace` 期間を超えていることを確認します。たとえば、`Grace` が 120 秒の場合、 `stopTimeout` を 150 秒に設定します。

次の例は、高スループットシナリオで推奨されるすべての設定を含む完全な Fluent Bit 設定を示しています。

```
[SERVICE]
    # Flush logs every 1 second
    Flush 1
    # Wait 120 seconds during shutdown to flush remaining logs
    Grace 120
    # Directory for filesystem buffering
    storage.path             /var/log/flb-storage/
    # Limit chunks stored 'up' in memory (reduce for memory-constrained environments)
    storage.max_chunks_up    32
    # Flush backlog chunks to destinations during shutdown (prevents log loss)
    storage.backlog.flush_on_shutdown On
    # Minimum seconds between retries
    scheduler.base           10
    # Maximum seconds between retries (exponential backoff cap)
    scheduler.cap            60

[INPUT]
    Name forward
    unix_path /var/run/fluent.sock
    # Run input in separate thread to prevent blocking
    threaded true
    # Enable filesystem buffering for persistence
    storage.type filesystem

[OUTPUT]
    Name cloudwatch_logs
    Match *
    region us-west-2
    log_group_name /aws/ecs/my-app
    log_stream_name $(ecs_task_id)
    # Use multiple workers for parallel processing
    workers 2
    # Retry failed flushes up to 15 times
    retry_limit 15
    # Maximum disk space for buffered data for this output
    storage.total_limit_size 10G
```

## マルチ送信先ログを使用して信頼性を高める
<a name="firelens-multi-destination"></a>

複数の送信先にログを送信すると、単一障害点がなくなります。たとえば、CloudWatch Logs で機能停止が発生した場合でも、ログは Amazon S3 に到達します。

マルチ送信先ログには、次の利点があります。Amazon S3 出力プラグインは、gzip 形式や Parquet 形式などの圧縮オプションもサポートしているため、ストレージコストを削減できます。詳細については、「Fluent Bit ドキュメント」の「[S3 圧縮](https://docs.fluentbit.io/manual/pipeline/outputs/s3#compression)」を参照してください。

マルチ送信先ログには、次の利点があります。
+ **冗長性** – 一方の送信先が失敗しても、ログはもう一方の送信先に到達します。
+ **復旧** – 一方のシステムのギャップを他方のシステムから再構築します。
+ **耐久性** – ログを Amazon S3 にアーカイブして長期保持します。
+ **コスト最適化** – 最近のログを CloudWatch Logs などの高速クエリサービスに短期間保存し、すべてのログを低コストの Amazon S3 ストレージにアーカイブして長期保持します。

次の Fluent Bit 設定は、CloudWatch Logs と Amazon S3 の両方にログを送信します。

```
[OUTPUT]
    Name cloudwatch_logs
    Match *
    region us-west-2
    log_group_name /aws/ecs/my-app
    log_stream_name $(ecs_task_id)
    workers 2
    retry_limit 15

[OUTPUT]
    Name s3
    Match *
    bucket my-logs-bucket
    region us-west-2
    total_file_size 100M
    s3_key_format /fluent-bit-logs/$(ecs_task_id)/%Y%m%d/%H/%M/$UUID
    upload_timeout 10m
    # Maximum disk space for buffered data for this output
    storage.total_limit_size 5G
```

どちらの出力も同じ `Match *` パターンを使用するため、すべてのレコードは両方の送信先に個別に送信されます。どちらか一方の送信先が停止しても、ログは引き続き他の送信先に流れ続け、失敗したフラッシュは後で再試行できるようにファイルシステムバッファに蓄積されます。

## tail 入力プラグインでファイルベースのログを使用する
<a name="firelens-tail-input"></a>

ログ損失が重大な懸念事項となる高スループットのシナリオでは、別の方法として、アプリケーションがディスク上のファイルにログを書き込み、`tail` 入力プラグインを使用してそれらを読み取るように Fluent Bit を設定します。このアプローチは、Docker ログドライバーレイヤーを完全にバイパスします。

tail プラグインを使用したファイルベースのログ記録には、次の利点があります。
+ **オフセット追跡** – tail プラグインはデータベースファイルにファイルオフセットを保存できるため (`DB` オプションを使用)、Fluent Bit 再起動した際に耐久性があります。これにより、コンテナの再起動時にログが消失するのを防ぐことができます。
+ **入力レベルのバッファリング** – `Mem_Buf_Limit` を使用して入力プラグインでメモリバッファ制限を直接設定できるため、メモリ使用量をより詳細に制御できます。
+ **Docker のオーバーヘッドを回避** – Docker のログバッファを経由することなく、ログはファイルから Fluent Bit に直接送信されます。

このアプローチを使用するには、アプリケーションが `stdout` ではなくファイルにログを書き込む必要があります。アプリケーションコンテナと Fluent Bit コンテナの両方が、ログファイルが保存されている共有ボリュームをマウントします。

次の例は、ベストプラクティスを使用した tail 入力設定を示しています。

```
[INPUT]
    Name tail
    # File path or glob pattern to tail
    Path /var/log/app.log
    # Database file for storing file offsets (enables resuming after restart)
    DB /var/log/flb_tail.db
    # when true, controls that only fluent-bit will access the database (improves performance)
    DB.locking true
    # Skip long lines instead of skipping the entire file
    Skip_Long_Lines On
    # How often (in seconds) to check for new files matching the glob pattern
    Refresh_Interval 10
    # Extra seconds to monitor a file after rotation to account for pending flush
    Rotate_Wait 30
    # Maximum size of the buffer for a single line
    Buffer_Max_Size 10MB
    # Initial allocation size for reading file data
    Buffer_Chunk_Size 1MB
    # Maximum memory buffer size (tail pauses when full)
    Mem_Buf_Limit 75MB
```

tail 入力プラグインを使用する場合は、次の点を考慮してください。
+ ディスクの枯渇を防ぐために、アプリケーションログのログローテーションを実装します。基盤となるボリュームメトリクスをモニタリングしてパフォーマンスを測定します。
+ ログ形式に基づいて、`Ignore_Older`、`Read_from_Head` および複数行パーサーなどの設定を検討してください。

詳細については、「Fluent Bit ドキュメント」の「[Tail](https://docs.fluentbit.io/manual/pipeline/inputs/tail)」を参照してください。ベストプラクティスについては、「Fluent Bit トラブルシューティングガイド」の AWS の「[ベストプラクティスを使用した Tail 設定](https://github.com/aws/aws-for-fluent-bit/blob/mainline/troubleshooting/debugging.md#tail-config-with-best-practices)」を参照してください。

## FireLens に直接ログ記録する
<a name="firelens-environment-variables"></a>

`awsfirelens` ログドライバーがタスク定義で指定されている場合、Amazon ECS コンテナエージェントは次の環境変数をコンテナに挿入します。

`FLUENT_HOST`  
FireLens コンテナに割り当てられた IP アドレス。  
`bridge` ネットワークモードの EC2 を使用している場合、FireLens ログルーターコンテナ (コンテナ定義に `firelensConfiguration` オブジェクトがあるコンテナ) を再起動した後で、アプリケーションコンテナの `FLUENT_HOST` 環境変数が不正確になる可能性があります。これは、`FLUENT_HOST` が動的 IP アドレスであり、再起動後に変更される場合があるためです。アプリケーションコンテナから `FLUENT_HOST` IP アドレスへの直接的なロギングは、アドレスの変更後に失敗することがあります。個々のコンテナの再起動に関する詳細については、「[コンテナ再起動ポリシーを使用して Amazon ECS タスク内の個々のコンテナを再起動する](container-restart-policy.md)」を参照してください。

`FLUENT_PORT`  
Fluent Forward プロトコルがリッスンしているポート。

これらの環境変数を使用して、`stdout` に書き込む代わりに Fluent Forward プロトコルを使用してアプリケーションコードから Fluent Bit ログルーターに直接ログを記録できます。このアプローチでは、Docker ログドライバーレイヤーをバイパスします。これにより、次の利点が得られます。
+ **低レイテンシー** – Docker のログインフラストラクチャを経由することなく、ログは Fluent Bit に直接送信されます。
+ **構造化ログ** – JSON エンコーディングのオーバーヘッドなしで、構造化ログデータをネイティブに送信します。
+ **より良い制御** – アプリケーションは独自のバッファリングとエラー処理ロジックを実装できます。

次の Fluent ロガーライブラリは Fluent Forward プロトコルをサポートし、ログを Fluent Bit に直接送信するために使用できます。
+ **Go** – [fluent-logger-golang](https://github.com/fluent/fluent-logger-golang)
+ **Python** – [fluent-logger-python](https://github.com/fluent/fluent-logger-python)
+ **Java** – [fluent-logger-java](https://github.com/fluent/fluent-logger-java)
+ **Node.js** – [fluent-logger-node](https://github.com/fluent/fluent-logger-node)
+ **Ruby** – [fluent-logger-ruby](https://github.com/fluent/fluent-logger-ruby)

## Docker バッファ制限を設定する
<a name="firelens-buffer-limit"></a>

タスク定義を作成する際は、`log-driver-buffer-limit` で値を指定することで、メモリにバッファリングされるログの行数を指定できます。これにより、Docker と Fluent Bit の間のバッファが制御されます。詳細については、Docker ドキュメントの「[Fluentd ロギングドライバー](https://docs.docker.com/engine/logging/drivers/fluentd/)」を参照してください。

このオプションは、スループットが高いために Docker がバッファメモリを使い果たし、新しいメッセージを追加するためにバッファメッセージを破棄する可能性がある場合に使用します。

このオプションを使用する場合は、次の点を考慮してください。
+ このオプションは、EC2 およびプラットフォームバージョン `1.4.0` 以降の Fargate でサポートされています。
+ このオプションは、`logDriver` が `awsfirelens` に設定されている場合にのみ有効です。
+ デフォルトのバッファ制限は `1048576` (ログの行数) です。
+ バッファ制限は、`0` ログ行以上、`536870912` ログ行未満である必要があります。
+ このバッファに使用されるメモリの最大量は、各ログ行のサイズとバッファのサイズ積です。たとえば、アプリケーションのログ行が平均 `2` KiB の場合、4096 のバッファ制限では最大 `8` MiB を使用します。タスクレベルで割り当てられるメモリの合計量は、ログドライバーのメモリバッファに加えて、すべてのコンテナに割り当てられたメモリ量よりも大きくなければなりません。

次のタスク定義は、`log-driver-buffer-limit` を設定する方法を示しています。

```
{
    "containerDefinitions": [
        {
            "name": "my_service_log_router",
            "image": "public.ecr.aws/aws-observability/aws-for-fluent-bit:3",
            "cpu": 0,
            "memoryReservation": 51,
            "essential": true,
            "firelensConfiguration": {
                "type": "fluentbit"
            }
        },
        {
            "essential": true,
            "image": "public.ecr.aws/docker/library/httpd:latest",
            "name": "app",
            "logConfiguration": {
                "logDriver": "awsfirelens",
                "options": {
                    "Name": "firehose",
                    "region": "us-west-2",
                    "delivery_stream": "my-stream",
                    "log-driver-buffer-limit": "52428800"
                }
            },
            "dependsOn": [
                {
                    "containerName": "my_service_log_router",
                    "condition": "START"
                }
            ],
            "memoryReservation": 100
        }
    ]
}
```

# Amazon ECS の Fluent Bit イメージリポジトリの AWS
<a name="firelens-using-fluentbit"></a>

AWS は、CloudWatch Logs と Firehose の両方のプラグインに Fluent Bit イメージを提供します。Fluent Bit は、リソース使用率が Fluentd よりも低いため、ログルーターとして使用することをお勧めします。詳細については、「[CloudWatch Logs for Fluent Bit](https://github.com/aws/amazon-cloudwatch-logs-for-fluent-bit)」および「[Amazon Kinesis Firehose for Fluent Bit](https://github.com/aws/amazon-kinesis-firehose-for-fluent-bit)」を参照してください。

**AWS for Fluent Bit** イメージは、Amazon ECR Public Gallery と Amazon ECR リポジトリの両方の Amazon ECR で利用が可能で、高可用性を実現できます。

## Amazon ECR Public Gallery
<a name="firelens-image-ecrpublic"></a>

AWS for Fluent Bit イメージは Amazon ECR Public Gallery で利用できます。これはパブリックリポジトリであり、すべての AWS リージョン リージョンから使用できるため、AWS for Fluent Bit イメージのダウンロード先として推奨されます 詳細については、Amazon ECR Public Gallery の「[aws-for-fluent-bit](https://gallery.ecr.aws/aws-observability/aws-for-fluent-bit)」を参照してください。

### Linux
<a name="firelens-image-ecrpublic-linux"></a>

Amazon ECR Public Gallery の AWS for Fluent Bit イメージは、`ARM64` または `x86-64` アーキテクチャの Amazon Linux オペレーティングシステムをサポートしています。

目的のイメージタグを使用してリポジトリ URL を指定することにより、Amazon ECR Public Gallery からAWS for Fluent Bit イメージをプルできます。利用可能な画像タグは、Amazon ECR Public Gallery の [**Image tags (画像タグ)**] タブにあります。

Docker CLI で使用する構文を以下に示します。

```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:tag
```

たとえば、次の Docker CLI コマンドを使用すれば、Fluent Bit リリースの AWS の「3.x」ファミリの最新イメージをプルできます。

```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:3
```

**注記**  
認証されていないプルは許可されますが、認証されたプルよりもレート制限が低くなります。プルする前に、次のコマンドを使用して AWS アカウントの使用を認証します。  

```
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
```

#### Fluent Bit 3.0.0 向けの AWS
<a name="firelens-image-ecrpublic-linux-3.0.0"></a>

Fluent Bit バージョン `2.x` の既存 AWS に加えて、Fluent Bit の AWS は新しいメジャーバージョン `3.x` をサポートします。新しいメジャーバージョンには、イメージを Amazon Linux 2 から Amazon Linux 2023 にアップグレードし、Fluent Bit バージョン `1.9.10` を `4.1.1` にアップグレードすることが含まれます。詳細は GitHub の「[AWS for Fluent Bit repository](https://github.com/aws/aws-for-fluent-bit/blob/mainline/VERSIONS.md)」を参照してください。

次の例は、Fluent Bit `3.x` イメージの AWS の更新済みタグを示しています。

Fluent Bit イメージの AWS にはマルチアーキテクチャタグを使用できます。

```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:3
```

### Server
<a name="firelens-image-ecrpublic-windows"></a>

Amazon ECR Public Gallery の AWS for Fluent Bit イメージは、次のオペレーティングシステムを備えた `AMD64` アーキテクチャをサポートしています。
+ Windows Server 2022 Full
+ Windows Server 2022 Core
+ Windows Server 2019 Full
+ Windows Server 2019 Core

AWS Fargate の Windows コンテナは FireLens をサポートしません。

目的のイメージタグを使用してリポジトリ URL を指定することにより、Amazon ECR Public Gallery からAWS for Fluent Bit イメージをプルできます。利用可能な画像タグは、Amazon ECR Public Gallery の [**Image tags (画像タグ)**] タブにあります。

Docker CLI で使用する構文を以下に示します。

```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:tag
```

例えば、次の Docker CLI コマンドを使用して、AWS for Fluent Bit イメージの最新安定版をプルできます。

```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:windowsservercore-stable
```

**注記**  
認証されていないプルは許可されますが、認証されたプルよりもレート制限が低くなります。プルする前に、次のコマンドを使用して AWS アカウントの使用を認証します。  

```
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
```

## Amazon ECR
<a name="firelens-image-ecr"></a>

AWS for Fluent Bit イメージは、Amazon ECR で高可用性を活用できます。次のコマンドを使用して、イメージ URI の取得および特定の AWS リージョンでイメージの可用性を確立できます。

### Linux
<a name="firelens-image-ecr-linux"></a>

最新の安定している AWS for Fluent Bit イメージの URI は、次のコマンドを使用して取得できます。

```
aws ssm get-parameters \
      --names /aws/service/aws-for-fluent-bit/stable \
      --region us-east-1
```

次のコマンドを使用して Systems Manager パラメータストアのパラメータをクエリすると、AWS for Fluent Bit イメージのすべてのバージョンを一覧表示できます。

```
aws ssm get-parameters-by-path \
      --path /aws/service/aws-for-fluent-bit \
      --region us-east-1
```

AWS for Fluent Bit イメージの最新安定版は、Systems Manager パラメータストア名を参照することにより、CloudFormation テンプレート内に見つかります。次にの例を示します。

```
Parameters:
  FireLensImage:
    Description: Fluent Bit image for the FireLens Container
    Type: AWS::SSM::Parameter::Value<String>
    Default: /aws/service/aws-for-fluent-bit/stable
```

**注記**  
コマンドが失敗するか、出力がない場合、イメージはコマンドが呼び出される AWS リージョンでは使用できません。

### Server
<a name="firelens-image-ecr-windows"></a>

最新の安定している AWS for Fluent Bit イメージの URI は、次のコマンドを使用して取得できます。

```
aws ssm get-parameters \
      --names /aws/service/aws-for-fluent-bit/windowsservercore-stable \
      --region us-east-1
```

次のコマンドを使用して Systems Manager パラメータストアのパラメータをクエリすると、AWS for Fluent Bit イメージのすべてのバージョンを一覧表示できます。

```
aws ssm get-parameters-by-path \
      --path /aws/service/aws-for-fluent-bit/windowsservercore \
      --region us-east-1
```

最新の安定している AWS for Fluent Bit イメージは、Systems Manager パラメータストア名を参照することにより、CloudFormation テンプレートで参照できます。次にの例を示します。

```
Parameters:
  FireLensImage:
    Description: Fluent Bit image for the FireLens Container
    Type: AWS::SSM::Parameter::Value<String>
    Default: /aws/service/aws-for-fluent-bit/windowsservercore-stable
```

# Amazon ECS タスク定義の例: FireLens にログをルーティングする
<a name="firelens-taskdef"></a>

FireLens でカスタムログルーティングを使用するには、タスク定義で以下を指定する必要があります。
+ FireLens 設定を含むログルーターコンテナ。コンテナは `essential` とマークすることが推奨されます。
+ `awsfirelens` ログドライバーを指定するログ設定を含む 1 つ以上のアプリケーションコンテナ。
+ タスクでログをルーティングするために必要なアクセス許可を含むタスク IAM ロール の、Amazon リソースネーム (ARN)。

AWS マネジメントコンソール を使用して新しいタスク定義を作成する場合、ログルーターコンテナを簡単に追加できる FireLens 統合セクションがあります。詳細については、「[コンソールを使用した Amazon ECS タスク定義の作成](create-task-definition.md)」を参照してください。

Amazon ECS はログ設定を変換し、Fluentd または Fluent Bit 出力設定を生成します。出力設定は、`/fluent-bit/etc/fluent-bit.conf` (Fluent Bit) および `/fluentd/etc/fluent.conf` (Fluentd) のログルーティングコンテナにマウントされます。

**重要**  
FireLens は、ポート `24224` でリッスンします。したがって、FireLens ログルーターがタスクの外に到達できないようにするには、タスクが使用するセキュリティグループで、ポート `24224` での入力トラフィックを許可してはなりません。`awsvpc` ネットワークモードを使用する場合、このセキュリティグループは、タスクに関連付けられたセキュリティグループです。`host` ネットワークモードを使用する場合、これはタスクをホストする Amazon EC2 インスタンスに関連付けられているセキュリティグループです。`bridge` ネットワークモードを使用するタスクの場合、ポート `24224` を使用するポートマッピングを作成しないでください。

デフォルトでは、Amazon ECS は、ログのソースを識別するのに役立つ追加のフィールドをログエントリに追加します。
+ `ecs_cluster` - タスクが所属するクラスターの名前。
+ `ecs_task_arn` – コンテナが属しているタスクの完全な Amazon リソースネーム (ARN)。
+ `ecs_task_definition` - タスクが使用しているタスク定義名とリビジョン。
+ `ec2_instance_id` - コンテナがホストされている Amazon EC2 インスタンス ID。このフィールドは、EC2 起動タイプを使用するタスクでのみ有効です。

メタデータが必要ない場合は、`enable-ecs-log-metadata` を `false` に設定できます。

以下のタスク定義の例では、Fluent Bit を使用してログを CloudWatch Logs にルーティングするログルーターコンテナを定義しています。また、これによりアプリケーションコンテナを定義します。このコンテナでは、ログ設定を使用してログを Amazon Data Firehose にルーティングし、イベントのバッファリングに使用されるメモリを 2MiB に設定します。

**注記**  
タスク定義のその他の例については、GitHub の [Amazon ECS FireLens の例](https://github.com/aws-samples/amazon-ecs-firelens-examples)を参照してください。

```
{
  "family": "firelens-example-firehose",
  "taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role",
  "containerDefinitions": [
    {
            "name": "log_router",
            "image": "public.ecr.aws/aws-observability/aws-for-fluent-bit:3",
            "cpu": 0,
            "memoryReservation": 51,
            "portMappings": [],
            "essential": true,
            "environment": [],
            "mountPoints": [],
            "volumesFrom": [],
            "logConfiguration": {
                "logDriver": "awslogs",
                "options": {
                    "awslogs-group": "/ecs/ecs-aws-firelens-sidecar-container",
                    "mode": "non-blocking",
                    "awslogs-create-group": "true",
                    "max-buffer-size": "25m",
                    "awslogs-region": "us-east-1",
                    "awslogs-stream-prefix": "firelens"
                },
                "secretOptions": []
            },
            "systemControls": [],
            "firelensConfiguration": {
                "type": "fluentbit"
            }
        },
    {
      "essential": true,
      "image": "public.ecr.aws/docker/library/httpd:latest",
      "name": "app",
      "logConfiguration": {
        "logDriver": "awsfirelens",
        "options": {
          "Name": "firehose",
          "region": "us-west-2",
          "delivery_stream": "my-stream",
          "log-driver-buffer-limit": "1048576"
        }
      },
      "memoryReservation": 100
    }
  ]
}
```

`logConfiguration` オブジェクトのオプションとして指定されたキーバリューペアは、Fluentd または Fluent Bit 出力設定の生成に使用されます。Fluent Bit 出力定義のコード例は次のとおりです。

```
[OUTPUT]
    Name   firehose
    Match  app-firelens*
    region us-west-2
    delivery_stream my-stream
```

**注記**  
FireLens は `match` 設定を管理します。タスク定義では `match` 設定を指定しません。

## カスタム設定ファイルを使用する
<a name="firelens-taskdef-customconfig"></a>

カスタム設定ファイルを指定できます。設定ファイルの形式は、使用しているログルーターでネイティブな形式を使用します。詳細については、「[Fluentd 設定ファイルの構文](https://docs.fluentd.org/configuration/config-file)」および「[YAML 設定](https://docs.fluentbit.io/manual/administration/configuring-fluent-bit/yaml)」を参照してください。

カスタム設定ファイルでは、`bridge` または `awsvpc` ネットワークモードを使用するタスクについて、TCP 経由で Fluentd または Fluent Bit の転送入力を設定しないでください。入力設定は FireLens により追加されています。

カスタム設定ファイルを指定するには、FireLens 設定に次のオプションを含める必要があります。

`config-file-type`  
カスタム設定ファイルのソースの場所。使用できるオプションは、`s3` または `file` です。  
AWS Fargate でホストされるタスクは、`file` 設定ファイルタイプのみをサポートします。ただし、Fluent Bit init コンテナの AWS を使用して、AWS Fargate の Amazon S3 でホストされている設定ファイルを使用できます。詳細については、GitHub の「[Init process for Fluent Bit on ECS, multi-config support](https://github.com/aws/aws-for-fluent-bit/blob/mainline/use_cases/init-process-for-fluent-bit/README.md)」を参照してください。

`config-file-value`  
カスタム設定ファイルのソース。`s3` 設定ファイルタイプを使用する場合、設定ファイルの値は Amazon S3 バケットとファイルの完全な ARN です。`file` 設定ファイルタイプを使用する場合、設定ファイルのこの値は、コンテナイメージ内、またはそのコンテナにマウントされているボリューム上に存在する設定ファイルへの完全パスです。  
カスタム設定ファイルを使用する場合、FireLens が使用するパスとは異なるパスを指定する必要があります。Amazon ECS は Fluent Bit に `/fluent-bit/etc/fluent-bit.conf` ファイルパスと Fluentd に `/fluentd/etc/fluent.conf` を指定します。

次の例は、カスタム設定を指定するときに必要な構文を示しています。

**重要**  
Amazon S3 でホストされるカスタム設定ファイルを指定するには、適切なアクセス許可を持つタスク実行 IAM ロールが作成されている必要があります。

次に、カスタム設定を指定する際に必要な構文を示します。

```
{
  "containerDefinitions": [
    {
      "essential": true,
      "image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:3",
      "name": "log_router",
      "firelensConfiguration": {
        "type": "fluentbit",
        "options": {
          "config-file-type": "s3 | file",
          "config-file-value": "arn:aws:s3:::amzn-s3-demo-bucket/fluent.conf | filepath"
        }
      }
    }
  ]
}
```

**注記**  
AWS Fargate でホストされるタスクは、`file` 設定ファイルタイプのみをサポートします。ただし、Fluent Bit init コンテナの AWS を使用して、AWS Fargate の Amazon S3 でホストされている設定ファイルを使用できます。詳細については、GitHub の「[Init process for Fluent Bit on ECS, multi-config support](https://github.com/aws/aws-for-fluent-bit/blob/mainline/use_cases/init-process-for-fluent-bit/README.md)」を参照してください。

# Amazon ECS での AWS 以外のコンテナイメージの使用
<a name="private-auth"></a>

プライベートレジストリを使用して認証情報を AWS Secrets Manager に保存し、タスク定義内で参照します。これは、タスク定義で認証が必要な AWS の外部にあるプライベートレジストリーに存在するコンテナイメージを参照できます。この機能は、Amazon ECS Anywhere を使用して Fargate、Amazon EC2 インスタンス、および外部インスタンスでホストされるタスクでサポートされています。

**重要**  
タスク定義で、Amazon ECR に保存されたイメージを参照している場合、このトピックは適用されません。詳細については、*Amazon Elastic Container Registry ユーザーガイド*の「[Amazon ECS で Amazon ECR イメージを使用する](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ECR_on_ECS.html)」を参照してください。

Amazon EC2 インスタンスでホストされるタスクの場合は、この機能のためにコンテナエージェントのバージョン `1.19.0` 以降が必要です。ただし、最新のコンテナエージェントのバージョンを使用することをお勧めします。エージェントのバージョンの確認方法と最新バージョンへの更新方法については、「[Amazon ECS コンテナエージェントをアップデートする](ecs-agent-update.md)」を参照してください。

Fargate でホストされているタスクの場合、この機能にはプラットフォームバージョン `1.2.0` 以降が必要です。詳細については、「[Amazon ECS 向け Fargate プラットフォームバージョン](platform-fargate.md)」を参照してください。

コンテナの定義内で、作成したシークレットの詳細 で `repositoryCredentials` オブジェクトを指定します。参照されるシークレットは、タスクが使用するものと異なる AWS リージョン、または異なるアカウントに置くことができます。

**注記**  
Amazon ECS API、AWS CLI、または AWS SDK を使用しており、起動するタスクと同じ AWS リージョン にシークレットが存在する場合は、シークレットの完全な ARN または名前のどちらも使用可能です。シークレットが別のアカウントに存在する場合は、シークレットの完全な ARN を指定する必要があります。AWS マネジメントコンソール を使用する場合は、シークレットの完全な ARN を常に指定する必要があります。

必要なパラメータが含まれるタスク定義のスニペットを、以下に示します。

次のパラメータを置き換えます。
+ *private-repo* をプライベートリポジトリのホスト名に 
+ *private-image* をイメージ名に
+ *arn:aws:secretsmanager:region:aws\$1account\$1id:secret:secret\$1name* をシークレット Amazon リソースネーム (ARN) に

```
"containerDefinitions": [
    {
        "image": "private-repo/private-image",
        "repositoryCredentials": {
            "credentialsParameter": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name"
        }
    }
]
```

**注記**  
プライベートレジストリ認証を有効にするもうひとつの方法として、Amazon ECS コンテナエージェントの環境変数を使用してプライベートレジストリを認証する方法があります。このメソッドは、Amazon EC2 インスタンスでホストされるタスクでのみサポートされています。詳細については、「[プライベート Docker イメージ用の Amazon ECS コンテナインスタンスを設定する](private-auth-container-instances.md)」を参照してください。

**プライベートレジストリを使用するには**

1. タスク定義にはタスク実行ロールが必要です。このロールを使用して、コンテナエージェントでコンテナイメージをプルできます。詳細については、「[Amazon ECS タスク実行IAM ロール](task_execution_IAM_role.md)」を参照してください。

   プライベートレジストリ認証を使用すると、Amazon ECS タスクは、認証情報を必要とする AWS の外部 (Docker Hub、Quay.io、独自のプライベートレジストリなど) のプライベートレジストリからコンテナイメージをプルすることができます。この機能は Secrets Manager を使用してレジストリ認証情報を安全に保存し、`repositoryCredentials` パラメータを使用してタスク定義で参照します。

   プライベートレジストリ認証の設定の詳細については、「[Amazon ECS での非 AWS コンテナイメージの使用](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth.html)」を参照してください。

   プライベートレジストリ認証情報を含むシークレットにアクセスできるようにするには、以下のアクセス許可を、インラインポリシーとしてタスクの実行ロールに追加します。詳細については、「[IAM ポリシーの追加と削除](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)」を参照してください。
   + `secretsmanager:GetSecretValue`— Secrets Manager からプライベートレジストリ認証情報を取得するために必要です。
   + `kms:Decrypt` – シークレットでカスタムの KMS キーを使用し、デフォルトのキーを使用しない場合にのみ必須です。カスタムキーの Amazon リソースネーム (ARN) は、リソースとして追加する必要があります。

   次の例では、インラインポリシーによりアクセス許可を追加しています。

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "kms:Decrypt",
                   "secretsmanager:GetSecretValue"
               ],
               "Resource": [
                   "arn:aws:secretsmanager:us-east-1:111122223333:secret:secret_name",
                   "arn:aws:kms:us-east-1:111122223333:key/key_id"
               ]
           }
       ]
   }
   ```

------

1. プライベートレジストリ認証情報のシークレットを作成するには、AWS Secrets Manager を使用します。シークレットの作成方法について、詳細は「*AWS Secrets Manager ユーザーガイド*」の「[AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)」を参照してください。

   以下の形式でプライベートレジストリの認証情報を入力します。

   ```
   {
     "username" : "privateRegistryUsername",
     "password" : "privateRegistryPassword"
   }
   ```

1. タスク定義を登録する 詳細については、「[コンソールを使用した Amazon ECS タスク定義の作成](create-task-definition.md)」を参照してください。

# コンテナ再起動ポリシーを使用して Amazon ECS タスク内の個々のコンテナを再起動する
<a name="container-restart-policy"></a>

タスク定義で定義されている必須のコンテナと必須ではないコンテナそれぞれに再起動ポリシーを有効にして、一時的な障害をより迅速に克服し、タスクの可用性を維持することができます。コンテナの再起動ポリシーを有効にすると、コンテナが終了した場合、Amazon ECS はタスクを置き換えることなくコンテナを再起動できます。

再起動ポリシーは、デフォルトではコンテナに対して有効になっていません。コンテナの再起動ポリシーを有効にすると、コンテナを再起動しない終了コードを指定できます。これらは、終了コード `0` のように再起動を必要としない成功を示す終了コードである可能性があります。再起動を試みる前に、コンテナが正常に実行する必要のある時間を指定することもできます。これらのパラメータの詳細については、「[再起動ポリシー](task_definition_parameters.md#container_definition_restart_policy)」を参照してください。これらの値を指定するタスク定義の例については、「[Amazon ECS タスク定義でコンテナ再起動ポリシーを指定する](container-restart-policy-example.md)」を参照してください。

Amazon ECS タスクメタデータエンドポイントまたは CloudWatch Container Insights を使用して、コンテナが再起動した回数をモニタリングできます。タスクメタデータエンドポイントの詳細については、「[Amazon ECS タスクメタデータエンドポイントバージョン 4](task-metadata-endpoint-v4.md)」および「[Fargate のタスク用の Amazon ECS タスクメタデータエンドポイントバージョン 4](task-metadata-endpoint-v4-fargate.md)」を参照してください。Amazon ECS Container Insights メトリクスの一覧については、「*Amazon CloudWatch ユーザーガイド*」の「[Amazon ECS Container Insights メトリクス](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Container-Insights-metrics-ECS.html)」を参照してください。

コンテナ再起動ポリシーは、Fargate、Amazon EC2 インスタンスに加えて、Amazon ECS Anywhere を使用する外部インスタンスでホストされるタスクでサポートされています。

## 考慮事項
<a name="container-restart-policy-considerations"></a>

コンテナの再起動ポリシーを有効にする前に、次の点を考慮してください。
+ Fargate の Windows コンテナでは、再起動ポリシーはサポートされません。
+ Amazon EC2 インスタンスでホストされるタスクの場合は、この機能のためにコンテナエージェントのバージョン `1.86.0` 以降が必要です。ただし、最新のコンテナエージェントのバージョンを使用することをお勧めします。エージェントのバージョンの確認方法と最新バージョンへの更新方法については、「[Amazon ECS コンテナエージェントをアップデートする](ecs-agent-update.md)」を参照してください。
+ `bridge` ネットワークモードの EC2 を使用している場合、FireLens ログルーターコンテナ (コンテナ定義に `firelensConfiguration` オブジェクトがあるコンテナ) を再起動した後で、アプリケーションコンテナの `FLUENT_HOST` 環境変数が不正確になる可能性があります。これは、`FLUENT_HOST` が動的 IP アドレスであり、再起動後に変更される場合があるためです。アプリケーションコンテナから `FLUENT_HOST` IP アドレスへの直接的なロギングは、アドレスの変更後に失敗することがあります。の詳細については、「`FLUENT_HOST`」を参照してください。[高スループットの Amazon ECS ログの設定](firelens-docker-buffer-limit.md)
+ Amazon ECS エージェントは、コンテナの再起動ポリシーを処理します。予期しない理由で Amazon ECS エージェントが失敗するか実行されなくなったりすると、コンテナは再起動されません。
+  ポリシーで定義された再起動試行期間は、Amazon ECS がコンテナを再起動するまでにコンテナが実行される必要のある期間 (秒単位) を決定します。

# Amazon ECS タスク定義でコンテナ再起動ポリシーを指定する
<a name="container-restart-policy-example"></a>

タスク定義でコンテナの再起動ポリシーを指定するには、コンテナ定義内で `restartPolicy` オブジェクトを指定します。`restartPolicy` オブジェクトの詳細については、「[再起動ポリシー](task_definition_parameters.md#container_definition_restart_policy)」を参照してください。

以下は、Web サーバーをセットアップするために、Fargate で Linux コンテナを使用するタスク定義です。コンテナ定義には、コンテナの再起動ポリシーを有効にするために `enabled` が true に設定された `restartPolicy` オブジェクトが含まれています。コンテナは再起動する前に 180 秒間実行する必要があります。成功を示す終了コード `0` で終了した場合、コンテナは再起動しません。

```
{
  "containerDefinitions": [
    {
      "command": [
        "/bin/sh -c \"echo '<html> <head> <title>Amazon ECS Sample App</title> <style>body {margin-top: 40px; background-color: #333;} </style> </head><body> <div style=color:white;text-align:center> <h1>Amazon ECS Sample App</h1> <h2>Congratulations!</h2> <p>Your application is now running on a container in Amazon ECS.</p> </div></body></html>' >  /usr/local/apache2/htdocs/index.html && httpd-foreground\""
      ],
      "entryPoint": ["sh", "-c"],
      "essential": true,
      "image": "public.ecr.aws/docker/library/httpd:2.4",
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/fargate-task-definition",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      },
      "name": "sample-fargate-app",
      "portMappings": [
        {
          "containerPort": 80,
          "hostPort": 80,
          "protocol": "tcp"
        }
      ],
      "restartPolicy": {
        "enabled": true,
        "ignoredExitCodes": [0],
        "restartAttemptPeriod": 180
      }
    }
  ],
  "cpu": "256",
  "executionRoleArn": "arn:aws:iam::012345678910:role/ecsTaskExecutionRole",
  "family": "fargate-task-definition",
  "memory": "512",
  "networkMode": "awsvpc",
  "runtimePlatform": {
    "operatingSystemFamily": "LINUX"
  },
  "requiresCompatibilities": ["FARGATE"]
}
```

コンテナ定義で `restartPolicy` オブジェクトを含むタスク定義を登録した後、そのタスク定義でタスクを実行するか、サービスを作成することができます。詳細については、「[Amazon ECS タスクとしてのアプリケーションの実行](standalone-task-create.md)」および「[Amazon ECS のローリング更新デプロイの作成](create-service-console-v2.md)」を参照してください。

# Amazon ECS コンテナに機密データを渡す
<a name="specifying-sensitive-data"></a>

認証情報などの機密データを、コンテナ内のデータベースなどに安全に渡すことができます。

API キーやデータベース認証情報などのシークレットは、アプリケーションが他のシステムにアクセスするためによく使用されます。多くの場合、ユーザー名とパスワード、証明書、または API キーで構成されます。これらのシークレットへのアクセスは、IAM を使用する特定の IAM プリンシパルに限定され、またランタイムにコンテナに挿入される必要があります。

シークレットは、AWS Secrets Manager または Amazon EC2 Systems Manager Parameter Store からコンテナにシームレスに挿入できます。これらのシークレットは、タスク内で以下のいずれかとして参照できます。

1. `secrets` コンテナ定義パラメータを使用する環境変数として参照されます。

1. ロギングプラットフォームが認証を必要とする場合、`secretOptions` として参照されます。詳細については、「[ログの設定オプション](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LogConfiguration.html#API_LogConfiguration_Contents)」を参照してください。

1. コンテナの取得元のレジストリーが認証を必要とする場合、これらは、`repositoryCredentials` コンテナ定義パラメータを使用するイメージによって取得されるシークレットとして参照されます。Amazon ECR Public Gallery からイメージを取得するときは、この方法を使用してください。詳細については、「[タスクのプライベートレジストリの認証](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth.html)」を参照してください。

シークレットの管理を設定するときは、次を行うことをお勧めします。

## シークレットマテリアルの保存に AWS Secrets Manager または AWS Systems Manager Parameter Store を使用する
<a name="security-secrets-management-recommendations-storing-secret-materials"></a>

API キー、データベース認証情報、およびその他のシークレットマテリアルは、Secrets Manager または暗号化されたパラメータとして Systems Manager Parameter Store に安全に保存する必要があります。これらのサービスは、どちらも AWS KMS を使用して機密データを暗号化する管理されたキー値ストアである点で似ています。ただし、Secrets Manager には、シークレットを自動的にローテーションし、ランダムなシークレットを生成し、アカウント間でシークレットを共有する機能も含まれています。これらの機能を利用するには、Secrets Manager を使用します。それ以外の場合は、Systems Manager パラメータストアで暗号化されたパラメータを使用します。

**重要**  
シークレットが変更された場合は、新しいデプロイを強制するか、新しいタスクを起動して最新のシークレット値を取得する必要があります。詳細については、以下の各トピックを参照してください。  
タスク - タスクを停止してから開始します。詳細については、「[Amazon ECS タスクの停止](standalone-task-stop.md)」および「[Amazon ECS タスクとしてのアプリケーションの実行](standalone-task-create.md)」を参照してください。
サービス - サービスを更新し、[新しいデプロイの強制] オプションを使用します。詳細については、「[Amazon ECS サービスを更新する](update-service-console-v2.md)」を参照してください。

## 暗号化された Amazon S3 バケットからデータを取得する
<a name="security-secrets-management-recommendations-encrypted-s3-buckets"></a>

暗号化された Amazon S3 バケットにシークレットを保存し、タスクロールを使用してそのシークレットへのアクセスを制限する必要があります。こうすることで、`docker inspect` の実行時に環境変数の値が誤ってログに漏れて公開されるのを防ぐことができます。これを行う場合、Amazon S3 バケットからシークレットを読み取るようにアプリケーションを作成する必要があります。手順については、「[Amazon S3 バケット向けのサーバー側のデフォルトの暗号化動作の設定](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-encryption.html)」を参照してください。

## サイドカーコンテナを使用してシークレットをボリュームにマウントする
<a name="security-secrets-management-recommendations-mount-secret-volumes"></a>

環境変数はデータ漏えいのリスクが高いため、AWS Secrets Manager からシークレットを読みとり、共有ボリュームに書き込むサイドカーコンテナを実行する必要があります。このコンテナは、[Amazon ECS コンテナの順序付け](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDependency.html)を使用することでアプリケーションコンテナより先に実行して終了できます。これを行うと、アプリケーションコンテナでシークレットが書き込まれたボリュームが後からマウントされます。Amazon S3 バケットメソッドと同様に、共有ボリュームからシークレットを読み取るようにアプリケーションを作成する必要があります。ボリュームの範囲はタスクに限定されるため、タスクが停止するとボリュームは自動的に削除されます。例については、[Task-def.json](https://github.com/aws-samples/aws-secret-sidecar-injector/blob/master/ecs-task-def/task-def.json) プロジェクトを参照してください。

Amazon EC2 では、シークレットが書き込まれるボリュームは、AWS KMS カスタマーマネージドキーで暗号化できます。AWS Fargate では、ボリュームストレージはサービスマネージドキーを使用して自動的に暗号化されます。

# 個々の環境変数を Amazon ECS コンテナに渡す
<a name="taskdef-envfiles"></a>

**重要**  
機密データは、AWS Secrets Manager secrets または AWS Systems Manager Parameter Store のパラメータに保存することをお勧めします。詳細については、「[Amazon ECS コンテナに機密データを渡す](specifying-sensitive-data.md)」を参照してください。  
タスク定義で指定された環境変数は、許可されたすべてのユーザーとロールが、タスク定義の `DescribeTaskDefinition` アクションを読み取ることができます。

環境変数は、以下の方法でコンテナに渡すことができます。
+ `environment` コンテナ定義パラメータを個別に使用します。これは、[https://docs.docker.com/reference/cli/docker/container/run/](https://docs.docker.com/reference/cli/docker/container/run/) の `--env` オプションにマッピングされます。
+ `environmentFiles` コンテナ定義パラメータを使用して、環境変数を含む 1 つ以上のファイルを一括で一覧表示します。ファイルは、Amazon S3 でホストされている必要があります。これは、[https://docs.docker.com/reference/cli/docker/container/run/](https://docs.docker.com/reference/cli/docker/container/run/) の `--env-file` オプションにマッピングされます。

以下は、個々の環境変数の指定方法を示すタスク定義のスニペットです。

```
{
    "family": "",
    "containerDefinitions": [
        {
            "name": "",
            "image": "",
            ...
            "environment": [
                {
                    "name": "variable",
                    "value": "value"
                }
            ],
            ...
        }
    ],
    ...
}
```

# 環境変数を Amazon ECS コンテナに渡す
<a name="use-environment-file"></a>

**重要**  
機密データは、AWS Secrets Manager secrets または AWS Systems Manager Parameter Store のパラメータに保存することをお勧めします。詳細については、「[Amazon ECS コンテナに機密データを渡す](specifying-sensitive-data.md)」を参照してください。  
環境変数ファイルは Amazon S3 のオブジェクトのため、Amazon S3 のセキュリティに関するすべての考慮事項が適用されます。  
Fargate の Windows コンテナと Windows コンテナでは、`environmentFiles` パラメータを使用できません。

環境変数ファイルを作成して Amazon S3 に保存し、環境変数をコンテナに渡すことができます。

ファイルに環境変数を指定することで、環境変数を一括で挿入できます。コンテナ定義内で、環境変数ファイルを含む `environmentFiles` バケットのリストを使用して Amazon S3 オブジェクトを指定します。

Amazon ECS は環境変数にサイズ制限を適用しませんが、環境変数ファイルが大きいとディスク容量が一杯になってしまう可能性があります。環境変数ファイルを使用する各タスクは、ファイルのコピーをディスクにダウンロードします。Amazon ECS は、タスクのクリーンアップの一環としてファイルを削除します。

サポートされている環境変数については、「[高度なコンテナ定義パラメータ - 環境](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_environment)」を参照してください。

コンテナ定義で環境変数ファイルを指定する際には、以下の点を考慮してください。
+ Amazon EC2 上の Amazon ECS タスクでこの機能を使用するには、コンテナインスタンスにバージョン `1.39.0` 以降のコンテナエージェントが必要です。エージェントのバージョンの確認方法と最新バージョンへの更新方法については、「[Amazon ECS コンテナエージェントをアップデートする](ecs-agent-update.md)」を参照してください。
+ AWS Fargate 上のAmazon ECS タスクでは、この機能を使用するには、タスクでプラットフォームバージョン `1.4.0` 以降 (Linux) を使用する必要があります。詳細については、「[Amazon ECS 向け Fargate プラットフォームバージョン](platform-fargate.md)」を参照してください。

  変数がオペレーティングシステムプラットフォームでサポートされていることを確認します。詳細については、「[コンテナ定義](task_definition_parameters.md#container_definitions)」および「[その他のタスク定義パラメータ](task_definition_parameters.md#other_task_definition_params)」を参照してください。
+ ファイルには、ファイル拡張子 `.env` と UTF-8 エンコーディングを使用する必要があります。
+ タスク実行ロールは、Amazon S3 の追加アクセス許可でこの機能を使用するのに必要です。これにより、コンテナエージェントは Amazon S3 から環境変数ファイルをプルできます。詳細については、「[Amazon ECS タスク実行IAM ロール](task_execution_IAM_role.md)」を参照してください。
+ 1 つのタスク定義につき 10 ファイルという制限があります。
+ 環境ファイルの各行には、`VARIABLE=VALUE` 形式で環境変数を含む必要があります。スペースまたは引用符は、Amazon ECS ファイルの値の一部として**含まれます**。`#` で始まる行はコメントとして扱われ、無視されます。環境変数ファイルの構文の詳細については、Docker ドキュメントの「[Set environment variables (-e, --env, --env-file)](https://docs.docker.com/reference/cli/docker/container/run/#env)」を参照してください。

  次に、適切な構文を示します。

  ```
  #This is a comment and will be ignored
  VARIABLE=VALUE
  ENVIRONMENT=PRODUCTION
  ```
+ コンテナ定義に `environment` パラメータを使用して環境変数が指定されている場合は、環境ファイルに含まれる変数よりも優先されます。
+ 同じ変数を含む複数の環境ファイルが指定されている場合、それらのファイルは入力順に処理されます。これは、変数の最初の値が使用され、重複する変数の後続の値は無視されることを意味します。一意の変数名を使用することをお勧めします。
+ 環境ファイルがコンテナをオーバーライドするように指定されている場合、そのファイルが適用されます。さらに、コンテナ定義で指定されているその他の環境ファイルは、すべて無視されます。
+ Fargate には次のルールが適用されます。
  + このファイルはネイティブの Docker env ファイルと同様に処理されます。
  + 空白で Amazon S3 に保存されている環境変数を参照するコンテナ定義は、コンテナに表示されません。
  + シェルエスケープ処理はサポートされていません。
  + コンテナのエントリポイントが `VARIABLE` 値を解釈します。

## 例
<a name="environment-file-example"></a>

以下は、環境変数ファイルの指定方法を示すタスク定義のスニペットを示します。

```
{
    "family": "",
    "containerDefinitions": [
        {
            "name": "",
            "image": "",
            ...
            "environmentFiles": [
                {
                    "value": "arn:aws:s3:::amzn-s3-demo-bucket/envfile_object_name.env",
                    "type": "s3"
                }
            ],
            ...
        }
    ],
    ...
}
```

# Amazon ECS で Secrets Manager シークレットをプログラムで伝達する
<a name="secrets-app-secrets-manager"></a>

アプリケーション内でプレーンテキストの機密情報をハードコーディングする代わりに、Secrets Manager を使用して機密データを保存することができます。

機密データの取得にはこの方法が推奨されます。これにより、以後、Secrets Manager のシークレットが更新された場合には、アプリケーションが自動的に最新バージョンのシークレットを取得するようになります。

Secrets Manager でシークレットを作成します。Secrets Manager シークレットの作成後、アプリケーションコードを更新して、そのシークレットを取得します。

Secrets Manager で機密データの保護を行う前に、以下の考慮事項を確認してください。
+ [CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html) API の `SecretString` パラメータで作成されたシークレットであるテキストデータを格納するシークレットのみがサポートされます。[CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html) API の `SecretBinary` パラメータで作成されたシークレットであるバイナリデータを格納するシークレットはサポートされていません。
+ セキュリティ制御を強化するために、インターフェイス VPC エンドポイントを使用します。Secrets Manager 用に、インターフェイス VPC エンドポイントを作成する必要があります。VPC エンドポイントについて、詳細は「*AWS Secrets Manager ユーザーガイド*」の「[VPC エンドポイントの作成](https://docs.aws.amazon.com/secretsmanager/latest/userguide/setup-create-vpc.html)」を参照してください。
+ タスクで使用する VPC は、DNS 解決を使用している必要があります。
+ タスク定義では、Secrets Manager の追加アクセス許可を持つタスク ロールを使用する必要があります。詳細については、「[Amazon ECS タスクの IAM ロール](task-iam-roles.md)」を参照してください。

## Secrets Manager シークレットを作成する
<a name="secrets-app-secrets-manager-create-secret"></a>

Secrets Manager コンソールを使用して、機密データ用のシークレットを作成できます。シークレットの作成方法について、詳細は「*AWS Secrets Manager ユーザーガイド*」の「[AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)」を参照してください。

## Secrets Manager シークレットをプログラムにより取得するようにアプリケーションを更新する
<a name="secrets-app-secrets-manager-update-app"></a>

アプリケーションから直接 Secrets Manager API を呼び出し、シークレットを取得することができます。詳細は「*AWS Secrets Manager ユーザーガイド*」の「[AWS Secrets Manager からのシークレットの取得](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html)」を参照してください。

AWS Secrets Manager に保存されている機密データを取得するには、*AWS SDK コードサンプルコードライブラリ*の「[AWS SDK を使用する AWS Secrets Manager のコードサンプル](https://docs.aws.amazon.com/code-library/latest/ug/secrets-manager_code_examples.html)」を参照してください。

# Amazon ECS で Systems Manager Parameter Store シークレットをプログラムで伝達する
<a name="secrets-app-ssm-paramstore"></a>

Systems Manager Parameter Store により、シークレットの安全な保管および管理ができます。パスワード、データベース文字列、EC2 インスタンス ID、AMI ID、ライセンスコードなどのデータをアプリケーションにハードコートする代わりに、パラメータ値として保存できます。値はプレーンテキストまたは暗号化されたデータとして保存できます。

機密データの取得にはこの方法が推奨されます。これにより、以後、Secrets Manager Parameter Store のパラメータが更新された場合にアプリケーションが自動的に最新バージョンを取得するようになります。

Systems Manager Parameter Store で機密データの保護を行う前に、以下の考慮事項を確認してください。
+ テキストデータを格納するシークレットのみがサポートされます。バイナリデータを格納するシークレットはサポートされません。
+ セキュリティ制御を強化するために、インターフェイス VPC エンドポイントを使用します。
+ タスクで使用する VPC は、DNS 解決を使用している必要があります。
+ EC2 を使用するタスクでは、この機能を使用するのに Amazon ECS エージェント設定変数 `ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE=true` を使用する必要があります。コンテナインスタンスの作成時に `/etc/ecs/ecs.config` ファイルに追加するか、既存のインスタンスに追加して ECS エージェントを再起動できます。詳細については、「[Amazon ECS コンテナエージェントの設定](ecs-agent-config.md)」を参照してください。
+ タスク定義では、Systems Manager パラメーター ストアに対する追加のアクセス許可を持つタスク ロールを使用する必要があります。詳細については、「[Amazon ECS タスクの IAM ロール](task-iam-roles.md)」を参照してください。

## パラメータを作成する
<a name="secrets-app-ssm-paramstore-create-secret"></a>

Systems Manager コンソールを使用すると、機密データ用に Systems Manager Parameter Store のパラメータを作成できます。詳細は「*AWS Systems Manager ユーザーガイド*」の「[Systems Manager パラメータを作成する (コンソール)](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-create-console.html)」または「[Systems Manager パラメータを作成する (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/param-create-cli.html)」を参照してください。

## Systems Manager Parameter Store のシークレットをプログラムで取得するようにアプリケーションを更新する
<a name="secrets-app-ssm-paramstore-update-app"></a>

Systems Manager Parameter Store のパラメータに保存されている機密データを取得するには、*AWS SDK コードサンプルコードライブラリ*の「[AWS SDK を使用した Systems Manager のコードサンプル](https://docs.aws.amazon.com/code-library/latest/ug/ssm_code_examples.html)」を参照してください。

# Amazon ECS 環境変数経由で Secrets Manager シークレットを伝達する
<a name="secrets-envvar-secrets-manager"></a>

シークレットを環境変数として挿入する場合、シークレットの内容全体、シークレット内の特定の JSON キーを指定できます。これは、コンテナに公開される機密データの制御に役立ちます。シークレットのバージョニングについて、詳細は「*AWS Secrets Manager ユーザーガイド*」の「[Secrets Manager シークレットの内容](https://docs.aws.amazon.com/secretsmanager/latest/userguide/whats-in-a-secret.html#term_version)」を参照してください。

環境変数を使用して Secrets Manager シークレットをコンテナに挿入する場合は、以下を考慮する必要があります。
+ 重要なデータは、コンテナが最初に開始されたときにコンテナに挿入されます。シークレットを後で更新またはローテーションすると、コンテナには更新された値が自動的に送信されなくなります。この場合は、新しいタスクを起動する必要があります。または、タスクがサービスの一部である場合は、サービスを更新し、**[Force new deployment]** (新しいデプロイの強制) オプションを使用して、新しいタスクの起動をサービスに強制できます。
+ コンテナとコンテナログ、およびデバッグツールで実行されるアプリケーションは、環境変数にアクセスできます。
+ AWS Fargate 上の Amazon ECS タスクでは、以下の点を考慮してください。
  + シークレットの内容全体を環境変数として挿入したり、ログ設定にシークレットを挿入したりするには、プラットフォームバージョン `1.3.0` 以降を使用する必要があります。詳細については、「[Amazon ECS 向け Fargate プラットフォームバージョン](platform-fargate.md)」を参照してください。
  + 特定の JSON キーまたはシークレットのバージョンを環境変数またはログ設定に挿入するには、プラットフォームバージョン `1.4.0` 以降 (Linux) または `1.0.0` (Windows) を使用する必要があります。詳細については、「[Amazon ECS 向け Fargate プラットフォームバージョン](platform-fargate.md)」を参照してください。
+ EC2 上の Amazon ECS タスクでは、以下の点を考慮する必要があります。
  + シークレットの特定の JSON キーやバージョンを使用してシークレットを挿入するには、コンテナインスタンスにバージョン `1.37.0` 以降のコンテナエージェントが必要です。ただし、最新のコンテナエージェントのバージョンを使用することをお勧めします。エージェントのバージョンの確認と最新バージョンへの更新については、「[Amazon ECS コンテナエージェントをアップデートする](ecs-agent-update.md)」を参照してください。

    シークレットの内容全体を環境変数として挿入したり、ログ設定にシークレットを挿入したりするには、コンテナインスタンスにバージョン `1.22.0` 以降のコンテナエージェントが必要です。
+ インターフェイス VPC エンドポイントを使用してセキュリティコントロールを強化し、プライベートサブネットを介して Secrets Manager に接続します。Secrets Manager 用に、インターフェイス VPC エンドポイントを作成する必要があります。VPC エンドポイントについて、詳細は「*AWS Secrets Manager ユーザーガイド*」の「[VPC エンドポイントの作成](https://docs.aws.amazon.com/secretsmanager/latest/userguide/setup-create-vpc.html)」を参照してください。Secrets Manager と Amazon VPC の使用の詳細については、「[How to connect to Secrets Manager service within a Amazon VPC](https://aws.amazon.com/blogs//security/how-to-connect-to-aws-secrets-manager-service-within-a-virtual-private-cloud/)」を参照してください。
+ `awslogs` ログドライバーを使用するように設定された Windows タスクの場合は、コンテナインスタンスで `ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE` 環境変数も設定する必要があります。次の構文を使用します。

  ```
  <powershell>
  [Environment]::SetEnvironmentVariable("ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE", $TRUE, "Machine")
  Initialize-ECSAgent -Cluster <cluster name> -EnableTaskIAMRole -LoggingDrivers '["json-file","awslogs"]'
  </powershell>
  ```
+ タスク定義では、Secrets Manager の追加アクセス許可を持つタスク実行ロールを使用する必要があります。詳細については、「[Amazon ECS タスク実行IAM ロール](task_execution_IAM_role.md)」を参照してください。

## AWS Secrets Manager シークレットを作成する
<a name="secrets-envvar-secrets-manager-create-secret"></a>

Secrets Manager コンソールを使用して、機密データ用のシークレットを作成できます。詳細については、*AWS Secrets Manager ユーザーガイド*の「[Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)」を参照してください。

## コンテナ定義に環境変数を追加します。
<a name="secrets-envvar-secrets-manager-update-container-definition"></a>

コンテナの定義内では、以下を指定できます。
+ コンテナに設定する環境変数の名前が含まれている `secrets` オブジェクト
+ Secrets Manager シークレットの Amazon リソースネーム (ARN)。
+ コンテナに渡す機密データが含まれている追加のパラメータ

次の例は、Secrets Manager シークレットに指定する必要がある完全な構文を示しています。

```
arn:aws:secretsmanager:region:aws_account_id:secret:secret-name:json-key:version-stage:version-id
```

次のセクションでは、追加のパラメータについて説明します。追加のパラメータはオプションですが、これらを使用しないでデフォルト値を使用する場合は、コロン `:` を含める必要があります。以下の例でより詳細なコンテキストを示します。

`json-key`  
キーと値のペアのキーの名前を指定します。値は設定する環境変数の値です。JSON 形式の値のみがサポートされます。JSON キーを指定しないと、シークレットの内容全体が使用されます。

`version-stage`  
使用するシークレットのバージョンのステージングラベルを指定します。バージョンのステージングラベルを指定した場合、バージョン ID は指定できません。バージョンのステージを指定しないと、デフォルトの動作として、`AWSCURRENT` ステージングラベルのシークレットが取得されます。  
ステージングラベルは、シークレットが更新またはローテーションされたときに、シークレットのさまざまなバージョンを追跡するために使用します。シークレットの各バージョンには、1 つ以上のステージングラベルと 1 つの ID があります。

`version-id`  
使用するシークレットのバージョンの固有 ID を指定します。バージョン ID を指定した場合、バージョンのステージングラベルは指定できません。バージョン ID を指定しないと、デフォルトの動作として、`AWSCURRENT` ステージングラベルのシークレットが取得されます。  
バージョン ID は、シークレットが更新またはローテーションされたときに、シークレットのさまざまなバージョンを追跡するために使用します。シークレットの各バージョンには ID があります。詳細については、*AWS Secrets Managerユーザーガイド*の「[AWS Secrets Managerの主な用語と概念](https://docs.aws.amazon.com/secretsmanager/latest/userguide/terms-concepts.html#term_secret)」を参照してください。

### コンテナの定義の例
<a name="secrets-examples"></a>

以下の例では、コンテナの定義で Secrets Manager シークレットを参照する方法を示します。

**Example シークレット全体を参照する**  
次に示すのは、Secrets Manager シークレットのテキスト全体を参照するときの形式を示すタスク定義のスニペットです。  

```
{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-AbCdEf"
    }]
  }]
}
```
コンテナ内から、このシークレットの値にアクセスするには、`$environment_variable_name` を呼び出します。

**Example シークレット全体を参照する**  
次に示すのは、複数の Secrets Manager シークレットのテキスト全体を参照するときの形式を示すタスク定義のスニペットです。  

```
{
  "containerDefinitions": [{
     "secrets": [
      {
        "name": "environment_variable_name1",
         "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-AbCdEf"
      },
      {
        "name": "environment_variable_name2",
         "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-abcdef"
      },
      {
        "name": "environment_variable_name3",
        "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-ABCDEF"
      }
    ]
  }]
}
```
コンテナ内から、このシークレットの値にアクセスするには、`$environment_variable_name1`、`$environment_variable_name2`、`$environment_variable_name3` を呼び出します。

**Example シークレット内の特定のキーを参照する**  
次に示すのは、シークレットの内容と、シークレットに関連付けられているバージョンのステージングラベルおよびバージョン ID を表示する [get-secret-value](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/get-secret-value.html) コマンドの出力例です。  

```
{
    "ARN": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf",
    "Name": "appauthexample",
    "VersionId": "871d9eca-18aa-46a9-8785-981ddEXAMPLE",
    "SecretString": "{\"username1\":\"password1\",\"username2\":\"password2\",\"username3\":\"password3\"}",
    "VersionStages": [
        "AWSCURRENT"
    ],
    "CreatedDate": 1581968848.921
}
```
前のコンテナの定義の出力で特定のキーを参照するには、ARN の最後にキー名を指定します。  

```
{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:username1::"
    }]
  }]
}
```

**Example 特定のシークレットバージョンを参照する**  
次に示すのは、シークレットの暗号化されていない内容と、シークレットのすべてのバージョンのメタデータを表示する [describe-secret](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/describe-secret.html) コマンドの出力例です。  

```
{
    "ARN": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf",
    "Name": "appauthexample",
    "Description": "Example of a secret containing application authorization data.",
    "RotationEnabled": false,
    "LastChangedDate": 1581968848.926,
    "LastAccessedDate": 1581897600.0,
    "Tags": [],
    "VersionIdsToStages": {
        "871d9eca-18aa-46a9-8785-981ddEXAMPLE": [
            "AWSCURRENT"
        ],
        "9d4cb84b-ad69-40c0-a0ab-cead3EXAMPLE": [
            "AWSPREVIOUS"
        ]
    }
}
```
前のコンテナの定義の出力で特定のバージョンのステージングラベルを参照するには、ARN の最後にキー名を指定します。  

```
{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf::AWSPREVIOUS:"
    }]
  }]
}
```
前のコンテナの定義の出力で特定のバージョン ID を参照するには、ARN の最後にキー名を指定します。  

```
{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:::9d4cb84b-ad69-40c0-a0ab-cead3EXAMPLE"
    }]
  }]
}
```

**Example シークレットの特定のキーおよびバージョンのステージングラベルを参照する**  
シークレット内の特定のキーと特定のバージョンのステージングラベルの両方を参照する方法は次のとおりです。  

```
{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:username1:AWSPREVIOUS:"
    }]
  }]
}
```
特定のキーとバージョン ID を指定するには、次の構文を使用します。  

```
{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:username1::9d4cb84b-ad69-40c0-a0ab-cead3EXAMPLE"
    }]
  }]
}
```

環境変数で指定されたシークレットを使用してタスク定義を作成する方法については、「[コンソールを使用した Amazon ECS タスク定義の作成](create-task-definition.md)」を参照してください。

# Amazon ECS 環境変数を使用して Systems Manager パラメータを伝達する
<a name="secrets-envvar-ssm-paramstore"></a>

Amazon ECS を使用すると、AWS Systems Manager Parameter Store のパラメータに機密データを保存した上で、コンテナの定義からそれを参照することによって、コンテナに機密データを取り込むことができます。

環境変数を使用して、コンテナに Systems Manager シークレットを注入する場合は、以下を考慮する必要があります。
+ 重要なデータは、コンテナが最初に開始されたときにコンテナに挿入されます。シークレットを後で更新またはローテーションすると、コンテナには更新された値が自動的に送信されなくなります。この場合は、新しいタスクを起動する必要があります。または、タスクがサービスの一部である場合は、サービスを更新し、**[Force new deployment]** (新しいデプロイの強制) オプションを使用して、新しいタスクの起動をサービスに強制できます。
+ AWS Fargate 上の Amazon ECS タスクでは、以下の点を考慮する必要があります。
  + シークレットの内容全体を環境変数として挿入したり、ログ設定にシークレットを挿入したりするには、プラットフォームバージョン `1.3.0` 以降を使用する必要があります。詳細については、「[Amazon ECS 向け Fargate プラットフォームバージョン](platform-fargate.md)」を参照してください。
  + 特定の JSON キーまたはシークレットのバージョンを環境変数またはログ設定に挿入するには、プラットフォームバージョン `1.4.0` 以降 (Linux) または `1.0.0` (Windows) を使用する必要があります。詳細については、「[Amazon ECS 向け Fargate プラットフォームバージョン](platform-fargate.md)」を参照してください。
+ EC2 上の Amazon ECS タスクでは、以下の点を考慮する必要があります。
  + シークレットの特定の JSON キーやバージョンを使用してシークレットを挿入するには、コンテナインスタンスにバージョン `1.37.0` 以降のコンテナエージェントが必要です。ただし、最新のコンテナエージェントのバージョンを使用することをお勧めします。エージェントのバージョンの確認と最新バージョンへの更新については、「[Amazon ECS コンテナエージェントをアップデートする](ecs-agent-update.md)」を参照してください。

    シークレットの内容全体を環境変数として挿入したり、ログ設定にシークレットを挿入したりするには、コンテナインスタンスにバージョン `1.22.0` 以降のコンテナエージェントが必要です。
+ セキュリティ制御を強化するために、インターフェイス VPC エンドポイントを使用します。Systems Manager 用に、インターフェイス VPC エンドポイントを作成する必要があります。VPC エンドポイントについては、「AWS Systems Manager ユーザーガイド」の「[Systems Manager のために VPC エンドポイントを使用して EC2 インスタンスのセキュリティを強化する](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-create-vpc.html)」を参照してください。**
+ タスク定義では、Systems Manager パラメーター ストアに対する追加のアクセス許可を持つタスク実行ロールを使用する必要があります。詳細については、「[Amazon ECS タスク実行IAM ロール](task_execution_IAM_role.md)」を参照してください。
+ `awslogs` ログドライバーを使用するように設定された Windows タスクの場合は、コンテナインスタンスで `ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE` 環境変数も設定する必要があります。次の構文を使用します。

  ```
  <powershell>
  [Environment]::SetEnvironmentVariable("ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE", $TRUE, "Machine")
  Initialize-ECSAgent -Cluster <cluster name> -EnableTaskIAMRole -LoggingDrivers '["json-file","awslogs"]'
  </powershell>
  ```

## Systems Manager パラメータを作成する
<a name="secrets-envvar-ssm-paramstore-create-parameter"></a>

Systems Manager コンソールを使用すると、機密データ用に Systems Manager Parameter Store のパラメータを作成できます。詳細は「*AWS Systems Manager ユーザーガイド*」の「[Systems Manager パラメータを作成する (コンソール)](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-create-console.html)」または「[Systems Manager パラメータを作成する (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/param-create-cli.html)」を参照してください。

## コンテナ定義に環境変数を追加します。
<a name="secrets-ssm-paramstore-update-container-definition"></a>

タスク定義でのコンテナ定義内では、コンテナに設定する環境変数の名前と、コンテナに渡す機密データが含まれている Systems Manager Parameter Store パラメータの ARN 全体を使用して `secrets` を指定します。詳細については、「[secrets](task_definition_parameters.md#ContainerDefinition-secrets)」を参照してください。

以下に示すのは、Systems Manager パラメータストアのパラメータを参照するときの形式を示すタスク定義のスニペットです。起動するタスクと同じリージョンに Systems Manager パラメータストアのパラメータが存在する場合は、パラメータの完全な ARN または名前のどちらも使用できます。パラメータが別のリージョンに存在する場合は、完全な ARN を指定する必要があります。

```
{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name"
    }]
  }]
}
```

環境変数で指定されたシークレットを使用してタスク定義を作成する方法については、「[コンソールを使用した Amazon ECS タスク定義の作成](create-task-definition.md)」を参照してください。

## Systems Manager Parameter Store のシークレットをプログラムで取得するようにアプリケーションを更新する
<a name="secrets-ssm-paramstore-update-app"></a>

Systems Manager Parameter Store のパラメータに保存されている機密データを取得するには、*AWS SDK コードサンプルコードライブラリ*の「[AWS SDK を使用した Systems Manager のコードサンプル](https://docs.aws.amazon.com/code-library/latest/ug/ssm_code_examples.html)」を参照してください。

# Amazon ECS ログ記録設定のシークレットを伝達する
<a name="secrets-logconfig"></a>

`logConfiguration` に `secretOptions` パラメータを使用することで、ロギングに使用される機密データを渡すことができます。

シークレットは Secrets Manager または Systems Manager に保存できます。

## Secrets Manager を使用する
<a name="secrets-logconfig-secrets-manager"></a>

コンテナの定義内で `logConfiguration` を指定するときに、コンテナに設定するログドライバーオプションの名前と、コンテナに渡す機密データが含まれている Secrets Manager シークレットの ARN 全体を使用して `secretOptions` を指定できます。シークレットの作成の詳細については、「[AWS Secrets Manager の作成](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)」を参照してください。

以下に示すのは、Secrets Manager シークレットを参照するときの形式を示すタスク定義のスニペットです。

```
{
  "containerDefinitions": [{
    "logConfiguration": [{
      "logDriver": "splunk",
      "options": {
        "splunk-url": "https://your_splunk_instance:8088"
      },
      "secretOptions": [{
        "name": "splunk-token",
        "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-AbCdEf"
      }]
    }]
  }]
}
```

## コンテナ定義に環境変数を追加します。
<a name="secrets-envvar-ssm-paramstore-update-container-definition"></a>

コンテナの定義内で、コンテナに設定する環境変数の名前と、コンテナに渡す機密データが含まれている Systems Manager パラメータストアのパラメータの ARN 全体を使用して `secrets` を指定できます。詳細については、「[secrets](task_definition_parameters.md#ContainerDefinition-secrets)」を参照してください。

以下に示すのは、Systems Manager パラメータストアのパラメータを参照するときの形式を示すタスク定義のスニペットです。起動するタスクと同じリージョンに Systems Manager パラメータストアのパラメータが存在する場合は、パラメータの完全な ARN または名前のどちらも使用できます。パラメータが別のリージョンに存在する場合は、完全な ARN を指定する必要があります。

```
{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name"
    }]
  }]
}
```

環境変数で指定されたシークレットを使用してタスク定義を作成する方法については、「[コンソールを使用した Amazon ECS タスク定義の作成](create-task-definition.md)」を参照してください。

## 使用アイテム Systems Manager
<a name="secrets-logconfig-ssm-paramstore"></a>

ログ設定には機密データを注入できます。コンテナの定義内で `logConfiguration` を指定するときに、コンテナに設定するログドライバーオプションの名前と、コンテナに渡す機密データが含まれている Systems Manager パラメータストアのパラメータの ARN 全体を使用して `secretOptions` を指定できます。

**重要**  
起動するタスクと同じリージョンに Systems Manager パラメータストアのパラメータが存在する場合は、パラメータの完全な ARN または名前のどちらも使用できます。パラメータが別のリージョンに存在する場合は、完全な ARN を指定する必要があります。

以下に示すのは、Systems Manager パラメータストアのパラメータを参照するときの形式を示すタスク定義のスニペットです。

```
{
  "containerDefinitions": [{
    "logConfiguration": [{
      "logDriver": "fluentd",
      "options": {
        "tag": "fluentd demo"
      },
      "secretOptions": [{
        "name": "fluentd-address",
        "valueFrom": "arn:aws:ssm:region:aws_account_id:parameter:/parameter_name"
      }]
    }]
  }]
}
```

# Amazon ECS の Secrets Manager シークレットを使用した機密データの指定
<a name="specifying-sensitive-data-tutorial"></a>

Amazon ECS では、機密データを AWS Secrets Manager シークレットに保存し、コンテナ定義でそれを参照することで、機密データをコンテナに挿入することができます。詳細については、「[Amazon ECS コンテナに機密データを渡す](specifying-sensitive-data.md)」を参照してください。

Secrets Manager シークレットを作成して、Amazon ECS タスク定義でシークレットを参照し、コンテナ内の環境変数をクエリすることでシークレットの内容を表示して正しく動作したことを確認する方法について説明します。

## 前提条件
<a name="specifying-sensitive-data-tutorial-prereqs"></a>

このチュートリアルでは、以下の前提条件が完了済みであることを前提としています。
+ 「[Amazon ECS を使用するようにセットアップする](get-set-up-for-amazon-ecs.md)」のステップを完了していること。
+ ユーザーに、Secrets Manager および Amazon ECS リソースを作成するのに必要な IAM アクセス許可があります。

## ステップ 1:Secrets Manager シークレットを作成する
<a name="specifying-sensitive-data-tutorial-create-secret"></a>

Secrets Manager コンソールを使用して、機密データ用のシークレットを作成できます。このチュートリアルでは、後にコンテナで参照するユーザー名とパスワードを保存するための基本的なシークレットを作成します。詳細については、*AWS Secrets Manager ユーザーガイド*の「[Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)」を参照してください。

**[key/value pairs to be stored in this secret]** (このシークレットに格納されたキーおよび値のペア) は、チュートリアルの最後にコンテナに存在する環境変数の値です。

**[Secret ARN]** (シークレット ARN) を保存し、後のステップのタスク実行 IAM ポリシーとタスク定義で参照できるようにします。

## ステップ 2: タスク実行ロールにシークレットアクセス許可を追加する
<a name="specifying-sensitive-data-tutorial-update-iam"></a>

Amazon ECS で Secrets Manager シークレットから機密データを取得するには、タスク実行ロールにシークレットアクセス許可が必要です。詳細については、「[Secrets Manager または Systems Manager のアクセス許可](task_execution_IAM_role.md#task-execution-secrets)」を参照してください。

## ステップ 3: タスク定義を作成する
<a name="specifying-sensitive-data-tutorial-create-taskdef"></a>

Amazon ECS コンソールを使用して、Secrets Manager シークレットを参照するタスク定義を作成します。

**シークレットを指定するタスク定義を作成するには**

IAM コンソールを使用して、必要なアクセス許可を持つタスク実行ロールを更新します。

1. コンソール ([https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)) を開きます。

1. ナビゲーションペインで、**タスクの定義** を選択します。

1. **[Create new task definition]** (新しいタスク定義の作成)、**[Create new task definition with JSON]** (JSON で新しいタスク定義を作成) の順に選択します。

1. JSON エディタボックスで、以下のタスク定義 JSON テキストを入力して、ステップ 1 で作成した Secrets Manager シークレットの完全な ARN と、ステップ 2 で更新したタスク定義ロールを指定します。**[保存]** を選択します。

1. 

   ```
   {
       "executionRoleArn": "arn:aws:iam::aws_account_id:role/ecsTaskExecutionRole",
       "containerDefinitions": [
           {
               "entryPoint": [
                   "sh",
                   "-c"
               ],
               "portMappings": [
                   {
                       "hostPort": 80,
                       "protocol": "tcp",
                       "containerPort": 80
                   }
               ],
               "command": [
                   "/bin/sh -c \"echo '<html> <head> <title>Amazon ECS Sample App</title> <style>body {margin-top: 40px; background-color: #333;} </style> </head><body> <div style=color:white;text-align:center> <h1>Amazon ECS Sample App</h1> <h2>Congratulations!</h2> <p>Your application is now running on a container in Amazon ECS.</p> </div></body></html>' >  /usr/local/apache2/htdocs/index.html && httpd-foreground\""
               ],
               "cpu": 10,
               "secrets": [
                   {
                       "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:username_value",
                       "name": "username_value"
                   }
               ],
               "memory": 300,
               "image": "public.ecr.aws/docker/library/httpd:2.4",
               "essential": true,
               "name": "ecs-secrets-container"
           }
       ],
       "family": "ecs-secrets-tutorial"
   }
   ```

1. **[作成]** を選択します。

## ステップ 4: クラスターを作成する
<a name="specifying-sensitive-data-tutorial-create-cluster"></a>

Amazon ECS コンソールを使用してコンテナインスタンスを含むクラスターを作成し、タスクを実行します。利用可能なリソースを使用して登録された少なくとも 1 つのコンテナインスタンスを持つ既存のクラスターがあり、このチュートリアル用に作成されたタスク定義の 1 つのインスタンスを実行できる場合は、次のステップに進みます。

このチュートリアルでは、Amazon ECS最適化Amazon Linux 2 AMIを使用して、1つの`t2.micro`コンテナ・インスタンスでクラスタを作成します。

EC2 用にクラスターを作成する方法については、「[Amazon EC2 ワークロード用の Amazon ECS クラスターを作成する](create-ec2-cluster-console-v2.md)」を参照してください。

## ステップ 5: タスクを実行する
<a name="specifying-sensitive-data-tutorial-run-task"></a>

Amazon ECS コンソールを使用し、作成したタスク定義を使用してタスクを実行できます。このチュートリアルでは、前のステップで作成したクラスターを使用し、EC2 を使用してタスクを実行します。

タスクを実行する方法については、「[Amazon ECS タスクとしてのアプリケーションの実行](standalone-task-create.md)」を参照してください。

## ステップ 6: 確認する
<a name="specifying-sensitive-data-tutorial-verify"></a>

以下のステップを使用して、すべてのステップが正常に完了し、コンテナに環境変数が適切に作成されたことを確認できます。

**環境変数が作成されたことを確認するには**

1. コンテナインスタンスのパブリック IP アドレスまたは DNS アドレスを見つけます。

   1. コンソール ([https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)) を開きます。

   1. ナビゲーションペインで **[クラスター]** を選択した後、作成してあるクラスターを選択します。

   1. **[インフラストラクチャ]** を選択した後、コンテナインスタンスを選択します。

   1. インスタンスの **[パブリック IP]** または **[パブリック DNS]** を記録します。

1. macOS または Linux コンピュータを使用している場合は、以下のコマンドでインスタンスに接続します (パスとアドレスはプライベートキーへのパスとインスタンスのパブリックアドレスに置き換えます)。

   ```
   $ ssh -i /path/to/my-key-pair.pem ec2-user@ec2-198-51-100-1.compute-1.amazonaws.com
   ```

   Windows コンピュータを使用している場合は、「*Amazon EC2 ユーザーガイド*」の「[PuTTY を使用して Linux インスタンスに接続する](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-linux-inst-from-windows.html)」を参照してください。
**重要**  
インスタンス接続時の問題について、詳細は「*Amazon EC2 ユーザーガイド*」の「[インスタンスへの接続に関するトラブルシューティング](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html)」を参照してください。

1. インスタンスで実行するコンテナを一覧表示します。`ecs-secrets-tutorial` コンテナのコンテナ ID をメモしておきます。

   ```
   docker ps
   ```

1. 前のステップの出力のコンテナ ID を使用して `ecs-secrets-tutorial` コンテナに接続します。

   ```
   docker exec -it container_ID /bin/bash
   ```

1. `echo` コマンドを使用して環境変数の値を出力します。

   ```
   echo $username_value
   ```

   このチュートリアルが成功すると、次のような出力が表示されます。

   ```
   password_value
   ```
**注記**  
あるいは、`env` (または `printenv`) コマンドを使用して、コンテナ内の環境変数をすべて一覧表示できます。

## ステップ 7: クリーンアップする
<a name="specifying-sensitive-data-tutorial-cleanup"></a>

このチュートリアルが終了したら、未使用のリソースに対する料金が発生しないように、それに関連付けられたリソースをクリーンアップする必要があります。

**リソースをクリーンアップするには**

1. コンソール ([https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)) を開きます。

1. ナビゲーションペインで **[Clusters]** (クラスター) を選択してください。

1. **[Clusters]** (クラスター) ページで、クラスターを選択します。

1. [**Delete Cluster**] を選択します。

1. 確認ボックスで、**delete *cluster name*** と入力し、[**削除**] を選択します。

1. IAM コンソール ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)) を開きます。

1. ナビゲーションペインで **Roles (ロール) ** を選択してください。

1. ロールの一覧で `ecsTaskExecutionRole` を探し、選択します。

1. **[アクセス許可]** を選択した後、**[ECSSecrets チュートリアル]** の横にある **[X]** を選択します。**[**を削除] を選択します。

1. [[https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)]で、Secrets Manager コンソール を開きます。

1. 作成した [**username\$1value**] シークレットを選択し、[**Actions (アクション)**]、[**Delete secret (シークレットの削除)**] の順に選択します。