MARA : désormais disponible sur un poste de travail près de chez vous

Jason Schmidt

Lorsque nous avons commencé à travailler sur le projet Architecture de référence NGINX pour les applications modernes (MARA), nous avons choisi AWS comme fournisseur IaaS, car nous connaissions déjà la plateforme et pouvions utiliser le budget de notre service pour le financer. Bien entendu, tout le monde ne dispose pas de la même expérience ni du même budget, et nombre d’entre vous nous ont demandé de proposer des solutions permettant d’exécuter MARA localement – dans un environnement de laboratoire ou même sur un poste de travail – avec des distributions Kubernetes telles que K3s, Canonical MicroK8s et minikube.

Nous vous avons entendus et sommes heureux de vous annoncer aujourd’hui que nous avons testé MARA sur MicroK8s et que nous mettons à votre disposition des instructions pour que vous puissiez le déployer vous-même !

Pourquoi avons-nous choisi MicroK8s pour nos tests ? Parce qu’il fournit les fonctionnalités de DNS, de stockage et de trafic sortant dont MARA a besoin, dans un modèle facile à déployer et peu gourmand en mémoire. Avec MicroK8s, nous pouvons facilement répéter différents scénarios de test afin de déterminer la configuration minimale requise pour des déploiements offrant des niveaux de performances satisfaisants.

Nous espérons que ce travail facilitera nos tests d’autres distributions Kubernetes. Pour connaître l’état actuel des différentes distributions, consultez notre dépôt GitHub. Si vous souhaitez voir votre distribution préférée figurer dans la liste, nous vous invitons à créer un fork, à effectuer des tests et à soumettre des pull requests !

Gérer les contraintes de ressources

Les principales contraintes liées à l’exécution locale de MARA concernent la mémoire et le processeur. Lors des tests préliminaires, nous avons constaté que la plupart des problèmes d’épuisement de la mémoire étaient liés à Elasticsearch. Kibana est pratiquement inutilisable dans les configurations disposant d’une quantité de mémoire extrêmement faible (moins de 16 Go). Pour remédier à ce problème, nous avons ajouté au fichier de configuration de MARA des paramètres qui désactivent les mécanismes de redondance normalement présents dans un déploiement Elasticsearch complet. Bien que cela augmente le nombre de scénarios de défaillance possibles, il s’agit d’un compromis nécessaire dans les environnements aux ressources limitées.

Les contraintes liées au processeur dépendent directement de la charge imposée à notre application d’exemple « Bank of Sirius ». Le déploiement de MARA inclut Locust pour générer de la charge sur Bank of Sirius, avec des paramètres permettant à l’utilisateur de définir le nombre d’utilisateurs et le rythme d’arrivée de nouveaux utilisateurs.

Notez que l’augmentation de la charge sur Bank of Sirius affecte également le reste du système. Si le nombre d’utilisateurs ou le taux de démarrage est trop élevé, les performances de MARA se dégradent au point que certains composants risquent de planter ou de se bloquer. Les valeurs provoquant ce comportement dépendent des ressources CPU disponibles, mais un déploiement disposant au minimum de la capacité indiquée dans la section Prérequis devrait pouvoir gérer la charge générée par un maximum de 64 utilisateurs, avec un taux de démarrage de 16 utilisateurs à la fois.

Déploiement de MARA sur MicroK8s

Maintenant que vous disposez de ces informations, vous êtes prêt à déployer MARA sur MicroK8s !

Prérequis

• root sur un système (serveur Linux physique, virtualisé ou dans le cloud) exécutant Ubuntu 20.04 (Focal) ou une version ultérieure, avec au minimum :
  • Disque de 20 Go
  • 16 Go de mémoire
  • L’équivalent de 4 processeurs
• Un environnement virtuel Python 3 sur le système local, avec toutes les bibliothèques et tous les fichiers binaires requis par MARA. Si Python 3 n’est pas déjà installé, exécutez les commandes suivantes :

$  sudo apt update$  sudo apt install -y python3-venv

• Au moins une adresse IPv4 libre que l’équilibreur de charge MetalLB intégré à MicroK8s pourra attribuer au trafic sortant du contrôleur Ingress NGINX. Si vous accédez à l’application Bank of Sirius via localhost, toute adresse privée disponible (conforme à la RFC 1918) convient. Par exemple, si votre réseau est 192.168.100.0/24, vous pouvez utiliser une adresse telle que 10.10.10.10.
• Un compte Pulumi et un jeton d’accès. Si vous n’en avez pas encore, vous les créerez à l’étape 1 de la section « Déployer MARA ». Notez que, bien que Pulumi vous permette de stocker le fichier d’état dans un magasin d’objets compatible S3 ou sur le système de fichiers local, MARA ne prend actuellement pas en charge cette fonctionnalité. Cette limitation sera supprimée dans une prochaine version de MARA ou de Pulumi.

