Esercitazione - 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 configurerà e si distribuirà 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 verrà inserita in un pacchetto come immagine Docker, ne verrà eseguito il push nel Registro Azure Container, verrà distribuita nel servizio Azure Kubernetes e verrà testata.

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Creare un account gratuito o provare gratuitamente Azure Cosmos DB senza una sottoscrizione 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 effettuare il provisioning dei servizi di Azure.
• Docker per gestire immagini e contenitori.
• Versione recente di Maven e Git.
• curl per richiamare le API REST esposte alle applicazioni.

Effettuare il provisioning dei servizi di Azure

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

• Azure Cosmos DB
• Registro Azure Container
• Servizio Azure Kubernetes

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

1. Accedere all'account Azure usando l'interfaccia della riga di comando di Azure:

   az login
   

2. Scegliere la sottoscrizione di Azure:

   az account set -s <enter subscription ID>
   

3. 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 database di Azure Cosmos DB for NoSQL

Usare questo comando per creare un account di database di Azure Cosmos DB for NoSQL usando l'interfaccia della riga di comando di Azure.

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

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

   Il completamento di questo comando può richiedere alcuni minuti.

2. Se kubectl non è installato, è possibile farlo usando l'interfaccia della riga di comando di Azure.

   az aks install-cli
   

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

1. Clonare l'applicazione e passare alla directory corretta.

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

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

1. 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) verranno creati automaticamente dopo l'avvio dell'applicazione.

2. Eseguire l'applicazione in locale.

   java -jar target/*.jar
   

3. Procedere con l’accesso all'applicazione o vedere la sezione successiva per distribuire l'applicazione in Kubernetes.

Eseguire il push dell'immagine Docker nel Registro Azure Container

1. Compilare l'immagine Docker

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

   Nota

   Sostituire cosmosdbspringbootregistry con il nome del Registro Azure Container

2. Accedere al Registro Azure Container.

   az acr login -n cosmosdbspringbootregistry
   

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

1. 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) verranno creati automaticamente dopo l'avvio dell'applicazione.

2. 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 il comando seguente:

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

Richiamare gli endpoint REST per testare l'applicazione. È 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.

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

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

3. Elencare tutti gli utenti

   curl -i http://localhost:8080/users
   

4. 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"
   }
   

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

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

7. Provare a sostituire un 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.

8. Eliminare un utente

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

9. 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 comporterà il provisioning di un servizio Azure Load Balancer. È quindi possibile accedere all'applicazione usando il relativo indirizzo IP pubblico.

1. Creare un servizio Kubernetes di tipo LoadBalancer

   Nota

   Verrà creato un servizio Azure Load Balancer con un indirizzo IP pubblico.

   kubectl apply -f deploy/load-balancer-service.yaml
   

2. Attendere che il servizio Azure Load Balancer venga creato. Fino ad allora, il EXTERNAL-IP del servizio Kubernetes rimarrà 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

   Il valore CLUSTER-IP può variare a seconda dei casi

3. Al termine della creazione di Azure Load Balancer, EXTERNAL-IP sarà 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

   Il valore EXTERNAL-IP può variare a seconda dei casi

4. 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 percorso /config all'interno del contenitore.

• Ciò è possibile usando un Kubernetes Volume che a sua volta fa riferimento a un segreto Kubernetes, creato insieme all'applicazione. È possibile eseguire il comando seguente 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:

1. Nella barra di ricerca del portale di Azure cercare e selezionare Gruppi di risorse.

2. Selezionare nell'elenco il gruppo di risorse creato in questa guida di avvio rapido.

   

3. Nella pagina Panoramica del gruppo di risorse selezionare Elimina gruppo di risorse.

   

4. Nella finestra successiva immettere il nome del gruppo di risorse da eliminare e quindi selezionare Elimina.

Passaggi successivi

In questa esercitazione si è appreso come distribuire un'applicazione Spring Boot nel servizio Azure Kubernetes e usarla per eseguire operazioni sui dati in un account Azure Cosmos DB for NoSQL.

Spring Data Azure Cosmos DB v3 per l' API NoSQL