Preparare il cluster Kubernetes con abilitazione per Azure Arc

Un cluster Kubernetes abilitato per Azure Arc è un prerequisito per la distribuzione delle operazioni di Azure IoT. Questo articolo descrive come preparare un cluster prima di distribuire le operazioni di Azure IoT. Questo articolo include indicazioni per Ubuntu, Windows, Azure Local e Tanzu Kubernetes Grid (TKG).

Per distribuire rapidamente Operazioni di Azure IoT ed eseguire un carico di lavoro di esempio in un ambiente di test, vedere Guida introduttiva: Eseguire Operazioni di Azure IoT in GitHub Codespaces con K3s.

Prerequisiti

Microsoft supporta il servizio Azure Kubernetes Edge Essentials per le distribuzioni in Windows, K3s per distribuzioni in Ubuntu, distribuzioni del servizio Azure Kubernetes in Azure locale e Tanzu Kubernetes (TKr) in TKG. Se si vuole distribuire le operazioni di Azure IoT in una soluzione multinodo, usare K3s in Ubuntu.

Ubuntu

Per preparare un cluster Kubernetes abilitato per Azure Arc, è necessario:

• Una sottoscrizione di Azure con il ruolo Owner o una combinazione del ruolo Collaboratore e del ruolo Amministratore di accesso utente. È possibile controllare il livello di accesso passando alla sottoscrizione, selezionando Controllo di accesso (IAM) sul lato sinistro del portale di Azure e quindi selezionando Visualizza l'accesso. Se non si dispone di sottoscrizione di Azure, crearne una gratuitamente prima di iniziare.

• Un gruppo di risorse di Azure. Per ogni gruppo di risorse è supportata una sola istanza di Operazioni IoT di Azure. Per creare un nuovo gruppo di risorse, usare il comando az group create. Per trovare l'elenco delle aree Azure attualmente supportate, vedere Aree supportate.

  az group create --location <REGION> --resource-group <RESOURCE_GROUP> --subscription <SUBSCRIPTION_ID>
  

• Interfaccia della riga di comando di Azure versione 2.62.0 o successiva installata nel computer cluster. Usare az --version per controllare la versione e az upgrade per aggiornarla, se necessario. Per altre informazioni, vedere Installare l'interfaccia della riga di comando di Azure.

• La versione più recente dell'estensione connectedk8s per l'interfaccia della riga di comando di Azure:

  az extension add --upgrade --name connectedk8s
  

• Hardware che soddisfa i requisiti di sistema:

  • Ambienti supportati dalle operazioni IoT di Azure.
  • Requisiti di sistema Kubernetes abilitati per Azure Arc.
  • RequisitiK3s.

• Se si intende distribuire le operazioni di Azure IoT in un cluster multinodo con tolleranza di errore abilitata, esaminare i requisiti hardware e di archiviazione in Preparare Linux per i volumi Edge.

AKS Edge Essentials

Per preparare un cluster Kubernetes abilitato per Azure Arc, è necessario:

• Una sottoscrizione di Azure. Se non si dispone di sottoscrizione di Azure, crearne una gratuitamente prima di iniziare.

• Hardware che soddisfa i requisiti di sistema:

  • Ambienti supportati dalle operazioni IoT di Azure.
  • Requisiti di sistema Kubernetes abilitati per Azure Arc.
  • Requisiti e matrice di supporto di Azure Kubernetes Edge Essentials.
  • Linee guida sulla rete di Azure Kubernetes Edge Essentials.

Servizio Azure Kubernetes in locale di Azure

Per preparare un cluster Kubernetes abilitato per Azure Arc, è necessario:

• Una sottoscrizione di Azure. Se non si dispone di sottoscrizione di Azure, crearne una gratuitamente prima di iniziare.

• Un server o un cluster locale di Azure.

• Hardware che soddisfa i requisiti di sistema:

  • Ambienti supportati dalle operazioni IoT di Azure.
  • Requisiti di sistema Kubernetes abilitati per Azure Arc.

TKG con un cluster di gestione

Per preparare un cluster del carico di lavoro TKG, è necessario:

• Una sottoscrizione di Azure con il ruolo Owner o una combinazione del ruolo Collaboratore e del ruolo Amministratore di accesso utente. È possibile controllare il livello di accesso passando alla sottoscrizione, selezionando Controllo di accesso (IAM) sul lato sinistro del portale di Azure e quindi selezionando Visualizza l'accesso. Se non si dispone di sottoscrizione di Azure, crearne una gratuitamente prima di iniziare.

