Aller au contenu principal

Kubernetes - Démarrage rapide

Prérequis pour suivre ce tutoriel​

Afin de profiter des fonctionnalités de gestion de cluster Kubernetes depuis la plateforme NumSpot, les prérequis sont:

  • Un compte utilisateur NumSpot détenant le rôle Kubernetes Admin.
  • Ce compte devant être rattaché à un espace NumSpot.

Créer mon premier cluster​

Pour commencer, nous allons créer un cluster Kubernetes en utilisant l'API en HTTP de NumSpot. Nous utiliserons la région standard (eu-west-2) pour limiter les coûts de PoC.

Notre premier cluster qui contiendra un seul Nodepool qui se composera de 2 nodes de type SMALL (associé à des caractéristiques spécifiques), et on l'appelera np1 pour l'identifier.

Pour plus de facilité, nous choisirons la dernière version disponible de l'offre Kubernetes de NumSpot que l'on récupère depuis la documentation sur les versions disponibles.

Et enfin, nous utiliserons le CIDR 10.X.0.0/16 ce qui donne la possibilité d'avoir 65,536 nodes, suffisant dans notre cas (voir: comment choisir le CIDR à la création d'un cluster).

Exemple de requête: Création d'un cluster Kubernetes
export REGION="eu-west-2"
export SPACE_ID="8e9cbfeb-573d-4f77-97c2-b7301f38bd2f"
export ACCESS_TOKEN="myaccesstoken"

curl -X POST https://api.$REGION.numspot.com/kubernetes/spaces/$SPACE_ID/clusters \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
  --data '{
    "name": "my-first-cluster",
    "cidr": "10.1.0.0/16",
    "version": "1.29.5",
    "nodeProfile": "verysmall",
    "nodeCount": 3
  }'
  | export OPERATION_ID=$(jq -r .id) && export CLUSTER_ID=$(jq -r .clusterid)
remarque

Dans la commande précédente, nous avons utilisé la commande jq pour récupérer:

  • L'identifiant de l'operation retourné par la requête de création de cluster et la stocker dans la variable d'environnement OPERATION_ID, qui nous servira lorsqu'on voudra suivre l'exécution de la création du cluster,
  • Le CLUSTER_ID pour opérer sur le cluster juste créé.

La requête retournée donne les informations de l'operation lancée, à savoir la création d'un cluster.

Exemple de réponse: Création d'un cluster Kubernetes
{
  "id": "4784f323-e98d-4d48-bf07-8fc6378a2a07",
  "operationType": "CreateCluster",
  "status": "PENDING",
  "target": "https://..../kubernetes/spaces/8e9cbfeb-573d-4f77-97c2-b7301f38bd2f/clusters/3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "selfLink": "https://..../spaces/8e9cbfeb-573d-4f77-97c2-b7301f38bd2f/operations/4784f323-e98d-4d48-bf07-8fc6378a2a07",
  "targetName": "my-first-cluster",
  "clusterid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    ...
}

Tracer l'operation de création du cluster en cours​

Nous pouvons vérifier notre operation en exécutant une requête qui récupère les détails de l'operation effectuée depuis son identifiant (que nous avons stocké plus tôt dans la variable d'environnement OPERATION_ID).

Exemple de requête: Récupérer les informations d'une operation
curl -X GET https://api.$REGION.numspot.com/kubernetes/spaces/$SPACE_ID/operations/$OPERATION_ID \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header 'Accept: application/json'
Exemple de réponse: Récupérer les informations d'une operation
{
  "id": "4784f323-e98d-4d48-bf07-8fc6378a2a07",
  "operationType": "CreateCluster",
  "status": "PENDING",
  "target": "https://..../kubernetes/spaces/8e9cbfeb-573d-4f77-97c2-b7301f38bd2f/clusters/3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "selfLink": "https://..../spaces/8e9cbfeb-573d-4f77-97c2-b7301f38bd2f/operations/4784f323-e98d-4d48-bf07-8fc6378a2a07",
  "targetName": "my-first-cluster",
  "clusterid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  ...
}

On peut remarquer que l'operation contient un operationType qui indique l'action de l'operation, et dans notre cas contient le type CreateCluster qui indique que l'operation est une création de cluster Kubernetes.

Le status d'une operation indique l'état d'avancement de celle-ci. Les valeurs possibles sont :

  • PENDING: l'operation est en attente d'être exécutée.
  • RUNNING: indique que l'operation est en cours d’exécution.
  • INTERRUPTED: l'operation a été interrompue par des processus d'administration de NumSpot et peut être reprise.
  • FAILED: l'operation a rencontrée un problème technique durant l'exécution et s'est terminé.
  • DONE: lorsque l'operation s'est terminée avec succès.

