教學課程 - Spring Boot 應用程式搭配 Azure Cosmos DB for NoSQL 和 Azure Kubernetes Service

發行項
08/15/2024

適用於：NoSQL

注意

對於 Spring Boot 應用程式，建議使用 Azure Spring 應用程式。不過，您仍可使用 Azure Kubernetes Service 作為目的地。如需建議，請參閱 Java 工作負載目的地指導。

在本教學課程中，您將會設定和部署可公開 REST API 的 Spring Boot 應用程式，以對 Azure Cosmos DB (API for NoSQL 帳戶) 中的資料執行 CRUD 作業。您會將應用程式封裝為 Docker 映像、將其推送至 Azure Container Registry、部署至 Azure Kubernetes Service，以及測試應用程式。

必要條件

具有有效訂用帳戶的 Azure 帳戶。建立免費帳戶或免費試用 Azure Cosmos DB (不需 Azure 訂用帳戶)。
Java 開發套件 (JDK) 8 $英文$。將 JAVA_HOME 環境變數指向 JDK 安裝所在的路徑。
Azure CLI 以佈建 Azure 服務。
Docker 以管理映像和容器。
Maven 和 Git 的最新版本。
curl 以叫用 REST API 公開的應用程式。

佈建 Azure 服務

在本節中，您將建立本教學課程所需的 Azure 服務。

Azure Cosmos DB
Azure Container Registry
Azure Kubernetes Service

為此教學課程中使用的 Azure 資源建立資源群組

使用 Azure CLI 來登入您的 Azure 帳戶：
```
az login
```

選擇您的 Azure 訂用帳戶：

az account set -s <enter subscription ID>

建立資源群組。
```
az group create --name=cosmosdb-springboot-aks-rg --location=eastus
```
注意

以資源群組的唯一名稱取代 cosmosdb-springboot-aks-rg。

建立 Azure Cosmos DB for NoSQL 資料庫帳戶

使用 Azure CLI，透過下列命令來建立 Azure Cosmos DB for NoSQL 資料庫帳戶。

az cosmosdb create --name <enter account name> --resource-group <enter resource group name>

使用 Azure CLI 建立私人 Azure Container Registry

注意

以登錄的唯一名稱取代 cosmosdbspringbootregistry。

az acr create --resource-group cosmosdb-springboot-aks-rg --location eastus \
    --name cosmosdbspringbootregistry --sku Basic

使用 Azure CLI 在 Azure 上建立 Kubernetes 叢集

下列命令會在 cosmosdb-springboot-aks-rg 資源群組中建立 Kubernetes 叢集，並以 cosmosdb-springboot-aks 作為叢集名稱，且附加 Azure Container Registry (ACR)cosmosdbspringbootregistry：
```
az aks create \
    --resource-group cosmosdb-springboot-aks-rg \
    --name cosmosdb-springboot-aks \
    --node-count 1 \
    --generate-ssh-keys \
    --attach-acr cosmosdbspringbootregistry \
    --dns-name-prefix=cosmosdb-springboot-aks-app
```
此命令可能需要一些時間才能完成。
如果您尚未安裝 kubectl，則可以使用 Azure CLI 來進行。
```
az aks install-cli
```

取得 Azure Kubernetes Service 叢集的存取認證。

az aks get-credentials --resource-group=cosmosdb-springboot-aks-rg --name=cosmosdb-springboot-aks

kubectl get nodes

建置應用程式

複製應用程式，並切換至正確的目錄。

git clone https://github.com/Azure-Samples/cosmosdb-springboot-aks.git

cd cosmosdb-springboot-aks

使用 Maven 以建置應用程式。在這個步驟結束時，您應該已在 target 資料夾中建立應用程式 JAR 檔案。
```
./mvnw install
```

在本機執行應用程式

如果您想要在 Azure Kubernetes Service 上執行應用程式，則請略過本節，並繼續將 Docker 映像推送至 Azure Container Registry

執行應用程式之前，請使用 Azure Cosmos DB 帳戶的詳細資料來更新 application.properties 檔案。

