メニュー
Amazon Elastic Container Service
開発者ガイド (API バージョン 2014-11-13)

Amazon ECS コンテナエージェントの設定

Amazon ECS コンテナエージェントでは、多数の設定オプションがサポートされており、そのほとんどは環境変数を通じて設定する必要があります。次の環境変数を使用できます。すべてオプションです。

コンテナインスタンスが Amazon ECS 最適化 AMI を使用して起動された場合は、これらの環境変数を /etc/ecs/ecs.config ファイルに設定してからエージェントを再び開始します。起動時に Amazon EC2 ユーザーデータを使用して、コンテナインスタンスにこれらの設定変数を作成することもできます。詳細については、「Amazon EC2 ユーザーデータを使用してコンテナインスタンスをブートストラップする」を参照してください。

Amazon ECS コンテナエージェントを手動で開始する場合 (Amazon ECS 最適化 AMI を使用していない場合)、これらの環境変数を docker run コマンドで使用できます。このコマンドは、構文 --env=VARIABLE_NAME=VARIABLE_VALUE を使用してエージェントを開始するために使用します。プライベートリポジトリの認証情報など、機密性の高い情報の場合は、エージェントの環境変数をファイルに保存し、--env-file path_to_env_file オプションを使用して、それらすべてを一度に渡す必要があります。

使用できるパラメーター

以下の環境キーが利用できます。

ECS_CLUSTER

値の例: MyCluster

Linux のデフォルト値: default

Windows のデフォルト値: default

このエージェントが確認するクラスター。この値を定義しない場合、default クラスターが想定されます。default クラスターが存在しない場合は、Amazon ECS コンテナエージェントによってその作成が試みられます。default 以外のクラスターを指定した場合、そのクラスターが存在しないと、登録は失敗します。

ECS_RESERVED_PORTS

値の例: [22, 80, 5000, 8080]

Linux のデフォルト値: [22, 2375, 2376, 51678, 51679]

Windows のデフォルト値: [53, 135, 139, 445, 2375, 2376, 3389, 5985, 51678, 51679]

このコンテナインスタンスのスケジューリングに使用できないとマークするポート配列。

ECS_RESERVED_PORTS_UDP

値の例: [53, 123]

Linux のデフォルト値: []

Windows のデフォルト値: []

このコンテナインスタンスのスケジューリングに使用できないとマークする UDP 配列。

ECS_ENGINE_AUTH_TYPE

値の例: dockercfg | docker

Linux のデフォルト値: Null

Windows のデフォルト値: Null

プライベートレジストリの認証で必須です。これは、ECS_ENGINE_AUTH_DATA の認証データのタイプです。詳細については、「認証形式」を参照してください。

ECS_ENGINE_AUTH_DATA

値の例:

  • ECS_ENGINE_AUTH_TYPE=dockercfg: {"https://index.docker.io/v1/":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"email@example.com"}}

  • ECS_ENGINE_AUTH_TYPE=docker: {"https://index.docker.io/v1/":{"username":"my_name","password":"my_password","email":"email@example.com"}}

Linux のデフォルト値: Null

Windows のデフォルト値: Null

プライベートレジストリの認証で必須です。ECS_ENGINE_AUTH_TYPE=dockercfg の場合、ECS_ENGINE_AUTH_DATA 値は、docker login を実行して作成された Docker 設定ファイル (~/.dockercfg または ~/.docker/config.json) の内容にする必要があります。ECS_ENGINE_AUTH_TYPE=docker の場合は、ECS_ENGINE_AUTH_DATA 値は、認証を受けるレジストリサーバーの JSON 表現であり、またそのレジストリに必要な認証パラメーターである必要があります (アカウントのユーザー名、パスワード、E メールアドレスなど)。詳細については、「認証形式」を参照してください。

AWS_DEFAULT_REGION

値の例: us-east-1

Linux のデフォルト値: EC2 インスタンスメタデータから取得されます。

Windows のデフォルト値: EC2 インスタンスメタデータから取得されます。

API リクエストで使用されるリージョン。正しいバックエンドホストを推測するためにも使用します。

AWS_ACCESS_KEY_ID

値の例: AKIAIOSFODNN7EXAMPLE

Linux のデフォルト値: EC2 インスタンスメタデータから取得されます。

Windows のデフォルト値: EC2 インスタンスメタデータから取得されます。

エージェントがすべてのコールで使用するアクセスキー

AWS_SECRET_ACCESS_KEY

値の例: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Linux のデフォルト値: EC2 インスタンスメタデータから取得されます。

Windows のデフォルト値: EC2 インスタンスメタデータから取得されます。

