Installer CAST AI Anywhere

Ce guide vous permet d'installer CAST AI Anywhere sur votre cluster Kubernetes. Vous choisirez parmi trois méthodes selon votre contexte : onboarding console (rapide), Helm manuel (contrôle), ou API (automatisation CI/CD).

Ce que vous apprendrez :

• Vérifier les prérequis (metrics-server, connectivité)
• Choisir la bonne méthode d'installation
• Installer et valider les composants CAST AI
• Diagnostiquer les problèmes courants

Choisir votre méthode d'installation

Les trois méthodes installent exactement les mêmes composants, elles se distinguent par le degré de contrôle et de reproductibilité. La console génère un script prêt à l'emploi contenant déjà vos identifiants, pratique pour un premier essai mais difficile à rejouer à l'identique. Helm et l'API demandent plus de préparation et vous rendent maîtres des versions déployées, ce qui est indispensable dès qu'un cluster de production est concerné.

Méthode	Usage	Avantage
Console (recommandé)	Premier déploiement, découverte	Script généré, tout-en-un
Helm manuel	Production, Infrastructure as Code	Contrôle des versions et values
API	CI/CD, multi-clusters	Automatisation complète

Glissez pour voir

Prérequis

Vérifiez ces points avant de commencer : un manque à ce stade se manifeste bien plus tard, sous la forme d'une erreur qui ne le désigne pas.

Outils requis

Ces trois outils s'exécutent depuis votre poste, pas sur le cluster. helm n'est nécessaire que pour la méthode manuelle, le script de la console embarquant sa propre logique d'installation.

Outil	Version minimum	Vérification
kubectl	1.18+	kubectl version --client
helm	3.14.0+ (si Helm manuel)	helm version --short
curl	-	curl --version

Glissez pour voir

Accès requis

L'installation crée des ressources à l'échelle du cluster, notamment des CRD (Custom Resource Definitions) et des webhooks, d'où l'exigence d'un rôle cluster-admin. Le trafic sortant est également indispensable, l'agent ouvrant lui-même la connexion vers l'API.

• Cluster Kubernetes fonctionnel avec accès cluster-admin
• Connectivité réseau vers l'API CAST AI (port 443)
• Compte CAST AI gratuit sur console.cast.ai

Endpoints API CAST AI

Le choix de l'endpoint détermine où vos données de télémétrie sont stockées. Il se fait à la création du cluster dans la console et doit être repris à l'identique dans tous les composants installés, une incohérence se traduisant par un cluster qui n'apparaît jamais comme connecté.

Région	URL
Global (US)	https://api.cast.ai
Europe (EU)	https://api.eu.cast.ai

Glissez pour voir

Choisissez l'endpoint selon votre région ou vos exigences de résidence des données. Documentation AI Enabler

Vérifier metrics-server

CAST AI collecte les métriques CPU/mémoire via metrics-server. Vérifiez qu'il est installé :

kubectl get deployment metrics-server -n kube-system

Installation automatique

Si vous utilisez la méthode Console, le script d'onboarding peut installer metrics-server automatiquement s'il est absent. Pour la méthode Helm manuel, vous devez l'installer vous-même. Téléchargez le manifeste d'une version précise relevée sur la page des releases du projet, relisez-le, puis appliquez-le : latest change sans prévenir et vous ne sauriez pas ce qui a été déployé.

# Remplacez par la version relevée sur github.com/kubernetes-sigs/metrics-server/releases
METRICS_SERVER_VERSION="vX.Y.Z"

curl -fsSL -o metrics-server.yaml \
  "https://github.com/kubernetes-sigs/metrics-server/releases/download/${METRICS_SERVER_VERSION}/components.yaml"

# Relire le manifeste avant de l'appliquer au cluster
less metrics-server.yaml

kubectl apply -f metrics-server.yaml

Documentation Workload Autoscaling

Vérifier l'accès au cluster

