本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 更新 Amazon ECS 容器代理程式
<a name="ecs-agent-update"></a>

有時，您可能需要更新 Amazon ECS 容器代理程式，以取得錯誤修正和新功能。更新 Amazon ECS 容器代理不會中斷容器執行個體上正在執行中的任務或服務。更新代理程式的程序有所不同，這取決於您是否使用 Amazon ECS 最佳化 AMI 來啟動容器執行個體，或是否是在其他作業系統上。

**注意**  
代理更新不適用於 Windows 容器執行個體。我們建議您啟動新的容器執行個體，以更新您 Windows 叢集中的代理版本。

## 檢查 Amazon ECS 容器代理程式版本
<a name="checking_agent_version"></a>

您可以檢查在您的容器執行個體上執行的容器代理版本，以查看是否需要更新它。Amazon ECS 主控台中的容器執行個體檢視可提供代理程式版本。請使用下列步驟來檢查您的代理版本。

------
#### [ Amazon ECS console ]

1. 開啟主控台，網址為 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)。

1. 從導覽列中選擇註冊外部執行個體所在的區域。

1. 在導覽窗格中選擇 **Clusters** (叢集)，並選取託管外部執行個體的叢集。

1. 在 **Cluster : *name*** (叢集：名稱) 頁面上，選擇 **Infrastructure** (基礎基礎設施) 索引標籤。

1. 在 **Container instances** (容器執行個體) 下，注意您容器執行個體的 **Agent version** (代理程式版本) 資料欄。如果容器執行個體不包含最新版的容器代理，主控台會使用訊息和標記提醒您過時的代理版本。

   若您的代理版本已過時，可以使用以下程序更新容器代理程式：
   + 若您的容器執行個體執行的是 Amazon ECS 最佳化 AMI，請參閱 [在 Amazon ECS 最佳化 AMI 上更新 Amazon ECS 容器代理](agent-update-ecs-ami.md)。
   + 若您的容器執行個體執行的不是 Amazon ECS 最佳化 AMI，請參閱 [手動更新 Amazon ECS 容器代理程式 (適用於非 Amazon ECS 最佳化 AMI)](manually_update_agent.md)。
**重要**  
若要在您的 Amazon ECS 最佳化 AMI 上，更新 v1.0.0 版本之前的 Amazon ECS 代理程式版本，我們建議您終止目前的容器執行個體，並使用最近的 AMI 版本啟動新的執行個體。任何使用預覽版本的容器執行個體都應進行淘汰，並使用最近的 AMI 取代。如需詳細資訊，請參閱[啟動 Amazon ECS Linux 容器執行個體](launch_container_instance.md)。

------
#### [ Amazon ECS container agent introspection API  ]

您也可以使用 Amazon ECS 容器代理程式從容器執行個體自我檢查 API 版本。如需詳細資訊，請參閱[Amazon ECS 容器自我檢查](ecs-agent-introspection.md)。

**若要使用自我檢查 API 檢查您的 Amazon ECS 容器代理是否執行最新版本**

1. 透過 SSH 登入您的容器執行個體。

1. 查詢自我檢查 API。

   ```
   [ec2-user ~]$ curl -s 127.0.0.1:51678/v1/metadata | python3 -mjson.tool
   ```
**注意**  
自我檢查 API 在 Amazon ECS 容器代理版本 v1.0.0 中新增 `Version` 資訊。若在查詢自我檢查 API 時沒有看見 `Version`，或是您的代理中甚至沒有自我檢查 API，則您執行的版本便是 v0.0.3 及更早版本。您應更新您的版本。

------

# 在 Amazon ECS 最佳化 AMI 上更新 Amazon ECS 容器代理
<a name="agent-update-ecs-ami"></a>

