La console Cloud π Native est une application web ayant pour but de piloter des services web dans un cluster Kubernetes afin de fournir une platefome cloud qui accompagne les produits numériques lors de toutes les phases de leur cycle de vie.
Cette console offre une interface unifiée vers un ensemble de services tout en garantissant une cohérence globale du système avec la création automatique d'un certain nombre de ressources comme par exemple les comptes d'accès, les robots ou encore des ressources Kubernetes. En addition du provisionnement automatique, elle garantit aussi le contrôle d'accès aux ressources du projet à l'aide d'une gestion d'équipe, de permissions, de quotas, etc...
Ce projet est construit avec NodeJS, VueJS, Postgres et Keycloak. Le serveur et le client sont livrés sous forme d'images Docker et sont déployées à l'aide de Helm dans Kubernetes.
Nom du service | Github project | Role | Déployé avec le Helm Chart de production |
---|---|---|---|
client | VueJS / Nginx | Interface graphique de l'application | Oui |
server | NodeJS | API de l'application | Oui |
postgres | Postgres | Base de données de l'application | Oui |
keycloak | Keycloak | Gestionnaire d'authentification / d'accès | - |
pgadmin | Pgadmin | Interface d'administration de Postgres | - |
Le serveur est construit selon une architecture core / plugins pour favoriser l'évolutivité et l'ajout de nouvelles fonctionnalités / la gestion de nouveaux services. Pour ce faire, les plugins s'enregistrent auprès de différents hooks
(qui suivent le cycle de vie d'un projet au sein de l'application), ces derniers seront déclenchés par les contrôleurs de l'application.
Plusieurs plugins sont nativement enregistrés auprès du serveur pour assurer le bon fonctionnement de la plateforme, à savoir :
Pour plus d'informations sur le développement d'un plugin, voir :
Le développement s'effectue à l'aide de Docker (le client et le serveur peuvent tourner en local ou dans Docker) ou encore directement dans un cluster Kubernetes à l'aide de Kind, un outil permettant de créer des noeuds Kubernetes dans des conteneurs Docker.
Liste des outils utilisés par le projet à installer sur son ordinateur :
- Docker - moteur d'exécution de conteneur
- Plugin compose - define and run multi-container applications with Docker
- Plugin buildx - Docker CLI plugin for extended build capabilities with BuildKit
- Kind - kubernetes dans Docker
- Kubectl - interface en ligne de commande pour kubernetes
- Helm - gestionnaire de paquets kubernetes
- Nodejs - environnement d'exécution javascript
- Pnpm - gestionnaire de paquets pour javascript
Pour une meilleure expérience développeur, il est recommandé :
Lancez les commandes suivantes dans votre terminal pour installer le projet :
# Cloner le projet
git clone https://github.com/cloud-pi-native/console.git
# Se rendre dans le dossier du projet
cd console
# Installer les dépendances du projet
pnpm install
# Copier les fichiers d'environnement exemples
./ci/scripts/init-env.sh
# Construire les paquets applicatifs
pnpm build
L'application peut se lancer de plusieurs manières, à savoir :
Local :
# Lancer keycloak, postgres et pgadmin dans des conteneurs
pnpm run dev
# Lancer le serveur
pnpm --filter @cpn-console/server run dev
# Lancer le client
pnpm --filter @cpn-console/client run dev
# Supprimer les conteneurs keycloak, postgres et pgadmin
pnpm run dev:clean
# Supprimer les conteneurs keycloak, postgres et pgadmin (supprime les volumes docker)
pnpm run dev:delete
Docker :
# Lancer l'application
pnpm run docker:dev
# Supprimer les conteneurs
pnpm run docker:dev:clean
# Supprimer les conteneurs (supprime les volumes docker)
pnpm run docker:dev:delete
Pour lancer le debugger nodejs sur le serveur, dans les fichiers
docker-compose
remplacer la directivecommand: ["dev"]
parcommand: ["debug"]
.
Kubernetes :
# Initialiser Kind (ajoute des noms de domaines dans /etc/hosts, le mot de passe sera demandé)
pnpm run kube:init
# Lancer l'application
pnpm run kube:dev
# Supprimer les ressources applicatives sans supprimer le cluster Kind
pnpm run kube:clean
# Supprimer entièrement le cluster et ses ressources
pnpm run kube:delete
L'application peut se lancer de plusieurs manières, à savoir :
Local :
# Lancer keycloak, postgres et pgadmin dans des conteneurs
pnpm run integ
# Lancer le serveur
pnpm --filter @cpn-console/server run integ
# Lancer le client
pnpm --filter @cpn-console/client run integ
# Supprimer les conteneurs keycloak, postgres et pgadmin
pnpm run integ:clean
# Supprimer les conteneurs keycloak, postgres et pgadmin (supprime les volumes docker)
pnpm run integ:delete
Docker :
# Lancer l'application
pnpm run docker:integ
# Supprimer les conteneurs
pnpm run docker:integ:clean
# Supprimer les conteneurs (supprime les volumes docker)
pnpm run docker:integ:delete
Kubernetes :
# Initialiser Kind (ajoute des noms de domaines dans /etc/hosts, le mot de passe sera demandé)
pnpm run kube:init
# Lancer l'application en mode développement
pnpm run kube:integ
# Supprimer les ressources applicatives sans supprimer le cluster Kind
pnpm run kube:clean
# Supprimer entièrement le cluster et ses ressources
pnpm run kube:delete
Les commandes utilitaires de l'application :
# Lancer la vérification syntaxique
pnpm run lint
# Lancer les tests unitaires
pnpm run test
# Lancer les tests de composants
pnpm run test:ct
# Lancer les tests de bout en bout
pnpm run test:e2e
L'intégralité des commandes est disponibles dans le fichier package.json à la racine du projet, vous pouvez lancer ces dernières à l'aide de la commande pnpm run <le_nom_du_script>
.
Les services sont disponibles via des nom de domaines ajouté dans le fichier /etc/hosts
de votre système, l'ajout des domaines se fait automatiquement lors de la commande pnpm run kube:init
.
Service | Url (kubernetes) | Url (local/docker) |
---|---|---|
Interface graphique - (client) | http://console.dso.local | http://localhost:8080 |
Serveur - (api) | http://console.dso.local/api | http://localhost:4000 |
Interface d'administration de base de données | http://pgadmin.dso.local | http://localhost:8081 |
Interface d'administration du serveur keycloak | http://keycloak.dso.local | http://localhost:8090 |
Notes:
Les comptes utilisés pendant le développement sont les suivants :
Service | Nom d'utilisateur | Mot de passe |
---|---|---|
Keycloak (admin) | admin |
admin |
Keycloak (user) | test |
test |
PgAdmin | admin@dso.fr |
admin |
Postgres | admin@dso.fr |
admin |
La liste complète des comptes Keycloak pré-créés est disponible ici.
Le nom de la base de données est :
dso-console-db
.
Local / Docker:
Les variables d'environnements sont gérées localement via des fichiers .env
(local) / .env.docker
(docker) dans les dossiers ./apps/server
et ./apps/client
, aux précédents fichiers s'ajoute un fichier .env.integ
utilisé pour le mode intégration (local et docker).
Kubernetes :
Un chart Helm utilitaire est installé pour déployer les services qui ne sont pas inclus dans le chart de la console :
- Pgadmin
Ces services sont personnalisables ici.
Différents fichiers de values.yml
sont disponibles pour personnaliser le déploiement de l'application dans le cluster Kind:
- Le fichier ./ci/kind/env/dso-values.yaml contient les variables de base l'application.
- Le fichier ./ci/kind/env/dso-values-dev.yaml contient les variables de l'application pour le mode développement.
- Le fichier ./ci/kind/env/dso-values-int-example.yaml contient les variables de l'application pour le mode intégration.
Notes:
- Les values du chart de la console sont disponibles ici.
Pour faciliter les opérations de migrations de base de données via Prisma, un script est disponible :
# Lancer le script
pnpm --filter @cpn-console/server run db:wrapper
# Voir l'aide du script
pnpm --filter @cpn-console/server run db:wrapper -h
Ce dépôt utilise des fichiers docker-compose pour construire les images docker:
- docker-compose.dev.yml pour la construction des images docker du mode développement.
- docker-compose.prod.yml pour la construction des images docker du mode production.
Pour pouvoir gérer les droits utilisateurs des services le pod server
doit accéder aux groupes des users. Cela signifie modifier le clientScope profile
:
- Onglet
Mappers
Add Mappers > By configuration > Group Membership
- Name:
groups
- Token Claim Name:
groups
- Full group path:
off
- Add to ID token:
on
- Add to access token:
on
- Add to userinfo:
off
- Name:
En environnement de dev l'import par défaut prévoit déjà cette modification.
Les utilisateurs faisant parti du group admin
ont également accès à l'interface administrateur de la console une fois connectés via un onglet supplémentaire Administration
dans le menu latéral de l'application.
Console Cloud Pi | Projet | Environnement | Dépots | Utilisateur / membre |
---|---|---|---|---|
Openshift | Namespace | |||
ArgoCD | (infra) Secret, AppProject, Application | |||
Gitlab | Group | Repository (Dépôt) | User | |
Harbor | Project | Repository [1] | ||
Keycloak | Group | User / member | ||
Sonar | User | |||
Nexus | Repositories, role, user ... |
[1] N'est pas crée par la console mais par le produit de la CI
La gestion des dépendances est effectuée à l'aide de pnpm selon la structure de dossiers suivante :
- Les différentes briques applicatives se trouvent dans le dossier
apps/
. - Les bibliothèques additionnelles se trouvent dans le dossier
packages/
. - Les plugins core se trouvent dans le dossier
plugins/
.
Schema de l'architecture du monorepo :
./
├── apps
│ ├── client
│ └── server
├── packages
│ ├── eslintconfig
│ ├── hooks
│ ├── shared
│ ├── test-utils
│ └── tsconfig
├── plugins
│ ├── argocd
│ ├── gitlab
│ ├── harbor
│ ├── keycloak
│ ├── kubernetes
│ ├── nexus
│ ├── sonarqube
│ └── vault
├── package.json
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
├── turbo.json
└── README.md
Le dépôt utilise Release Please pour automatiquement générer les tags Git ainsi que les releases GitHub. À chaque fois que du code est poussé dans la branche main
, une pull request est créée en analysant les messages de commits pour déterminer le numéro de version à créer.
À chaque fois qu'une pull request de release est fusionnée, les images de conteneur du serveur et du client sont créées et hébergées dans la registry Github associée au dépôt.
Pour publier les versions des modules npm du dépôt un pipeline est disponible dans les GitHub Actions, il analysera les numéros de version présents dans les différents fichiers package.json
pour déterminer si une nouvelle version du module doit être créée et publiée.
Il est possible de créer une version de pré-release d'un module npm en modifiant la clé
publishConfig.tag
dans lepackage.json
avec par exemplebeta
pour générer une version beta.
La console embarque une dépendance avec le Helm Chart utilisé par ArgoCD pour consommer le fichier values qu'elle construit. Afin d'assurer la compatibilité, il faut toujours que la version du Helm chart associé ait été publiée au préalable (voir la documentation dédiée).
Cf. Conventions - MIOM Fabrique Numérique.
Les commits restent néanmoins rédigés en anglais.
Les commits doivent suivre la spécification des Commits Conventionnels, il est possible d'ajouter l'extension VSCode pour faciliter la création des commits.
Une PR doit être faite avec une branche à jour avec la branche develop
en rebase (et sans merge) avant demande de fusion, et la fusion doit être demandée dans develop
.