Confirmez que votre contexte kubectl pointe bien sur le cluster à connecter, une erreur de contexte se traduisant par une installation sur le mauvais environnement :

kubectl get nodes

Tous les nœuds doivent être en état Ready.

Variables d'environnement

Quelle que soit la méthode, vous aurez besoin de ces informations (générées depuis la console). La clé d'API authentifie l'agent, l'identifiant de cluster lui indique à quelle entrée de votre organisation rattacher les données. Ces deux valeurs sont créées avant l'installation : la console enregistre le cluster dès que vous validez son nom, bien avant qu'un composant ne tourne.

Variable	Description	Où la trouver
CASTAI_API_KEY	Clé d'authentification API	Console → API Access Keys
CASTAI_CLUSTER_ID	Identifiant unique du cluster	Console → Cluster → Settings
CASTAI_API_URL	Endpoint API (US ou EU)	https://api.cast.ai ou https://api.eu.cast.ai

Glissez pour voir

Sécurité des credentials

• Ne jamais versionner les clés API dans Git
• Utilisez des secrets managers (Vault, AWS Secrets Manager, etc.)
• Préférez des clés avec permissions minimales

---

Méthode 1 : Console (recommandé)

C'est la méthode la plus simple pour un premier déploiement. CAST AI génère un script personnalisé pour votre cluster.

1. Connectez-vous à console.cast.ai

2. Cliquez sur "Connect cluster" en haut à droite

3. Sélectionnez "Anywhere" comme provider

   Cette option fonctionne pour tous les clusters non-AWS/GCP/Azure (OKS, OVH, Scaleway, on-prem, bare-metal).

4. Nommez votre cluster (exemple : production-oks, demo-cluster)

5. Cliquez sur "Generate script"

   CAST AI génère un script d'onboarding personnalisé contenant :

   • Votre CASTAI_API_KEY
   • Votre CASTAI_CLUSTER_ID
   • Les charts Helm préconfigurés

6. Enregistrez le script dans un fichier, relisez-le, puis exécutez-le

   La console propose une commande qui télécharge et exécute le script d'un seul tenant. Ne la collez pas telle quelle : coupez l'étape en deux pour garder la possibilité de lire ce qui va s'exécuter avec vos droits cluster-admin.

   curl -fsSL "URL_DU_SCRIPT_GENERE" -o castai-install.sh
   less castai-install.sh
   bash castai-install.sh

Bonne pratique sécurité

Enchaîner curl et bash dans une même commande exécute un contenu distant que personne n'a lu, avec les droits cluster-admin. En téléchargeant d'abord le fichier, vous pouvez vérifier trois choses avant de le lancer : les charts Helm installés et leur dépôt d'origine, les droits demandés par les manifestes, et le fait que la clé d'API n'y soit pas écrite en dur si vous comptez conserver ce fichier.

Le script contient vos identifiants : ne le versionnez pas et supprimez-le une fois l'installation terminée.

Ce que le script installe

Selon la documentation Anywhere, le script installe ces composants dans le namespace castai-agent :

Composant	Rôle
castai-agent	Collecte les métriques, synchronise avec l'API
cluster-controller	Applique les recommandations, gère les CRDs
workload-autoscaler	Calcule les recommandations VPA
workload-autoscaler-exporter	Expose les métriques Prometheus
evictor	Consolidation des pods (optionnel)

Glissez pour voir

Composants optionnels

Selon les features activées, d'autres composants peuvent être installés :

• pod-mutator : si Pod Mutations est activé
• metrics-server : si absent du cluster

Documentation Helm charts

---

Méthode 2 : Helm manuel

Pour un contrôle complet des versions et de la configuration, installez chaque composant via Helm. Cette méthode demande quatre étapes : préparer les identifiants, déclarer le dépôt de charts, créer le namespace, puis installer les composants dans l'ordre de leurs dépendances. Elle est aussi la seule qui vous permette de figer la version de chaque chart, condition d'une installation reproductible d'un environnement à l'autre.