Tant que l'operation n'est pas terminée (FAILED ou DONE), continuez à surveiller avec cette même requête. Si le status devient DONE, félicitations, vous avez enfin votre premier cluster prêt à être utilisé.

Vérifier l'état du cluster Kubernetes​

Une fois le cluster correctement créé, il est important de vérifier que le cluster soit dans un état exploitable.

Exemple de requête: Récupérer l'état du cluster et de ces workers
curl -X GET  https://api.$REGION.numspot.com/kubernetes/spaces/$SPACE_ID/clusters/$CLUSTER_ID/state \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header 'Content-Type: application/json'

Et cela nous retournera les informations du cluster.

Exemple de réponse: Récupérer les informations d'un cluster Kubernetes
{
  "name": "my-first-cluster",
  "health": "OK",
  "nodes": [
    {
      "name": "worker1",
      "status": "OK",
      "cpu": {
        "used": "2000m",
        "available": "92m"
      },
      "memory": {
        "used": "102400Ki",
        "available": "3633016Ki"
      }
    }
    {
      "name": "worker2",
      "status": "OK",
      "cpu": {
        "used": "2000m",
        "available": "147m"
      },
      "memory": {
        "used": "102400Ki",
        "available": "3633016Ki"
      }
    }
    {
      "name": "worker3",
      "status": "OK",
      "cpu": {
        "used": "2000m",
        "available": "114m"
      },
      "memory": {
        "used": "102400Ki",
        "available": "3633016Ki"
      }
    }
  ]
}

On retrouve dans le corps de la réponse le champ nodes qui donne des informations sur chaque nœud utilisable par l'utilisateur. Un nœud est identifiable par son nom, le statut indique si le nœud en question est fonctionnel ou non utilisable. Dans notre cas, les 3 nœuds que nous avions demandés à la création sont bel et bien utilisables dans le cluster.

Accéder au cluster via l'outil de commande​

Pour utiliser le cluster au travers de l'invité de commande kubectl, il est nécessaire de se prémunir de:

  • Les liens permettant de communiquer avec le cluster
  • Le fichier KubeConfig que kubectl utilisera
  • La clé ssh pour être autorisé à accéder au cluster

Récupérer les liens du cluster​

Pour récupérer l'URL du cluster qui sera utilisé par kubectl, retrouvez les informations du cluster:

Exemple de requête: Récupérer les informations du cluster
curl -X GET  https://api.$REGION.numspot.com/kubernetes/spaces/$SPACE_ID/clusters/$CLUSTER_ID \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header 'Content-Type: application/json'

Vous retrouverez le champ urls.[0].api contenant le nom de domaine du cluster, ainsi que le champ $clientBastionPublicIP détenant l'adresse IP du bastion du cluster.

Pour simplifier l'explication, nous associerons l'URL de l'API de Kubernetes du cluster par $kubernetesApiHost.

Exemple de réponse: Récupérer les informations d'un cluster
{
  "id": "5953ed12-062e-4f16-a49f-7ca242f00c18",
  "version": "1.29.5",
  "clientBastionPublicIP": "80.247.12.251",
  ...
  "urls": [
    {
      "api": "internal-lbm-910bd3953029-840420822.cloudgouv-eu-west-1.lbu.outscale.com"
    }
  ]
}

Récupérer les fichiers​

Dans cette étape, nous allons récupérer deux fichiers, la PrivateKey (clé ssh) permettant d'être autorisé à accéder au cluster, ainsi que la KubeConfig qui permet l'authentification à l'API Kubernetes du cluster.

Nous allons d'abord récupérer la clé privée de la manière suivante:

Exemple de requête: Récupérer la clé SSH du cluster
curl -X GET  https://api.$REGION.numspot.com/kubernetes/spaces/$SPACE_ID/clusters/$CLUSTER_ID/privatekey \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header 'Content-Type: application/octet-stream'

Le contenu devra être stocké dans un fichier que l'on nommera $privateKey, et modifier les permissions avec la commande suivante:

# $privateKey est le chemin qui pointe vers le fichier privateKey stocké
chmod 0600 $privateKey

Nous allons ensuite, avec le même processus, récupérer le fichier KubeConfig:

Exemple de requête: Récupérer KubeConfig du cluster
curl -X GET  https://api.$REGION.numspot.com/kubernetes/spaces/$SPACE_ID/clusters/$CLUSTER_ID/kubeconfig \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header 'Content-Type: application/octet-stream'