エージェントがすべてのコールで使用するシークレットキー

AWS_SESSION_TOKEN

Linux のデフォルト値: EC2 インスタンスメタデータから取得されます。

Windows のデフォルト値: EC2 インスタンスメタデータから取得されます。

一時的な認証情報を使用したセッショントークン

DOCKER_HOST

値の例: unix:///var/run/docker.sock

Linux のデフォルト値: unix:///var/run/docker.sock

Windows のデフォルト値: npipe:////./pipe/docker_engine

Docker デーモンへの接続を作成するために使用されます。Docker クライアントで使用される環境変数と同じように動作します。

ECS_LOGLEVEL

値の例: crit | error | warn | info | debug

Linux のデフォルト値: info

Windows のデフォルト値: info

stdout でログ記録するレベル。

ECS_LOGFILE

値の例: /ecs-agent.log

Linux のデフォルト値: Null

Windows のデフォルト値: Null

完全なデバッグ情報を出力するパス。空白の場合、ログは記録されません。この値が設定されている場合、デバッグレベルのログが (ECS_LOGLEVEL に関わらず) そのファイルに書き込まれます。

ECS_CHECKPOINT

値の例: true | false

Linux のデフォルト値: ECS_DATADIR に、空ではない値が明示的に設定されている場合、ECS_CHECKPOINTtrue に設定されます。それ以外の場合は false に設定されます。

Windows のデフォルト値: ECS_DATADIR に、空ではない値が明示的に設定されている場合、ECS_CHECKPOINTtrue に設定されます。それ以外の場合は false に設定されます。

ECS_DATADIR で指定された場所にチェックポイント状態を保存するかどうか。

ECS_DATADIR

値の例: /data

Linux のデフォルト値: /data/

Windows のデフォルト値: C:\ProgramData\Amazon\ECS\data

Amazon ECS コンテナエージェントを実行しているコンテナの永続データディレクトリの名前。ディレクトリは、クラスターおよびエージェントの状態に関する情報を保存するために使用されます。

ECS_UPDATES_ENABLED

値の例: true | false

Linux のデフォルト値: false

Windows のデフォルト値: false

ECS エージェントの更新がリクエストされた場合に終了するかどうか。

ECS_UPDATE_DOWNLOAD_DIR

値の例: /cache

Linux のデフォルト値: Null

Windows のデフォルト値: Null

更新 tarball をダウンロードしたときにそれを配置するコンテナ内のファイルシステムの場所。

ECS_DISABLE_METRICS

値の例: true | false

Linux のデフォルト値: false

Windows のデフォルト値: true

Amazon ECS の CloudWatch メトリクスを無効にするかどうか。この値が true に設定されている場合は、CloudWatch メトリクスは収集されません。

ECS_RESERVED_MEMORY

値の例: 32

Linux のデフォルト値: 0

Windows のデフォルト値: 0

タスクに割り当てられているプールから削除するメモリ量 (MiB)。これにより、Docker デーモンや Amazon ECS コンテナエージェントなど、重要なシステムプロセスのメモリが効果的に確保することができます。たとえば、ECS_RESERVED_MEMORY=256 を指定した場合、エージェントは、合計メモリから 256 MiB を差し引いた分をそのインスタンスに登録するため、ECS タスクで 256 MiB のシステムメモリを割り当てることができません。詳細については、「コンテナインスタンス メモリ管理」を参照してください。

ECS_AVAILABLE_LOGGING_DRIVERS

値の例: ["awslogs","fluentd","gelf","json-file","journald","splunk"]

Linux のデフォルト値: ["json-file","none"]

Windows のデフォルト値: ["json-file","none"]

コンテナインスタンスで使用できるロギングドライバー。コンテナインスタンスで実行する Amazon ECS コンテナエージェントは、ECS_AVAILABLE_LOGGING_DRIVERS 環境変数を使用して、そのインスタンスで使用できるロギングドライバーを登録する必要があります。その後、そのインスタンスに配置されたコンテナがタスクでこれらのドライバーのログ設定オプションを使用できるようになります。awslogs ログドライバーの使用方法については、「awslogs ログドライバーを使用する」を参照してください。ご使用の Docker バージョンで使用できるさまざまなロギングドライバーおよびその設定方法の詳細については、Docker ドキュメントの Configure logging drivers を参照してください。

ECS_DISABLE_PRIVILEGED

値の例: true | false

Linux のデフォルト値: false

Windows のデフォルト値: false

特権を持つコンテナの起動がコンテナインスタンスで無効になっているかどうか。この値を true に設定すると、特権を持つコンテナは許可されません。

ECS_SELINUX_CAPABLE