Préparer les variables

Ces variables sont reprises dans toutes les commandes qui suivent. Exportez-les dans le shell courant plutôt que de recopier les valeurs, et évitez de les inscrire dans un fichier d'historique en préfixant la commande d'un espace si votre shell l'ignore :

# Récupérez ces valeurs depuis la console CAST AI
export CASTAI_API_KEY="votre-api-key"
export CASTAI_CLUSTER_ID="votre-cluster-id"
export CASTAI_API_URL="https://api.cast.ai"  # ou https://api.eu.cast.ai

Ajouter le repository Helm

Le dépôt public de CAST AI héberge tous les charts utilisés ici. La commande helm repo update rafraîchit l'index local, sans quoi les versions publiées après votre dernier ajout resteraient invisibles :

helm repo add castai-helm https://castai.github.io/helm-charts
helm repo update castai-helm

Listez les versions disponibles d'un chart pour choisir celle que vous allez figer :

helm search repo castai-helm/castai-agent --versions

Créer le namespace

Tous les composants cohabitent dans le namespace castai-agent, ce qui simplifie la supervision et la désinstallation. Créez-le avant les installations, les charts ne le fabriquent pas d'office :

kubectl create namespace castai-agent

Installer les composants

Respectez l'ordre des onglets : l'agent enregistre le cluster auprès de l'API, les composants suivants supposent cet enregistrement déjà fait. L'option --wait bloque la commande jusqu'à ce que les pods soient prêts, ce qui évite d'enchaîner sur une installation dont la précédente n'a pas abouti.

Figer la version des charts

Les commandes ci-dessous installent la dernière version publiée de chaque chart, donc un résultat qui change avec le temps. Sur un cluster de production, ajoutez --version <version> à chaque helm upgrade --install, en reprenant les versions listées par la commande helm search précédente, et conservez ces valeurs dans votre dépôt d'infrastructure.

1. Agent

L'agent collecte les métriques et synchronise avec l'API CAST AI :

helm upgrade --install castai-agent castai-helm/castai-agent \
  --namespace castai-agent \
  --set apiKey="$CASTAI_API_KEY" \
  --set apiURL="$CASTAI_API_URL" \
  --set provider=anywhere \
  --wait --timeout 5m

Vérification :

kubectl get pods -n castai-agent -l app.kubernetes.io/name=castai-agent

2. Controller

Le cluster-controller applique les recommandations et gère les CRDs :

helm upgrade --install castai-cluster-controller castai-helm/castai-cluster-controller \
  --namespace castai-agent \
  --set castai.apiKey="$CASTAI_API_KEY" \
  --set castai.apiURL="$CASTAI_API_URL" \
  --set castai.clusterID="$CASTAI_CLUSTER_ID" \
  --wait --timeout 5m

Vérification :

kubectl get pods -n castai-agent -l app.kubernetes.io/name=castai-cluster-controller

3. Autoscaler

Le workload-autoscaler génère les recommandations. Installez aussi l'exporter :

# Workload Autoscaler
helm upgrade --install castai-workload-autoscaler castai-helm/castai-workload-autoscaler \
  --namespace castai-agent \
  --set castai.apiKey="$CASTAI_API_KEY" \
  --set castai.apiURL="$CASTAI_API_URL" \
  --set castai.clusterID="$CASTAI_CLUSTER_ID" \
  --wait --timeout 5m

# Workload Autoscaler Exporter (métriques Prometheus)
helm upgrade --install castai-workload-autoscaler-exporter castai-helm/castai-workload-autoscaler-exporter \
  --namespace castai-agent \
  --set castai.apiKey="$CASTAI_API_KEY" \
  --set castai.clusterID="$CASTAI_CLUSTER_ID" \
  --wait --timeout 5m

Vérification :

