Applicazione Spring Boot con Azure Cosmos DB for NoSQL e il servizio Azure Kubernetes

Si applica a: ✅ NoSQL

Nota

Per le applicazioni Spring Boot, è consigliabile usare Azure Spring Apps. Tuttavia, è comunque possibile usare il servizio Azure Kubernetes come destinazione. Per consigli, vedere Indicazioni sulla destinazione del carico di lavoro Java.

In questa esercitazione, si configura e si distribuisce un'applicazione Spring Boot che espone le API REST per eseguire operazioni CRUD sui dati in Azure Cosmos DB (account API per NoSQL). L'applicazione viene inserita in un pacchetto come immagine Docker, ne viene eseguito il push nel Registro Azure Container, viene distribuita nel servizio Azure Kubernetes e viene testata.

Prerequisiti

Un account Azure con una sottoscrizione attiva. Creare un account gratuito se non si dispone di una sottoscrizione di Azure.
Java Development Kit (JDK) 8. Indirizzare la variabile di ambiente JAVA_HOME al percorso di installazione del JDK.
Interfaccia della riga di comando di Azure per creare servizi di Azure.
Docker per gestire immagini e contenitori.
Versione recente di Maven e Git.
curl per richiamare le API REST esposte alle applicazioni.

Creare servizi di Azure

In questa sezione vengono creati i servizi di Azure necessari per l’esercitazione.

Azure Cosmos DB
Registro dei Contenitori di Azure
Servizio Azure Kubernetes

Creare un gruppo di risorse per le risorse di Azure usate in questa esercitazione

Accedere all'account Azure usando l'interfaccia della riga di comando di Azure:
```
az login
```

Scegliere la sottoscrizione di Azure:

az account set -s <enter subscription ID>

Crea un gruppo di risorse.
```
az group create --name=cosmosdb-springboot-aks-rg --location=eastus
```
Nota

Sostituire cosmosdb-springboot-aks-rg con un nome univoco per il gruppo di risorse.

Creare un account di database Azure Cosmos DB per NoSQL

Usa questo comando per creare un account di database Azure Cosmos DB per NoSQL usando Azure CLI.

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

Creare un Registro Azure Container privato usando l'interfaccia della riga di comando di Azure

Nota

Sostituire cosmosdbspringbootregistry con un nome univoco da assegnare al registro.

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

Creare un cluster Kubernetes su Azure usando l'interfaccia della riga di comando di Azure

Il comando seguente crea un cluster Kubernetes nel gruppo di risorse cosmosdb-springboot-aks-rg, con cosmosdb-springboot-aks come nome del cluster, con il Registro Azure Container (ACR) cosmosdbspringbootregistry collegato:
```
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
```
Nota

Il completamento di questo comando potrebbe richiedere alcuni minuti.
Se kubectl non è installato, è possibile farlo usando l'interfaccia della riga di comando di Azure.
```
az aks install-cli
```

Ottenere le credenziali di accesso per il cluster del servizio Azure Kubernetes.

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

kubectl get nodes

Compilare l'applicazione

Clonare l'applicazione e passare alla directory corretta.

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

cd cosmosdb-springboot-aks

Usare Maven per compilare l'applicazione. Al termine di questo passaggio, è necessario creare il file JAR dell'applicazione nella cartella target.
```
./mvnw install
```

Eseguire l'applicazione in locale

Se si intende eseguire l'applicazione nel servizio Azure Kubernetes, ignorare questa sezione e passare a Eseguire il push dell'immagine Docker nel Registro Azure Container

Prima di eseguire l'applicazione, aggiornare il file application.properties con i dettagli dell'account Azure Cosmos DB.

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

Nota

Il database e il contenitore (denominato users) vengono creati automaticamente dopo l'avvio dell'applicazione.

Eseguire l'applicazione in locale.
```
java -jar target/*.jar
```

Eseguire il push dell'immagine Docker nel Registro Azure Container

Compilare l'immagine Docker
```
docker build -t cosmosdbspringbootregistry.azurecr.io/spring-cosmos-app:v1 .
```
Nota

Sostituire cosmosdbspringbootregistry con il nome del Registro Azure Container

Accedere al Registro Azure Container.

az acr login -n cosmosdbspringbootregistry

Eseguire il push dell'immagine in Registro Azure Container ed elencarla.

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

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

Distribuire l'applicazione nel servizio Azure Kubernetes

Modificare Secret in app.yaml con i dettagli della configurazione di Azure Cosmos DB.

...
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
...

Nota

Il database e un contenitore (users) vengono creati automaticamente dopo l'avvio dell'applicazione.

Eseguire la distribuzione in Kubernetes e attendere la transizione di Pod nello stato Running:
```
kubectl apply -f deploy/app.yaml

kubectl get pods -l=app=spring-cosmos-app -w
```
Nota

È possibile controllare i log applicazioni usando: kubectl logs -f $(kubectl get pods -l=app=spring-cosmos-app -o=jsonpath='{.items[0].metadata.name}') -c spring-cosmos-app

Accedere all'applicazione

Se l'applicazione è in esecuzione in Kubernetes e vi si vuole accedere localmente sulla porta 8080, eseguire questo comando:

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

