支援終止通知：2026 年 10 月 7 日 AWS 將停止 的支援 AWS IoT Greengrass Version 1。2026 年 10 月 7 日之後，您將無法再存取 AWS IoT Greengrass V1 資源。如需詳細資訊，請造訪[從 遷移 AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html)。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS IoT Greengrass Core 軟體的 OTA 更新
Core AWS IoT Greengrass 軟體套件包含更新代理程式，可執行 AWS IoT Greengrass 軟體的over-the-air(OTA) 更新。您可以使用 OTA 更新，在一或多個核心上安裝最新版本 AWS IoT Greengrass 的核心軟體或 OTA 更新代理程式軟體。透過 OTA 更新，您的核心裝置就不需要實際存在。
我們建議您盡可能使用 OTA 更新。它們提供了一種機制，讓您用來追蹤更新狀態和更新歷程記錄。如果發生更新失敗，OTA 更新代理程式會轉返至先前的軟體版本。
**注意**
當您使用 安裝 AWS IoT Greengrass Core 軟體時`apt`，不支援 OTA 更新。針對這些安裝，我們建議您使用 `apt` 以升級軟體。如需詳細資訊，請參閱[從 APT 儲存庫安裝 AWS IoT Greengrass 核心軟體](install-ggc.md#ggc-package-manager)。
OTA 更新可讓您更有效率地執行下列作業：
+ 修復安全漏洞。
+ 解決軟體穩定性問題。
+ 部署新功能和改良的功能。
此功能與 [AWS IoT 任務](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)整合。
## 要求
下列需求適用於 AWS IoT Greengrass 軟體的 OTA 更新。
+ Greengrass 核心在本機儲存中必須至少有 400 MB 的可用磁碟空間。OTA 更新代理程式需要大約 AWS IoT Greengrass Core 軟體執行時間用量需求的三倍。如需詳細資訊，請參閱《》中的 Greengrass 核心[的服務配額](https://docs.aws.amazon.com/general/latest/gr/greengrass.html#limits_greengrass)*Amazon Web Services 一般參考*。
+ Greengrass 核心必須具有與 的連線 AWS 雲端。
+ Greengrass 核心必須使用憑證和金鑰正確設定和佈建，以使用 AWS IoT Core 和 進行身分驗證 AWS IoT Greengrass。如需詳細資訊，請參閱[X.509 憑證](device-auth.md#x509-certificates)。
+ Greengrass 核心無法設定為使用網路代理。
**注意**
從 AWS IoT Greengrass v1.9.3 開始，設定 MQTT 流量使用連接埠 443 而非預設連接埠 8883 的核心支援 OTA 更新。不過，OTA 更新代理程式不支援透過網路代理進行更新。如需詳細資訊，請參閱[連線至連接埠 443 或透過網路代理](gg-core.md#alpn-network-proxy)。
+ 無法在包含 AWS IoT Greengrass Core 軟體的分割區中啟用信任的開機。
**注意**
您可以在已啟用信任開機的分割區上安裝和執行 AWS IoT Greengrass Core 軟體，但不支援 OTA 更新。
+ AWS IoT Greengrass 必須在包含 Core 軟體的 AWS IoT Greengrass 分割區上具有讀取/寫入許可。
+ 如果您使用初始化系統來管理您的 Greengrass 核心，則必須設定 OTA 更新以與初始化系統整合。如需詳細資訊，請參閱[與初始化系統整合](#integration-with-init)。
+ 您必須建立用來預先簽署 Amazon S3 URLs 以 AWS IoT Greengrass 軟體更新成品的角色。此簽署者角色允許 代表您 AWS IoT Core 存取存放在 Amazon S3 中的軟體更新成品。如需詳細資訊，請參閱[OTA 更新的 IAM 許可](#ota-permissions)。
### OTA 更新的 IAM 許可
當 AWS IoT Greengrass 發行新版本的 AWS IoT Greengrass 核心軟體時， 會 AWS IoT Greengrass 更新存放在 Amazon S3 中用於 OTA 更新的軟體成品。
您的 AWS 帳戶 必須包含可用於存取這些成品的 Amazon S3 URL 簽署者角色。角色必須具有許可政策，允許對目標 中的儲存貯體執行 AWS 區域`s3:GetObject`動作。該角色也必須具有允許 `iot.amazonaws.com` 將角色視為信任實體的信任政策。
**許可政策**
對於角色許可，您可以使用 AWS 受管政策或建立自訂政策。
+ **使用 AWS 受管政策**
[ GreengrassOTAUpdateArtifactAccess](https://console.aws.amazon.com/iam/home?region=us-west-2#/policies/arn%3Aaws%3Aiam%3A%3Aaws%3Apolicy%2Fservice-role%2FGreengrassOTAUpdateArtifactAccess) 受管政策是由 AWS IoT Greengrass提供。如果您想要允許在目前和未來支援的所有 Amazon Web Services 區域中存取 AWS IoT Greengrass，請使用此政策。
+ **建立自訂政策**
如果您想要明確指定核心部署所在的 Amazon Web Services 區域，您應該建立自訂政策。下列範例政策允許存取六個區域中的 AWS IoT Greengrass 軟體更新。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowAccessToGreengrassOTAUpdateArtifacts",
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::us-east-1-greengrass-updates/*",
"arn:aws:s3:::us-west-2-greengrass-updates/*",
"arn:aws:s3:::ap-northeast-1-greengrass-updates/*",
"arn:aws:s3:::ap-southeast-2-greengrass-updates/*",
"arn:aws:s3:::eu-central-1-greengrass-updates/*",
"arn:aws:s3:::eu-west-1-greengrass-updates/*"
]
}
]
}
```
------
**信任政策**
連接至角色的信任政策必須允許 `sts:AssumeRole` 動作並定義 `iot.amazonaws.com` 為委託人。這允許 AWS IoT Core 將角色擔任信任的實體。以下是範例政策文件：
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowIotToAssumeRole",
"Action": "sts:AssumeRole",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Effect": "Allow"
}
]
}
```
此外，起始 OTA 更新的使用者必須具有 `greengrass:CreateSoftwareUpdateJob` 和 `iot:CreateJob` 的使用許可，以及使用 `iam:PassRole` 傳遞簽署者角色的許可。以下是 IAM 政策範例：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"greengrass:CreateSoftwareUpdateJob"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iot:CreateJob"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": "arn:aws:iam::123456789012:role/name-of-s3-url-signer-role"
}
]
}
```
------
## 考量事項
啟動 Greengrass 核心軟體的 OTA 更新前，請注意更新會對 Greengrass 群組中的裝置造成的影響，不論群組是在核心裝置上還是在本機連線至該核心的用戶端裝置上：
+ 更新期間會關閉核心。
+ 會關閉在核心執行的任何 Lambda 函數。如果這些函數寫入到本機資源，這些函數可能會讓這些資源處於不正確的狀態，除非有正確地關閉。
+ 在核心停機時間期間，其與 的所有連線 AWS 雲端 都會遺失。由用戶端裝置透過核心路由傳送的訊息將會遺失。
+ 登入資料快取會遺失。
+ 佇列為 Lambda 函數所保留待處理的工作會遺失。
+ 長期 Lambda 函數會遺失其動態狀態資訊，並捨棄所有待定工作。
在 OTA 更新期間，以下狀態資訊皆會保留：
+ 核心組態
+ Greengrass 群組組態
+ 本機陰影
+ Greengrass 日誌
+ OTA 更新代理程式日誌
## Greengrass OTA 更新代理程式
Greengrass OTA 更新代理程式是裝置上的軟體元件，可處理在雲端中建立和部署的更新任務。OTA 更新代理程式會分佈在與 AWS IoT Greengrass Core 軟體相同的軟體套件中。代理程式位於 `/greengrass-root/ota/ota_agent/ggc-ota` 中。它會將日誌寫入 `/var/log/greengrass/ota/ggc_ota.txt`。
**注意**
*greengrass-root* 代表 Core AWS IoT Greengrass 軟體安裝在您裝置上的路徑。通常，這是 `/greengrass` 目錄。
您可以透過手動執行二進位檔，或將其整合為初始化指令碼的一部分，例如系統化服務檔案，來啟動 OTA 更新代理程式。如果您手動執行二進位檔，它應該做為根執行。啟動時，OTA 更新代理程式會接聽來自 的 AWS IoT Greengrass 軟體更新任務， AWS IoT Core 並依序執行這些任務。OTA 更新代理程式會忽略所有其他 AWS IoT 任務類型。
以下摘錄顯示啟動、停止和重新啟動 OTA 更新代理程式的系統化服務檔案範例：
```
[Unit]
Description=Greengrass OTA Daemon
[Service]
Type=forking
Restart=on-failure
ExecStart=/greengrass/ota/ota_agent/ggc-ota
[Install]
WantedBy=multi-user.target
```
作為更新目標的核心不得執行兩個 OTA 更新代理程式的執行個體。這麼做會讓兩個代理程式處理相同的任務，而造成衝突。
## 與初始化系統整合
在 OTA 更新期間，OTA 更新代理程式會在核心裝置上重新啟動二進位檔。如果二進位檔正在執行，當初始化系統在更新期間監控 AWS IoT Greengrass 核心軟體或代理程式的狀態時，這可能會導致衝突。為了協助整合 OTA 更新機制與監控策略，您可以撰寫在更新前後執行的 shell 指令碼。例如，您可以使用`ggc_pre_update.sh`指令碼在裝置關閉之前備份資料或停止程序。
若要告知 OTA 更新代理程式執行這些指令碼，您必須在 [config.json ](gg-core.md#config-json)檔案中包含 `"managedRespawn" : true`旗標。此設定會顯示在下列摘錄中：
```
{
"coreThing": {
…
},
"runtime": {
…
},
"managedRespawn": true
…
}
```
### 透過 OTA 更新受管的 respawn
下列需求適用於將 `managedRespawn`設為 的 OTA 更新`true`：
+ `/greengrass-root/usr/scripts` 目錄中必須存在下列 shell 指令碼：
+ `ggc_pre_update.sh`
+ `ggc_post_update.sh`
+ `ota_pre_update.sh`
+ `ota_post_update.sh`
+ 指令碼必須傳回成功的傳回碼。
+ 這些指令碼必須由根目錄擁有，而且只能由根目錄執行。
+ `ggc_pre_update.sh` 指令碼必須停止 Greengrass 協助程式。
+ `ggc_post_update.sh` 指令碼必須啟動 Greengrass 協助程式。
**注意**
由於 OTA 更新代理程式會管理自己的程序，因此 `ota_pre_update.sh`和 `ota_post_update.sh`指令碼不需要停止或啟動 OTA 服務。
OTA 更新代理程式會從 執行指令碼`/greengrass-root/usr/scripts`。目錄樹狀圖看起來應該如下所示：
```
|-- certs
|-- config
| |-- config.json
|-- ggc
|-- usr/scripts
| |-- ggc_pre_update.sh
| |-- ggc_post_update.sh
| |-- ota_pre_update.sh
| |-- ota_post_update.sh
|-- ota
```
當 `managedRespawn` 設定為 時`true`，OTA 更新代理程式會在軟體更新前後檢查這些指令碼的`/greengrass-root/usr/scripts`目錄。如果指令碼不存在，更新會失敗。 AWS IoT Greengrass 不會驗證這些指令碼的內容。最佳實務是驗證您的指令碼是否正常運作，並針對錯誤發出適當的結束代碼。
**針對 AWS IoT Greengrass Core 軟體的 OTA 更新：**
+ 在開始更新之前，代理程式會執行 `ggc_pre_update.sh` 指令碼。將此指令碼用於在 OTA 更新代理程式啟動 AWS IoT Greengrass 核心軟體更新之前需要執行的命令，例如備份資料或停止任何執行中的程序。下列範例顯示停止 Greengrass 協助程式的簡單指令碼。
```
#!/bin/bash
set -euo pipefail
systemctl stop greengrass
```
+ 完成更新後，代理程式會執行 `ggc_post_update.sh` 指令碼。將此指令碼用於在 OTA 更新代理程式啟動 AWS IoT Greengrass 核心軟體更新後需要執行的命令，例如重新啟動程序。下列範例顯示啟動 Greengrass 協助程式的簡單指令碼。
```
#!/bin/bash
set -euo pipefail
systemctl start greengrass
```
**對於 OTA 更新代理程式的 OTA 更新：**
+ 在開始更新之前，代理程式會執行 `ota_pre_update.sh` 指令碼。將此指令碼用於需要在 OTA 更新代理程式自行更新之前執行的命令，例如備份資料或停止任何執行中的程序。
+ 完成更新後，代理程式會執行 `ota_post_update.sh` 指令碼。將此指令碼用於在 OTA 更新代理程式更新之後需要執行的命令，例如重新啟動程序。
**注意**
如果 `managedRespawn` 設定為 `false`，OTA 更新代理程式不會執行指令碼。
## 建立 OTA 更新
請依照下列步驟，在一或多個核心上執行 AWS IoT Greengrass 軟體的 OTA 更新：
1. 確定您的核心符合 OTA 更新的[要求](#ota-update-requirements)。
**注意**
如果您已設定初始化系統來管理 AWS IoT Greengrass 核心軟體或 OTA 更新代理程式，請在您的核心上驗證下列項目：
[config.json](gg-core.md#config-json) 檔案會指定 `"managedRespawn" : true`。
/*greengrass-root*/usr/scripts 目錄包含下列指令碼：
ggc\$1pre\$1update.sh
ggc\$1post\$1update.sh
ota\$1pre\$1update.sh
ota\$1post\$1update.sh
如需詳細資訊，請參閱[與初始化系統整合](#integration-with-init)。
1. 在核心裝置終端機中，啟動 OTA 更新代理程式。
```
cd /greengrass-root/ota/ota_agent
sudo ./ggc-ota
```
**注意**
*greengrass-root* 代表 Core AWS IoT Greengrass 軟體安裝在您裝置上的路徑。通常，這是 `/greengrass` 目錄。
請勿在核心上啟動多個 OTA 更新代理程式執行個體，因為它可能會導致衝突。
1. 使用 AWS IoT Greengrass API 建立軟體更新任務。
1. 呼叫 [CreateSoftwareUpdateJob](#create-software-update-job) API。在此範例程序中，我們使用 AWS CLI 命令。
下列命令會建立任務，以更新一個核心上的 AWS IoT Greengrass Core 軟體。取代範例值，然後執行命令。
------
#### [ Linux or macOS terminal ]
```
aws greengrass create-software-update-job \
--update-targets-architecture x86_64 \
--update-targets [\"arn:aws:iot:region:123456789012:thing/myCoreDevice\"] \
--update-targets-operating-system ubuntu \
--software-to-update core \
--s3-url-signer-role arn:aws:iam::123456789012:role/myS3UrlSignerRole \
--update-agent-log-level WARN \
--amzn-client-token myClientToken1
```
------
#### [ Windows command prompt ]
```
aws greengrass create-software-update-job ^
--update-targets-architecture x86_64 ^
--update-targets [\"arn:aws:iot:region:123456789012:thing/myCoreDevice\"] ^
--update-targets-operating-system ubuntu ^
--software-to-update core ^
--s3-url-signer-role arn:aws:iam::123456789012:role/myS3UrlSignerRole ^
--update-agent-log-level WARN ^
--amzn-client-token myClientToken1
```
------
該命令會傳回下列回應。
```
{
"IotJobId": "GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE",
"IotJobArn": "arn:aws:iot:region:123456789012:job/GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE",
"PlatformSoftwareVersion": "1.10.1"
}
```
1. 從回應複製 `IoTJobId`。
1. 在 AWS IoT Core API 中呼叫 [DescribeJob](https://docs.aws.amazon.com/iot/latest/developerguide/manage-job-cli.html#describe-job) 以查看任務狀態。以您的任務 ID 取代範例值，然後執行命令。
```
aws iot describe-job --job-id GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE
```
此命令會傳回包含任務相關資訊的回應物件，包括 `status` 和 `jobProcessDetails`。
```
{
"job": {
"jobArn": "arn:aws:iot:region:123456789012:job/GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE",
"jobId": "GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE",
"targetSelection": "SNAPSHOT",
"status": "IN_PROGRESS",
"targets": [
"arn:aws:iot:region:123456789012:thing/myCoreDevice"
],
"description": "This job was created by Greengrass to update the Greengrass Cores in the targets with version 1.10.1 of the core software running on x86_64 architecture.",
"presignedUrlConfig": {
"roleArn": "arn:aws::iam::123456789012:role/myS3UrlSignerRole",
"expiresInSec": 3600
},
"jobExecutionsRolloutConfig": {},
"createdAt": 1588718249.079,
"lastUpdatedAt": 1588718253.419,
"jobProcessDetails": {
"numberOfCanceledThings": 0,
"numberOfSucceededThings": 0,
"numberOfFailedThings": 0,
"numberOfRejectedThings": 0,
"numberOfQueuedThings": 1,
"numberOfInProgressThings": 0,
"numberOfRemovedThings": 0,
"numberOfTimedOutThings": 0
},
"timeoutConfig": {}
}
}
```
如需故障診斷協助，請參閱[故障診斷 AWS IoT Greengrass](gg-troubleshooting.md)。
## CreateSoftwareUpdateJob API
您可以使用 `CreateSoftwareUpdateJob` API 來更新核心裝置上的 AWS IoT Greengrass 核心軟體或 OTA 更新代理程式軟體。此 API 會建立 AWS IoT 快照任務，在有可用更新時通知裝置。呼叫 之後`CreateSoftwareUpdateJob`，您可以使用其他 AWS IoT 任務命令來追蹤軟體更新。如需詳細資訊，請參閱《 *AWS IoT 開發人員指南*》中的[任務](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)。
下列範例示範如何使用 AWS CLI 來建立任務，以更新 AWS IoT Greengrass 核心裝置上的 Core 軟體：
```
aws greengrass create-software-update-job \
--update-targets-architecture x86_64 \
--update-targets [\"arn:aws:iot:region:123456789012:thing/myCoreDevice\"] \
--update-targets-operating-system ubuntu \
--software-to-update core \
--s3-url-signer-role arn:aws:iam::123456789012:role/myS3UrlSignerRole \
--update-agent-log-level WARN \
--amzn-client-token myClientToken1
```
`create-software-update-job` 命令會傳回一個 JSON 回應，其中包含任務 ID、任務 ARN，以及更新所安裝的軟體版本：
```
{
"IotJobId": "GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE",
"IotJobArn": "arn:aws:iot:region:123456789012:job/GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE",
"PlatformSoftwareVersion": "1.9.2"
}
```
如需說明如何使用 `create-software-update-job` 更新核心裝置的步驟，請參閱 [建立 OTA 更新](#create-ota-update)。
`create-software-update-job` 命令具有下列參數：
`--update-targets-architecture`
核心裝置的架構。
有效值：`armv7l`、`armv6l`、`x86_64` 或 `aarch64`
`--update-targets`
要更新的核心。此清單可包含個別核心的 ARN，以及其成員為核心之物件群組的 ARN。如需物件群組的詳細資訊，請參閱《 *AWS IoT 開發人員指南*》中的[靜態物件群組](https://docs.aws.amazon.com/iot/latest/developerguide/thing-groups.html)。
`--update-targets-operating-system`
核心裝置的作業系統。
有效值：`ubuntu`、`amazon_linux`、`raspbian` 或 `openwrt`
`--software-to-update`
指定核心的軟體或 OTA 更新代理程式軟體是否應更新。
有效值：`core` 或 `ota_agent`
`--s3-url-signer-role`
用於預先簽署連結至 AWS IoT Greengrass 軟體更新成品之 Amazon S3 URL 的 IAM 角色 ARN。角色連接的許可政策必須允許對目標 中的儲存貯體執行 `s3:GetObject`動作 AWS 區域。角色也必須允許 `iot.amazonaws.com` 將角色擔任為信任的實體。如需詳細資訊，請參閱[OTA 更新的 IAM 許可](#ota-permissions)。
`--amzn-client-token`
(選用) 使用用戶端字符發出等冪請求。提供一組唯一的字符，避免因內部重新嘗試而產生重複更新。
`--update-agent-log-level`
（選用） OTA 更新代理程式產生之日誌陳述式的記錄層級。預設值為 `ERROR`。
有效值：`NONE`、`TRACE`、`DEBUG`、`VERBOSE`、`INFO`、`WARN`、`ERROR` 或 `FATAL`
**注意**
`CreateSoftwareUpdateJob` 僅接受下列支援架構和作業系統組合的要求：
ubuntu/x86\$164
ubuntu/aarch64
amazon\$1linux/x86\$164
raspbian/armv7l
raspbian/armv6l
openwrt/aarch64
openwrt/armv7l