azure.cosmos.uri=https://<enter Azure Cosmos DB db account name>.azure.com:443/
azure.cosmos.key=<enter Azure Cosmos DB db primary key>
azure.cosmos.database=<enter Azure Cosmos DB db database name>
azure.cosmos.populateQueryMetrics=false

注意

當您啟動應用程式之後，將會自動建立資料庫和容器 (稱為 users)。

在本機執行應用程式。
```
java -jar target/*.jar
```
繼續存取應用程式，或參閱下節以將應用程式部署至 Kubernetes。

將 Docker 映像推送至 Azure Container Registry

組建 Docker 映像
```
docker build -t cosmosdbspringbootregistry.azurecr.io/spring-cosmos-app:v1 .
```
注意

將 cosmosdbspringbootregistry 取代為您 Azure Container Registry 的名稱

登入 Azure Container Registry。

az acr login -n cosmosdbspringbootregistry

將映像推送至 Azure Container Registry，並將其列出。

docker push cosmosdbspringbootregistry.azurecr.io/spring-cosmos-app:v1

az acr repository list --name cosmosdbspringbootregistry --output table

將應用程式部署至 Azure Kubernetes Service

使用 Azure Cosmos DB 設定的詳細資料，編輯 app.yaml 中的 Secret。

...
apiVersion: v1
kind: Secret
metadata:
  name: app-config
type: Opaque
stringData:
  application.properties: |
    azure.cosmos.uri=https://<enter Azure Cosmos DB db account name>.azure.com:443/
    azure.cosmos.key=<enter Azure Cosmos DB db primary key>
    azure.cosmos.database=<enter Azure Cosmos DB db database name>
    azure.cosmos.populateQueryMetrics=false
...

注意

當您啟動應用程式之後，將會自動建立資料庫和容器 (users)。

部署至 Kubernetes，並等候 Pod 轉換至 Running 狀態：
```
kubectl apply -f deploy/app.yaml

kubectl get pods -l=app=spring-cosmos-app -w
```
注意

您可以使用下列命令來檢查應用程式記錄：kubectl logs -f $(kubectl get pods -l=app=spring-cosmos-app -o=jsonpath='{.items[0].metadata.name}') -c spring-cosmos-app

存取應用程式

如果應用程式是在 Kubernetes 中執行，而您想要透過連接埠 8080 在本機存取它，則請執行下列命令：

kubectl port-forward svc/spring-cosmos-app-internal 8080:8080

叫用 REST 端點以測試應用程式。您也可以導覽至 Azure 入口網站中 Azure Cosmos DB 帳戶的 Data Explorer 功能表，並存取 users 容器來確認作業的結果。

建立新的使用者

curl -i -X POST -H "Content-Type: application/json" -d '{"email":"john.doe@foobar.com", "firstName": "John", "lastName": "Doe", "city": "NYC"}' http://localhost:8080/users

curl -i -X POST -H "Content-Type: application/json" -d '{"email":"mr.jim@foobar.com", "firstName": "mr", "lastName": "jim", "city": "Seattle"}' http://localhost:8080/users

如果成功，則您應該會收到 HTTP 201 回應。

更新使用者

curl -i -X POST -H "Content-Type: application/json" -d '{"email":"john.doe@foobar.com", "firstName": "John", "lastName": "Doe", "city": "Dallas"}' http://localhost:8080/users

列出所有使用者
```
curl -i http://localhost:8080/users
```

取得現有使用者

curl -i http://localhost:8080/users/john.doe@foobar.com

您應該會取回具有使用者詳細資料的 JSON 承載。例如：

{
  "email": "john.doe@foobar.com",
  "firstName": "John",
  "lastName": "Doe",
  "city": "Dallas"
}

嘗試取得不存在的使用者
```
curl -i http://localhost:8080/users/not.there@foobar.com
```
您應該會收到 HTTP 404 回應。

取代使用者

curl -i -X PUT -H "Content-Type: application/json" -d '{"email":"john.doe@foobar.com", "firstName": "john", "lastName": "doe","city": "New Jersey"}' http://localhost:8080/users/

嘗試取代不存在的使用者