値の例: true | false

Linux のデフォルト値: false

Windows のデフォルト値: false

SELinux がコンテナインスタンスで使用できるかどうか。

ECS_APPARMOR_CAPABLE

値の例: true | false

Linux のデフォルト値: false

Windows のデフォルト値: false

AppArmor がコンテナインスタンスで使用できるかどうか。

ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION

値の例: 1h (有効な時間単位は「ns」、「us」 (または「µs」)、「ms」、「s」、「m」、および「h」です。)

Linux のデフォルト値: 3h

Windows のデフォルト値: 3h

タスクが停止してから Docker コンテナが削除されるまでの待機時間。これは Docker コンテナのデータを削除するため、この値の設定が小さすぎると、削除される前に停止したコンテナを調べたりログを確認したりできない場合があることに注意してください。最小の期間は 1m です。1 分より短い値は無視されます。

ECS_CONTAINER_STOP_TIMEOUT

値の例: 10m (有効な時間単位は「ns」、「us」 (または「µs」)、「ms」、「s」、「m」、および「h」です。)

Linux のデフォルト値: 30s

Windows のデフォルト値: 30s

タスクが停止してから、コンテナが正常に自己終了しない場合に強制的に終了されるまでの待機時間。

ECS_CONTAINER_START_TIMEOUT

値の例: 10m (有効な時間単位は「ns」、「us」 (または「µs」)、「ms」、「s」、「m」、および「h」です。)

Linux のデフォルト値: 3m

Windows のデフォルト値: 8m

コンテナの起動の再試行を止めるまでの待機時間。

HTTP_PROXY

値の例: 10.0.0.131:3128

Linux のデフォルト値: Null

Windows のデフォルト値: Null

ECS エージェントがインターネットに接続するために使用する HTTP プロキシのホスト名 (または IP アドレス) およびポート番号 (たとえば、コンテナインスタンスに Amazon VPC インターネットゲートウェイまたは NAT ゲートウェイまたはインスタンスを経由した外部ネットワークアクセスがない場合)。この変数を設定する場合は、NO_PROXY 変数も設定して、プロキシから EC2 インスタンスのメタデータおよび Docker デーモンのトラフィックをフィルタリングする必要があります。詳細については、「HTTP プロキシ設定」を参照してください。

NO_PROXY

値の例:

  • Linux: 169.254.169.254,169.254.170.2,/var/run/docker.sock

  • Windows: 169.254.169.254,169.254.170.2,\\.\pipe\docker_engine

Linux のデフォルト値: Null

Windows のデフォルト値: Null

指定された HTTP_PROXY に転送しない HTTP トラフィック。プロキシから EC2 インスタンスのメタデータおよび Docker デーモントラフィックをフィルタリングするには、169.254.169.254,/var/run/docker.sock を指定する必要があります。詳細については、「HTTP プロキシ設定」を参照してください。

ECS_ENABLE_TASK_IAM_ROLE

値の例: true | false

Linux のデフォルト値: false

Windows のデフォルト値: false

bridge または default ネットワークモードを使用しているタスクコンテナのコンテナインスタンスで、タスク用の IAM ロールを有効にする必要があります。詳細については、「タスク用の IAM ロール」を参照してください。

ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST

値の例: true | false

Linux のデフォルト値: false

Windows のデフォルト値: false

host ネットワークモードを使用しているタスクコンテナのコンテナインスタンスで、タスク用の IAM ロールを有効にする必要があります。この変数はエージェントバージョン 1.12.0 以降でのみサポートされています。詳細については、「タスク用の IAM ロール」を参照してください。

ECS_DISABLE_IMAGE_CLEANUP

値の例: true

Linux のデフォルト値: false

Windows のデフォルト値: false

Amazon ECS エージェントで自動イメージクリーンアップを無効にするかどうか。詳細については、「自動化タスクとイメージのクリーンアップ」を参照してください。

ECS_IMAGE_CLEANUP_INTERVAL

値の例: 30m

Linux のデフォルト値: 30m

Windows のデフォルト値: 30m

自動化されたイメージクリーンアップサイクルの間隔。10 分未満に設定すると、値は無視されます。

ECS_IMAGE_MINIMUM_CLEANUP_AGE

値の例: 30m

Linux のデフォルト値: 1h

Windows のデフォルト値: 1h

イメージが取得されてから自動イメージクリーンアップの対象になるまでの時間の最小間隔。

ECS_NUM_IMAGES_DELETE_PER_CYCLE

値の例: 5

Linux のデフォルト値: 5

Windows のデフォルト値: 5