Testare l'applicazione richiamando gli endpoint REST. È inoltre possibile passare al menu Data Explorer dell'account Azure Cosmos DB nel portale di Azure e accedere al contenitore users per confermare il risultato delle operazioni.

Creare nuovi utenti

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

In caso di esito positivo, si dovrebbe ottenere una risposta HTTP 201.

Aggiornare un utente

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

Elencare tutti gli utenti
```
curl -i http://localhost:8080/users
```

Ottenere un utente esistente

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

Dovrebbe essere restituito un payload JSON con i dettagli dell'utente. Ad esempio:

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

Provare a ottenere un utente che non esiste
```
curl -i http://localhost:8080/users/not.there@foobar.com
```
Si dovrebbe ricevere una risposta HTTP 404.

Sostituire un utente

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/

Provare a sostituire l'utente che non esiste

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/

Si dovrebbe ricevere una risposta HTTP 404.

Eliminare un utente

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

Eliminare un utente che non esiste
```
curl -X DELETE http://localhost:8080/users/go.nuts@foobar.com
```
Si dovrebbe ricevere una risposta HTTP 404.

Accedere all'applicazione usando un indirizzo IP pubblico (facoltativo)

La creazione di un servizio di tipo LoadBalancer nel servizio Azure Kubernetes comporta il provisioning di un'istanza di Azure Load Balancer. È quindi possibile accedere all'applicazione usando il relativo indirizzo IP pubblico.

Creare un servizio Kubernetes di tipo LoadBalancer

Nota

Questo passaggio crea un Azure Load Balancer con un indirizzo IP pubblico.
```
kubectl apply -f deploy/load-balancer-service.yaml
```

Attendere che il servizio Azure Load Balancer venga creato. Fino ad allora, EXTERNAL-IP per il servizio Kubernetes rimane nello stato <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

Nota

CLUSTER-IP il valore potrebbe differire in questo caso

Al termine della creazione di Azure Load Balancer, EXTERNAL-IP è disponibile.

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

Nota

EXTERNAL-IP il valore potrebbe differire in questo caso

Usare l'indirizzo IP pubblico

Terminare il processo kubectl watch e ripetere i comandi curl precedenti con l'indirizzo IP pubblico insieme alla porta 8080. Ad esempio, per elencare tutti gli utenti:
```
 curl -i http://20.81.108.180:8080/users
```
Nota

Sostituire 20.81.108.180 con l'indirizzo IP pubblico per il proprio ambiente

Risorse Kubernetes per l'applicazione

Ecco alcuni dei punti chiave correlati alle risorse Kubernetes per questa applicazione:

L'applicazione Spring Boot è un Deployment Kubernetes basato sull'immagine Docker nel Registro Azure Container
La configurazione di Azure Cosmos DB viene montata nel application.properties nel percorso /configall'interno del contenitore.
Questo montaggio è possibile usando un Kubernetes Volume che a sua volta fa riferimento a un segreto Kubernetes, creato insieme all'applicazione. È possibile eseguire questo comando per verificare che questo file sia presente nel contenitore dell'applicazione:
```
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
```
La configurazione dei probe di attività e idoneità di questa applicazione fanno riferimento agli endpoint HTTP resi disponibili dall’attuatore Spring Boot quando un'applicazione Spring Boot viene distribuita in un ambiente Kubernetes - /actuator/health/liveness e /actuator/health/readiness.
È possibile creare un servizio ClusterIP per accedere agli endpoint REST dell'applicazione Spring Boot internamente, nel cluster Kubernetes.
È possibile creare un servizio LoadBalancer per accedere all'applicazione tramite un indirizzo IP pubblico.

Pulire le risorse

Dopo aver completato le operazioni con l'app e l'account Azure Cosmos DB, è possibile eliminare le risorse di Azure create in modo da non incorrere in altri costi. Per eliminare le risorse:

Nella barra di ricerca del portale di Azure cercare e selezionare Gruppi di risorse.
Selezionare nell'elenco il gruppo di risorse creato in questa guida di avvio rapido.
Nella pagina Panoramica del gruppo di risorse selezionare Elimina gruppo di risorse.
Nella finestra successiva immettere il nome del gruppo di risorse da eliminare e quindi selezionare Elimina.

Passo successivo

Spring Data Azure Cosmos DB v3 per l' API NoSQL

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-09-03

Condividi tramite

Applicazione Spring Boot con Azure Cosmos DB for NoSQL e il servizio Azure Kubernetes

Prerequisiti

Creare servizi di Azure

Creare un gruppo di risorse per le risorse di Azure usate in questa esercitazione

Creare un account di database Azure Cosmos DB per NoSQL

Creare un Registro Azure Container privato usando l'interfaccia della riga di comando di Azure

Creare un cluster Kubernetes su Azure usando l'interfaccia della riga di comando di Azure

Compilare l'applicazione

Eseguire l'applicazione in locale

Eseguire il push dell'immagine Docker nel Registro Azure Container

Distribuire l'applicazione nel servizio Azure Kubernetes

Accedere all'applicazione

Accedere all'applicazione usando un indirizzo IP pubblico (facoltativo)

Risorse Kubernetes per l'applicazione

Pulire le risorse

Passo successivo

Commenti e suggerimenti

Risorse aggiuntive