curl -i -X PUT -H "Content-Type: application/json" -d '{"email":"not.there@foobar.com", "firstName": "john", "lastName": "doe","city": "New Jersey"}' http://localhost:8080/users/

您應該會收到 HTTP 404 回應。

刪除使用者

curl -i -X DELETE http://localhost:8080/users/mr.jim@foobar.com

刪除不存在的使用者

curl -X DELETE http://localhost:8080/users/go.nuts@foobar.com

您應該會收到 HTTP 404 回應。

使用公用 IP 位址存取應用程式 (選用)

在 Azure Kubernetes Service 中建立類型 LoadBalancer 的服務，將會導致佈建 Azure Load Balancer。您接著可以使用應用程式的公用 IP 位址來存取應用程式。

建立類型為 LoadBalancer 的 Kubernetes 服務

注意

這將會建立具有公用 IP 位址的 Azure Load Balancer。
```
kubectl apply -f deploy/load-balancer-service.yaml
```

等候建立 Azure Load Balancer。在那之前，Kubernetes 服務的 EXTERNAL-IP 將會維持 <pending> 狀態。

kubectl get service spring-cosmos-app -w

NAME                TYPE           CLUSTER-IP   EXTERNAL-IP   PORT(S)          AGE
spring-cosmos-app   LoadBalancer   10.0.68.83   <pending>     8080:31523/TCP   6s

注意

在您的案例中，CLUSTER-IP 值可能會不同

Azure Load Balancer 建立完成之後，EXTERNAL-IP 就可以使用。

NAME                TYPE           CLUSTER-IP   EXTERNAL-IP   PORT(S)          AGE
spring-cosmos-app   LoadBalancer   10.0.68.83   20.81.108.180   8080:31523/TCP   18s

注意

在您的案例中，EXTERNAL-IP 值可能會不同

使用公用 IP 位址

終止 kubectl watch 程序，然後使用公用 IP 位址和連接埠 8080 來重複上述 curl 命令。例如，若要列出所有使用者：
```
 curl -i http://20.81.108.180:8080/users
```
注意

將 20.81.108.180 取代為您環境的公用 IP 位址

應用程式的 Kubernetes 資源

以下一些重點是有關此應用程式的 Kubernetes 資源：

Spring Boot 應用程式是根據 Azure Container Registry 中的 Docker 映像的 Kubernetes Deployment
Azure Cosmos DB 組態會掛接在application.properties容器內的路徑/config中。
這可以使用 Kubernetes Volume 來完成，而其接著會參照 Kubernetes 祕密 (與應用程式一起建立)。您可以執行下列命令，以確認此檔案存在於應用程式容器內：
```
kubectl exec -it $(kubectl get pods -l=app=spring-cosmos-app -o=jsonpath='{.items[0].metadata.name}') -c spring-cosmos-app -- cat /config/application.properties
```
此應用程式的活躍度和整備度探查設定是參照將 Spring Boot 應用程式部署至 Kubernetes 環境 - /actuator/health/liveness 和 /actuator/health/readiness 時，由 Spring Boot Actuator 所提供的 HTTP 端點。
您可以建立 ClusterIP 服務，以在 Kubernetes 叢集「內部」存取 Spring Boot 應用程式的 REST 端點。
您可以建立 LoadBalancer 服務，以透過公用 IP 位址存取應用程式。

清除資源

完成您的應用程式和 Azure Cosmos DB 帳戶之後，您可以將建立的 Azure 資源刪除，以免產生更多費用。若要刪除資源：

在 Azure 入口網站的 [搜尋] 列中，搜尋並選取 [資源群組]。
在該清單中，選取您在本快速入門中建立的資源群組。
在 [資源群組] 的 [概觀] 頁面中，選取 [刪除資源群組]。
在下個視窗中輸入要刪除的資源群組名稱，然後選取 [刪除]。

下一步

在本教學課程中，您已了解如何將 Spring Boot 應用程式部署至 Azure Kubernetes Service，並使用它以對 Azure Cosmos DB for NoSQL 帳戶中的資料執行作業。

適用於 API for NoSQL 的 Spring Data Azure Cosmos DB v3

共用方式為