kubectl get pods -n castai-agent -l app.kubernetes.io/name=castai-workload-autoscaler
kubectl get pods -n castai-agent -l app.kubernetes.io/name=castai-workload-autoscaler-exporter

4. Evictor (optionnel)

L'evictor permet la consolidation des pods sur moins de nœuds :

helm upgrade --install castai-evictor castai-helm/castai-evictor \
  --namespace castai-agent \
  --set castai.apiKey="$CASTAI_API_KEY" \
  --set castai.clusterID="$CASTAI_CLUSTER_ID" \
  --wait --timeout 5m

Quand utiliser l'evictor ?

L'evictor est utile si vous voulez que CAST AI consolide les pods pour libérer des nœuds. Sur Anywhere, cela ne supprime pas les nœuds (pas de provisioning), mais peut améliorer l'utilisation.

Récapitulatif des charts

Quatre charts forment le socle minimal, les deux derniers restent facultatifs. L'oubli le plus fréquent porte sur l'exporter du workload-autoscaler : son absence ne provoque aucune erreur visible, elle prive simplement Prometheus des métriques de recommandation.

Chart	Obligatoire	Description
castai-agent	✅	Collecte métriques
castai-cluster-controller	✅	Applique recommandations
castai-workload-autoscaler	✅	Génère recommandations
castai-workload-autoscaler-exporter	✅	Métriques Prometheus
castai-evictor	❌	Consolidation (optionnel)
castai-pod-mutator	❌	Pod Mutations (feature séparée)

Glissez pour voir

Documentation Helm charts

---

Méthode 3 : API (automatisation)

Pour l'automatisation CI/CD ou le déploiement multi-clusters, utilisez l'API CAST AI. Le principe reste celui de la console, à ceci près que le script d'onboarding est récupéré par un appel HTTP authentifié au lieu d'un copier-coller depuis l'interface. C'est la voie à suivre quand des dizaines de clusters doivent être connectés de façon identique.

Récupérer le script d'onboarding via API

L'appel authentifie la requête par l'en-tête X-API-Key et écrit le script dans un fichier. Conservez l'étape de relecture même en contexte automatisé, au moins lors de la mise au point du pipeline :

# Variables
CASTAI_API_KEY="votre-api-key"
CASTAI_CLUSTER_ID="votre-cluster-id"
CASTAI_API_URL="https://api.cast.ai"

# Récupérer le script d'onboarding
curl -s "$CASTAI_API_URL/v1/kubernetes/external-clusters/$CASTAI_CLUSTER_ID/onboarding-script" \
  -H "X-API-Key: $CASTAI_API_KEY" \
  -o castai-onboarding.sh

# Inspecter avant d'exécuter
less castai-onboarding.sh

# Exécuter
bash castai-onboarding.sh

Intégration GitOps / Terraform

Pour une approche Infrastructure as Code, CAST AI fournit :

• Terraform provider : terraform-provider-castai
• ArgoCD / Flux : Déployez les charts Helm via GitOps

Documentation API Reference

---

Validation de l'installation

Une installation réussie se constate à deux endroits complémentaires : sur le cluster, où les pods doivent tourner sans redémarrage, et dans la console, où le cluster doit passer à l'état connecté. Les deux vérifications sont nécessaires, des pods en bon état n'impliquant pas que la communication vers l'API aboutisse. Ajoutez le contrôle des CRD, qui conditionne la remontée des recommandations.

Vérifier les pods

La colonne READY compte les conteneurs prêts sur le total du pod : 2/2 sur l'agent est normal, celui-ci embarquant un conteneur secondaire. Une valeur de RESTARTS qui augmente signale un problème d'authentification ou de connectivité.

kubectl get pods -n castai-agent

Tous les pods doivent être Running :