• Un gruppo di risorse di Azure. Per ogni gruppo di risorse è supportata una sola istanza di Operazioni IoT di Azure. Per creare un nuovo gruppo di risorse, usare il comando az group create. Per trovare l'elenco delle aree Azure attualmente supportate, vedere Aree supportate.

  az group create --location <REGION> --resource-group <RESOURCE_GROUP> --subscription <SUBSCRIPTION_ID>
  

• Interfaccia della riga di comando di Azure versione 2.62.0 o successiva installata nel computer cluster. Usare az --version per controllare la versione e az upgrade per aggiornarla, se necessario. Per altre informazioni, vedere Installare l'interfaccia della riga di comando di Azure.

• La versione più recente dell'estensione connectedk8s per l'interfaccia della riga di comando di Azure:

  az extension add --upgrade --name connectedk8s
  

• TKG con un cluster di gestione autonomo.

• Hardware che soddisfa i requisiti di sistema:

  • Ambienti supportati dalle operazioni IoT di Azure.

  • Requisiti di sistema Kubernetes abilitati per Azure Arc.

  • Requisiti del cluster di gestione autonomo TKG.

Creare e abilitare Arc per un cluster

Questa sezione illustra la procedura per creare cluster in ambienti convalidati in Linux e Windows.

Ubuntu

Per preparare un cluster Kubernetes K3s in Ubuntu:

1. Creare un cluster K3s a nodo singolo o multinodo. Per esempi, vedere la guida introduttiva di K3s o i progetti correlati a K3s.

2. Verificare che kubectl sia stato installato come parte di K3s. In caso contrario, seguire le istruzioni per installare kubectl su Linux.

   kubectl version --client
   

3. Seguire le istruzioni per installare Helm.

4. Creare un file yaml di configurazione K3s in .kube/config:

   mkdir ~/.kube
   sudo KUBECONFIG=~/.kube/config:/etc/rancher/k3s/k3s.yaml kubectl config view --flatten > ~/.kube/merged
   mv ~/.kube/merged ~/.kube/config
   chmod  0600 ~/.kube/config
   export KUBECONFIG=~/.kube/config
   #switch to k3s context
   kubectl config use-context default
   sudo chmod 644 /etc/rancher/k3s/k3s.yaml
   

5. Eseguire il comando seguente per aumentare i limiti di controllo/istanza dell'utente.

   echo fs.inotify.max_user_instances=8192 | sudo tee -a /etc/sysctl.conf
   echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
   
   sudo sysctl -p
   

6. Per prestazioni migliori, aumentare il limite del descrittore di file:

   echo fs.file-max = 100000 | sudo tee -a /etc/sysctl.conf
   
   sudo sysctl -p
   

Abilitare Arc per il cluster

Connettere il cluster ad Azure Arc in modo che possa essere gestito in remoto.

1. Da un computer che ha kubectl accesso al cluster, accedere all'interfaccia della riga di comando di Azure con l'account utente Microsoft Entra con i ruoli necessari per la sottoscrizione di Azure:

   az login
   

   Se in qualsiasi momento viene visualizzato un errore che indica che il dispositivo deve essere gestito per accedere alla risorsa, eseguire di nuovo az login e assicurarsi di accedere in modo interattivo con un browser.

2. Dopo l'accesso, l'interfaccia della riga di comando di Azure visualizza tutte le sottoscrizioni e indica la sottoscrizione predefinita con un asterisco *. Per continuare con la sottoscrizione predefinita, selezionare Enter. In caso contrario, digitare il numero della sottoscrizione di Azure che si vuole usare.

3. Registrare i provider di risorse necessari nella sottoscrizione.

   Note

   Questo passaggio deve essere eseguito una volta sola per ogni sottoscrizione. Per registrare i provider di risorse, è necessaria l'autorizzazione per eseguire l'operazione /register/action, inclusa nei ruoli Collaboratore e Proprietario della sottoscrizione. Per altre informazioni, vedere Provider e tipi di risorse di Azure.

   az provider register -n "Microsoft.ExtendedLocation"
   az provider register -n "Microsoft.Kubernetes"
   az provider register -n "Microsoft.KubernetesConfiguration"
   az provider register -n "Microsoft.IoTOperations"
   az provider register -n "Microsoft.DeviceRegistry"
   az provider register -n "Microsoft.SecretSyncController"
   

