Helm chart di Cheshire Cat AI per Rancher / Kubernetes

In questo post realizziamo un semplice Helm Chart per installare Cheshire Cat AI come applicazione (app) su un sitema Rancher basato su Kubernetes.

Iniziamo riassumendo i concetti chiavi di un sistema Kubernetes, poi descriviamo l’Helm Chart e infine vediamo come fare in modo che sia posibile impostare alcuni parametri dall’interfaccia web di Rancher in fase di installazione e aggiornamento dell’app.

Introduzione: le componenti del sistema

Clicca sul nome per leggere la descrizione di ciascuna componente.

Chesshire Cat AI

Detto anche Stregatto è un framework open source che consente di creare e distribuire facilmente agenti di intelligenza artificiale. Il termine agente è sempre molto generico, in questo caso si intende una applicazione che permette di realizzare chatbot, sistemi RAG e assistenti basati su IA che interagiscono attraverso plugin e tools con altre applicazioni. E’ open source, facilmente personalizzazbile, espandibile ed integrabile con altri sistemi. Può essere distribuito e scalato in ambienti cloud o containerizzati per garantire alta disponibilità e flessibilità. E’ già dotato di diversi plugin gratuiti che ne estendono le funzionalità, di una comunità molto attiva e presto supporterà il protocollo MCP. [1]

Docker

È una piattaforma open-source di containerizzazione che consente di impacchettare un’applicazione insieme a tutte le sue dipendenze (librerie, configurazioni, runtime) in un “contenitore” leggero e isolato. Questo permette di eseguire l’applicazione in modo identico su qualsiasi ambiente, migliorando portabilità e coerenza tra sviluppo, test e produzione. Quindi un container, di solito, contiene una sola applicazione o addirittura soltanto dei moduli di questa. Per quanto riguarda lo storage si usano i volumi per i dischi e le varibili d’ambiente per i parametri di configurazione. [2][7][8]

Kubernetes

È un sistema open-source di orchestrazione di container che automatizza il deployment, la gestione e il dimensionamento di applicazioni basate su container. Gestisce cluster di macchine fisiche o virtuali, distribuendo i carichi di lavoro, preoccupandosi del recupero da errori, monitorando lo stato delle applicazioni e garantendo il loro corretto funzionamento anche in caso di guasti. In pratica offre una serie di strumenti che permettono di gestire applicazioni complesse che sono state suddivise in microservizi. [3][7][8] Oltre alla gestione di container, volumi e variabili d’ambiente, Kubernetes introduce molti altri concetti, tra questi:

Pod: E’ l’unità più piccola di Kubernetes contiene uno o più container che condividono rete e storage. Serve a raggruppare container strettamente collegati, per esempio un container web e il suo container di logging.
Deployment: E’ l’entità che gestisce la creazione e lò’aggiornamento di pod identici, serve per esempio ad aggiornare una applicazione da una versione alla successiva senza downtime e a garantire scalabilità e rollback automatico in caso di problemi.
Secret: Serve a memorizzare dati sensibili: password, certificati TSL, chiavi di autenticazione, ecc. Posso essere usati nelle variabili d’ambiente, nei file o nelle Config Map.
Config Map: E’ una entità che viene usata per gestire file di configurazione, parametri, variabili d’ambiente pubbliche e tutto ciò che non contiene informazioni sensibili. Sono montate come file nei pod.
Stateful Set: E’ un deployment specifico per applicazioni come i database che richiedono uno storage persistente e un ordine di avvio ben preciso.
Replica Set: Serve a garantire che ci sia un certo numero di repliche di un pod in esecuzioine in base alle necessità del momento.
Job e Cronjob: Sono dei task che sono eseguiti una volta o che sono schedulati: backup, elaborazioni batch, ecc.
Service: E’ l’entità che permette di esporre i pod e di distribuire il traffico tra di loro (load balancing).
Ingress: Gestisce l’accesso HTTP/HTTPS dall’esterno del cluster, il routing e la cifratura SSL delle comunicazioni.
Persistent Volume (PV): E’ lo storage fisico disponibile nel cluster, può essere di vario tipi in base alla Storage Class scelta.
Persistent Volume Claim (PVC): E’ la richiesta di storage da parte dei pod di una applicazione.
Storage Class: E’ un template per creare dinamicamente degli storage, definisce anche il tipo di storage.
Namespace: E’ una suddivisione logica di tutte le componenti del cluster, serve per raggruppare: pod, deployment, ingress, ecc, in base al progetto o all’applicazione, per esempio.
Resource Quota: Sono le risorse (CPU, memoria, storage) assegnate a ciascun namespace.

Helm

E’ il “package manager” di Kubernetes. Semplifica l’installazione e la gestione di applicazioni complesse attraverso “chart“, pacchetti preconfigurati che contengono tutti i componenti necessari. Helm facilita anche l’aggiornamento e la gestione delle release. In pratica è un template che contiene la definizione e la descrizione di tutte le componenti Kubernetes (pod, deployment, service, ingress, volumi, ecc.) che servono per installare e configurare una applicazione. Un Helm Chart consiste in una directory che contiene un insieme di file in formato YAML ognuno dei quali definisce una o più componenti del sistema. [4]

Rancher

È una applicazione web che fornisce un’interfaccia grafica intuitiva per amministrare cluster Kubernetes. Rancher semplifica operazioni complesse come il provisioning di cluster, il controllo degli accessi, il monitoraggio e l’installazione di applicazioni, rendendo Kubernetes accessibile anche a team meno esperti. In pratica permette di semplificare le operazioni di gestione dei cluster che normalmente andrebbero effettuate “a linea di comando” utilizzando una interfaccia semplice e intuitiva. Rancher introduce il concetto di applicazione che è una astrazione di alto livello, ossia un oggetto che contiene tutte le componenti Kubernetes che servono per installare, configurare e gestire appunto una applicazione più o meno complessa. Inoltre fornisce un App Catalog con applicazioni pre-configurate. Le applicazioni sono definite tramite Helm Chart ai quali è pèossibile aggiungere un file chiamato questions.yml che permette di definire da interfaccia web alcuni parametri dell’applicazione. [5]

