# Reference Cluster API

import { Tabs, TabItem } from '@astrojs/starlight/components';

La Kubetail Cluster API est un serveur HTTP base sur Go qui fournit l'API GraphQL utilisee par le Dashboard pour effectuer des operations sur le cluster. L'executable du serveur est compile a partir du code source situe dans le depot Kubetail sous [modules/cluster-api](https://github.com/kubetail-org/kubetail/tree/main/modules/cluster-api) et est generalement deploye via l'image Docker `kubetail-cluster-api` (voir ci-dessous). Il est possible d'executer `kubetail-cluster-api` comme conteneur autonome, mais nous recommandons de le deployer avec le [chart Helm](/fr/reference/helm-chart) officiel de Kubetail.

## Image Docker

L'image Docker `kubetail-cluster-api` est publiee sur Docker Hub et GitHub Container Registry a chaque release:

| Registry | Image |
|----------|-------|
| Docker Hub | `kubetail/kubetail-cluster-api` |
| GHCR | `ghcr.io/kubetail-org/kubetail-cluster-api` |

Deux variantes sont disponibles:

| Suffixe de tag | Image de base | Description |
|----------------|---------------|-------------|
| _(aucun)_ | `scratch` | Image minimale, empreinte la plus reduite |
| `-alpine` | `alpine` | Inclut un shell et les utilitaires standard |

## Entrypoint

L'entrypoint par defaut du conteneur est `/cluster-api/cluster-api`:

```sh
cluster-api [flags]
```

## Indicateurs

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--config` | `-c` | | Chemin vers le fichier de configuration (par ex. `/etc/kubetail/cluster-api.yaml`) |
| `--addr` | `-a` | `:8080` | Adresse hote a laquelle se lier |
| `--gin-mode` | | `release` | Mode du framework Gin (`release`, `debug`) |

## Configuration

La Cluster API peut etre configuree avec un fichier de configuration YAML, JSON ou TOML. Passez le chemin du fichier avec `-c` / `--config`. Les variables d'environnement peuvent etre referencees dans le fichier de configuration avec la syntaxe `${VARIABLE_NAME}`.

```sh
cluster-api --config /etc/kubetail/cluster-api.yaml
```

<Tabs>
  <TabItem label="YAML">
    ```yaml
    ## Kubetail Cluster API Configuration File
    #
    # Ce fichier definit le comportement du kubetail cluster API server,
    # qui fournit l'API GraphQL pour les operations du cluster.
    #

    ## allowed-namespaces ##
    #
    # Liste des namespaces auxquels l'API est autorisee a acceder.
    # Si vide, tous les namespaces sont accessibles.
    #
    # Valeur par defaut: []
    #
    allowed-namespaces: []

    ## addr ##
    #
    # Adresse reseau et port auxquels le serveur HTTP doit se lier.
    #
    # Valeur par defaut: :8080
    #
    addr: ":8080"

    ## base-path ##
    #
    # Chemin URL de base pour tous les endpoints de l'API.
    #
    # Valeur par defaut: /
    #
    base-path: /

    ## gin-mode ##
    #
    # Mode du framework Gin.
    # Valeurs valides: debug, release
    #
    # Valeur par defaut: release
    #
    gin-mode: release

    ## cluster-agent ##
    #
    # Configuration de la connexion au Cluster Agent
    #
    cluster-agent:

      ## dispatch-url ##
      #
      # URL utilisee pour se connecter au Cluster Agent.
      # Prend en charge le schema kubernetes:// pour la decouverte de services in-cluster.
      #
      # Valeur par defaut: kubernetes://kubetail-cluster-agent:50051
      #
      dispatch-url: kubernetes://kubetail-cluster-agent:50051

      ## tls ##
      #
      # Configuration TLS pour les connexions au Cluster Agent
      #
      tls:

        ## enabled ##
        #
        # Indique si TLS est active pour les connexions au Cluster Agent.
        #
        # Valeur par defaut: false
        #
        enabled: false

        ## cert-file ##
        #
        # Chemin vers le fichier de certificat TLS.
        #
        # Valeur par defaut: ""
        #
        cert-file: ""

        ## key-file ##
        #
        # Chemin vers le fichier de cle privee TLS.
        #
        # Valeur par defaut: ""
        #
        key-file: ""

        ## ca-file ##
        #
        # Chemin vers le fichier de certificat CA utilise pour verifier le certificat du Cluster Agent.
        #
        # Valeur par defaut: ""
        #
        ca-file: ""

        ## server-name ##
        #
        # Nom du serveur utilise pour la verification TLS.
        # Si vide, le nom d'hote de dispatch-url est utilise.
        #
        # Valeur par defaut: ""
        #
        server-name: ""

    ## csrf ##
    #
    # Parametres de protection CSRF
    #
    csrf:

      ## enabled ##
      #
      # Indique si la protection CSRF est activee.
      #
      # Valeur par defaut: true
      #
      enabled: true

    ## logging ##
    #
    # Configuration de la sortie de logs du serveur API
    #
    logging:

      ## enabled ##
      #
      # Indique si le logging est active pour le serveur.
      #
      # Valeur par defaut: true
      #
      enabled: true

      ## level ##
      #
      # Niveau minimal de log a produire.
      # Valeurs valides: debug, info, warn, error, disabled
      #
      # Valeur par defaut: info
      #
      level: info

      ## format ##
      #
      # Format de la sortie de logs.
      # Valeurs valides: json, pretty
      #
      # Valeur par defaut: json
      #
      format: json

      ## access-log ##
      #
      # Configuration du journal d'acces HTTP
      #
      access-log:

        ## enabled ##
        #
        # Indique si le journal d'acces est active.
        #
        # Valeur par defaut: true
        #
        enabled: true

        ## hide-health-checks ##
        #
        # Indique s'il faut omettre les requetes de health check (/healthz) du journal d'acces.
        #
        # Valeur par defaut: false
        #
        hide-health-checks: false

    ## tls ##
    #
    # Configuration TLS pour le serveur HTTP
    #
    tls:

      ## enabled ##
      #
      # Indique si TLS est active.
      #
      # Valeur par defaut: false
      #
      enabled: false

      ## cert-file ##
      #
      # Chemin vers le fichier de certificat TLS.
      #
      # Valeur par defaut: ""
      #
      cert-file: ""

      ## key-file ##
      #
      # Chemin vers le fichier de cle privee TLS.
      #
      # Valeur par defaut: ""
      #
      key-file: ""
    ```
  </TabItem>
</Tabs>