Installer et configurer MicroK8s

1. Installez MicroK8s :

$ sudo snap install microk8s --classicmicrok8s (1.23/stable) v1.23.3 from Canonical✓ installed

1. Définissez les autorisations nécessaires pour exécuter les commandes microk8s. Remplacez <username> par le nom de votre compte disposant des privilèges root sur le système :

$ sudo usermod -a -G microk8s <username>$ sudo chown -f -R <username> ~/.kube
$ newgrp microk8s

1. Déconnectez-vous de votre compte disposant des privilèges root, puis reconnectez-vous afin que les nouvelles autorisations prennent effet.
2. Activez les modules complémentaires MicroK8s pour DNS, le stockage et MetalLB. À l’invite, indiquez une plage d’adresses IP au format X.X.X.X‑X.X.X.Y correspondant à l’une des options suivantes :

$ microk8s enable dns storage metallbEnabling DNS
Applying manifest
...
Restarting kubelet
DNS is enabled
Enabling default storage class
...
Storage will be available soon
Enabling MetalLB
Enter each IP address range delimited by comma (e.g. '10.64.140.43-10.64.140.49,192.168.0.105-192.168.0.111'): 192.168.100.100-192.168.100.110
Applying Metallb manifest
...
MetalLB is enabled

• Une plage réelle d’adresses IP privées (par exemple, 192.168.100.100-192.168.100.110, la valeur utilisée ci-dessous)
• Une seule adresse IP privée (par exemple, 192.168.100.100-192.168.100.100)

1. Vérifiez que MicroK8s est en cours d’exécution :

$ microk8s statusmicrok8s is running
high-availability: no
  datastore master nodes: 127.0.0.1:19001
  datastore standby nodes: none
addons:
  enabled:
    dns           # CoreDNS
    ha-cluster    # Configure high availability on the current node
    metallb       # Loadbalancer for your Kubernetes cluster
    storage       # Storage class; allocates storage from host directory
...

1. Chargez la configuration de MicroK8s dans le fichier où la plupart des utilitaires s’attendent à la trouver (~/.kube/config) et définissez les autorisations recommandées pour le répertoire et le fichier :

$ microk8s config > ~/.kube/config$ sudo chmod 0644 ~/.kube/config

Clonez le dépôt MARA et configurez le cluster MicroK8s

1. Clonez le dépôt MARA et initialisez le sous-module Bank of Sirius :

$ git clone https://github.com/nginxinc/kic-reference-architectures.git$ cd kic-reference-architectures/
$ git submodule update --init --recursive --remote

1. Depuis le répertoire racine du dépôt MARA cloné (dans lequel vous vous êtes placé à l’étape précédente), configurez l’environnement virtuel Python pour le cluster MicroK8s :

$ ./bin/setup_venv.sh

1. Cette commande génère une longue trace d’exécution. En cas d’erreur, veuillez consulter la section « Problèmes connus/Mises en garde » du dépôt GitHub de MARA pour obtenir des suggestions.
2. Activez l’environnement virtuel Python. Cette commande configure votre PATH ainsi que d’autres variables d’environnement afin d’utiliser l’environnement virtuel :

$ source ./pulumi/python/venv/bin/activate

1. Vérifiez que le cluster MicroK8s est correctement configuré pour le déploiement de MARA :

$ ./bin/testcap.sh
This script will perform testing on the current kubernetes installation using the currently active kubernetes configuration and context.
Any failures should be investigated, as they will indicate that the installation does not meet the minimum set of capabilities required to run MARA.

...
==============================================================
| All tests passed! This system meets the basic requirements |
| to deploy MARA.                                            |
==============================================================

Déployer MARA

Le script start.sh, utilisé dans cette section pour déployer MARA, prend en charge des options qui nécessitent des actions supplémentaires pour que le déploiement aboutisse. Par souci de simplicité, nous supposons ici un déploiement de base qui :

• Utilise des fichiers kubeconfig plutôt que l’une des autres options de déploiement prises en charge. Pour en savoir plus sur les autres options, consultez le Guide de démarrage dans notre dépôt GitHub.
• Utilise la version la plus récente de NGINX Open Source avec laquelle nous avons testé MARA (pas nécessairement la toute dernière version).
• Utilise le contrôleur Ingress NGINX basé sur NGINX Open Source. Si vous souhaitez utiliser le contrôleur Ingress NGINX basé sur NGINX Plus, vous devez utiliser une image basée sur NGINX Plus provenant du registre Docker de F5 dans votre cluster Kubernetes. Consultez le premier AVIS ! de l’étape 3 ci-dessous pour plus d’informations.
• Utilise un seul contexte Kubernetes standard. Consultez la deuxième REMARQUE ! à l’étape 3.