若您使用的是 Amazon ECS 最佳化 AMI，您有幾個選項可取得最新版本的 Amazon ECS 容器代理程式 (以下顯示的順序為建議順序)：
+ 終止容器執行個體，並啟動最新版本的 Amazon ECS 最佳化 Amazon Linux 2 AMI (以手動方式或使用最新 AMI 更新您的 Auto Scaling 啟動組態)。這可提供全新的容器執行個體，以及最新已測試和驗證的 Amazon Linux、Docker、`ecs-init` 和 Amazon ECS 容器代理程式的版本。如需詳細資訊，請參閱[Amazon ECS 最佳化 Linux AMI](ecs-optimized_AMI.md)。
+ 使用 SSH 連線到執行個體，將 `ecs-init` 套裝服務 (及其相依性) 更新到最新版本。此操作可提供 Amazon Linux 儲存庫中目前經過測試及驗證的 Docker 和 `ecs-init` 版本，以及最新版 Amazon ECS 容器代理程式。如需詳細資訊，請參閱[若要更新 Amazon ECS 最佳化 AMI 上的 `ecs-init` 套件](#procedure_update_ecs-init)。
+ 透過主控台或使用 AWS CLI AWS SDKs，使用 `UpdateContainerAgent` API 操作更新容器代理程式。如需詳細資訊，請參閱[使用 `UpdateContainerAgent` API 操作更新 Amazon ECS 容器代理程式](#agent-update-api)。

**注意**  
代理更新不適用於 Windows 容器執行個體。我們建議您啟動新的容器執行個體，以更新您 Windows 叢集中的代理版本。<a name="procedure_update_ecs-init"></a>

**若要更新 Amazon ECS 最佳化 AMI 上的 `ecs-init` 套件**

1. 透過 SSH 登入您的容器執行個體。

1. 使用以下命令更新 `ecs-init` 套裝服務。

   ```
   sudo yum update -y ecs-init
   ```
**注意**  
`ecs-init` 套件和 Amazon ECS 容器代理程式會立即更新。但是，直到 Docker 常駐程式重新啟動前，都不會載入較新版本的 Docker。將執行個體重新開機，或在執行個體上執行下列命令，以重新啟動：  
Amazon ECS 最佳化 Amazon Linux 2 AMI：  

     ```
     sudo systemctl restart docker
     ```
Amazon ECS 最佳化 Amazon Linux AMI：  

     ```
     sudo service docker restart && sudo start ecs
     ```

## 使用 `UpdateContainerAgent` API 操作更新 Amazon ECS 容器代理程式
<a name="agent-update-api"></a>

**重要**  
僅在 Amazon ECS 最佳化 AMI 的 Linux 變體上支援 `UpdateContainerAgent` API，但 Amazon ECS 最佳化 Amazon Linux 2 (arm64) AMI 除外。對於使用 Amazon ECS 最佳化 Amazon Linux 2 (arm64) AMI 的容器執行個體，請更新 `ecs-init` 套件以更新代理程式。針對在其他作業系統上執行的容器執行個體，請參閱「[手動更新 Amazon ECS 容器代理程式 (適用於非 Amazon ECS 最佳化 AMI)](manually_update_agent.md)」。如果您正在使用 Windows 容器執行個體，我們建議您啟動新的容器執行個體，以更新您 Windows 叢集中的代理程式版本。

當您透過主控台或使用 AWS CLI AWS SDKs 請求代理程式更新時，`UpdateContainerAgent`API 程序就會開始。Amazon ECS 會比對您目前的代理程式版本與最新可用的代理程式版本，判斷是否可執行更新。若無法取得更新 (例如若代理已在執行最近的版本)，便會傳回 `NoUpdateAvailableException`。

上圖顯示更新程序中的階段如下：

`PENDING`  
有可用的代理更新，並已啟動更新程序。

`STAGING`  
代理已開始下載代理更新。若代理無法下載更新，或更新的內容不正確或已損毀，則代理會傳送失敗的通知，且更新的狀態會轉換成 `FAILED` 狀態。

`STAGED`  
代理下載已完成並已驗證代理內容。

`UPDATING`  
`ecs-init` 服務已重新啟動，並使用最新版本的代理。若代理程式因為某些原因無法重新啟動，則更新會轉換為 `FAILED` 狀態；否則，代理程式會通知 Amazon ECS 更新已完成。

**注意**  
代理更新不適用於 Windows 容器執行個體。我們建議您啟動新的容器執行個體，以更新您 Windows 叢集中的代理版本。

**若要在主控台的 Amazon ECS 最佳化 AMI 上更新 Amazon ECS 容器代理程式**

1. 開啟主控台，網址為 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)。

1. 從導覽列中選擇註冊外部執行個體所在的區域。

1. 在導覽窗格中，選擇 **Clusters** (叢集)，然後選取叢集。

1. 在 **Cluster : *name*** (叢集：名稱) 頁面上，選擇 **Infrastructure** (基礎基礎設施) 索引標籤。

1. 在**容器執行個體**下，選取要更新的執行個體，然後選擇**動作**、**更新代理程式**。

# 手動更新 Amazon ECS 容器代理程式 (適用於非 Amazon ECS 最佳化 AMI)
<a name="manually_update_agent"></a>

有時，您可能需要更新 Amazon ECS 容器代理程式，以取得錯誤修正和新功能。更新 Amazon ECS 容器代理不會中斷容器執行個體上正在執行中的任務或服務。
**注意**  
代理更新不適用於 Windows 容器執行個體。我們建議您啟動新的容器執行個體，以更新您 Windows 叢集中的代理版本。

1. 透過 SSH 登入您的容器執行個體。

1. 檢查以查看您的代理是否是使用 `ECS_DATADIR` 環境變數儲存其狀態。

   ```
   ubuntu:~$ docker inspect ecs-agent | grep ECS_DATADIR
   ```

   輸出：

   ```
   "ECS_DATADIR=/data",
   ```
**重要**  
若先前的命令並未傳回 `ECS_DATADIR` 環境變數，您必須停止任何在此容器執行個體上執行的任務，才能更新您的代理。較新的代理會使用 `ECS_DATADIR` 環境變數儲存其狀態，讓您可以在任務執行中時更新它們，而不會有任何問題。

1. 停用 Amazon ECS 容器代理程式。

   ```
   ubuntu:~$ docker stop ecs-agent
   ```

1. 刪除代理容器。

   ```
   ubuntu:~$ docker rm ecs-agent
   ```

1. 確認 `/etc/ecs` 目錄和 Amazon ECS 容器代理程式組態檔案存在於 `/etc/ecs/ecs.config`。

   ```
   ubuntu:~$ sudo mkdir -p /etc/ecs && sudo touch /etc/ecs/ecs.config
   ```

1. 編輯 `/etc/ecs/ecs.config` 檔案，並確保其至少包含以下變數宣告。若您不希望您的容器執行個體使用預設叢集註冊，請將叢集名稱指定為 `ECS_CLUSTER` 的值。

   ```
   ECS_DATADIR=/data
   ECS_ENABLE_TASK_IAM_ROLE=true
   ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST=true
   ECS_LOGFILE=/log/ecs-agent.log
   ECS_AVAILABLE_LOGGING_DRIVERS=["json-file","awslogs"]
   ECS_LOGLEVEL=info
   ECS_CLUSTER=default
   ```

   如需這些和其他代理執行時間選項的詳細資訊，請參閱「[Amazon ECS 容器代理程式組態](ecs-agent-config.md)」。
**注意**  
您可以選擇性地將您的代理程式環境變數存放在 Amazon S3 中 (可在啟動時使用 Amazon EC2 使用者資料將其下載到您的容器執行個體)。針對敏感性資訊 (例如私有存放庫的身分驗證登入資料)，此為建議選項。如需詳細資訊，請參閱[將 Amazon ECS 容器執行個體組態儲存於 Amazon S3 中](ecs-config-s3.md)及[在 Amazon ECS 中使用非AWS 容器映像](private-auth.md)。

1. 從 Amazon Elastic Container Registry Public 取出最新的 Amazon ECS 容器代理程式映像。

   ```
   ubuntu:~$ docker pull public.ecr.aws/ecs/amazon-ecs-agent:latest
   ```

   輸出：

   ```
   Pulling repository amazon/amazon-ecs-agent
   a5a56a5e13dc: Download complete
   511136ea3c5a: Download complete
   9950b5d678a1: Download complete
   c48ddcf21b63: Download complete
   Status: Image is up to date for amazon/amazon-ecs-agent:latest
   ```

1. 在您的容器執行個體上執行最新的 Amazon ECS 容器代理程式。
**注意**  
使用 Docker 重新啟動政策或處理序管理員 (例如 **upstart** 或 **systemd**) 將容器代理程式做為服務或常駐程式處理，並確保在結束後重新啟動它。因此 Amazon ECS 最佳化 AMI 會使用 `ecs-init` RPM，您可以在 GitHub 上檢視[此 RPM 的來源程式碼](https://github.com/aws/amazon-ecs-init)。

   以下代理程式執行命令範例分成獨立的各行來顯示每個選項。如需這些和其他代理執行時間選項的詳細資訊，請參閱「[Amazon ECS 容器代理程式組態](ecs-agent-config.md)」。
**重要**  
針對啟用 SELinux 的作業系統，需要在您的 **docker run** 命令中包含 `--privileged` 選項。此外，針對啟用 SELinux 的容器執行個體，我們建議您為 `/log` 和 `/data` 磁碟區掛載新增 `:Z` 選項。但是，這些磁碟區的主機掛載必須在您執行命令前存在，否則您會接收到 `no such file or directory` 錯誤。若您在啟用 SELinux 的容器執行個體上執行 Amazon ECS 代理程式時遭遇困難，請採取以下動作：  
在您的容器執行個體上建立主機磁碟區掛載點。  

     ```
     ubuntu:~$ sudo mkdir -p /var/log/ecs /var/lib/ecs/data
     ```
為以下 **docker run** 命令新增 `--privileged` 選項。
為以下 **docker run** 命令的 `/log` 和 `/data` 容器磁碟區掛載附加 `:Z` 選項 (例如，`--volume=/var/log/ecs/:/log:Z`)。

   ```
   ubuntu:~$ sudo docker run --name ecs-agent \
   --detach=true \
   --restart=on-failure:10 \
   --volume=/var/run:/var/run \
   --volume=/var/log/ecs/:/log \
   --volume=/var/lib/ecs/data:/data \
   --volume=/etc/ecs:/etc/ecs \
   --volume=/etc/ecs:/etc/ecs/pki \
   --net=host \
   --env-file=/etc/ecs/ecs.config \
   amazon/amazon-ecs-agent:latest
   ```
**注意**  
若您接收到 `Error response from daemon: Cannot start container` 訊息，您可以使用 **sudo docker rm ecs-agent** 命令刪除失敗的容器，並再度嘗試執行代理程式。