NAME                                                   READY   STATUS    RESTARTS   AGE
castai-agent-xxxxx-xxxxx                               2/2     Running   0          5m
castai-cluster-controller-xxxxx-xxxxx                  2/2     Running   0          5m
castai-workload-autoscaler-xxxxx-xxxxx                 1/1     Running   0          5m
castai-workload-autoscaler-exporter-xxxxx-xxxxx        1/1     Running   0          5m

Vérifier le CRD Recommendation

Les recommandations de dimensionnement sont stockées dans le cluster sous forme d'objets Kubernetes, ce qui suppose que leur définition de ressource personnalisée ait bien été créée. Si la commande répond NotFound, le cluster-controller n'a pas terminé son initialisation :

kubectl get crd recommendations.autoscaling.cast.ai

Vérifier dans la console

Ce dernier contrôle prouve que le trafic sortant atteint bien l'API et que les identifiants sont valides. Les workloads n'apparaissent pas immédiatement, l'agent envoyant ses premières données par lots.

1. Allez sur console.cast.ai
2. Votre cluster doit apparaître avec le statut "Connected" (icône verte)
3. Après quelques minutes, les workloads apparaissent dans Workload Optimization

Temps de synchronisation

• Connexion initiale : 1-2 minutes
• Premières recommandations : quelques heures (selon l'activité)
• Full confidence : 24h+ de données

Vérifier les versions

Relevez les images réellement déployées et notez-les quelque part : c'est cette liste, et non le numéro du chart, qui vous permettra de reproduire l'installation ou de comparer deux clusters en cas de comportement divergent.

# Toutes les images CAST AI
kubectl get pods -n castai-agent -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'

---

Troubleshooting

Presque tous les incidents d'installation se ramènent à trois causes : des identifiants erronés, un blocage réseau vers l'API, ou un webhook injoignable depuis le serveur d'API. Procédez du général au particulier, en partant de la liste de contrôle ci-dessous avant d'ouvrir les journaux d'un composant précis.

Checklist de diagnostic

Avant de chercher une erreur spécifique, vérifiez ces points :

Vérification	Commande	Attendu
Pods running	kubectl get pods -n castai-agent	Tous en Running
Logs sans erreur	kubectl logs -n castai-agent -l app.kubernetes.io/name=castai-agent --tail=20	Pas d'erreurs répétées
CRD présent	kubectl get crd recommendations.autoscaling.cast.ai	CRD listé
Connectivité API	Voir test ci-dessous	Connexion établie

Glissez pour voir

Test de connectivité vers l'API :

kubectl run test-api --rm --restart=Never --image=curlimages/curl --attach -- \
  curl -s -o /dev/null -w "%{http_code}" --connect-timeout 5 https://api.cast.ai

Résultat attendu : 302 (redirect vers la console, confirme que l'API est joignable). Le pod de test s'appuie ici sur une image publique dont le tag n'est pas figé ; sur un cluster de production, utilisez une image de votre propre registre épinglée par digest @sha256:.

Problèmes courants

Chaque onglet part d'un symptôme observable et remonte vers sa cause probable. Ouvrez celui qui correspond à ce que vous constatez, les diagnostics n'ont pas de raison d'être enchaînés.

Pods CrashLoop

Symptôme : Pods en CrashLoopBackOff

Diagnostic :

kubectl logs -n castai-agent -l app.kubernetes.io/name=castai-agent --tail=50

Causes et solutions :

Erreur	Cause	Solution
invalid API key	Clé incorrecte ou expirée	Régénérer depuis la console
connection refused	Pas de connectivité réseau	Vérifier firewall, proxy, DNS
certificate error	Proxy HTTPS interceptant	Configurer certificat CA
cluster not found	CLUSTER_ID incorrect	Vérifier l'ID dans la console

Glissez pour voir

Webhook

Symptôme : Les pods ne sont pas mutés (pas de nouvelles requests/limits)

Checklist webhook :

1. MutatingWebhookConfiguration présent ?

   kubectl get mutatingwebhookconfigurations | grep castai

2. Service du webhook accessible ?

   kubectl get svc -n castai-agent | grep mutator
   kubectl get endpoints -n castai-agent | grep mutator

3. NetworkPolicies bloquantes ?

   kubectl get networkpolicies -n castai-agent

4. Logs du webhook ?

   kubectl logs -n castai-agent -l app.kubernetes.io/name=castai-workload-autoscaler --tail=50

Si le webhook n'est pas accessible depuis l'API server, consultez la documentation réseau de votre CNI (Calico, Cilium, etc.).

CPVPA

Symptôme : Pod castai-agent-cpvpa en erreur

Le Cluster Proportional Vertical Autoscaler ajuste automatiquement les ressources de l'agent selon la taille du cluster. Documentation Hosted components

Diagnostic :

kubectl logs -n castai-agent -l app=castai-agent-cpvpa --tail=20

Pour désactiver (si problème persistant) :

Consultez les values du chart castai-agent pour l'option de désactivation :

helm show values castai-helm/castai-agent | grep -i cpvpa

Ou consultez la documentation troubleshooting composants.

Cluster non visible

Symptôme : Le cluster n'apparaît pas dans la console

Vérifications :

1. L'agent envoie des données ?

   kubectl logs -n castai-agent -l app.kubernetes.io/name=castai-agent --tail=30 | grep -i "sync\|send\|connect"

2. Bon endpoint API ?

   Vérifiez que CASTAI_API_URL correspond à votre région (US vs EU).

3. Cluster ID correct ?

   kubectl get configmap -n castai-agent castai-agent -o yaml | grep -i cluster

---

Désinstallation

La désinstallation se fait dans l'ordre inverse de l'installation : releases Helm, namespace, puis ressources créées à l'échelle du cluster. Ces dernières survivent à la suppression du namespace et doivent être retirées explicitement, sans quoi une réinstallation ultérieure se heurtera à des webhooks pointant vers des services inexistants. Les 2>/dev/null || true de l'exemple absorbent l'erreur des composants optionnels qui n'auraient jamais été installés.

# Supprimer les releases Helm
helm uninstall castai-agent -n castai-agent
helm uninstall castai-cluster-controller -n castai-agent
helm uninstall castai-workload-autoscaler -n castai-agent
helm uninstall castai-workload-autoscaler-exporter -n castai-agent
helm uninstall castai-evictor -n castai-agent 2>/dev/null || true
helm uninstall castai-pod-mutator -n castai-agent 2>/dev/null || true

# Supprimer le namespace
kubectl delete namespace castai-agent

# Supprimer les webhooks orphelins
kubectl delete mutatingwebhookconfigurations -l app.kubernetes.io/managed-by=castai 2>/dev/null || true

CRDs

Par défaut, les CRDs ne sont pas supprimés (protection Helm). Pour les supprimer :

kubectl delete crd recommendations.autoscaling.cast.ai
kubectl delete crd workloadscalingpolicies.autoscaling.cast.ai 2>/dev/null || true

Cela efface aussi toutes les recommandations stockées.

---

À retenir

• Trois méthodes : Console (simple), Helm (contrôle), API (automatisation)
• Console recommandée pour un premier déploiement : script généré et personnalisé
• Helm manuel : n'oubliez pas le workload-autoscaler-exporter
• metrics-server requis (installé automatiquement par le script console)
• Sécurité : ne pas versionner les clés, inspecter les scripts avant exécution
• Validation : tous les pods Running + cluster "Connected" dans la console
• 24h+ pour des recommandations fiables (full confidence)

Prochaines étapes

Découvrir la console CAST AI Naviguer dans l'interface, explorer vos workloads et consulter les premières recommandations

Ressources

• Getting started with CAST AI Anywhere, Documentation officielle
• Helm charts, Liste des charts disponibles
• Components troubleshooting, Diagnostic des composants
• API Reference, Documentation API

×

📖 Voir la documentation →