4. Usare il comando az connectedk8s connect per abilitare il cluster Kubernetes per Arc e gestirlo come parte del gruppo di risorse di Azure.

   az connectedk8s connect --name <CLUSTER_NAME> -l <REGION> --resource-group <RESOURCE_GROUP> --subscription <SUBSCRIPTION_ID> --enable-oidc-issuer --enable-workload-identity --disable-auto-upgrade
   

   Per impedire gli aggiornamenti non pianificati in Azure Arc e le estensioni Arc di sistema usate da Operazioni IoT di Azure come dipendenze, questo comando disabilita il downgrade automatico. Invece, Aggiornare manualmente gli agenti in base alle esigenze.

   Importante

   Se l'ambiente usa un server proxy o Azure Arc Gateway, modificare il comando az connectedk8s connect con le informazioni del proxy:

   1. Seguire le istruzioni riportate in Connettersi usando un server proxy in uscita o Eseguire l'onboarding di cluster Kubernetes in Azure Arc con Azure Arc Gateway.
   2. Aggiungere 169.254.169.254 al parametro --proxy-skip-range del comando az connectedk8s connect. Registro dispositivi di Azure usa questo endpoint locale per ottenere i token di accesso per l'autorizzazione.

   Le operazioni di Azure IoT non supportano i server proxy che richiedono un certificato attendibile.

5. Ottenere l'URL dell'autorità di certificazione del cluster.

   az connectedk8s show --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --query oidcIssuerProfile.issuerUrl --output tsv
   

   Salvare l'output di questo comando da usare nei passaggi successivi.

6. Creare un file di configurazione k3s.

   sudo nano /etc/rancher/k3s/config.yaml
   

7. Aggiungere il contenuto seguente al file config.yaml, sostituendo il segnaposto <SERVICE_ACCOUNT_ISSUER> con l'URL dell'autorità di certificazione del cluster.

   kube-apiserver-arg:
    - service-account-issuer=<SERVICE_ACCOUNT_ISSUER>
    - service-account-max-token-expiration=24h
   

8. Salvare il file e uscire dall'editor nano.

9. Prepararsi per abilitare il servizio Azure Arc, la posizione personalizzata, nel cluster Arc recuperando l'ID oggetto percorso personalizzato e salvandolo come variabile di ambiente, OBJECT_ID. Per eseguire correttamente il comando, non un'entità servizio, è necessario accedere all'interfaccia della riga di comando di Azure con un account utente di Microsoft Entra. Eseguire il comando seguente esattamente come scritto, senza modificare il valore GUID.

   export OBJECT_ID=$(az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query id -o tsv)
   

   Note

   Se viene visualizzato l'errore: "Impossibile recuperare l'oid dell'app 'custom-locations'. Procedere senza abilitare la funzionalità. Privilegi insufficienti per completare l'operazione", l'entità servizio potrebbe non disporre delle autorizzazioni necessarie per recuperare l'ID oggetto della posizione personalizzata. Accedere all'interfaccia della riga di comando di Azure con un account utente di Microsoft Entra che soddisfi i prerequisiti. Per altre informazioni, vedere Creare e gestire posizioni personalizzate.

10. Usare il comando az connectedk8s enable-features per abilitare la funzionalità di posizione personalizzata nel cluster Arc. Questo comando usa la variabile di ambiente OBJECT_ID salvata dal passaggio precedente per impostare il valore per il parametro custom-locations-oid. Eseguire questo comando nel computer in cui è stato distribuito il cluster Kubernetes:

    az connectedk8s enable-features -n <CLUSTER_NAME> -g <RESOURCE_GROUP> --custom-locations-oid $OBJECT_ID --features cluster-connect custom-locations
    

11. Riavviare K3s.

    systemctl restart k3s
    

Configurare cluster multinodo per Archiviazione contenitori di Azure

Nei cluster Ubuntu multinodo con almeno tre nodi è possibile abilitare la tolleranza di errore per l'archiviazione con Archiviazione azure Container abilitata da Azure Arc quando si distribuiscono le operazioni di Azure IoT.

Se si vuole abilitare la tolleranza di errore durante la distribuzione, configurare i cluster seguendo la procedura descritta in Preparare Linux per i volumi Edge usando un cluster Ubuntu multinodo.

Se si esegue il cluster in una distribuzione Kubernetes diversa da k3s, vedere le indicazioni per Preparare Linux con altre piattaforme.

AKS Edge Essentials

