AccediPrenota un briefing

Capitolo 2.7

Installare Enterprise e applicare una licenza

Cosa cambia quando si installa l'edizione Enterprise, come richiedere una licenza dal proprio account Adverant, i tre modi per importarla con tutti i codici di rifiuto e come Harrow Port Authority ha convertito sul posto il proprio progetto pilota Community a Enterprise senza perdere nulla.

Questa pagina è stata tradotta dall'IA a partire dall'originale in inglese. In caso di dubbi, fa fede la pagina in inglese. Legga questa pagina in inglese

17 minuti di lettura

Un'installazione Enterprise è composta da due metà, che arrivano per strade diverse. Le immagini Enterprise sono incluse nel chart Enterprise, scaricate tramite un token di pull. La licenza arriva come file firmato dal Suo account Adverant e viene importata nell'installazione in esecuzione. Nessuna delle due metà funziona senza l'altra: le immagini prive di licenza operano al livello base Community, mentre una licenza senza le immagini Enterprise non ha nulla da attivare.

Presso la Harrow Port Authority abbiamo proceduto in quest'ordine, sei settimane dopo il progetto pilota Community descritto nel capitolo 2.6, Installazione di Community su Kubernetes. L'aggiornamento al chart Enterprise ha richiesto una finestra di manutenzione; l'importazione della licenza ha richiesto due minuti. Questo capitolo tratta entrambe le metà. Inizia con una nuova installazione e termina con la transizione sul posto di un'installazione Community esistente.

Due corsie parallele che confluiscono in un unico riquadro a destra denominato "Installazione Enterprise". Corsia superiore: "Account Adverant: Download" porta a "Chart Enterprise e relativo blocco delle immagini", poi a "helm install o helm upgrade, edition: enterprise", a cui si unisce un riquadro laterale "token di pull su ogni nodo". Corsia inferiore: "Account Adverant: Deployment" porta a "file di licenza firmato", poi a "importazione nell'installazione in esecuzione". Entrambe le corsie si incontrano nel riquadro di destra. Sotto di esso, una didascalia riporta "le immagini prive di licenza operano al livello base Community".
Le due metà di un'installazione Enterprise e la rispettiva provenienza.

Cosa cambia rispetto a Community

Due valori e il chart che li legge.

# harrow-values.yaml (Helm values, Enterprise: only these two keys change)
edition: enterprise
enterprise:
  enabled: true

Tutto il resto nel file dei valori rimane esattamente com'era, soprattutto il nome dell'installazione e i custodi. Le due chiavi devono concordare e il chart rifiuta edition: enterprise con enterprise.enabled: false, o il contrario.

L'edizione deve inoltre concordare con il blocco delle immagini del chart. Ogni pacchetto chart contiene il blocco per una sola edizione, e il blocco Enterprise elenca le immagini Community più le build Enterprise. Se si punta un file dei valori Enterprise al chart Community, il rendering si interrompe con files/images.lock.json is the community lock; this install is edition enterprise. Pertanto, l'installazione Enterprise richiede il chart Enterprise.

Il chart e il bundle Enterprise si trovano nella pagina Download del Suo account Adverant, che segue la Sua licenza. Il file del chart ha lo stesso nome di quello Community, nexus-1.0.0-alpha.1.tgz, quindi conservi i due file in cartelle separate. Lo verifichi esattamente come descritto nel capitolo 2.4, Ottenimento e verifica di una release, rispetto alla chiave di rilascio di cui ha controllato l'impronta digitale:

nexusctl verify enterprise/nexus-1.0.0-alpha.1.tgz
tar -xzf enterprise/nexus-1.0.0-alpha.1.tgz -C enterprise
jq -r '.version, .edition' enterprise/nexus/files/images.lock.json
1.0.0-alpha.1
enterprise

Esegua quindi il ciclo di verifica delle firme del capitolo 2.4, Ottenimento e verifica di una release, su enterprise/nexus/files/images.lock.json. Esso copre sia le immagini Enterprise sia quelle condivise.

Il pull token

Le immagini Community sono pubbliche. Le immagini Enterprise richiedono un token di pull dalla pagina Token di pull e comandi di installazione del Suo account, configurato per il container runtime dei Suoi nodi come illustrato nel capitolo 2.4, Ottenimento e verifica di una release, passaggio 3. Su k3s si tratta di una voce configs per registry.adverant.ai in /etc/rancher/k3s/registries.yaml su ogni nodo.

