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

# 搭配 Amazon EMR on EKS 使用 Apache Livy
<a name="job-runs-apache-livy"></a>

透過 Amazon EMR 7.1.0 版和更新版本，您可以使用 Apache Livy 在 Amazon EMR on EKS 上提交任務。使用 Apache Livy，您可以設定自己的 Apache Livy REST 端點，並使用它在 Amazon EKS 叢集上部署和管理 Spark 應用程式。在 Amazon EKS 叢集中安裝 Livy 之後，您可以使用 Livy 端點將 Spark 應用程式提交到您的 Livy 伺服器。伺服器會管理 Spark 應用程式的生命週期。

**注意**  
Amazon EMR 會根據 vCPU 和記憶體使用量計算 Amazon EKS 定價。此計算適用於驅動程式和執行器 Pod。此計算從您下載 Amazon EMR 應用程式映像時開始，直到 Amazon EKS Pod 終止且四捨五入至最接近的秒。

**Topics**
+ [為 Amazon EMR on EKS 設定 Apache Livy](job-runs-apache-livy-setup.md)
+ [Apache Livy on Amazon EMR on EKS 入門](job-runs-apache-livy-install.md)
+ [使用適用於 Amazon EMR on EKS 的 Apache Livy 執行 Spark 應用程式](job-runs-apache-livy-run-spark.md)
+ [使用 Amazon EMR on EKS 解除安裝 Apache Livy](job-runs-apache-livy-uninstall.md)
+ [Apache Livy 搭配 Amazon EMR on EKS 的安全性](job-runs-apache-livy-security.md)
+ [Amazon EMR on EKS 版本上 Apache Livy 的安裝屬性](job-runs-apache-livy-installation-properties.md)
+ [疑難排解常見的環境變數格式錯誤](job-runs-apache-livy-troubleshooting.md)

# 為 Amazon EMR on EKS 設定 Apache Livy
<a name="job-runs-apache-livy-setup"></a>

