Cheshire Cat AI Helm Chart for Rancher / Kubernetes

In this post, we create a simple Helm Chart to install Cheshire Cat AI as an application (app) on a Rancher system based on Kubernetes.

We start by summarizing the key concepts of a Kubernetes system, then describe the Helm Chart, and finally see how to enable setting some parameters from the Rancher web interface during app installation and update.

Introduction: System Components

Click on the name to read the description of each component.

Chesshire Cat AI

Also known as Stregatto, it is an open-source framework that allows easy creation and deployment of artificial intelligence agents. The term agent is quite generic; here it means an application that enables building chatbots, RAG systems, and assistants based on AI that interact through plugins and tools with other applications. It is open source, easily customizable, extensible, and integrable with other systems. It can be deployed and scaled in cloud or containerized environments to ensure high availability and flexibility. It already includes several free plugins that extend its functionalities, has a very active community, and will soon support the MCP protocol. [1]

Docker

It is an open-source containerization platform that allows packaging an application together with all its dependencies (libraries, configurations, runtime) into a lightweight, isolated “container.” This enables running the application identically in any environment, improving portability and consistency across development, testing, and production. Typically, a container contains a single application or even just modules of it. For storage, volumes are used for disks and environment variables for configuration parameters. [2][7][8]

Kubernetes

It is an open-source container orchestration system that automates deployment, management, and scaling of container-based applications. It manages clusters of physical or virtual machines, distributing workloads, handling error recovery, monitoring application status, and ensuring proper operation even in case of failures. Essentially, it provides tools to manage complex applications divided into microservices. [3][7][8] Besides managing containers, volumes, and environment variables, Kubernetes introduces many other concepts, including:

Pod: The smallest Kubernetes unit containing one or more containers sharing network and storage. It groups closely related containers, e.g., a web container and its logging container.
Deployment: Manages creation and updating of identical pods, enabling application upgrades without downtime and ensuring scalability and automatic rollback on issues.
Secret: Stores sensitive data like passwords, TLS certificates, authentication keys, etc. They can be used in environment variables, files, or Config Maps.
Config Map: Used to manage configuration files, parameters, public environment variables, and anything not sensitive. Mounted as files in pods.
Stateful Set: A deployment for applications like databases requiring persistent storage and a specific startup order.
Replica Set: Ensures a specified number of pod replicas run as needed.
Job and Cronjob: Tasks executed once or scheduled, e.g., backups, batch processing.
Service: Exposes pods and distributes traffic among them (load balancing).
Ingress: Manages HTTP/HTTPS access from outside the cluster, routing, and SSL encryption.
Persistent Volume (PV): Physical storage available in the cluster, varying by Storage Class.
Persistent Volume Claim (PVC): Storage request by application pods.
Storage Class: Template for dynamically creating storage, defining storage type.
Namespace: Logical subdivision of all cluster components, grouping pods, deployments, ingress, etc., by project or application.
Resource Quota: Resources (CPU, memory, storage) assigned to each namespace.

Helm

It is the Kubernetes “package manager.” It simplifies installation and management of complex applications through “charts,” preconfigured packages containing all necessary components. Helm also facilitates upgrades and release management. Essentially, it is a template defining and describing all Kubernetes components (pods, deployments, services, ingress, volumes, etc.) needed to install and configure an application. A Helm Chart consists of a directory containing a set of YAML files, each defining one or more system components. [4]

Rancher

It is a web application providing an intuitive graphical interface to manage Kubernetes clusters. Rancher simplifies complex operations like cluster provisioning, access control, monitoring, and application installation, making Kubernetes accessible even to less experienced teams. It essentially simplifies cluster management tasks normally done via command line by offering a simple, intuitive interface. Rancher introduces the concept of an application as a high-level abstraction, an object containing all Kubernetes components needed to install, configure, and manage a more or less complex application. It also provides an App Catalog with pre-configured applications. Applications are defined via Helm Charts to which a file called questions.yml can be added to define some application parameters via the web interface. [5]

In practice, it is possible to create, for example, an AI assistant with Cheshire Cat, install it on Docker containers within a Kubernetes-based system. All configurations of the components making up this system can be described via Helm Charts and managed through the Rancher web interface.

Description of the Helm Chart

The Helm Chart created defines all components that make up the system and allow the application to run on the cluster.

The main files are:

Chart.yaml: The main file defining the package and containing chart metadata: version, name, icon, description, keywords, maintainers, etc.
values.yaml: Contains configurable properties of all components, e.g., the Docker image of Cheshire Cat AI to use, the port it should run on, volume sizes, number of pod replicas, etc.
questions.yaml: Defines interactive fields visible in the Rancher web interface to customize deployment.
templates/deployment.yaml: Template to create the Deployment resource managing the app pods. Here, we create a kk-cheshirecatai container on which we install the image
ghcr.io/cheshire-cat-ai/core:latest and mount three volumes: static-volume, data-volume, and plugins-volume. We also define the environment variable CCAT_API_KEY and expose ports 80 and 5678.
templates/service.yaml: Specifies the ports the service exposes (80 and 5678) and how load balancing is performed (ClusterIP).
templates/ingress.yaml: Specifies that the application is associated with the URL cheshirecatai.cbc.it and must handle HTTPS.
templates/secret.yaml: Defines the secret cheshirecatai-secret, an API key that can be used for communication between a WordPress site and this Cheshire Cat AI instance.
templates/_helpers.tpl: Contains reusable functions to centralize creation of names and labels for reuse in other files, e.g., {{- define “kk-cheshirecatai.name” -}}.

As mentioned, all files are in YAML format except the last one; the extensions yaml or yml can be used interchangeably.

How Rancher’s questions.yaml Works

All YAML files defining cluster components contain variables, for example:

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

This syntax indicates that the value to use is the one present in the values.yaml file.

When an application is installed or updated on Kubernetes, all variable values are retrieved and used to create a component.

On Rancher, it is possible to set all or a subset of parameters via its graphical interface. To do this, the parameters to be set must be indicated in the questions.yaml file, as shown in the following screenshot. During installation or update, these values are used to build a new values file, which merges the original with the overridden values from questions.yaml. The new values file is passed to the helm command with the –values parameter, and its values are used to create/modify various components (deployment.yaml, service.yaml, ingress.yaml, etc.).

App Verification and Installation

When creating Helm Charts, it is easy to make various errors, especially syntax and indentation mistakes.

You can run these two commands: the first performs simple checks, the second produces a file describing all components that will be created/modified, substituting variables with the values to be used (except for customizations made directly on Rancher).

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

To install the application on Rancher, you need to connect it to the repository containing the Helm Chart (Rancher->Apps->Repositories).

At this point, the app will be visible in Rancher->Apps->Charts and can be installed via the web interface.

To install/update the app directly on Kubernetes, without Rancher, you can use these commands:

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

However, in this case, the questions.yaml file is ignored.

Sources and References

Cheshire Cat AI, official website.
Docker, official website.
Kubernetes, official website.
Helm, official website.
Rancher, official website.
Simple chatbot for WordPress with Cheshire Cat AI, on this blog.
Components and technologies for managing a microservices system, on this blog.
Microservices: architecture, components, and interoperability, on this blog.
Helm chart described in this article.

*** Note: This article was translated using an automated workflow built with n8n and OpenAI.

Posted In: Artificial Intelligence, DevOps, IT

Il blog di Claudio