Crei un token per cluster e gli assegni una data di scadenza ben visibile. Quando un token scade, i pod in esecuzione continuano a funzionare, ma un pod ripianificato su un nodo che non dispone ancora dell'immagine non può scaricarla. Noi abbiamo inserito la data di scadenza del token nello stesso calendario di quella del certificato.

Una nuova installazione Enterprise

Se sta installando Enterprise da zero, segua passo dopo passo il capitolo 2.6, Installazione di Community su Kubernetes, con tre differenze:

  1. Inserisca il token di pull su ogni nodo prima del passaggio 6.

  2. Utilizzi i valori Enterprise (le due chiavi indicate sopra) nel passaggio 4.

  3. Nel passaggio 6, esegua l'installazione dal file del chart Enterprise che ha scaricato:

    helm install nexus enterprise/nexus-1.0.0-alpha.1.tgz \
      --namespace nexus -f harrow-values.yaml --timeout 45m

Tutto ciò che segue il comando di installazione è identico a quanto descritto nel capitolo 2.6, Installazione di Community su Kubernetes, così come la regola relativa a --wait: non lo utilizzi. Se invece installa con nexusctl, aggiunga --edition enterprise al comando:

nexusctl install --context harrow-prod --values harrow-values.yaml --edition enterprise

Quando ogni carico di lavoro è pronto, completi il primo avvio descritto nel capitolo 2.12, Il primo avvio. La licenza è uno dei sei elementi elencati dalla console prima che chiunque effettui l'accesso. Finché non viene importata, l'installazione opera al livello base Community e ogni area Enterprise appare disattivata in grigio con un lucchetto.

Richiedere la licenza

Una licenza di Adverant viene emessa per l'identità di una specifica installazione, quella generata dal key store sotto keys.installationName al momento dell'installazione. L'account deve quindi sapere a quale installazione Lei si riferisce prima di poterne emettere una.

  1. Acceda al Suo account Adverant all'indirizzo https://account.adverant.ai.
  2. Sull'installazione, apra Questa installazione, quindi Licenza. Verranno mostrati un codice monouso e l'impronta digitale dell'installazione.
  3. Nel Suo account, apra Rivendica un deployment e inserisca il codice. Confronti quindi l'impronta digitale ricevuta dall'account con quella mostrata dall'installazione, gruppo per gruppo; ogni gruppo deve corrispondere.
  4. Prema il pulsante di rivendicazione. L'installazione viene aggiunta ai Deployment del Suo account, con la relativa versione e lo stato della licenza.
  5. Adverant emette la licenza per quell'installazione. Scarichi il file dal Suo account; prende il nome dall'ID della licenza, <licence-id>.json.

Un codice di rivendicazione funziona una sola volta e per un breve periodo. Se scade, l'account lo rifiuta con CLAIM_CODE_EXPIRED e l'installazione ne mostra uno nuovo.

Rivendica un deployment
Rivendica un deployment
Rivendicazione di un deployment nell'account Adverant. Prima si inserisce il codice monouso, poi si confronta l'impronta digitale in gruppi di quattro, in modo che nessuno possa rivendicare un'installazione senza trovarsi direttamente davanti ad essa.

Esistono altre due modalità, ed entrambe sono trattate in dettaglio nel capitolo 2.13, Licenze. Le appliance e i kit edge non hanno uno schermo per mostrare un codice, pertanto vengono rivendicati tramite una chiave di rivendicazione stampata sulla confezione, digitata in Inserisci una chiave di rivendicazione o letta dal file d'ordine del produttore. Un'installazione priva di connessione verso l'esterno utilizza lo Scambio offline: genera un file firmato di richiesta di licenza, Lei lo trasferisce sul Suo account e riporta indietro il file di licenza. Una volta all'anno genera allo stesso modo una dichiarazione d'uso firmata. Ogni file nello scambio è firmato, quindi un file modificato durante il tragitto viene rifiutato, con LICENCE_REQUEST_SIGNATURE_INVALID per una richiesta e USAGE_FILE_SIGNATURE_INVALID per un file d'uso.

Scambio offline
Scambio offline
Lo scambio offline nell'account Adverant. I file firmati vengono trasferiti manualmente in entrambe le direzioni e un file modificato durante il tragitto viene rifiutato in modo specifico.

Cosa contiene il file di licenza

La licenza è un documento JSON nel formato nexus-licence/v1, firmato due volte da Adverant con due chiavi indipendenti. Non è necessario leggerlo, ma è utile sapere cosa contiene quando qualcuno chiede che cosa è stato acquistato.