您必須先安裝和設定一組先決條件工具，才能在 Amazon EKS 叢集上安裝 Apache Livy。其中包括 AWS CLI，這是使用 AWS 資源的基本命令列工具、使用 Amazon EKS 的命令列工具，以及在此使用案例中使用的控制器，讓您的叢集應用程式可供網際網路使用，以及路由網路流量。
+ **[安裝或更新至最新版本的 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)**- 如果您已安裝 AWS CLI，請確認您擁有最新版本。
+ **[設定 kubectl 和 eksctl](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html) ** – eksctl 是您用來與 Amazon EKS 通訊的命令列工具。
+ **[安裝 Helm](https://docs.aws.amazon.com/eks/latest/userguide/helm.html)** – Kubernetes 的 Helm 套件管理工具可協助您安裝和管理 Kubernetes 叢集上的應用程式。
+ **[開始使用 Amazon EKS – eksctl](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html) ** – 請依照步驟在 Amazon EKS 中建立具有節點的新 Kubernetes 叢集。
+ **[選取 Amazon EMR 發行標籤](docker-custom-images-tag.md)** – Amazon EMR 7.1.0 及更高版本支援 Apache Livy。
+ **[安裝 ALB 控制器](https://docs.aws.amazon.com/eks/latest/userguide/aws-load-balancer-controller.html)** – ALB 控制器管理 Kubernetes 叢集的 AWS Elastic Load Balancing。當您在設定 Apache Livy 時建立 Kubernetes 輸入時，它會建立 AWS Network Load Balancer (NLB)。

# Apache Livy on Amazon EMR on EKS 入門
<a name="job-runs-apache-livy-install"></a>

完成下列步驟以安裝 Apache Livy。其中包括設定套件管理員、建立執行 Spark 工作負載的命名空間、安裝 Livy、設定負載平衡和驗證步驟。您必須完成這些步驟，才能使用 Spark 執行批次任務。

1. 如果您尚未設定 [Amazon EMR on EKS 的 Apache Livy](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/job-runs-apache-livy-setup.html)。

1. 向 Amazon ECR 登錄檔驗證 Helm 用戶端。您可以從 AWS 區域 [Amazon ECR 登錄帳戶依區域](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/docker-custom-images-tag.html#docker-custom-images-ECR)尋找 的對應`ECR-registry-account`值。

   ```
   aws ecr get-login-password \--region <AWS_REGION> | helm registry login \
   --username AWS \
   --password-stdin <ECR-registry-account>.dkr.ecr.<region-id>.amazonaws.com
   ```

1. 設定 Livy 會為 Livy 伺服器建立服務帳戶，並為 Spark 應用程式建立另一個帳戶。若要設定服務帳戶的 IRSA，請參閱[使用服務帳戶 (IRSA) 的 IAM 角色設定存取許可](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/job-runs-apache-livy-irsa.html)。

1. 建立命名空間來執行 Spark 工作負載。

   ```
   kubectl create ns <spark-ns>
   ```

1. 使用下列命令來安裝 Livy。

   此 Livy 端點只能在內部供 EKS 叢集中的 VPC 使用。若要啟用 VPC 以外的存取，請在 Helm 安裝命令`—-set loadbalancer.internal=false`中設定 。
**注意**  
根據預設，在此 Livy 端點內不會啟用 SSL，而且端點僅在 EKS 叢集的 VPC 內可見。如果您設定 `loadbalancer.internal=false`和 `ssl.enabled=false`，則會將不安全的端點公開到 VPC 外部。若要設定安全 Livy 端點，請參閱[使用 TLS/SSL 設定安全 Apache Livy 端點](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/job-runs-apache-livy-secure-endpoint.html)。

   ```
   helm install livy-demo \
     oci://895885662937.dkr.ecr.region-id.amazonaws.com/livy \
     --version 7.12.0 \
     --namespace livy-ns \
     --set image=ECR-registry-account.dkr.ecr.region-id.amazonaws.com/livy/emr-7.12.0:latest \
     --set sparkNamespace=<spark-ns> \
     --create-namespace
   ```

   您應該會看到下列輸出。

   ```
   NAME: livy-demo
   LAST DEPLOYED: Mon Mar 18 09:23:23 2024
   NAMESPACE: livy-ns
   STATUS: deployed
   REVISION: 1
   TEST SUITE: None
   NOTES:
   The Livy server has been installed.
   Check installation status:
   1. Check Livy Server pod is running
     kubectl --namespace livy-ns get pods -l "app.kubernetes.io/instance=livy-demo"
   2. Verify created NLB is in Active state and it's target groups are healthy (if loadbalancer.enabled is true)
   
   Access LIVY APIs:
       # Ensure your NLB is active and healthy
       # Get the Livy endpoint using command:
       LIVY_ENDPOINT=$(kubectl get svc -n livy-ns -l app.kubernetes.io/instance=livy-demo,emr-containers.amazonaws.com/type=loadbalancer -o jsonpath='{.items[0].status.loadBalancer.ingress[0].hostname}' |  awk '{printf "%s:8998\n", $0}')
       # Access Livy APIs using http://$LIVY_ENDPOINT or https://$LIVY_ENDPOINT (if SSL is enabled)
       # Note: While uninstalling Livy, makes sure the ingress and NLB are deleted after running the helm command to avoid dangling resources
   ```

   Livy 伺服器和 Spark 工作階段的預設服務帳戶名稱為 `emr-containers-sa-livy`和 `emr-containers-sa-spark-livy`。若要使用自訂名稱，請使用 `serviceAccounts.name`和 `sparkServiceAccount.name` 參數。

   ```
   --set serviceAccounts.name=my-service-account-for-livy
   --set sparkServiceAccount.name=my-service-account-for-spark
   ```

1. 確認您已安裝 Helm Chart。

   ```
   helm list -n livy-ns -o yaml
   ```

   `helm list` 命令應會傳回新 Helm Chart 的相關資訊。

   ```
   app_version: 0.7.1-incubating
   chart: livy-emr-7.12.0
   name: livy-demo
   namespace: livy-ns
   revision: "1"
   status: deployed
   updated: 2024-02-08 22:39:53.539243 -0800 PST
   ```

1. 確認 Network Load Balancer 處於作用中狀態。

   ```
   LIVY_NAMESPACE=<livy-ns>
   LIVY_APP_NAME=<livy-app-name>
   AWS_REGION=<AWS_REGION>
   
   # Get the NLB Endpoint URL
   NLB_ENDPOINT=$(kubectl --namespace $LIVY_NAMESPACE get svc -l "app.kubernetes.io/instance=$LIVY_APP_NAME,emr-containers.amazonaws.com/type=loadbalancer" -o jsonpath='{.items[0].status.loadBalancer.ingress[0].hostname}') 
   
   # Get all the load balancers in the account's region
   ELB_LIST=$(aws elbv2 describe-load-balancers --region $AWS_REGION)
   
   # Get the status of the NLB that matching the endpoint from the Kubernetes service
   NLB_STATUS=$(echo $ELB_LIST | grep -A 8 "\"DNSName\": \"$NLB_ENDPOINT\"" | awk '/Code/{print $2}/}/' | tr -d '"},\n')
   echo $NLB_STATUS
   ```

1. 現在驗證 Network Load Balancer 中的目標群組是否正常運作。

   ```
   LIVY_NAMESPACE=<livy-ns>
   LIVY_APP_NAME=<livy-app-name>
   AWS_REGION=<AWS_REGION>
   
   # Get the NLB endpoint
   NLB_ENDPOINT=$(kubectl --namespace $LIVY_NAMESPACE get svc -l "app.kubernetes.io/instance=$LIVY_APP_NAME,emr-containers.amazonaws.com/type=loadbalancer" -o jsonpath='{.items[0].status.loadBalancer.ingress[0].hostname}') 
   
   # Get all the load balancers in the account's region
   ELB_LIST=$(aws elbv2 describe-load-balancers --region $AWS_REGION)
   
   # Get the NLB ARN from the NLB endpoint
   NLB_ARN=$(echo $ELB_LIST | grep -B 1 "\"DNSName\": \"$NLB_ENDPOINT\"" | awk '/"LoadBalancerArn":/,/"/'| awk '/:/{print $2}' | tr -d \",)
   
   # Get the target group from the NLB. Livy setup only deploys 1 target group
   TARGET_GROUP_ARN=$(aws elbv2 describe-target-groups --load-balancer-arn $NLB_ARN --region $AWS_REGION | awk '/"TargetGroupArn":/,/"/'| awk '/:/{print $2}' | tr -d \",)
   
   # Get health of target group
   aws elbv2 describe-target-health --target-group-arn $TARGET_GROUP_ARN
   ```

   以下是顯示目標群組狀態的範例輸出：

   ```
   {
       "TargetHealthDescriptions": [
           {
               "Target": {
                   "Id": "<target IP>",
                   "Port": 8998,
                   "AvailabilityZone": "us-west-2d"
               },
               "HealthCheckPort": "8998",
               "TargetHealth": {
                   "State": "healthy"
               }
           }
       ]
   }
   ```

   一旦 NLB 狀態變為 `active` 且目標群組為 `healthy`，您就可以繼續。可能需要幾分鐘的時間。

1. 從 Helm 安裝擷取 Livy 端點。您的 Livy 端點是否安全取決於您是否啟用 SSL。

   ```
   LIVY_NAMESPACE=<livy-ns>
    LIVY_APP_NAME=livy-app-name
    LIVY_ENDPOINT=$(kubectl get svc -n livy-ns -l app.kubernetes.io/instance=livy-app-name,emr-containers.amazonaws.com/type=loadbalancer -o jsonpath='{.items[0].status.loadBalancer.ingress[0].hostname}' |  awk '{printf "%s:8998\n", $0}')
    echo "$LIVY_ENDPOINT"
   ```

1. 從 Helm 安裝擷取 Spark 服務帳戶

   ```
   SPARK_NAMESPACE=spark-ns
   LIVY_APP_NAME=<livy-app-name>
   SPARK_SERVICE_ACCOUNT=$(kubectl --namespace $SPARK_NAMESPACE get sa -l "app.kubernetes.io/instance=$LIVY_APP_NAME" -o jsonpath='{.items[0].metadata.name}')
   echo "$SPARK_SERVICE_ACCOUNT"
   ```

   您應該會看到類似下列的輸出內容：

   ```
   emr-containers-sa-spark-livy
   ```

1. 如果您`internalALB=true`將 設定為從 VPC 外部啟用存取，請建立 Amazon EC2 執行個體，並確保 Network Load Balancer 允許來自 EC2 執行個體的網路流量。您必須這樣做，執行個體才能存取您的 Livy 端點。如需在 VPC 外部安全地公開端點的詳細資訊，請參閱[使用 TLS/SSL 設定安全的 Apache Livy 端點](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/job-runs-apache-livy-secure-endpoint.html)。

1. 安裝 Livy 會建立服務帳戶`emr-containers-sa-spark`以執行 Spark 應用程式。如果您的 Spark 應用程式使用任何 AWS 資源，例如 S3 或呼叫 AWS API 或 CLI 操作，您必須將具有必要許可的 IAM 角色連結至您的 Spark 服務帳戶。如需詳細資訊，請參閱[使用服務帳戶 (IRSA) 的 IAM 角色設定存取許可。](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/job-runs-apache-livy-irsa.html)

Apache Livy 支援您可以在安裝 Livy 時使用的其他組態。如需詳細資訊，請參閱 Amazon EMR on EKS 版本上 Apache Livy 的安裝屬性。

# 使用適用於 Amazon EMR on EKS 的 Apache Livy 執行 Spark 應用程式
<a name="job-runs-apache-livy-run-spark"></a>

在使用 Apache Livy 執行 Spark 應用程式之前，請確定您已完成設定適用於 [Amazon EMR on EKS 的 Apache Livy](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/job-runs-apache-livy-setup.html) 和[適用於 Amazon EMR on EKS 的 Apache Livy 入門](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/job-runs-apache-livy-install.html)中的步驟。

您可以使用 Apache Livy 來執行兩種類型的應用程式：
+ 批次工作階段 – 一種 Livy 工作負載，用於提交 Spark 批次任務。
+ 互動式工作階段 – 一種 Livy 工作負載，提供程式設計和視覺化界面來執行 Spark 查詢。

**注意**  
來自不同工作階段的驅動程式和執行器 Pod 可以互相通訊。命名空間不保證 Pod 之間的任何安全性。Kubernetes 不允許特定命名空間內 Pod 子集的選擇性許可。

## 執行批次工作階段
<a name="job-runs-apache-livy-run-spark-batch"></a>

若要提交批次任務，請使用下列命令。

```
curl -s -k -H 'Content-Type: application/json' -X POST \
      -d '{
            "name": "my-session",
            "file": "entryPoint_location (S3 or local)",
            "args": ["argument1", "argument2", ...],
            "conf": {
                "spark.kubernetes.namespace": "<spark-namespace>",
                "spark.kubernetes.container.image": "public.ecr.aws/emr-on-eks/spark/emr-7.12.0:latest",
                "spark.kubernetes.authenticate.driver.serviceAccountName": "<spark-service-account>"
            }
          }' <livy-endpoint>/batches
```

若要監控您的批次任務，請使用下列命令。

```
curl -s -k -H 'Content-Type: application/json' -X GET <livy-endpoint>/batches/my-session
```

## 執行互動式工作階段
<a name="job-runs-apache-livy-run-spark-interactive"></a>

若要使用 Apache Livy 執行互動式工作階段，請參閱下列步驟。

1. 請確定您能夠存取自我託管或受管 Jupyter 筆記本，例如 SageMaker AI Jupyter 筆記本。您的 jupyter 筆記本必須已安裝 [Sparkmagic](https://github.com/jupyter-incubator/sparkmagic/blob/master/README.md)。

1. 建立 Spark 組態 的儲存貯體`spark.kubernetes.file.upload.path`。確定 Spark 服務帳戶具有對儲存貯體的讀取和寫入存取權。如需如何設定 Spark 服務帳戶的詳細資訊，請參閱使用服務帳戶 (IRSA) 的 IAM 角色設定存取許可

1. 使用命令 在 Jupyter 筆記本中載入 Sparkmagic`%load_ext sparkmagic.magics`。

1. 執行 命令`%manage_spark`，使用 Jupyter 筆記本設定您的 Livy 端點。選擇**新增端點**索引標籤，選擇設定的身分驗證類型，將 Livy 端點新增至筆記本，然後選擇**新增端點**。

1. `%manage_spark` 再次執行 以建立 Spark 內容，然後前往**建立工作階段**。選擇 Livy 端點，指定唯一的工作階段名稱選擇語言，然後新增下列屬性。

   ```
   {
     "conf": {
       "spark.kubernetes.namespace": "livy-namespace",
       "spark.kubernetes.container.image": "public.ecr.aws/emr-on-eks/spark/emr-7.12.0:latest",
       "spark.kubernetes.authenticate.driver.serviceAccountName": "<spark-service-account>", 
       "spark.kubernetes.file.upload.path": "<URI_TO_S3_LOCATION_>"
     }
   }
   ```

1. 提交應用程式並等待它建立 Spark 內容。

1. 若要監控互動式工作階段的狀態，請執行下列命令。

   ```
   curl -s -k -H 'Content-Type: application/json' -X GET livy-endpoint/sessions/my-interactive-session
   ```

## 監控 Spark 應用程式
<a name="job-runs-apache-livy-run-ui"></a>

若要使用 Livy UI 監控 Spark 應用程式的進度，請使用連結 `http://<livy-endpoint>/ui`。

# 使用 Amazon EMR on EKS 解除安裝 Apache Livy
<a name="job-runs-apache-livy-uninstall"></a>

請依照下列步驟解除安裝 Apache Livy。

1. 使用命名空間名稱和應用程式名稱刪除 Livy 設定。在此範例中，應用程式名稱為 `livy-demo`，命名空間為 `livy-ns`。

   ```
   helm uninstall livy-demo -n livy-ns
   ```

1. 解除安裝時，Amazon EMR on EKS 會刪除 Livy 中的 Kubernetes 服務、 AWS 負載平衡器，以及您在安裝期間建立的目標群組。刪除資源可能需要幾分鐘的時間。再次在命名空間上安裝 Livy 之前，請確定已刪除資源。

1. 刪除 Spark 命名空間。

   ```
   kubectl delete namespace spark-ns
   ```

# Apache Livy 搭配 Amazon EMR on EKS 的安全性
<a name="job-runs-apache-livy-security"></a>

請參閱下列主題，進一步了解如何使用 Amazon EMR on EKS 設定 Apache Livy 的安全性。這些選項包括使用傳輸層安全性、角色型存取控制，這是根據個人在組織內的角色進行存取，以及使用 IAM 角色，根據授予的許可提供對資源的存取。

**Topics**
+ [使用 TLS/SSL 設定安全的 Apache Livy 端點](job-runs-apache-livy-secure-endpoint.md)
+ [使用角色型存取控制 (RBAC) 設定 Apache Livy 和 Spark 應用程式許可](job-runs-apache-livy-rbac.md)
+ [使用服務帳戶的 IAM 角色設定存取許可 (IRSA)](job-runs-apache-livy-irsa.md)

# 使用 TLS/SSL 設定安全的 Apache Livy 端點
<a name="job-runs-apache-livy-secure-endpoint"></a>

請參閱下列各節，進一步了解如何使用end-to-end TLS 和 SSL 加密為 Amazon EMR on EKS 設定 Apache Livy。

## 設定 TLS 和 SSL 加密
<a name="job-runs-apache-livy-security-tls"></a>

若要在 Apache Livy 端點上設定 SSL 加密，請遵循下列步驟。
+ [安裝 Secrets Store CSI 驅動程式和 AWS Secrets and Configuration Provider (ASCP)](https://docs.aws.amazon.com/secretsmanager/latest/userguide/integrating_csi_driver.html) – Secrets Store CSI Driver 和 ASCP 安全地存放 Livy 伺服器裝置啟用 SSL 所需的 Livy 的 JKS 憑證和密碼。您也可以僅安裝 Secrets Store CSI Driver，並使用任何其他支援的秘密提供者。
+ [建立 ACM 憑證](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html) – 需要此憑證才能保護用戶端與 ALB 端點之間的連線。
+ 為 - 設定 JKS 憑證、金鑰密碼和金鑰存放區密碼 AWS Secrets Manager ，以保護 ALB 端點與 Livy 伺服器之間的連線。
+ 將許可新增至 Livy 服務帳戶以從中擷取秘密 AWS Secrets Manager – Livy 伺服器需要這些許可才能從 ASCP 擷取秘密，並新增 Livy 組態以保護 Livy 伺服器。若要將 IAM 許可新增至服務帳戶，請參閱使用服務帳戶 (IRSA) 的 IAM 角色設定存取許可。

### 使用 的金鑰和金鑰存放區密碼設定 JKS 憑證 AWS Secrets Manager
<a name="job-runs-apache-livy-jks-certificate"></a>

請依照下列步驟，使用金鑰和金鑰存放區密碼來設定 JKS 憑證。

1. 產生 Livy 伺服器的金鑰存放區檔案。

   ```
   keytool -genkey -alias <host> -keyalg RSA -keysize 2048 –dname CN=<host>,OU=hw,O=hw,L=<your_location>,ST=<state>,C=<country> –keypass <keyPassword> -keystore <keystore_file> -storepass <storePassword> --validity 3650
   ```

1. 建立憑證。

   ```
   keytool -export -alias <host> -keystore mykeystore.jks -rfc -file mycertificate.cert -storepass <storePassword>
   ```

1. 建立信任存放區檔案。

   ```
   keytool -import -noprompt -alias <host>-file <cert_file> -keystore <truststore_file> -storepass <truststorePassword>
   ```

1. 將 JKS 憑證儲存在其中 AWS Secrets Manager。將 取代`livy-jks-secret`為您的秘密，並將 `fileb://mykeystore.jks` 取代為金鑰存放區 JKS 憑證的路徑。

   ```
   aws secretsmanager create-secret \ 
   --name livy-jks-secret \
   --description "My Livy keystore JKS secret" \
   --secret-binary fileb://mykeystore.jks
   ```

1. 在 Secrets Manager 中儲存金鑰存放區和金鑰密碼。請務必使用您自己的參數。

   ```
   aws secretsmanager create-secret \
   --name livy-jks-secret \
   --description "My Livy key and keystore password secret" \
   --secret-string "{\"keyPassword\":\"<test-key-password>\",\"keyStorePassword\":\"<test-key-store-password>\"}"
   ```

1. 使用下列命令建立 Livy 伺服器命名空間。

   ```
   kubectl create ns <livy-ns>
   ```

1. 為具有 JKS 憑證和密碼的 Livy 伺服器建立 `ServiceProviderClass` 物件。

   ```
   cat >livy-secret-provider-class.yaml << EOF
   apiVersion: secrets-store.csi.x-k8s.io/v1
   kind: SecretProviderClass
   metadata:
     name: aws-secrets
   spec:
     provider: aws
     parameters:
       objects: |
           - objectName: "livy-jks-secret"
             objectType: "secretsmanager"
           - objectName: "livy-passwords"
             objectType: "secretsmanager"
                        
   EOF
   kubectl apply -f livy-secret-provider-class.yaml -n <livy-ns>
   ```

## 啟用 SSL 的 Apache Livy 入門
<a name="job-runs-apache-livy-ssl-enabled-getting-started"></a>

在 Livy 伺服器上啟用 SSL 之後，您必須設定 `serviceAccount` 才能存取 `keyStore`和 `keyPasswords`秘密 AWS Secrets Manager。

1. 建立 Livy 伺服器命名空間。

   ```
   kubectl create namespace <livy-ns>
   ```

1. 設定 Livy 服務帳戶以存取 Secrets Manager 中的秘密。如需設定 IRSA 的詳細資訊，請參閱在[安裝 Apache Livy 時設定 IRSA](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/job-runs-apache-livy-irsa.html#job-runs-apache-livy-irsa)。

   ```
   aws ecr get-login-password \--region region-id | helm registry login \
   --username AWS \
   --password-stdin ECR-registry-account.dkr.ecr.region-id.amazonaws.com
   ```

1. 安裝 Livy。對於 Helm Chart --version 參數，請使用您的 Amazon EMR 發行標籤，例如 `7.1.0`。您也必須將 Amazon ECR 登錄帳戶 ID 和區域 ID 取代為您自己的 IDs。您可以從 AWS 區域 [Amazon ECR 登錄帳戶依區域](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/docker-custom-images-tag.html#docker-custom-images-ECR)尋找 的對應`ECR-registry-account`值。

   ```
   helm install <livy-app-name> \
     oci://895885662937.dkr.ecr.region-id.amazonaws.com/livy \
     --version 7.12.0 \
     --namespace livy-namespace-name \
     --set image=<ECR-registry-account.dkr.ecr>.<region>.amazonaws.com/livy/emr-7.12.0:latest \
     --set sparkNamespace=spark-namespace \
     --set ssl.enabled=true
     --set ssl.CertificateArn=livy-acm-certificate-arn
     --set ssl.secretProviderClassName=aws-secrets
     --set ssl.keyStoreObjectName=livy-jks-secret
     --set ssl.keyPasswordsObjectName=livy-passwords
     --create-namespace
   ```

1. 從[在 Amazon EMR on EKS 上安裝 Apache Livy 的步驟 ](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/job-runs-apache-livy-setup.html#job-runs-apache-livy-install)5 繼續。

# 使用角色型存取控制 (RBAC) 設定 Apache Livy 和 Spark 應用程式許可
<a name="job-runs-apache-livy-rbac"></a>

若要部署 Livy，Amazon EMR on EKS 會建立伺服器服務帳戶和角色，以及 Spark 服務帳戶和角色。這些角色必須具備必要的 RBAC 許可，才能完成設定並執行 Spark 應用程式。

**伺服器服務帳戶和角色的 RBAC 許可**

Amazon EMR on EKS 會建立 Livy 伺服器服務帳戶和角色，以管理 Spark 任務的 Livy 工作階段，以及將流量路由到輸入和其他資源或從中路由。

此服務帳戶的預設名稱為 `emr-containers-sa-livy`。它必須具有下列許可。

```
rules:
- apiGroups:
  - ""
  resources:
  - "namespaces"
  verbs:
  - "get"
- apiGroups:
  - ""
  resources:
  - "serviceaccounts"
    "services"
    "configmaps"
    "events"
    "pods"
    "pods/log"
  verbs:
  - "get"
    "list"
    "watch"
    "describe"
    "create"
    "edit"
    "delete"
    "deletecollection"
    "annotate"
    "patch"
    "label"
 - apiGroups:
   - ""
   resources:
   - "secrets"
   verbs:
   - "create"
     "patch"
     "delete"
     "watch"
 - apiGroups:
   - ""
   resources:
   - "persistentvolumeclaims"
   verbs:
   - "get"
     "list"
     "watch"
     "describe"
     "create"
     "edit"
     "delete"
     "annotate"
     "patch"
     "label"
```

**Spark 服務帳戶和角色的 RBAC 許可**

Spark 驅動程式 Pod 需要與該 Pod 位於相同命名空間的 Kubernetes 服務帳戶。此服務帳戶需要管理執行器 Pod 和驅動程式 Pod 所需任何資源的許可。除非命名空間中的預設服務帳戶具有必要的許可，否則驅動程式會失敗並結束。需要下列 RBAC 許可。

```
rules:
- apiGroups:
  - ""
    "batch"
    "extensions"
    "apps"
  resources:
  - "configmaps"
    "serviceaccounts"
    "events"
    "pods"
    "pods/exec"
    "pods/log"
    "pods/portforward"
    "secrets"
    "services"
    "persistentvolumeclaims"
    "statefulsets"
  verbs:
  - "create"
    "delete"
    "get"
    "list"
    "patch"
    "update"
    "watch"
    "describe"
    "edit"
    "deletecollection"
    "patch"
    "label"
```

# 使用服務帳戶的 IAM 角色設定存取許可 (IRSA)
<a name="job-runs-apache-livy-irsa"></a>

根據預設，Livy 伺服器和 Spark 應用程式的驅動程式和執行程式無法存取 AWS 資源。伺服器服務帳戶和 Spark 服務帳戶控制對 Livy 伺服器和 Spark 應用程式 Pod AWS 資源的存取。若要授予存取權，您需要將服務帳戶對應至具有必要 AWS 許可的 IAM 角色。

您可以在安裝 Apache Livy 之前、安裝期間或完成安裝之後設定 IRSA 映射。

## 在安裝 Apache Livy 時設定 IRSA （適用於伺服器服務帳戶）
<a name="job-runs-apache-livy-irsa"></a>

**注意**  
只有伺服器服務帳戶才支援此映射。

1. 請確定您已完成[為 Amazon EMR on EKS 設定 Apache Livy，](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/job-runs-apache-livy-setup.html)並且正在[搭配 Amazon EMR on EKS 安裝 Apache Livy](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/job-runs-apache-livy-install.html)。

1. 為 Livy 伺服器建立 Kubernetes 命名空間。在此範例中，命名空間的名稱為 `livy-ns`。

1. 建立 IAM 政策，其中包含您希望 Pod 存取 AWS 服務 的 許可。下列範例會建立 IAM 政策，以取得 Spark 進入點的 Amazon S3 資源。

   ```
   cat >my-policy.json <<EOF{
   "Version": "2012-10-17",		 	 	 
       "Statement": [
           {
   "Effect": "Allow",
               "Action": "s3:GetObject",
               "Resource": "arn:aws:s3:::my-spark-entrypoint-bucket"
           }
       ]
   }
   EOF
   
   aws iam create-policy --policy-name my-policy --policy-document file://my-policy.json
   ```

1. 使用下列命令將您的 AWS 帳戶 ID 設定為變數。

   ```
   account_id=$(aws sts get-caller-identity --query "Account" --output text)
   ```

1. 將叢集的 OpenID Connect (OIDC) 身分提供者設定為 環境變數。

   ```
   oidc_provider=$(aws eks describe-cluster --name my-cluster --region $AWS_REGION --query "cluster.identity.oidc.issuer" --output text | sed -e "s/^https:\/\///")
   ```

1. 設定命名空間和服務帳戶名稱的變數。請務必使用您自己的值。

   ```
   export namespace=default
   export service_account=my-service-account
   ```

1. 使用下列命令建立信任政策檔案。如果您想要將角色的存取權授予命名空間中的所有服務帳戶，請複製下列命令，並將 取代`StringEquals`為 `StringLike`，並將 取代`$service_account`為 `*`。

   ```
   cat >trust-relationship.json <<EOF
   {
     "Version": "2012-10-17",		 	 	 
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "Federated": "arn:aws:iam::$account_id:oidc-provider/$oidc_provider"
         },
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Condition": {
           "StringEquals": {
             "$oidc_provider:aud": "sts.amazonaws.com",
             "$oidc_provider:sub": "system:serviceaccount:$namespace:$service_account"
           }
         }
       }
     ]
   }
   EOF
   ```

1. 建立角色。

   ```
   aws iam create-role --role-name my-role --assume-role-policy-document file://trust-relationship.json --description "my-role-description"
   ```

1. 使用下列 Helm 安裝命令來設定 `serviceAccount.executionRoleArn`以對應 IRSA。以下是 Helm 安裝命令的範例。您可以從 AWS 區域 [Amazon ECR 登錄帳戶依區域](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/docker-custom-images-tag.html#docker-custom-images-ECR)尋找 的對應`ECR-registry-account`值。

   ```
   helm install livy-demo \
     oci://895885662937.dkr.ecr.us-west-2.amazonaws.com/livy \
     --version 7.12.0 \
     --namespace livy-ns \
     --set image=ECR-registry-account.dkr.ecr.region-id.amazonaws.com/livy/emr-7.12.0:latest \
     --set sparkNamespace=spark-ns \
     --set serviceAccount.executionRoleArn=arn:aws:iam::123456789012:role/my-role
   ```

## 將 IRSA 映射至 Spark 服務帳戶
<a name="job-runs-apache-livy-irsa-spark"></a>

將 IRSA 映射至 Spark 服務帳戶之前，請確定您已完成下列項目：
+ 請確定您已完成[為 Amazon EMR on EKS 設定 Apache Livy，](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/job-runs-apache-livy-setup.html)並且正在[搭配 Amazon EMR on EKS 安裝 Apache Livy](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/job-runs-apache-livy-install.html)。
+ 您必須為叢集擁有現有的 IAM OpenID Connect (OIDC) 提供者。若要查看您是否已經擁有或如何建立，請參閱[為您的叢集建立 IAM OIDC 提供者](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html)。
+ 請確定您已安裝 或 的 `eksctl` CLI 版本 0.171.0 或更新版本 AWS CloudShell。若要安裝或更新 `eksctl`，請參閱[安裝](https://eksctl.io/installation/) `eksctl` 文件。

請依照下列步驟將 IRSA 映射到您的 Spark 服務帳戶：

1. 使用下列命令來取得 Spark 服務帳戶。

   ```
   SPARK_NAMESPACE=<spark-ns>
   LIVY_APP_NAME=<livy-app-name>
   kubectl --namespace $SPARK_NAMESPACE describe sa -l "app.kubernetes.io/instance=$LIVY_APP_NAME" | awk '/^Name:/ {print $2}'
   ```

1. 為服務帳戶的命名空間和名稱設定變數。

   ```
   export namespace=default
   export service_account=my-service-account
   ```

1. 使用下列命令為 IAM 角色建立信任政策檔案。下列範例會授予 命名空間內所有服務帳戶的許可，以使用 角色。若要這樣做，請將 取代`StringEquals`為 `StringLike`，並將 取代`$service_account`為 \$1。

   ```
   cat >trust-relationship.json <<EOF
   {
     "Version": "2012-10-17",		 	 	 
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "Federated": "arn:aws:iam::$account_id:oidc-provider/$oidc_provider"
         },
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Condition": {
           "StringEquals": {
             "$oidc_provider:aud": "sts.amazonaws.com",
             "$oidc_provider:sub": "system:serviceaccount:$namespace:$service_account"
           }
         }
       }
     ]
   }
   EOF
   ```

1. 建立角色。

   ```
   aws iam create-role --role-name my-role --assume-role-policy-document file://trust-relationship.json --description "my-role-description"
   ```

1. 使用下列`eksctl`命令對應伺服器或 Spark 服務帳戶。請務必使用您自己的值。

   ```
    eksctl create iamserviceaccount --name spark-sa \
    --namespace spark-namespace --cluster livy-eks-cluster \
    --attach-role-arn arn:aws:iam::0123456789012:role/my-role \
    --approve --override-existing-serviceaccounts
   ```

# Amazon EMR on EKS 版本上 Apache Livy 的安裝屬性
<a name="job-runs-apache-livy-installation-properties"></a>

Apache Livy 安裝可讓您選取 Livy Helm Chart 的版本。Helm Chart 提供各種屬性，可自訂您的安裝和設定體驗。Amazon EMR on EKS 7.1.0 版及更新版本支援這些屬性。

**Topics**
+ [Amazon EMR 7.1.0 安裝屬性](#job-runs-apache-livy-installation-properties-710)

## Amazon EMR 7.1.0 安裝屬性
<a name="job-runs-apache-livy-installation-properties-710"></a>

下表說明所有支援的 Livy 屬性。安裝 Apache Livy 時，您可以選擇 Livy Helm Chart 版本。若要在安裝期間設定屬性，請使用命令 `--set <property>=<value>`。


| 屬性 | 描述 | 預設 | 
| --- | --- | --- | 
| image | Livy 伺服器的 Amazon EMR 版本 URI。這是必要的組態。 | "" | 
| sparkNamespace | 執行 Livy Spark 工作階段的命名空間。例如，指定「livy」。這是必要的組態。 | "" | 
| nameOverride | 提供名稱而非 livy。名稱會設定為所有 Livy 資源的標籤 | "livy" | 
| fullnameOverride | 提供要使用的名稱，而非資源的完整名稱。 | "" | 
| ssl.enabled | 啟用從 Livy 端點到 Livy 伺服器的end-to-end SSL。 | FALSE | 
| ssl.certificateArn | 如果啟用 SSL，這是服務所建立 NLB 的 ACM 憑證 ARN。 | "" | 
| ssl.secretProviderClassName | 如果啟用 SSL，這是使用 SSL 保護 Livy 伺服器連線 NLB 的秘密提供者類別名稱。 | "" | 
| ssl.keyStoreObjectName | 如果啟用 SSL，則秘密提供者類別中金鑰存放區憑證的物件名稱。 | "" | 
| ssl.keyPasswordsObjectName | 如果已啟用 SSL，則具有金鑰存放區和金鑰密碼之秘密的物件名稱。 | "" | 
| rbac.create | 如果為 true， 會建立 RBAC 資源。 | FALSE | 
| serviceAccount.create | 如果為 true， 會建立 Livy 服務帳戶。 | TRUE | 
| serviceAccount.name | 用於 Livy 的服務帳戶名稱。如果您未設定此屬性並建立服務帳戶，Amazon EMR on EKS 會使用fullname覆寫屬性自動產生名稱。 | 「emr-containers-sa-livy」 | 
| serviceAccount.executionRoleArn | Livy 服務帳戶的執行角色 ARN。 | "" | 
| sparkServiceAccount.create | 如果為 true， 會在 中建立 Spark 服務帳戶 .Release.Namespace | TRUE | 
| sparkServiceAccount.name | 用於 Spark 的服務帳戶名稱。如果您未設定此屬性並建立 Spark 服務帳戶，Amazon EMR on EKS -spark-livy 會自動產生帶有尾碼fullnameOverride屬性的名稱。 | 「emr-containers-sa-spark-livy」 | 
| service.name | Livy 服務的名稱 | "emr-containers-livy" | 
| service.annotations | Livy 服務註釋 | \$1\$1 | 
| loadbalancer.enabled | 是否要為用於在 Amazon EKS 叢集外部公開 Livy 端點的 Livy 服務建立負載平衡器。 | FALSE | 
| loadbalancer.internal | 是否要將 Livy 端點設定為 VPC 內部或外部。 將此屬性設定為向 VPC 外部的來源`FALSE`公開端點。我們建議您使用 TLS/SSL 保護您的端點。如需詳細資訊，請參閱[設定 TLS 和 SSL 加密](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/job-runs-apache-livy-security.html#job-runs-apache-livy-security-tls)。 | FALSE | 
| imagePullSecrets | 用於從私有儲存庫提取 Livy 映像imagePullSecret的名稱清單。 | [] | 
| resources | Livy 容器的資源請求和限制。 | \$1\$1 | 
| nodeSelector | 排程 Livy Pod 的節點。 | \$1\$1 | 
| 容差 | 包含要定義的 Livy Pod 容錯的清單。 | [] | 
| 親和性 | Livy Pod 親和性規則。 | \$1\$1 | 
| persistence.enabled | 如果為 true， 會啟用工作階段目錄的持久性。 | FALSE | 
| persistence.subPath | 掛載至工作階段目錄的 PVC 子路徑。 | "" | 
| persistence.existingClaim | 要使用的 PVC，而不是建立新的 PVC。 | \$1\$1 | 
| persistence.storageClass | 要使用的儲存體方案。若要定義此參數，請使用格式 storageClassName: <storageClass>。將此參數設定為 會"-"停用動態佈建。如果您將此參數設定為 null 或未指定任何項目，Amazon EMR on EKS 不會設定 storageClassName 並使用預設佈建器。 | "" | 
| persistence.accessMode | PVC 存取模式。 | ReadWriteOnce | 
| persistence.size | PVC 大小。 | 20Gi | 
| persistence.annotations | PVC 的其他註釋。 | \$1\$1 | 
| env.\$1 | 要設定為 Livy 容器的其他 env。如需詳細資訊，請參閱在[安裝 Livy 時輸入您自己的 Livy 和 Spark 組態](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/job-runs-apache-livy-troubleshooting.html)。 | \$1\$1 | 
| envFrom.\$1 | 從 Kubernetes 組態映射或秘密設定為 Livy 的其他 env。 | [] | 
| livyConf.\$1 | 從掛載的 Kubernetes 組態映射或秘密設定的其他 livy.conf 項目。 | \$1\$1 | 
| sparkDefaultsConf.\$1 | 從掛載的 Kubernetes 組態映射或秘密設定的其他spark-defaults.conf項目。 | \$1\$1 | 

# 疑難排解常見的環境變數格式錯誤
<a name="job-runs-apache-livy-troubleshooting"></a>

當您輸入 Livy 和 Spark 組態時，不支援環境變數格式，並可能導致錯誤。此程序會引導您完成一系列步驟，以協助確保您使用正確的格式。

**在安裝 Livy 時輸入您自己的 Livy 和 Spark 組態**

您可以使用 `env.*` Helm 屬性設定任何 Apache Livy 或 Apache Spark 環境變數。請依照下列步驟，將範例組態轉換為`example.config.with-dash.withUppercase`支援的環境變數格式。

1. 使用 1 和小寫字母取代大寫字母。例如，`example.config.with-dash.withUppercase` 會變成 `example.config.with-dash.with1uppercase`。

1. 將破折號 (-) 取代為 0。例如， `example.config.with-dash.with1uppercase`會變成 `example.config.with0dash.with1uppercase`

1. 以底線 (\$1) 取代點 (.)。例如，`example.config.with0dash.with1uppercase` 會變成 `example_config_with0dash_with1uppercase`。

1. 以大寫字母取代所有小寫字母。

1. 將 字首`LIVY_`新增至變數名稱。

1. 使用格式 --set env.*YOUR\$1VARIABLE\$1NAME*.value=*yourvalue* 透過 Helm Chart 安裝 Livy 時，請使用 變數

例如，若要設定 Livy 和 Spark 組態 `livy.server.recovery.state-store = filesystem` 和 `spark.kubernetes.executor.podNamePrefix = my-prefix`，請使用下列 Helm 屬性：

```
—set env.LIVY_LIVY_SERVER_RECOVERY_STATE0STORE.value=filesystem
—set env.LIVY_SPARK_KUBERNETES_EXECUTOR_POD0NAME0PREFIX.value=myprefix
```