Azure Kubernetes Service Edge Essentials è un'implementazione locale Kubernetes del Servizio Azure Kubernetes (AKS), che automatizza l'esecuzione di applicazioni in contenitori su larga scala. AKS Edge Essentials include una piattaforma Kubernetes supportata da Microsoft che include una distribuzione Kubernetes leggera con un footprint ridotto e un'esperienza di installazione semplice che supporta hardware perimetrale di classe PC o "leggera".

Lo script AksEdgeQuickStartForAio.ps1 automatizza il processo di creazione e connessione di un cluster ed è il percorso consigliato per la distribuzione di operazioni IoT di Azure in AKS Edge Essentials.

Per istruzioni sull'esecuzione dello script, vedere Configurare un cluster Azure Kubernetes Edge Essentials per le operazioni di Azure IoT.

Servizio Azure Kubernetes in locale di Azure

• Per istruzioni su come creare e abilitare Arc per un cluster del servizio Azure Kubernetes in Locale di Azure, vedere Creare cluster Kubernetes usando l'interfaccia della riga di comando di Azure.
• Per istruzioni sulla distribuzione di un cluster del servizio Azure Kubernetes in Locale di Azure con identità del carico di lavoro (anteprima) abilitata per la sicurezza avanzata, vedere Distribuire e configurare l'identità del carico di lavoro in un cluster del servizio Azure Kubernetes. La funzionalità di identità del carico di lavoro può essere abilitata solo durante la creazione del cluster. L'esecuzione di operazioni IoT di Azure con impostazioni sicure richiede l'identità del carico di lavoro.

Per impostazione predefinita, viene creato un cluster Kubernetes con un pool di nodi in grado di eseguire contenitori Linux. Se si aggiungono altri pool di nodi dopo la creazione, assicurarsi che il sistema operativo sia impostato su Linux. Le operazioni IoT di Azure non supportano la distribuzione nei nodi Windows.

Dopo aver creato un cluster Kubernetes abilitato per Azure Arc, è possibile distribuire le operazioni IoT di Azure.

TKG con un cluster di gestione

Per preparare un cluster del carico di lavoro TKG, è necessario:

• Un cluster di carico di lavoro TKG a nodo singolo o multinodo. Per indicazioni, vedere la documentazione di Tanzu.

Aggiornare le impostazioni di ammissione di sicurezza dei pod

Prima di distribuire le operazioni di Azure IoT, è necessario aggiornare le impostazioni di ammissione di sicurezza dei pod nel cluster TKG. L'applicazione di questo file pre-crea etichette dello spazio dei nomi e imposta la sicurezza dei pod su privileged.

kubectl apply -f https://raw.githubusercontent.com/Azure-Samples/explore-iot-operations/main/samples/tanzu-config/psa.yaml

Abilitare Arc per il cluster

Connettere il cluster ad Azure Arc in modo che possa essere gestito in remoto.

1. Nel computer in cui è stato distribuito il cluster Kubernetes, accedere all'interfaccia della riga di comando di Azure con l'account utente Microsoft Entra con i ruoli necessari per la sottoscrizione di Azure:

   az login
   

2. Dopo l'accesso, l'interfaccia della riga di comando di Azure visualizza tutte le sottoscrizioni e indica la sottoscrizione predefinita con un asterisco *. Per continuare con la sottoscrizione predefinita, selezionare Enter. In caso contrario, digitare il numero della sottoscrizione di Azure che si vuole usare.

3. Registrare i provider di risorse necessari nella sottoscrizione.

   Note

   Questo passaggio deve essere eseguito una volta sola per ogni sottoscrizione. Per registrare i provider di risorse, è necessaria l'autorizzazione per eseguire l'operazione /register/action, inclusa nei ruoli Collaboratore e Proprietario della sottoscrizione. Per altre informazioni, vedere Provider e tipi di risorse di Azure.

   az provider register -n "Microsoft.ExtendedLocation"
   az provider register -n "Microsoft.Kubernetes"
   az provider register -n "Microsoft.KubernetesConfiguration"
   az provider register -n "Microsoft.IoTOperations"
   az provider register -n "Microsoft.DeviceRegistry"
   az provider register -n "Microsoft.SecretSyncController"
   