Campo Cosa indica
licence_id L'ID proprio della licenza, un UUID (identificatore universalmente unico) in lettere minuscole
type alpha, evaluation o commercial
licensee Il nome dell'organizzazione e l'ID cliente Adverant
scope L'installazione a cui è destinata e le eventuali organizzazioni nominate da una concessione
edition enterprise
grants I gruppi di funzionalità che sblocca, ciascuno per l'intera installazione o per organizzazioni specifiche
add_ons e domain_packs Capacità concesse in licenza separatamente; il pacchetto Logistica e settore marittimo è una di queste
metric Come viene conteggiata la licenza, named-seat, per-core o per-environment, e la quantità
term starts_on, ends_on, e i giorni di preavviso e di tolleranza
matrix La versione della matrice delle edizioni rispetto alla quale è stata redatta
signatures Le due firme di Adverant

Una licenza di valutazione dura al massimo 30 giorni, per un massimo di cinque persone nominali, senza periodo di tolleranza. Una licenza commerciale mostra un avviso 30 giorni prima della scadenza e concede poi per impostazione predefinita 30 giorni di tolleranza. Ciò che accade a ogni passaggio di questa sequenza è descritto nel capitolo 2.13, Licenze.

Le firme coprono il documento così come Adverant lo ha generato. Lo invii esattamente come lo ha ricevuto; non lo apra in un editor che potrebbe riformattarlo.

Importare la licenza

Solo un amministratore dell'installazione può importare una licenza: un proprietario o un amministratore dell'intera organizzazione che possiede l'installazione, mentre ha effettuato l'accesso ad essa. Anche un amministratore completo della piattaforma può importarne una. La licenza non è mai un valore del chart né un file montato in un pod. Viene inviata al servizio di accesso, nexus-auth, che la verifica offline rispetto alle radici di attendibilità integrate nella propria immagine e la registra in un'unica transazione. Può importarla in tre modi, che portano tutti allo stesso risultato.

Nella console

Durante il primo avvio, apra Sei cose prima che chiunque effettui l'accesso, quindi Licenza. La pagina Importa la licenza accetta il file: lo trascini sulla pagina oppure lo selezioni. La pagina lo verifica offline sull'installazione stessa, quindi elenca i gruppi di funzionalità che sblocca, indicando come ciascuno è protetto e fino a quando. I gruppi non inclusi nella licenza rimangono in elenco, disattivati in grigio.

In seguito, la stessa importazione si effettua tramite il pulsante Importa una nuova licenza nella pagina della licenza dell'installazione. Quando una licenza è scaduta, la pagina della licenza con restrizioni propone Importa una licenza rinnovata.

Importa la licenza
Importa la licenza
Importazione della licenza nella console. Il file viene verificato sull'installazione stessa; la pagina elenca ciò che viene sbloccato per gruppo di funzionalità, mentre un file che non supera il controllo della firma viene trattato come assente, con il relativo codice.

Con nexusctl

nexusctl licence import <licence-id>.json

nexusctl invia il file, inalterato, alla rotta di importazione dell'installazione come amministratore dell'installazione e riporta lo stato della licenza o il codice di rifiuto indicato nella tabella seguente.

Tramite l'API

La rotta di importazione fa parte dell'interfaccia di programmazione delle applicazioni (API) del servizio di accesso, sul Suo indirizzo hosts.auth. Il corpo della richiesta è il documento di licenza, byte per byte:

curl -sS -X POST https://auth.harrow.example/api/v1/installation/licence \
  -H "authorization: Bearer <admin-token>" \
  -H "content-type: application/json" \
  --data-binary @<licence-id>.json

<admin-token> è il token di accesso di un amministratore dell'installazione che ha effettuato l'accesso. Utilizzi --data-binary, mai -d, poiché quest'ultimo rimuove le interruzioni di riga modificando così i byte inviati. La rotta non accetta stringhe di query né altro nel corpo oltre al documento; un corpo che tenti di specificare un'organizzazione o una persona al livello principale viene rifiutato prima ancora che venga letto alcunché.

Un'importazione andata a buon fine risponde con 201 Created. In forma abbreviata, il corpo appare così:

{
  "licence": {
    "licence_id": "<licence-id>",
    "state": "licensed",
    "edition": "enterprise",
    "licensee": {"name": "Harrow Port Authority", "customer_id": "<customer-id>"},
    "term": {"starts_on": "2026-12-01", "ends_on": "2027-11-30", "warn_days": 30, "grace_days": 30},
    "groups": ["enterprise-base", "..."]
  },
  "organizations": 1,
  "tenants_without_organisation": 0
}