In pratica è possibile creare, per esempio, un assistente AI con Cheshire Cat installarlo su dei container Docker, all’interno di un sistema basato su Kubernetes. Tutte le configurazioni delle componenti che costituiscono questo sistema possono essere descritte tramite degli Helm Chart e possono essere gestite tramite l’interfaccia web di Rancher.

Descrizione dell’ Helm Chart

L’Helm Chart realizzato definisce tutte le componenti che costituiscono il sistema e permettono all’applicazione di girare sul cluster.

I file principali sono:

Chart.yaml: E’ il file principale che definisce il pacchetto e contiene i metadati del chart: versione, nome, icona, descrizione, keywords, manteiners, ecc.
values.yaml: Contiene le proprietà configurabili di tutte le componenti, per esempio: l’immagine Docker di Cheshire Cat AI da usare, la porta su cui deve girare, la dimensione dei volumi usati, il numero di repliche di ciascun pod, ecc.
questions.yaml: Definisce i campi interattivi visibili nell’interfaccia web di Rancher per personalizzare il deploy.
templates/deployment.yaml: Template per creare la risorsa Deployment che gestisce i pod dell’app. In questo caso creiamo un container kk-cheshirecatai sul quale installiamo l’immagine
ghcr.io/cheshire-cat-ai/core:latest e sul quale vanno montati tre volumi: static-volume, data-volume e plugins-volume. Inoltre definiamo la variabile d’ambiente CCAT_API_KEY ed esponiamo le porte 80 e 5678.
templates/service.yaml: Indica quali sono le porte che il servizio espone (80 e 5678) e come deve essere effettuato il load balancing (ClusterIP).
templates/ingress.yaml: Indica che l’applicazione è associale all’URL cheshirecatai.cbc.it e deve gestire l’HTTPS.
templates/secret.yaml: Definisce il secret cheshirecatai-secret che è una API key che può essere usata per far comunicar eun sito WordPress con questa istanza di Cheshire Cat AI.
templates/_helpers.tpl: Contiene alcune funzioni riutilizzabili allo scopo di centralizzare la creazione di nomi ed etichette da riutilizzare negli altri file, per esempio {{- define “kk-cheshirecatai.name” -}} .

Come già detto tutti i file sono in formato YAML, tranne l’ultimo; e si può usare indifferentemente l’estensione yaml o yml.

Come funziona il file questions.yaml di Rancher

Tutti i file YAML che definisco le componenti del cluster contengono delle variabili, per esempio:

{{ .Values.service.ports.http }}
{{ .Values.image.repository }}:{{ .Values.image.tag }}
{{ .Values.image.pullPolicy }}

Questa sintassi indica che il valore da utilizzare è quello presente nel file values.yaml.

Quando viene installata o aggiornata una applicazione su Kubernetes tutti i valori delle variabili sono recuperati ed utilizzati per creare un certo componente.

Su Rancher è possibile impostare tutti o un sottoinsieme di parameteri dalla sua interfaccia grafica, per poterlo fare è necessario indicare nel file questions.yaml i parametri che si vogliono impostare, come mostrato nello screenshot seguente. Al momento di una installazione o di un aggiornamento questi valori sono usati per costruire un nuovo file values che è il merge di quello originale e dei valori sovrasctitti da questions.yaml. Il nuovo file values sarà passato al comado helm con il parametro –-values e i suoi valori saranno usati per creare/modificare i vari componenti (deployment.yaml, service.yaml, ingress.yaml, ecc.).

Verifica e installazione dell’App

Nella creazione degli Helm Chart è molto facile commettere vari tipi di errori, soprattutto di sintassi e di indentazione.

Si possono eseguire questi due comandi: il primo effettua alcuni semplici controlli, il secondo produce un file contenente la descrizione di tutte le componenti che saranno create/modificate sostituendo alle variabili i valori che verranno utilizzati (a meno delle personalizzazoni fatte direttamente su Rancher).

helm lint
helm template my-release . --debug > prova.yml

Per installare l’applicazione su Rancher è necessario collegare quest’ultimo al repository che contiene l’Helm Chart (Rancher->Apps->Repositories).

A questo punto l’app sarà visibile in Rancher->Apps->Charts e sarà installabile tramite l’interfaccia web.

Per installare/aggiornare l’app direttamente su Kubernetes, in mancanza di Rancher, si possono usare questi comandi:

helm install kk-cheshirecatai .  --namespace cheshire-cat --create-namespace
helm upgrade kk-cheshirecatai . --namespace cheshire-cat

In questo caso però il file questions.yaml è ignorato.

Fonti e riferimenti

Cheshire Cat AI, sito ufficiale.
Docker, sito ufficiale.
Kubernetes, sito ufficiale.
Helm, sito ufficiale.
Rancher, sito ufficiale.
Semplice chatbot per WordPress con Cheshire Cat AI, su questo blog.
Componenti e tecnologie per la gestione di un sistema a microservizi, su questo blog.
Microservizi: architettura, componenti e interoperabilità, su questo blog.
Helm chart descritto in questo articolo.

Posted In: DevOps, Informatica, Intelligenza Artificiale

Tagged In: Agenti IA, AI, Cheshire Cat AI, Helm charts, Informatica, Informatizzazione PA, Kubernetes, LLM, RAG, Rancher

Il blog di Claudio