4. Usare il comando az connectedk8s connect per abilitare il cluster Kubernetes per Arc e gestirlo come parte del gruppo di risorse di Azure.

   az connectedk8s connect --name <CLUSTER_NAME> -l <REGION> --resource-group <RESOURCE_GROUP> --subscription <SUBSCRIPTION_ID> --enable-oidc-issuer --enable-workload-identity --disable-auto-upgrade
   

   Per impedire gli aggiornamenti non pianificati in Azure Arc e le estensioni Arc di sistema usate da Operazioni IoT di Azure come dipendenze, questo comando disabilita il downgrade automatico. Invece, Aggiornare manualmente gli agenti in base alle esigenze.

   Importante

   Se l'ambiente usa un server proxy o Azure Arc Gateway, modificare il comando az connectedk8s connect con le informazioni del proxy:

   1. Seguire le istruzioni riportate in Connettersi usando un server proxy in uscita o Eseguire l'onboarding di cluster Kubernetes in Azure Arc con Azure Arc Gateway.
   2. Aggiungere 169.254.169.254 al parametro --proxy-skip-range del comando az connectedk8s connect. Registro dispositivi di Azure usa questo endpoint locale per ottenere i token di accesso per l'autorizzazione.

   Le operazioni di Azure IoT non supportano i server proxy che richiedono un certificato attendibile.

5. Ottenere l'URL dell'autorità di certificazione del cluster.

   az connectedk8s show --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --query oidcIssuerProfile.issuerUrl --output tsv
   

Salvare l'output di questo comando da usare nei passaggi successivi.

1. Connettersi al cluster di gestione TKG. Modificare la risorsa personalizzata per il cluster del carico di lavoro con l'URL dell'autorità di certificazione del passaggio precedente.

   kubectl edit cluster <CLUSTER_NAME> 
   

2. Aggiungere il contenuto seguente nel file config.yaml, sostituendo il segnaposto <OIDC_ISSUER_URL> con l'URL dell'emittente del cluster.

   Note

   L'URL deve essere copiata esattamente come stampata dal comando precedente, inclusi caratteri come /.

   - name: apiServerExtraArgs
     value: {"service-account-issuer":"<OIDC_ISSUER_URL>"}
   

3. Prepararsi per abilitare il servizio Azure Arc, la posizione personalizzata, nel cluster Arc recuperando l'ID oggetto percorso personalizzato e salvandolo come variabile di ambiente, OBJECT_ID. Per eseguire correttamente il comando, non un'entità servizio, è necessario accedere all'interfaccia della riga di comando di Azure con un account utente di Microsoft Entra. Eseguire il comando seguente esattamente come scritto, senza modificare il valore GUID.

   export OBJECT_ID=$(az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query id -o tsv)
   

   Note

   Se viene visualizzato l'errore: "Impossibile recuperare l'oid dell'app 'custom-locations'. Procedere senza abilitare la funzionalità. Privilegi insufficienti per completare l'operazione", l'entità servizio potrebbe non disporre delle autorizzazioni necessarie per recuperare l'ID oggetto della posizione personalizzata. Accedere all'interfaccia della riga di comando di Azure con un account utente di Microsoft Entra che soddisfi i prerequisiti. Per altre informazioni, vedere Creare e gestire posizioni personalizzate.

4. Usare il comando az connectedk8s enable-features per abilitare la funzionalità di posizione personalizzata nel cluster Arc. Questo comando usa la variabile di ambiente OBJECT_ID salvata dal passaggio precedente per impostare il valore per il parametro custom-locations-oid. Eseguire questo comando nel computer in cui è stato distribuito il cluster Kubernetes:

   az connectedk8s enable-features -n <CLUSTER_NAME> -g <RESOURCE_GROUP> --custom-locations-oid $OBJECT_ID --features cluster-connect custom-locations
   

Configurazione avanzata

A questo punto, quando si dispone di un cluster Kubernetes abilitato per Azure Arc, ma prima di distribuire operazioni IoT di Azure, è possibile configurare il cluster per scenari avanzati.

• Per abilitare le funzionalità di osservabilità nel cluster, seguire la procedura descritta in Distribuire le risorse di osservabilità e configurare i log.
• Se si vuole configurare un'autorità di certificazione personalizzata nel cluster, seguire la procedura descritta in Gestione certificati > Porta il tuo emittente.

Passaggi successivi

Ora che si dispone di un cluster Kubernetes abilitato per Azure Arc, è possibile scegliere di distribuire Operazioni di Azure IoT con le impostazioni di test o con le impostazioni di produzione.

• Distribuzione di test: consigliata per la valutazione rapida e la creazione di prototipi prima della distribuzione nell'ambiente di produzione. La distribuzione dei test non è adatta per l'ambiente di produzione perché manca di osservabilità e sicurezza con protezione avanzata.
• Distribuzione di produzione: consigliata per i carichi di lavoro pronti per la produzione. La distribuzione di produzione è adatta alle distribuzioni IoT reali con esigenze di conformità e sicurezza.