Installation : Kubernetes (Helm)

Déployez KiloCenter sur Kubernetes avec Helm — chart, prérequis (k8s 1.25+, PostgreSQL 14+, Redis 7+), et ingress.

Objectif

Déployez KiloCenter sur un cluster Kubernetes à l'aide du chart Helm inclus dans ce dépôt.

Prérequis

Exigence	Version minimale
Cluster Kubernetes	1.25+
Helm	3.x
PostgreSQL externe	14+
Redis externe	7+

PostgreSQL et Redis ne sont pas déployés par ce chart. Provisionnez-les séparément (services gérés, opérateurs ou autonome) et fournissez les détails de connexion dans votre override de valeurs.

Architecture

                  Internet
                     |
               [ Ingress ] (facultatif)
                /         \
         kc-web:80    kc-gateway:9090
                          |
                    kc-core:50051 ---- kc-identity:50052
                    /      |      \
             bssci:5000  scaci:5001  mosquitto:1883
                                         |
                                    [clients MQTT]

Le chart déploie cinq services et un broker MQTT :

Composant	Port(s)	Description
kc-core	50051 (gRPC), 5000 (BSSCI), 5001 (SCACI), 8086 (santé)	Moteur du centre de services
kc-gateway	9090 (gRPC-web), 8087 (santé)	Point d'entrée de l'API externe
kc-identity	50052 (gRPC), 8088 (santé)	Identité, utilisateurs, organisations
kc-web	80	Interface de gestion web (nginx)
mosquitto	1883, 9001 (WebSocket)	Broker MQTT
certgen	—	Hook de pré-installation qui génère des certificats TLS

Étape 1 : Créer un override de valeurs

Au minimum, remplacez les paramètres de base de données, de Redis et de secrets :

# my-values.yaml
postgresql:
  host: my-postgres.default.svc.cluster.local
  password: "a-strong-password"
  sslMode: "require"

redis:
  host: my-redis.default.svc.cluster.local

secrets:
  authHmacSecret: "replace-with-a-random-string-at-least-32-bytes"
  mqttAdminPassword: "strong-mqtt-admin-pw"
  mqttClientPassword: "strong-mqtt-client-pw"

certgen:
  serverName: "kilocenter.example.com"

Important : Le authHmacSecret est utilisé pour signer et vérifier les jetons JWT entre KC-Gateway et KC-Identity. Il doit comporter au moins 32 caractères.

Étape 2 : Installer

helm install kilocenter ./helm/kilocenter -f my-values.yaml

Lors de la première installation, une tâche hook de pré-installation exécute le certgen binaire pour générer une autorité de certification (CA) auto-signée et un certificat serveur dans un PVC partagé. Les mises à niveau ultérieures ignorent la génération si les certificats existent déjà.

Étape 3 : Valider

# Vérifiez que tous les pods sont en cours d'exécution
kubectl get pods -l app.kubernetes.io/instance=kilocenter

# Vérifiez l'état des services
kubectl exec deploy/kilocenter-kc-core -- wget -qO- http://localhost:8086/health/ping
kubectl exec deploy/kilocenter-kc-identity -- wget -qO- http://localhost:8088/health
kubectl exec deploy/kilocenter-kc-gateway -- wget -qO- http://localhost:8087/health

Étape 4 : Accéder à l’interface utilisateur

Sans ingress, utilisez le transfert de port :

kubectl port-forward svc/kilocenter-kc-web 8080:80

Puis ouvrez http://localhost:8080/ dans votre navigateur.

Compte administrateur par défaut

Au premier démarrage, un utilisateur administrateur par défaut est créé via une migration de base de données :

E-mail	admin [at] kilocenter.local
Mot de passe	admin123!

Remplacez [at] par @ lors de la connexion.

Avertissement : Modifiez le mot de passe ou supprimez ce compte avant tout déploiement accessible au public. Les identifiants sont publiés dans ce dépôt.

Ingress

Activez l’Ingress Kubernetes standard dans votre override de valeurs :

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: kilocenter.example.com
      paths:
        - path: /
          pathType: Prefix
          service: kc-web
          port: 80
        - path: /kilocenter.api
          pathType: Prefix
          service: kc-gateway
          port: 9090
  tls:
    - secretName: kilocenter-tls
      hosts:
        - kilocenter.example.com

Lorsque vous utilisez ingress, ajoutez votre domaine aux origines autorisées CORS :

kcGateway:
  config:
    corsOrigins:
      - "https://kilocenter.example.com"

Accès au protocole BSSCI/SCACI

Les stations de base se connectent directement à KC-Core via TCP+TLS sur les ports 5000 (BSSCI) et 5001 (SCACI). Il s'agit de connexions TCP brutes, pas HTTP. Pour les exposer à l'extérieur, créez un service LoadBalancer :

apiVersion: v1
kind: Service
metadata:
  name: kilocenter-bssci
spec:
  type: LoadBalancer
  selector:
    app.kubernetes.io/name: kc-core
    app.kubernetes.io/instance: kilocenter
  ports:
    - name: bssci
      port: 5000
      targetPort: 5000
    - name: scaci
      port: 5001
      targetPort: 5001

Certificats TLS

Le certgen hook génère une CA auto-signée et un certificat serveur lors de la première installation. En production, remplacez-les par des certificats signés par une CA de confiance en montant votre propre secret ou PVC à /app/certificates dans le pod kc-core.

Référence de configuration

Pour la liste complète des paramètres configurables, consultez le README du chart Helm.

Mise à niveau

helm upgrade kilocenter ./helm/kilocenter -f my-values.yaml

Définissez un tag d’image spécifique pour verrouiller une version :

global:
  imageTag: "1.0.0"

Dépannage

Symptôme	Cause probable	Correctif
Pods en ImagePullBackOff	Secret de pull d’image manquant	Ajoutez global.imagePullSecrets avec les identifiants de votre registre
Sonde de préparation KC-Core 503	Dépendance non prête	Vérifiez que KC-Identity et PostgreSQL sont en cours d'exécution
invalid_token après la connexion	Incompatibilité du secret HMAC	Assurez-vous que secrets.authHmacSecret est défini (identique pour gateway et identity)
Connexion BSSCI refusée	Aucun service externe	Créez un service LoadBalancer pour les ports 5000/5001
Erreurs gRPC-web dans le navigateur	CORS ou ingress mal configuré	Vérifiez kcGateway.config.corsOrigins et les chemins ingress