Le contenu devra être stocké dans un fichier que l'on nommera $kubeConfig.

Préparer le fichier Kubeconfig​

Dans le fichier $kubeConfig, remplacer toutes les valeurs des champs server par https://127.0.0.1:6443.

Connexion avec le bastion du cluster​

Il est nécessaire d'initier une connexion pour que les requêtes de l'invité de commande kubectl puissent passer par le bastion pour atteindre l'API du cluster:

Exemple de command: Connexion SSH vers le bastion du cluster
ssh-keyscan $clientBastionPublicIP >> ~/.ssh/known_hosts
ssh -i $privateKey -o IdentitiesOnly=yes -l outscale -L 127.0.0.1:6443:$kubernetesApiHost:6443 -N $clientBastionPublicIP &

Définir la configuration de kubernetes​

Une fois la connexion établie, exportez la variable d'environnement KUBECONFIG en utilisant le chemin de $kubeConfig:

Exemple de commande: Exporter le fichier KubeConfig
export KUBECONFIG=$kubeConfig

Tester la connection​

Verifiez que le cluster est accessible par l'outil de commande kubectl en utilisant la comande suivante:

Exemple de commande: Récupérer les versions de Kubernetes client et serveur
kubectl version

La réponse de la commande doit comprendre la version de l'API Kubernetes du cluster:

Exemple de réponse: Récupérer les versions de Kubernetes client et serveur
Client Version: v1.X.X
...
Server Version: v1.29.5

Créer mon premier déploiement en ligne de commande​

Nous sommes directement dans un projet par défaut. Une fois connecté via la ligne de commande kubectl, nous allons pouvoir déployer notre première application.

Créez un fichier deployments.yaml dans lequel vous collez le contenu suivant.

Fichier: deployments.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 3
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.27.0
        ports:
        - containerPort: 80

Ensuite pour déployer cette ressource, il suffit d’exécuter:

Créer une ressource
kubectl create deployment -f deployments.yaml

La demande de création de déploiement a été validée et est en train d'être exécutée par Kubernetes.

Nous allons vérifier que le pod correspondant au déploiement est fonctionnel. Pour cela, il est nécessaire de connaître l'état du pod (readynessProbe et livenessProbe) depuis la ligne de commande suivante:

Retrouver la liste des pods filtrés par le label de déploiement
kubectl get pods -l app=nginx

Vérifions que le pod du déploiement Nginx est correctement déployé et fonctionnel. Ceci s'effectue par le positionnement des livenessProbe (nombre de droite de l'exécution en cours du conteneur) et readynessProbe (nombre de gauche permettant de savoir si le conteneur est prêt à servir des requêtes) au sein du conteneur qui est représenté par le nombre effectif sous le libellé READY :

Liste des pods Nginx dont réplica
# Montrer les lignes des pods en running
NAME                                 READY   STATUS    RESTARTS   AGE
nginx-56d947767c-2948z               1/1     Running   0          2d11h

Voilà, votre première application est correctement déployée et prête à recevoir des requêtes.

Augmenter le nombre de worker du cluster​

Initialement, le cluster contient seulement 2 workers et nous allons en ajouter 2 supplémentaires pour en avoir 4.

Rappelons-nous que nous avons demandé des profils de workers verysmall.

Exemple de requête: Éditer le nombre de **nodes**
curl -X POST https://api.$REGION.numspot.com/kubernetes/spaces/$SPACE_ID/clusters/workers/add \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
  --data '{
    "nodeCount": 2,
    "nodeProfile": "versymall",
  }'

La requête renvoie les informations de l'operation lancée.

Exemple de réponse: Ajouter des workers dans un cluster
{
  "clusterId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "id": "680d2446-dc82-4a98-8b6b-71f3f982acaa",
  "operationType": "AddWorkers",
  "status": "PENDING",
  "targetLink": "https://..../spaces/8e9cbfeb-573d-4f77-97c2-b7301f38bd2f/clusters/3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "selfLink": "https://..../spaces/8e9cbfeb-573d-4f77-97c2-b7301f38bd2f/operations/680d2446-dc82-4a98-8b6b-71f3f982acaa",
  ...
}

Pour rappel, on peut suivre la bonne exécution de l'operation d'ajout de workers dans le cluster à partir de l'API :

Exemple de requête: Récupérer les informations d'une operation
curl -X GET /kubernetes/spaces/$SPACE_ID/operations/$OPERATION_ID \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header 'Accept: application/json'