1 つの自動イメージクリーンアップのサイクルで削除するイメージの最大数。1 未満に設定すると、値は無視されます。

ECS_IMAGE_PULL_BEHAVIOR

値の例: default | always | once | prefer-cached

Linux のデフォルト値: default

Windows のデフォルト値: default

コンテナインスタンスでイメージをプルするプロセスをカスタマイズするために使用される動作。オプションの動作について次に説明します。

  • default を指定した場合、リモートでイメージがプルされます。イメージのプルに失敗した場合、コンテナはそのインスタンスにキャッシュされたイメージを使用します。

  • always を指定した場合、常にリモートでイメージがプルされます。イメージのプルに失敗した場合、そのタスクは失敗します。このオプションを選択すると、最新バージョンのイメージが常にプルされます。キャッシュされたイメージはすべて無視され、イメージの自動クリーンアッププロセスが適用されます。

  • once を指定した場合、イメージが以前にプルされていないか、自動クリーンアッププロセスによって削除された場合に、イメージがリモートでプルされます。それ以外の場合は、インスタンスにキャッシュされたイメージが使用されます。これにより、不要なイメージのプルがなくなります。

  • prefer-cached を指定した場合、キャッシュされたイメージがない場合に、リモートでイメージがプルされます。それ以外の場合は、インスタンスにキャッシュされたイメージが使用されます。キャッシュされたイメージが削除されないように、そのコンテナの自動イメージクリーンアップは無効です。

ECS_INSTANCE_ATTRIBUTES

値の例: {"custom attribute": "custom_attribute_value"}

Linux のデフォルト値: Null

Windows のデフォルト値: Null

コンテナインスタンスに適用する JSON 形式のカスタム属性のリスト。インスタンス登録でこの属性を使用すると、カスタム属性を追加し、AWS マネジメントコンソール経由でカスタム属性を追加する手動メソッドをスキップできます。

注記

追加された属性は、登録済みのコンテナインスタンスには適用されません。登録済みのコンテナインスタンスにカスタム属性を追加する場合は、「属性の追加」を参照してください。

カスタム属性の使用方法の詳細については、「属性」を参照してください。

この変数に無効な JSON 値を使用すると、エージェントはコード 5 とともに終了し、エージェントログにメッセージが表示されます。JSON 値が有効でも属性の検証時に問題が検出される (値が長すぎる、無効な文字が含まれているなど) と、コンテナインスタンスの登録は実行されますが、エージェントはコード 5 とともに終了し、エージェントログにメッセージが書き込まれます。エージェントログを確認する方法については、「Amazon ECS コンテナエージェントログ」を参照してください。

ECS_ENABLE_TASK_ENI

値の例: true | false

Linux のデフォルト値: false

Windows のデフォルト値: 該当しません

独自のネットワークインターフェイスを使用して起動されるタスクのタスクネットワーキングを有効にするかどうか。

ECS_CNI_PLUGINS_PATH

値の例: /ecs/cni

Linux のデフォルト値: /amazon-ecs-cni-plugins

Windows のデフォルト値: 該当しません

cni バイナリファイルが存在するパス。

ECS_AWSVPC_BLOCK_IMDS

値の例: true | false

Linux のデフォルト値: false

Windows のデフォルト値: 該当しません

awsvpc ネットワークモードを使用して起動されるタスクのインスタンスメタデータへのアクセスをブロックするかどうか。

ECS_AWSVPC_ADDITIONAL_LOCAL_ROUTES

値の例: ["10.0.15.0/24"]

Linux のデフォルト値: []

Windows のデフォルト値: 該当しません

awsvpc ネットワークモードでは、これらのプレフィックスへのトラフィックは、タスク Elastic Network Interface ではなく、ホストブリッジ経由でルーティングされます。

ECS_ENABLE_CONTAINER_METADATA

値の例: true

Linux のデフォルト値: false

Windows のデフォルト値: false

true の場合、コンテナのメタデータを記述するファイルをエージェントが作成します。このファイルは、コンテナ環境変数 $ECS_CONTAINER_METADATA_FILE を使って配置および使用できます。

ECS_HOST_DATA_DIR

値の例: /var/lib/ecs

Linux のデフォルト値: /var/lib/ecs

Windows のデフォルト値: 該当しません

ECS_DATADIR のマウント元となるホスト上のソースディレクトリ。ECS エージェントがコンテナとして実行されている場合に、これを使ってコンテナメタデータファイルのソースマウントパスを判定できます。ECS エージェントがコンテナとして実行されないため、Windows ではこの値を使用しません。

ECS_ENABLE_TASK_CPU_MEM_LIMIT

値の例: true | false

Linux のデフォルト値: true