organizations conta le organizzazioni sull'installazione che ora detengono la licenza. tenants_without_organisation conta le organizzazioni nominate dalla licenza che questa installazione non ospita.

Quando l'importazione viene rifiutata

Un'importazione rifiutata non modifica nulla: non viene scritta alcuna riga e la licenza in vigore, se presente, rimane invariata. Il registro di audit dell'installazione registra ogni tentativo, inclusi quelli rifiutati.

Codice Stato Cosa significa Cosa fare
LICENCE_SIGNATURE_INVALID 422 Una delle due firme di Adverant è mancante o non supera la verifica; il file è stato modificato dopo la firma Richieda nuovamente il file ad Adverant; non lo modifichi
LICENCE_FORMAT_INVALID 422 Il file non è una licenza che questa release è in grado di leggere Invii il file esattamente come fornito da Adverant
LICENCE_ROOT_UNKNOWN 422 È firmato con una chiave che questa installazione non considera attendibile Richieda una licenza firmata per le radici di attendibilità di questa release, oppure esegua l'aggiornamento
LICENCE_MATRIX_MISMATCH 422 È redatta rispetto a una matrice delle edizioni che questa release non legge, oppure concede un gruppo che questa release non conosce Esegua l'aggiornamento, oppure richieda una licenza redatta per questa release
LICENCE_OTHER_INSTALLATION 409 È stata emessa per un'altra installazione Richieda una licenza emessa per l'identità di questa installazione
TRANSITION_NOT_PERMITTED 409 Una licenza con questo ID è già stata importata; ciascuna licenza può essere importata una sola volta Richieda ad Adverant una nuova licenza se è necessario modificare i termini
LICENCE_REVOKED 403 Adverant ha revocato questa licenza Ne richieda una nuova ad Adverant
LICENCE_LOCKED 403 Il periodo di validità della licenza non è ancora iniziato; fino ad allora si applica il livello base Community La importi nuovamente a partire dal primo giorno di validità
RECORD_NOT_FOUND 404 L'installazione non è ancora stata dichiarata, quindi non possiede un'identità con cui effettuare il controllo Completi il passaggio del primo amministratore (capitolo 2.12, Il primo avvio), quindi proceda all'importazione
VALIDATION_FAILED 400 Il corpo era illeggibile o superiore a 1 MiB, oppure è stata inviata una stringa di query Invii il file come unico contenuto del corpo, senza alcuna query

Un ulteriore codice può essere restituito in caso di importazione riuscita, come avviso anziché come rifiuto: LICENCE_CLOCK_BEHIND_FLOOR significa che l'orologio dell'installazione segna un orario antecedente rispetto all'ultimo orario già registrato, pertanto la licenza viene letta a tale orario successivo. Portare indietro l'orologio non riattiva mai una licenza scaduta. Solo un token di reimpostazione dell'orario firmato da Adverant per l'installazione può abbassare tale limite temporale.

Passare da Community a Enterprise sul posto

Questo è ciò che abbiamo fatto a Harrow. Non viene reinstallato né migrato nulla: è la stessa installazione, con la stessa identità e gli stessi dati, ma con più funzionalità attivate. Il nome dell'installazione e i custodi rimangono esattamente com'erano; durante un aggiornamento, l'hook di custodia verifica che il key store sia già inizializzato e non fa nient'altro.

  1. Inserisca il token di pull su ogni nodo e riavvii il container runtime su ciascuno di essi.

  2. Scarichi il chart Enterprise da Download e verifichi sia il chart sia le relative immagini come indicato sopra.

  3. Modifichi i due valori nel Suo file dei valori esistente: edition: enterprise e enterprise.enabled: true. Non modifichi nient'altro.

  4. Esegua la verifica preliminare (preflight) con il nuovo file.

    nexusctl preflight --context harrow-prod --values harrow-values.yaml
  5. Aggiorni la release al chart Enterprise, anche in questo caso senza --wait.

    helm upgrade nexus enterprise/nexus-1.0.0-alpha.1.tgz \
      --namespace nexus -f harrow-values.yaml --timeout 45m

    Durante un aggiornamento, gli hook vengono eseguiti prima dell'avvio dei nuovi pod e ciascuna migrazione applica solo i file che non ha già applicato in precedenza. I segreti generati vengono riletti dall'installazione e mantenuti. Helm termina con:

    NAME: nexus
    NAMESPACE: nexus
    STATUS: deployed
    REVISION: 2
  6. Attenda che i carichi di lavoro siano pronti, esattamente come nel capitolo 2.6, Installazione di Community su Kubernetes, passaggio 7.

    kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s
  7. Importi la licenza, utilizzando uno qualsiasi dei tre metodi descritti sopra.

  8. Nella console, apra Questa installazione, quindi Licenza, poi Passa a Enterprise. La pagina legge la licenza e mostra che cosa verrà scaricato e che cosa cambierà prima che avvenga qualsiasi operazione. Conta inoltre le persone e i contenuti dell'organizzazione e contrassegna ciascun elemento come mantenuto. Prema Scarica e attiva. Ogni componente viene verificato rispetto alla chiave di rilascio di Adverant prima di essere utilizzato e i gruppi di funzionalità si attivano uno alla volta.