Déployez MARA dans le cluster MicroK8s :

1. Exécutez le script start.sh. Si vous n’avez pas encore configuré votre poste de travail pour utiliser Pulumi, vous serez invité à vous connecter à Pulumi (en créant un compte si nécessaire), puis à saisir le jeton d’API associé à votre compte Pulumi.

$ ./bin/start.shAdding to [/home/ubuntu/kic-reference-architectures/bin/venv/bin] to PATH
Manage your Pulumi stacks by logging in.
Run `pulumi login --help` for alternative login options.
Enter your access token from https://app.pulumi.com/account/tokens
    or hit <ENTER> to log in using your browser            : <token>

Please read the documentation for more details.

1. Sélectionnez le type de déploiement en saisissant « k » à l’invite afin de créer le déploiement avec des fichiers kubeconfig. Ignorez les avertissements indiquant que make et Docker ne sont pas installés : le déploiement utilise à la place une image du contrôleur Ingress NGINX provenant d’un registre.

Type a for AWS, k for kubeconfig? k
Calling kubeconfig startup script
make is not installed - it must be installed if you intend to build NGINX Kubernetes Ingress Controller from source.
docker is not installed - it must be installed if you intend to build NGINX Kubernetes Ingress Controller from source.

1. À l’invite, indiquez le nom de la pile Pulumi à créer (ici, mara). Il doit être unique au sein de votre compte Pulumi.

Enter the name of the Pulumi stack to use in all projects: maraSubmodule source found
Configuring all Pulumi projects to use the stack: mara
Created stack 'mara'

NOTICE! Currently the deployment via kubeconfig only supports pulling images from the registry! A JWT is required in order to access the NGINX Plus repository. This should be placed in a file in the extras directory in the root, in a file named jwt.token

See https://docs.nginx.com/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret/ for more details and examples.

No JWT found; writing placeholder manifest

NOTICE! When using a kubeconfig file you need to ensure that your environment is configured to connect to Kubernetes properly. If you have multiple kubernetes contexts (or custom contexts) you may need to remove them and replace them with a simple ~/.kube/config file. This will be addressed in a future release.

1. Lorsque vous y êtes invité, indiquez le chemin d’accès complet à votre fichier kubeconfig ainsi que le nom du cluster. Dans cet exemple, il s’agit de « /home/<username>/.kube/config » et de « microk8s-cluster ».

Provide an absolute path to your kubeconfig filevalue: /home/<username>/.kube/config
Provide your clustername
value: microk8s-cluster
Attempting to connect to kubernetes cluster

1. À l’invite suivante, indiquez le nom de domaine complet (FQDN) du cluster. Le script utilise ce FQDN à deux fins : configurer le contrôleur Ingress NGINX et créer le certificat autosigné (ce second usage implique que la valeur ne peut pas être une adresse IP). Si vous remplacez le FQDN mara.example.com par un autre, veillez à l’utiliser également dans les étapes suivantes.

Create a fqdn for your deploymentvalue: mara.example.com

1. Spécifiez le mot de passe administrateur de Grafana :

Create a password for the grafana admin user; this password will be used to access the Grafana dashboardThis should be an alphanumeric string without any shell special characters; it is presented in plain text due to current limitations with Pulumi secrets. You will need this password to access the Grafana dashboard.
value: <password>

Une trace du processus d’installation s’affiche, présentant les informations suivantes pour chaque étape :

• Une bannière décrivant l’action principale effectuée lors de l’étape (par exemple, Logstore indique le début du déploiement d’Elasticsearch)
• Une liste des tâches que Pulumi va effectuer
• Un indicateur d’état en temps réel pour chaque tâche Pulumi
• Diagnostics générés par Pulumi et MARA, par exemple le nom d’hôte et l’adresse IP définis
• Le nombre de ressources affectées
• Le temps écoulé

Lorsque la dernière étape (pour Bank of Sirius) est terminée, la trace indique l’adresse IP attribuée au contrôleur Ingress NGINX par MetalLB (ici « 192.168.100.100 ») ainsi que le nom de domaine complet que vous avez choisi pour le déploiement (ici « mara.example.com »), en plus d’autres informations sur le déploiement.