Windows のデフォルト値: false

タスクレベルの CPU とメモリ制限を有効にするかどうか。

ECS_CGROUP_PATH

値の例: /sys/fs/cgroup

Linux のデフォルト値: /sys/fs/cgroup

Windows のデフォルト値: 該当しません

ECS エージェントで期待されている cgroup のルートパス。このパスは、エージェントマウントからアクセスできます。

ECS_ENABLE_CPU_UNBOUNDED_WINDOWS_WORKAROUND

値の例: true | false

Linux のデフォルト値: 該当しません

Windows のデフォルト値: false

true の場合、ECS では、Windows のバインドされていない CPU (CPU=0) タスクを、バインドされた CPU のタスクと一緒に実行できます。

ECS_TASK_METADATA_RPS_LIMIT

値の例: 100,150

Linux のデフォルト値: 40,60

Windows のデフォルト値: 40,60

タスクメタデータエンドポイントの定常状態およびバーストスロットル制限に使用するカンマ区切り整数値。

Amazon S3 にコンテナインスタンスの構成を保存する

Amazon ECS コンテナエージェントの設定は、上記の環境変数によって制御されます。コンテナエージェントの開始時に Amazon ECS 最適化 AMI が /etc/ecs/ecs.config 内のこれらの変数を確認し、それに従ってエージェントを設定します。ECS_CLUSTER など、問題のない特定の環境変数は、Amazon EC2 ユーザーデータを経由して起動時にコンテナインスタンスに渡され、そのままこのファイルに書き込まれます。ただし、AWS 認証情報や ECS_ENGINE_AUTH_DATA 変数など機密性の高い情報は、ユーザーデータでインスタンスに渡したり、.bash_history ファイルに表示される可能性のある方法で /etc/ecs/ecs.config に書き込んではいけません。

設定情報を Amazon S3 のプライベートバケットに保存し、コンテナインスタンスの IAM ロールに読み取り専用アクセス権限を付与するのが、コンテナインスタンスの起動時に設定を許可する安全で便利な方法です。ecs.config ファイルのコピーをプライベートバケットに保存します。その後、Amazon EC2 ユーザーデータを使用して AWS CLI をインストールし、インスタンスの起動時に設定情報を /etc/ecs/ecs.config にコピーできます。

Amazon S3 の読み取り専用アクセス権限をコンテナインスタンスのロールに許可するには

  1. https://console.aws.amazon.com/iam/ にある IAM コンソールを開きます。

  2. ナビゲーションペインで [Roles (ロール) ] を選択します。

  3. コンテナインスタンスに対して使用する IAM ロールを選択します (このロールには多くの場合、ecsInstanceRole というタイトルが付けられます)。詳細については、「Amazon ECS コンテナインスタンスの IAM ロール」を参照してください。

  4. [Managed Policies] の下で、[Attach Policy] を選択します。

  5. [Attach Policy] ページの [Filter] フィールドに S3 と入力し、ポリシーの結果を絞り込みます。

  6. [AmazonS3ReadOnlyAccess] ポリシーの左にあるチェックボックスをオンにし、[Attach Policy] を選択します。

ecs.config ファイルを Amazon S3 に保存するには

  1. 以下の形式を使用して、有効な環境変数と「ecs.config」からの値を持つ Amazon ECS コンテナエージェントの設定 ファイルを作成します。この例では、プライベートレジストリ認証を設定しています。詳細については、「プライベートレジストリの認証」を参照してください。

    ECS_ENGINE_AUTH_TYPE=dockercfg ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"email@example.com"}}
  2. 設定ファイルを保存するには、Amazon S3 内にプライベートバケットを作成します。詳細については、Amazon Simple Storage Service 入門ガイド の「バケットの作成」を参照してください。

  3. ecs.config ファイルを S3 バケットにアップロードします。詳細については、Amazon Simple Storage Service 入門ガイド の「バケットへのオブジェクトの追加」を参照してください。

起動時に ecs.config ファイルを Amazon S3 からロードするには

  1. このセクションの上記の手順を完了して、読み取り専用 Amazon S3 アクセス権限をコンテナインスタンスに許可し、ecs.config ファイルをプライベート S3 バケットに保存します。

  2. Amazon ECS コンテナインスタンスの起動」のステップに従って、新しいコンテナインスタンスを起動します。「ステップ 7」の手順に従って、AWS CLI をインストールする以下のスクリプト例を使用し、設定ファイルを /etc/ecs/ecs.config にコピーします。

    #!/bin/bash yum install -y aws-cli aws s3 cp s3://your_bucket_name/ecs.config /etc/ecs/ecs.config