本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 搭配 Amazon MWAA 使用啟動指令碼
啟動指令碼是您在環境 Amazon S3 儲存貯體中託管的 shell (`.sh`) 指令碼，類似於您的 DAGs、需求和外掛程式。在安裝需求和初始化 Apache Airflow 程序之前，Amazon MWAA 會在每個個別 Apache Airflow 元件 （工作者、排程器和 Web 伺服器） 的啟動期間執行此指令碼。使用啟動指令碼執行下列動作：
+ **安裝執行時間** – 安裝工作流程和連線所需的 Linux 執行時間。
+ **設定環境變數** – 為每個 Apache Airflow 元件設定環境變數。覆寫常見的變數，例如 `PATH`、 `PYTHONPATH`和 `LD_LIBRARY_PATH`。
+ **管理金鑰和字符** – 將自訂儲存庫的存取字符傳遞給 `requirements.txt`並設定安全金鑰。
下列主題說明如何設定啟動指令碼來安裝 Linux 執行期、設定環境變數，以及使用 CloudWatch Logs 疑難排解相關問題。
**Topics**
+ [設定啟動指令碼](#create-startup-script)
+ [使用啟動指令碼安裝 Linux 執行期](#install-dependencies-using-startup-script)
+ [使用啟動指令碼設定環境變數](#set-variables-using-startup-script)
## 設定啟動指令碼
若要將啟動指令碼與現有的 Amazon MWAA 環境搭配使用，請將`.sh`檔案上傳至您環境的 Amazon S3 儲存貯體。然後，若要將指令碼與環境建立關聯，請在環境詳細資訊中指定下列項目：
+ **指令碼的 Amazon S3 URL 路徑** – 儲存貯體中託管指令碼的相對路徑，例如， `s3://mwaa-environment/startup.sh`
+ **指令碼的 Amazon S3 版本 ID** – Amazon S3 儲存貯體中啟動 shell 指令碼的版本。每次更新指令碼時，您必須指定 Amazon S3 指派給檔案的[版本 ID](https://docs.aws.amazon.com/AmazonS3/latest/userguide/versioning-workflows.html)。版本 IDs為 Unicode、UTF-8 編碼、URL 就緒、不透明字串，長度不超過 1，024 個位元組，例如 `3sL4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo`。
若要完成本節中的步驟，請使用下列範例指令碼。指令碼會輸出指派給 的值`MWAA_AIRFLOW_COMPONENT`。此環境變數可識別指令碼執行所在的每個 Apache Airflow 元件。
複製程式碼並在本機儲存為 `startup.sh`。
```
#!/bin/sh
echo "Printing Apache Airflow component"
echo $MWAA_AIRFLOW_COMPONENT
```
接著，將指令碼上傳至您的 Amazon S3 儲存貯體。
------
#### [ AWS 管理主控台 ]
**上傳 shell 指令碼 （主控台）**
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 開啟 Amazon S3 主控台。
1. 從**儲存貯**體清單中，選擇與您的環境相關聯的儲存貯體名稱。
1. 在 **Objects (物件)**標籤上，選擇 **Upload (上傳)**。
1. 在**上傳**頁面上，拖放您建立的 shell 指令碼。
1. 選擇**上傳**。
指令碼會列在**物件**清單中。Amazon S3 會為 檔案建立新的版本 ID。如果您更新指令碼並使用相同的檔案名稱再次上傳，則會將新的版本 ID 指派給檔案。
------
#### [ AWS CLI ]
**建立和上傳 shell 指令碼 (CLI)**
1. 開啟新的命令提示，並執行 Amazon S3 `ls`命令來列出和識別與您的環境相關聯的儲存貯體。
```
aws s3 ls
```
1. 導覽至您儲存 shell 指令碼的資料夾。`cp` 在新的提示視窗中使用 ，將指令碼上傳至您的儲存貯體。將 *amzn-s3-demo-bucket* 取代為您的資訊。
```
aws s3 cp startup.sh s3://amzn-s3-demo-bucket/startup.sh
```
如果成功，Amazon S3 會輸出物件的 URL 路徑：
```
upload: ./startup.sh to s3://amzn-s3-demo-bucket/startup.sh
```
1. 使用下列命令來擷取指令碼的最新版本 ID。
```
aws s3api list-object-versions --bucket amzn-s3-demo-bucket --prefix startup --query 'Versions[?IsLatest].[VersionId]' --output text
```
```
BbdVMmBRjtestta1EsVnbybZp1Wqh1J4
```
當您將指令碼與 環境建立關聯時，您可以指定此版本 ID。
------
現在，將指令碼與您的環境建立關聯。
------
#### [ AWS 管理主控台 ]
**將指令碼與環境建立關聯 （主控台）**
1. 在 Amazon MWAA 主控台上開啟[環境](https://console.aws.amazon.com/mwaa/home#/environments)頁面。
1. 選取您要更新的環境資料列，然後選擇**編輯**。
1. 在**指定詳細資訊**頁面上，針對**啟動指令碼檔案 - *選用***，輸入指令碼的 Amazon S3 URL，例如：`s3://amzn-s3-demo-bucket/startup-sh.`。
1. 從下拉式清單中選擇最新版本，或**瀏覽S3**以尋找指令碼。
1. 選擇**下一步**，然後前往**檢閱並儲存**頁面。
1. 檢閱變更，然後選擇**儲存**。
環境更新可能需要 10 到 30 分鐘。Amazon MWAA 會在環境中的每個元件重新啟動時執行啟動指令碼。
------
#### [ AWS CLI ]
**將指令碼與環境建立關聯 (CLI)**
+ 開啟命令提示，並使用 `update-environment` 指定指令碼的 Amazon S3 URL 和版本 ID。
```
aws mwaa update-environment \
--name your-mwaa-environment \
--startup-script-s3-path startup.sh \
--startup-script-s3-object-version BbdVMmBRjtestta1EsVnbybZp1Wqh1J4
```
如果成功，Amazon MWAA 會傳回環境的 Amazon Resource Name (ARN)：
```
arn:aws:airflow:us-west-2:123456789012:environment/your-mwaa-environment
```
環境更新可能需要 10 到 30 分鐘。Amazon MWAA 會在環境中的每個元件重新啟動時執行啟動指令碼。
------
最後，擷取日誌事件，以驗證指令碼是否如預期般運作。當您為每個 Apache Airflow 元件啟用記錄時，Amazon MWAA 會建立新的日誌群組和日誌串流。如需詳細資訊，請參閱 [Apache Airflow 日誌類型](monitoring-airflow.md#monitoring-airflow-log-groups)。
------
#### [ AWS 管理主控台 ]
**取得 Apache Airflow 日誌串流 （主控台）**
1. 在 Amazon MWAA 主控台上開啟[環境](https://console.aws.amazon.com/mwaa/home#/environments)頁面。
1. 選擇您的環境。
1. 在**監控**窗格中，選擇您要存取日誌的日誌群組，例如 **Airflow 排程器日誌群組 **。
1. 在 CloudWatch 主控台的**日誌串流**清單中，選擇具有下列字首的串流：`startup_script_execution_ip`。
1. 在**日誌事件**窗格中，您將參考列印 值的命令輸出`MWAA_AIRFLOW_COMPONENT`。例如，對於排程器日誌，您將執行下列操作：
```
Printing Apache Airflow component
scheduler
Finished running startup script. Execution time: 0.004s.
Running verification
Verification completed
```
您可以重複上述步驟來存取工作者和 Web 伺服器日誌。
------
## 使用啟動指令碼安裝 Linux 執行期
使用啟動指令碼來更新 Apache Airflow 元件的作業系統，並安裝其他執行時間程式庫以搭配工作流程使用。例如，執行下列指令碼`yum update`來更新作業系統。
在啟動指令碼`yum update`中執行 時，您必須使用 排除 Python，`--exclude=python*`如範例所列。為了讓您的環境執行，Amazon MWAA 會安裝與您的環境相容的 Python 特定版本。因此，您無法使用啟動指令碼更新環境的 Python 版本。
```
#!/bin/sh
echo "Updating operating system"
sudo yum update -y --exclude=python*
```
若要在特定 Apache Airflow 元件上安裝執行時間，請使用 `MWAA_AIRFLOW_COMPONENT`和 `if`和 `fi` 條件式陳述式。此範例會執行單一命令，以在排程器和工作者上安裝程式`libaio`庫，但不會在 Web 伺服器上安裝程式庫。
**重要**
如果您已設定[私有 Web 伺服器](configuring-networking.md#access-overview-private)，則必須使用下列條件或在本機提供所有安裝檔案，以避免安裝逾時。
使用 `sudo`執行需要管理權限的操作。
```
#!/bin/sh
if [[ "${MWAA_AIRFLOW_COMPONENT}" != "webserver" ]]
then
sudo yum -y install libaio
fi
```
您可以使用啟動指令碼來取得 Python 版本。
```
#!/bin/sh
export PYTHON_VERSION_CHECK=`python -c 'import sys; version=sys.version_info[:3]; print("{0}.{1}.{2}".format(*version))'`
echo "Python version is $PYTHON_VERSION_CHECK"
```
Amazon MWAA 不支援覆寫預設 Python 版本，因為這可能會導致與已安裝的 Apache Airflow 程式庫不相容。
## 使用啟動指令碼設定環境變數
使用啟動指令碼來設定環境變數和修改 Apache Airflow 組態。以下定義了新的變數 `ENVIRONMENT_STAGE`。您可以在 DAG 或自訂模組中參考此變數。
```
#!/bin/sh
export ENVIRONMENT_STAGE="development"
echo "$ENVIRONMENT_STAGE"
```
使用啟動指令碼覆寫常見的 Apache Airflow 或系統變數。例如，您設定 `LD_LIBRARY_PATH` 指示 Python 在您指定的路徑中搜尋二進位檔。這可讓您使用[外掛程式](https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/plugins.html)為工作流程提供自訂二進位檔：
```
#!/bin/sh
export LD_LIBRARY_PATH=/usr/local/airflow/plugins/your-custom-binary
```
### 預留環境變數
Amazon MWAA 會保留一組重要的環境變數。如果您覆寫*預留*變數，Amazon MWAA 會將其還原為其預設值。下列列出預留變數：
+ `MWAA__AIRFLOW__COMPONENT` – 用來識別具有下列其中一個值的 Apache Airflow 元件：`scheduler`、 `worker`或 `webserver`。
+ `AIRFLOW__WEBSERVER__SECRET_KEY` – 用於在 Apache Airflow Web 伺服器中安全簽署工作階段 Cookie 的私密金鑰。
+ `AIRFLOW__CORE__FERNET_KEY` – 用於加密和解密存放在中繼資料資料庫中之敏感資料的金鑰，例如連線密碼。
+ `AIRFLOW_HOME` – Apache Airflow 主目錄的路徑，其中組態檔案和 DAG 檔案存放在本機。
+ `AIRFLOW__CELERY__BROKER_URL` – 用於 Apache Airflow 排程器與 Celery 工作者節點之間通訊的訊息中介裝置 URL。
+ `AIRFLOW__CELERY__RESULT_BACKEND` – 用來存放 Celery 任務結果的資料庫 URL。
+ `AIRFLOW__CORE__EXECUTOR` – Apache Airflow 必須使用的執行器類別。在 Amazon MWAA 中，這是 `CeleryExecutor`
+ `AIRFLOW__CORE__LOAD_EXAMPLES` – 用來啟用或停用範例 DAGs的載入。
+ `AIRFLOW__METRICS__METRICS_BLOCK_LIST` – 用來管理 Amazon MWAA 在 CloudWatch 中發出和擷取哪些 Apache Airflow 指標。
+ `SQL_ALCHEMY_CONN` – RDS for PostgreSQL 資料庫的連線字串，用於將 Apache Airflow 中繼資料存放在 Amazon MWAA 中。
+ `AIRFLOW__CORE__SQL_ALCHEMY_CONN` – 用於與 相同的用途`SQL_ALCHEMY_CONN`，但遵循新的 Apache Airflow 命名慣例。
+ `AIRFLOW__CELERY__DEFAULT_QUEUE` – Apache Airflow 中 Celery 任務的預設佇列。
+ `AIRFLOW__OPERATORS__DEFAULT_QUEUE` – 使用特定 Apache Airflow 運算子的任務的預設佇列。
+ `AIRFLOW_VERSION` – 安裝在 Amazon MWAA 環境中的 Apache Airflow 版本。
+ `AIRFLOW_CONN_AWS_DEFAULT` – 用來與其他 AWS 服務整合的預設 AWS 登入資料。
+ `AWS_DEFAULT_REGION` – 設定預設 搭配預設登入資料 AWS 區域 使用，以與其他 AWS 服務整合。
+ `AWS_REGION` – 如果已定義，此環境變數會覆寫環境變數`AWS_DEFAULT_REGION`和設定檔設定區域中的值。
+ `PYTHONUNBUFFERED` – `stderr` 用來傳送`stdout`和串流至容器日誌。
+ `AIRFLOW__METRICS__STATSD_ALLOW_LIST` – 用來設定允許逗號分隔字首清單，以傳送以清單元素開頭的指標。
+ `AIRFLOW__METRICS__STATSD_ON` – 啟用傳送指標至 `StatsD`。
+ `AIRFLOW__METRICS__STATSD_HOST` – 用來連線至`StatSD`協助程式。
+ `AIRFLOW__METRICS__STATSD_PORT` – 用來連線至`StatSD`協助程式。
+ `AIRFLOW__METRICS__STATSD_PREFIX` – 用來連線至`StatSD`協助程式。
+ `AIRFLOW__CELERY__WORKER_AUTOSCALE` – 設定最大和最小並行。
+ `AIRFLOW__CORE__DAG_CONCURRENCY` – 設定排程器在一個 DAG 中可同時執行的任務執行個體數目。
+ `AIRFLOW__CORE__MAX_ACTIVE_TASKS_PER_DAG` – 設定每個 DAG 的作用中任務數目上限。
+ `AIRFLOW__CORE__PARALLELISM` – 定義可同時執行的任務執行個體數量上限。
+ `AIRFLOW__SCHEDULER__PARSING_PROCESSES` – 設定排程器剖析以排程 DAGs 的程序數目上限。
+ `AIRFLOW__CELERY_BROKER_TRANSPORT_OPTIONS__VISIBILITY_TIMEOUT` – 定義重新傳遞訊息給另一個工作者之前，工作者等待確認任務的秒數。
+ `AIRFLOW__CELERY_BROKER_TRANSPORT_OPTIONS__REGION` – 設定基礎 Celery 傳輸 AWS 區域 的 。
+ `AIRFLOW__CELERY_BROKER_TRANSPORT_OPTIONS__PREDEFINED_QUEUES` – 設定基礎 Celery 傳輸的佇列。
+ `AIRFLOW_SCHEDULER_ALLOWED_RUN_ID_PATTERN` – 用於在觸發 DAG `run_id`時驗證參數輸入的有效性。
+ `AIRFLOW__WEBSERVER__BASE_URL` – 用來託管 Apache Airflow UI 的 Web 伺服器 URL。
+ `PYTHONPATH` （僅適用於 Apache Airflow v2.9 和更新版本） – 由 Amazon MWAA 預留，以確保所有基本環境功能都能正常運作。
**注意**
對於 v2.9 之前的 Apache Airflow 版本， `PYTHONPATH` 是*未保留*的環境變數。
### 未預留的環境變數
您可以使用啟動指令碼來覆寫*未保留*的環境變數。以下列出其中一些常見變數：
+ `PATH` – 指定目錄清單，其中作業系統會搜尋可執行檔和指令碼。當命令在命令列中執行時，系統會檢查 中的目錄`PATH`，以尋找並執行命令。當您在 Apache Airflow 中建立自訂運算子或任務時，您可能需要依賴外部指令碼或可執行檔。如果包含這些檔案的目錄不在 `PATH`變數中指定的 中，則當系統找不到任務時，任務會無法執行。透過將適當的目錄新增至 `PATH`，Apache Airflow 任務可以尋找並執行所需的可執行檔。
+ `PYTHONPATH` – Python 解譯器用來判斷要搜尋匯入模組和套件的目錄。這是您可以新增至預設搜尋路徑的目錄清單。這可讓解譯器尋找和載入標準程式庫中未包含或安裝在系統目錄中的 Python 程式庫。使用此變數來新增您的模組和自訂 Python 套件，並將其與 DAGs搭配使用。
**注意**
對於 Apache Airflow v2.9 和更新版本， `PYTHONPATH` 是*預留*環境變數。
+ `LD_LIBRARY_PATH` – 動態連結器和載入器在 Linux 中用來尋找和載入共用程式庫的環境變數。它會指定包含共用程式庫的目錄清單，這些程式庫會在預設系統程式庫目錄之前搜尋。使用此變數來指定您的自訂二進位檔。
+ `CLASSPATH` – Java 執行期環境 (JRE) 和 Java 開發套件 (JDK) 用來在執行期尋找和載入 Java 類別、程式庫和資源。這是目錄、JAR 檔案和 ZIP 封存的清單，其中包含編譯的 Java 程式碼。