La nostra finestra di manutenzione era di un'ora; il lavoro al suo interno ha richiesto circa venti minuti, per la maggior parte dovuti all'attesa dello schema durante l'esecuzione degli hook. Il mattino seguente i partecipanti al progetto pilota hanno effettuato l'accesso allo stesso spazio di lavoro, trovando le aree Enterprise del menu non più disattivate in grigio.

Da Community a Enterprise
Da Community a Enterprise
Passaggio di un'installazione Community a Enterprise. La pagina conferma l'autenticità della licenza ed elenca ciò che verrà scaricato prima che il download abbia inizio; le persone e i file dell'organizzazione sono contrassegnati come mantenuti.

Dopo l'importazione

La pagina della licenza sotto Questa installazione elenca ogni gruppo di funzionalità presente nella licenza con le relative postazioni e il periodo di validità. Indica inoltre come viene fornito ciascun componente, ad esempio compilato e concesso in licenza per un gruppo Enterprise, oppure open source per il livello base Community. I gruppi non coperti dalla licenza rimangono in elenco, disattivati in grigio. Gli amministratori possono restringere l'ambito di applicazione di un gruppo all'interno dell'organizzazione; nessuno tranne Adverant può ampliare ciò che una licenza concede.

Lo stato della licenza viene ricalcolato a partire dal documento e dalla data a ogni lettura, pertanto la scadenza avviene senza bisogno di un processo pianificato. Tutti gli utenti dell'installazione vedono lo stesso avviso nella console man mano che si avvicina la scadenza: LICENCE_ENDS_SOON a partire da 30 giorni prima della fine, poi LICENCE_IN_GRACE durante il periodo di tolleranza. I membri vedono l'avviso e le date; solo gli amministratori dell'installazione vedono la licenza stessa. Il capitolo 2.13, Licenze, tratta il rinnovo e le fasi di scadenza.

Licenza e cosa sblocca
La licenza e cosa sblocca
Questa è la pagina della licenza di un'installazione Enterprise. I dati nella parte superiore indicano le postazioni e il periodo di validità; sotto di essi, ogni gruppo di funzionalità è elencato con la rispettiva modalità di protezione, mentre i gruppi non coperti dalla licenza rimangono disattivati in grigio.

Se l'operazione fallisce

Cosa si vede Causa Cosa fare
edition=enterprise but enterprise.enabled=false: they must agree È stata modificata solo una delle due chiavi Le modifichi entrambe
files/images.lock.json is the community lock; this install is edition enterprise È stato utilizzato il chart Community Utilizzi il chart Enterprise dalla pagina Download
image ... is a enterprise image; a community install takes only community images Il nome di un'immagine Enterprise ha raggiunto un rendering Community Controlli edition e la cartella del chart
ImagePullBackOff su un'immagine Enterprise dopo l'aggiornamento Un nodo è privo di token di pull, oppure il suo token non è più valido Controlli registries.yaml su quel nodo, oppure crei un nuovo token
Un codice di rifiuto della licenza Consulti la tabella dei rifiuti riportata sopra Segua la riga corrispondente; non è stato modificato nulla

Quando la pagina della licenza mostra Enterprise e i gruppi previsti, l'installazione è regolarmente dotata di licenza. La tappa successiva è il primo avvio descritto nel capitolo 2.12, Il primo avvio, se non ha ancora rivendicato l'installazione. Se lo ha già fatto, l'assistente ha comunque bisogno delle chiavi dei modelli di intelligenza artificiale (IA) proprie dell'organizzazione prima di poter rispondere a chiunque. Il capitolo 2.14, Fornitori e modelli di IA, mostra come collegarle.