The startup process has finished successfully
Next Steps:
1. Map the IP address (192.168.100.100) of your Ingress Controller with your FQDN (mara.example.com).
2. Use the ./bin/test-forward.sh program to establish tunnels you can use to connect to the management tools.
3. Use kubectl, k9s, or the Kubernetes dashboard to explore your deployment.

To review your configuration options, including the passwords defined, you can access the pulumi secrets via the following commands:

Main Configuration: pulumi config -C /jenkins/workspace/jaytest/bin/../pulumi/python/config

Bank of Sirius (Example Application) Configuration: pulumi config -C /jenkins/workspace/jaytest/bin/../pulumi/python/kubernetes/applications/sirius

K8 Loadbalancer IP: kubectl get services --namespace nginx-ingress

Please see the documentation in the github repository for more information

1. Créez une correspondance entre le nom de domaine complet (FQDN) et l’adresse IP indiquée à l’étape précédente dans l’outil que vous utilisez pour résoudre les FQDN (tel que le fichier local /etc/hosts ou le serveur DNS).
2. Vérifiez qu’une requête adressée au déploiement MARA aboutit. Incluez l’option -k afin que curl accepte un certificat autosigné. Pour afficher davantage d’informations sur le certificat, ajoutez l’option -v.

$ curl -k -I https://mara.example.comHTTP/1.1 200 OK
Server: nginx/1.21.5
Date: Day, DD Mon YYYY hh:mm:ss TZ
Content-Type: text/html; charset=utf-8
Content-Length: 7016
Connection: keep-alive

1. Dans un navigateur, accédez à https://mara.example.com pour afficher le site web de la Bank of Sirius. À l’heure où nous écrivons ces lignes, de nombreux navigateurs (notamment Firefox et Safari) vous permettent d’ignorer sans risque l’avertissement indiquant que le site utilise un certificat autosigné. Nous vous recommandons de ne pas utiliser Chrome : en raison de récentes modifications de sécurité, il est susceptible de vous empêcher d’accéder au site.
2. Exécutez le script test-forward.sh pour configurer la redirection de ports Kubernetes afin de pouvoir accéder aux outils de la suite de gestion MARA : Elasticsearch, Grafana, Kibana, Locust et Prometheus. Le script détermine les noms de services appropriés et exécute des commandes kubectl pour les rediriger vers des ports locaux. Remarque : pour que la redirection de ports fonctionne correctement, votre navigateur doit s’exécuter sur le même système que l’interpréteur de commandes dans lequel vous exécutez cette commande. Dans le cas contraire (par exemple, si vous utilisez un environnement de virtualisation), la commande semble s’exécuter correctement, mais la redirection de ports ne fonctionne pas réellement. Pour plus d’informations, consultez Accès aux outils de gestion dans MARA dans notre dépôt GitHub.

$ ./bin/test-forward.shConnections Details
====================================
Kibana:        http://localhost:5601
Grafana:       http://localhost:3000
Locust:        http://localhost:8089
Prometheus:    http://localhost:9090
Elasticsearch: http://localhost:9200
====================================

Issue Ctrl-C to Exit

Résumé

Et voilà ! En suivant ces instructions, vous disposerez en une vingtaine de minutes d’un déploiement MARA opérationnel dans votre environnement. Vous pourrez alors interagir avec l’application Bank of Sirius comme avec n’importe quelle autre application Kubernetes. Pour commencer, vous pouvez utiliser les outils d’observabilité intégrés afin de tester le comportement de l’environnement en générant différents niveaux de charge avec Locust.

Notre objectif est de rendre MARA aussi utile que possible au plus grand nombre d’utilisateurs de Kubernetes. Certains de nos choix de composants ne vous conviennent pas ? Nous vous encourageons à les remplacer par les composants de votre choix et à ouvrir une pull request si vous souhaitez partager votre travail. N’hésitez pas non plus à nous faire part de vos réflexions et à poser vos questions – notamment au sujet de toute hypothèse discutable que nous aurions formulée – sur les pages Issues et Discussions de notre dépôt.

Articles connexes

Cet article fait partie d’une série. À mesure que nous enrichissons les fonctionnalités de MARA, nous en publions les détails sur le blog :

• Une nouvelle architecture de référence open source pour les applications modernes
• Intégration d’OpenTelemetry à l’architecture de référence pour les applications modernes – Rapport d’avancement
• MARA : désormais disponible sur un poste de travail près de chez vous (cet article)
• Annonce de la version 1.0.0 de l’architecture de référence NGINX pour les applications modernes

À propos de l’auteur

Jason Schmidt

Autres articles de Jason Schmidt