Un Talos européen de qualité - Part XI - CI/CD et OpenTelemetry

Objectif 🎯

Dans cette dernière partie de la série, nous allons mettre en place un système d’intégration continue (CI) pour automatiser les tests et la validation de notre code avant son déploiement en mode continue (CD). Enfin, nous ferons un rapide aperçu de l’intégration de OpenTelemetry dans l’application au sein de notre infrastructure.

Continuous Integration

Le but suivant sera de générer notre application en image OCI correctement taguée sur le container registry de Gitea, directement via Gitea Action inclus par défaut.

Act Runner

Le 1er élément indispensable est la mise en place d’un runner. Le principe est de créer un VPS Hetzner ou autre indépendant du cluster kube qui se connectera à votre instance Gitea. Un VPS avec haute capacité de disque et haute performance CPU est conseillé. Assurez-vous d’avoir docker préinstallé via curl -fsSL https://get.docker.com | sh (n’utilisez pas cette commande en production !).

Puis créez les fichiers de config suivants :

1
cache:
2
  host: 172.17.0.1
3
  port: 8088
4
log:
5
  level: info
6
runner:
7
  capacity: 3

1
services:
2
  act:
3
    environment:
4
      CONFIG_FILE: /etc/act/config.yaml
5
      GITEA_INSTANCE_URL: https://gitea.ohmytalos.io
6
      GITEA_RUNNER_REGISTRATION_TOKEN: <token>
7
    image: gitea/act_runner:nightly
8
    ports:
9
    - 8088:8088
10
    restart: always
11
    volumes:
12
    - /var/run/docker.sock:/var/run/docker.sock
13
    - /etc/act/config.yaml:/etc/act/config.yaml
14
    - act_data:/data
15
    - act_cache:/root/.cache
16

17
volumes:
18
    act_data:
19
    act_cache:

Un petit docker compose up -d et le runner devrait apparaître comme disponible sur votre interface Gitea dans l’administration des runners.

Gitea Action

Depuis le projet ohmytalos/conduit, créons un workflow de base juste pour le build, lancement des tests et publication.

1
on:
2
  push:
3
    branches:
4
      - main
5

6
jobs:
7
  build:
8
    runs-on: ubuntu-latest
9
    steps:
10
      - uses: actions/checkout@v6
11
      - uses: actions/setup-dotnet@v5
12
        with:
13
          dotnet-version: 10.x
14
          cache: true
15
          cache-dependency-path: "**/packages.lock.json"
16
      - name: install
17
        run: |
18
          dotnet tool restore
19
          dotnet restore
20
      - name: lint
21
        run: |
22
          dotnet format --verify-no-changes
23
      - name: build
24
        run: |
25
          dotnet build -c Release --no-restore
26
      - name: test
27
        run: |
28
          dotnet coverlet Conduit.Tests/bin/Release/net10.0/Conduit.Tests.dll --target "dotnet" --targetargs "test -c Release --no-restore --no-build" -f=opencover -o="coverage.xml"
29
      - name: publish
30
        run: |
31
          dotnet publish -c Release -o ./publish --no-restore --no-build

Les testcontainers utilisés pour les tests d’intégration devraient se lancer automatiquement sans problème, ce qui nous évite de les déclarer manuellement dans le workflow via jobs.build.services, que du bon en somme.

Vous pouvez apercevoir le résultat de la couverture en sortie des tests :

Les prochaines relances devraient aussi tenir compte du cache NuGet pour accélérer le processus à l’étape install.

Image OCI

Nous ne faisons ici que publier l’artifact sans rien derrière, il est temps de construire notre image OCI et de la pousser sur le registry Gitea.

Préparons quelques variables et secrets sur Gitea sur l’interface des variables globales :

CONTAINER_REGISTRY=gitea.ohmytalos.io
CONTAINER_REGISTRY_USERNAME=ohmytalos

Aller ensuite au niveau des secrets de l’organisation puis créer le secret suivant :

CONTAINER_REGISTRY_PASSWORD=<personal access token under ohmytalos with write:packages scope>

Rajouter les actions spécifiques au build et push de l’image OCI dans le workflow build.yaml :

1
      # ...
2

3
      - uses: docker/metadata-action@v5
4
        id: meta
5
        with:
6
          images: ${{ vars.CONTAINER_REGISTRY }}/${{ gitea.repository }}
7
          tags: |
8
            type=raw,value=latest,enable={{is_default_branch}}
9
            type=ref,event=branch
10
      - uses: docker/login-action@v3
11
        with:
12
          registry: ${{ vars.CONTAINER_REGISTRY }}
13
          username: ${{ vars.CONTAINER_REGISTRY_USERNAME }}
14
          password: ${{ secrets.CONTAINER_REGISTRY_PASSWORD }}
15
      - uses: docker/build-push-action@v6
16
        with:
17
          context: .
18
          push: true
19
          tags: ${{ steps.meta.outputs.tags }}
20
          labels: ${{ steps.meta.outputs.labels }}

Le fichier Dockerfile de production à la racine du repo pour embarquer l’application .NET publiée précédemment situé dans le répertoire ./publish :

1
FROM mcr.microsoft.com/dotnet/aspnet:10.0
2
USER app
3

4
COPY --chown=app:app /publish /app
5
WORKDIR /app
6

7
ENV ASPNETCORE_URLS=http://+:8080
8

9
EXPOSE 8080
10
ENTRYPOINT ["dotnet", "Conduit.WebApi.dll"]

Commiter et pousser les modifications, le workflow devrait se déclencher et aboutir à la création de l’image OCI dans le registry Gitea, sous les tags latest et main.

L’image OCI étant générée, ajoutez-la directement dans le repo en tant que package via l’onglet Packages du repo.

Versionning

Nous sommes en capacité de builder et pousser automatiquement notre application en package OCI, prêt à l’emploi pour le déploiement en production, mais il nous manque encore un élément important : le versionning sémantique. L’image est systématiquement taguée main, ce qui rendrait tout déploiement via flux compliqué sans suivi de version.

Pour faire propre et efficient, une release Gitea devrait être automatiquement créée à chaque commit dans main, avec incrémentation patch automatique en restant dans la logique semver. Nous allons utiliser GitVersion pour cela, qui s’appuiera sur les tags Git existants.

L’idée est donc de créer un token personnel avec accès en écriture aux repos sous l’organisation ohmytalos, puis de l’utiliser dans le workflow Gitea Action pour créer la release automatiquement en la liant à un tag git suivant la convention semver.

Retourner sur la gestion des secrets de l’organisation, puis créer un token avec accès en écriture au repo cible.

RELEASE_TOKEN=<personal access token under ohmytalos with write:repository scope>

On s’attelle maintenant à l’installation de GitVersion :

dotnet tool install GitVersion.Tool

1
mode: ContinuousDeployment
2
next-version: 1.0.0
3
branches:
4
  main:
5
    increment: Patch

Tester localement avec dotnet gitversion /output json, la version FullSemVer devrait démarrer à 1.0.0. Plus qu’à adapter notre workflow :

1
    # ...
2

3
    steps:
4
      - uses: actions/checkout@v5
5
        with:
6
          fetch-depth: 0
7
      # ...
8
      - name: install
9
        run: |
10
          dotnet tool restore
11
          dotnet restore
12
      - name: version
13
        id: gitversion
14
        run: |
15
          echo "version=$(dotnet gitversion /output | jq -r .FullSemVer)" >> $GITHUB_OUTPUT
16

17
      # ...
18

19
      - uses: docker/metadata-action@v5
20
        id: meta
21
        with:
22
          images: ${{ vars.CONTAINER_REGISTRY }}/${{ gitea.repository }}
23
          tags: |
24
            type=raw,value=latest,enable={{is_default_branch}}
25
            type=ref,event=branch
26
            type=raw,value=v${{ steps.gitversion.outputs.version }}
27

28
      # ...
29

30
      - uses: akkuman/gitea-release-action@v1
31
        with:
32
          token: ${{ secrets.RELEASE_TOKEN }}
33
          name: Release v${{ steps.gitversion.outputs.version }}
34
          tag_name: v${{ steps.gitversion.outputs.version }}

Poussez les modifications, le workflow devrait se déclencher et aboutir à la création d’une release Gitea avec le tag v1.0.0, ainsi qu’une image OCI taguée v1.0.0 dans le registry. Chaque nouveau commit dans main générera une nouvelle release avec incrémentation automatique du patch (v1.0.1, v1.0.2, etc.). On est nickel.

SonarQube

Allons encore un peu plus loin sur l’analyse statique de code avec SonarQube.

Indiquer dans les variables globales de l’administration Gitea l’URL de l’instance SonarQube :

SONAR_HOST_URL=https://sonarqube.ohmytalos.io

Ensuite aller sur l’interface SonarQube normalement hébergée sur https://sonarqube.ohmytalos.io/ puis créer un nouveau projet ohmytalos/conduit. Ajouter dans les variables propres au repo Gitea l’ID du projet SonarQube :

SONAR_PROJECT_ID=ohmytalos-conduit

Enfin générer un token d’analyse projet dans l’onglet security, puis revenez sur Gitea et rajouter le token dans les secrets spécifiques au repo :

SONAR_TOKEN=sqp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ceci étant fait il ne nous reste plus qu’à rajouter quelques étapes dans le workflow Gitea Action pour analyser le code source avec l’outil SonarScanner for .NET déjà installé au début.

1
    # ...
2

3
    steps:
4
      # ...
5

6
      - uses: actions/setup-dotnet@v5
7
        with:
8
          dotnet-version: 10.x
9
          cache: true
10
          cache-dependency-path: "**/packages.lock.json"
11
      - uses: actions/setup-java@v5
12
        with:
13
          distribution: temurin
14
          java-version: 21
15
      - name: Cache SonarQube packages
16
        uses: actions/cache@v5
17
        with:
18
          path: ~/.sonar/cache
19
          key: ${{ runner.os }}-sonar
20

21
      # ...
22

23
      - name: build
24
        run: |
25
          dotnet sonarscanner begin /k:"${{ vars.SONAR_PROJECT_ID }}" /d:sonar.host.url="${{ vars.SONAR_HOST_URL }}" /d:sonar.token="${{ secrets.SONAR_TOKEN }}" /d:sonar.cs.opencover.reportsPaths=coverage.xml
26
          dotnet build -c Release --no-restore
27
      - name: test
28
        run: |
29
          dotnet coverlet Conduit.Tests/bin/Release/net10.0/Conduit.Tests.dll --target "dotnet" --targetargs "test -c Release --no-restore --no-build" -f=opencover -o="coverage.xml"
30
          dotnet sonarscanner end /d:sonar.token="${{ secrets.SONAR_TOKEN }}"

Aller sur l’interface SonarQube après le push des modifications, l’analyse devrait apparaître dans le projet avec les métriques de niveau de qualité/sécurité global du code, couverture de test incluse.

Continuous Deployment

Nous en avons fini avec la CI, passons au CD avec FluxCD pour déployer automatiquement notre application sur le cluster Talos à chaque nouvelle release. Le schéma complet du flux CI/CD sera le suivant :

Nous sommes donc sur un modèle pull, où FluxCD surveille les releases Gitea et déploie automatiquement la nouvelle version de l’application sur le cluster Talos. A aucun moment la CI n’a connaissance de l’environnement de run, et se limite à la génération d’artifacts (images OCI) versionnés.

Kubernetes manifests

Commencer par créer une base de données conduit PostgreSQL dédiée à l’app à déployer, directement sur pgAdmin, avec un utilisateur de même nom conduit et un mot de passe solide. Créer ensuite un secret Kubernetes pour stocker le mot de passe de connexion.

1
apiVersion: v1
2
kind: Secret
3
metadata:
4
  name: conduit-database
5
  namespace: ohmytalos
6
type: Opaque
7
data:
8
  postgres-password: <votre-mot-de-passe-postgres | base64>

Chiffrez immédiatement ce fichier via la commande sops -e -i clusters/dev/ohmytalos/secret-conduit-database.yaml.

Préparer ensuite le déploiement Kubernetes en 2 replicas de l’application Conduit, toujours constitué au minimum d’un deployment, un service, et un ingress :

1
apiVersion: v1
2
kind: Namespace
3
metadata:
4
  name: ohmytalos
5
  labels:
6
    pod-security.kubernetes.io/enforce: privileged
7
---
8
apiVersion: apps/v1
9
kind: Deployment
10
metadata:
11
  name: conduit
12
  namespace: ohmytalos
13
spec:
14
  replicas: 2
15
  selector:
16
    matchLabels:
17
      app: conduit
18
  template:
19
    metadata:
20
      labels:
21
        app: conduit
22
    spec:
23
      containers:
24
        - name: conduit
25
          image: gitea.ohmytalos.io/ohmytalos/conduit:main
26
          env:
27
            - name: DB_PASSWORD
28
              valueFrom:
29
                secretKeyRef:
30
                  name: conduit-database
31
                  key: postgres-password
32
            - name: ConnectionStrings__DefaultConnection
33
              value: Host=ohmytalos-dev-rw.postgres;Username=conduit;Password='$(DB_PASSWORD)';Database=conduit;
34
      affinity:
35
        podAntiAffinity:
36
          requiredDuringSchedulingIgnoredDuringExecution:
37
            - topologyKey: kubernetes.io/hostname
38
              labelSelector:
39
                matchLabels:
40
                  app: conduit
41
---
42
apiVersion: v1
43
kind: Service
44
metadata:
45
  name: conduit
46
  namespace: ohmytalos
47
  labels:
48
    app: conduit
49
spec:
50
  selector:
51
    app: conduit
52
  ports:
53
    - name: http
54
      port: 8080
55
---
56
apiVersion: traefik.io/v1alpha1
57
kind: IngressRoute
58
metadata:
59
  name: conduit
60
  namespace: ohmytalos
61
spec:
62
  routes:
63
    - match: Host(`conduit.ohmytalos.io`)
64
      kind: Rule
65
      services:
66
        - name: conduit
67
          port: http

Puis le fichier Kustomization pour regrouper le tout :

1
apiVersion: kustomize.config.k8s.io/v1beta1
2
kind: Kustomization
3
resources:
4
  - deployment-conduit.yaml
5
  - secret-conduit-database.yaml

On commit tout ça et checker le status du déploiement via kgp -n ohmytalos. Si tout est bon go sur https://conduit.ohmytalos.io/scalar/ et admirer. Tester l’endpoint /article, vous devriez avoir une erreur 500. Utiliser kl -n ohmytalos deploy/conduit -c conduit pour voir les logs, qui devrait indiquer relation "Articles" does not exist. La base de données n’a effectivement pas été migrée. Nous traiterons ce cas plus tard.

Images manifests

Bien, l’application est déployée, mais sans aucun système de déploiement continue. Il est temps de s’appuyer sur les composants ImageReflector et ImageAutomation de FluxCD pour automatiser tout ça.

Pour fonctionner ces 2 composants utilisent 3 CRDs essentiels :

• ImageRepository : Indique à image reflector quel repository OCI à surveiller et d’y injecter tous les tags trouvés.
• ImagePolicy : Indique à image reflector quelle politique de versionning à appliqué pour obtenir le dernier tag à utiliser. Le dernier tag retenu y est stocké.
• ImageUpdateAutomation : Indique à image automation comment mettre à jour le repo git source selon le dernier tag récupéré par l’ensemble des ImagePolicy défini pour chaque image.

Nous allons commencer par créer les manifests Kubernetes nécessaires au déploiement automatisé de l’application Conduit.

1
apiVersion: image.toolkit.fluxcd.io/v1
2
kind: ImageRepository
3
metadata:
4
  name: image-conduit
5
  namespace: flux-system
6
spec:
7
  image: gitea.ohmytalos.io/ohmytalos/conduit
8
  interval: 1m0s
9
---
10
apiVersion: image.toolkit.fluxcd.io/v1
11
kind: ImagePolicy
12
metadata:
13
  name: image-conduit
14
  namespace: flux-system
15
spec:
16
  imageRepositoryRef:
17
    name: image-conduit
18
    namespace: flux-system
19
  policy:
20
    semver:
21
      range: ">=1.0.0"

1
apiVersion: kustomize.config.k8s.io/v1beta1
2
kind: Kustomization
3
resources:
4
  # ...
5
  - images.yaml

Quelques commandes utiles :

• k describe -n flux-system imgrepo image-conduit pour voir les tags récupérés.
• k describe -n flux-system imgpol image-conduit pour vous voir le dernier tag actif selon la politique définie.

Définir ensuite le CRD ImageUpdateAutomation pour automatiser la mise à jour du repo git source, avec un template de commit + author. Peut être défini une seule fois par repo git source.

1
apiVersion: image.toolkit.fluxcd.io/v1
2
kind: ImageUpdateAutomation
3
metadata:
4
  name: flux-system
5
  namespace: flux-system
6
spec:
7
  interval: 1m0s
8
  sourceRef:
9
    kind: GitRepository
10
    name: flux-system
11
  git:
12
    checkout:
13
      ref:
14
        branch: main
15
    commit:
16
      author:
17
        email: fluxcdbot@users.noreply.github.com
18
        name: fluxcdbot
19
      messageTemplate: |-
20
        Automated image update
21

22
        Changes:
23
        {{ range .Changed.Changes -}}
24
        - {{ .OldValue }} -> {{ .NewValue }}
25
        {{ end -}}
26

27
        Files:
28
        {{ range $filename, $_ := .Changed.FileChanges -}}
29
        - {{ $filename }}
30
        {{ end -}}
31
    push:
32
      branch: main
33
  update:
34
    strategy: Setters

Enfin, il ne reste plus qu’à appliquer l’ImagePolicy définie précédemment juste au niveau de l’image de déploiement. C’est qui indiquera à ImageAutomation l’emplacement exact de l’image à mettre à jour dans le manifest selon la policy cible.

1
# ...
2
spec:
3
  # ...
4
  template:
5
    # ...
6
    spec:
7
      containers:
8
        - name: conduit
9
          image: gitea.ohmytalos.io/ohmytalos/conduit:main # {"$imagepolicy": "flux-system:image-conduit"}

Une fois commité, utiliser k describe -n flux-system iua flux-system pour vérifier que cette ImagePolicy a bien été pris en compte dans la section Observed Policies :

1
Status:
2
  Observed Policies:
3
    Image - Conduit:
4
      Name:  gitea.ohmytalos.io/ohmytalos/conduit
5
      Tag:   vX.Y.Z

À cet instant précis, ImageAutomation va récupérer le dernier tag dans la policy puis mettre à jour le manifest deployment-conduit.yaml dans le repo git source en conséquence, en remplaçant :main par :vX.Y.Z. Un commit sera automatiquement créé et poussé sur la branche main.

Et voilà, le déploiement continu est en place. À chaque nouvelle release Gitea, FluxCD détectera le nouveau tag, mettra à jour le manifest dans le repo git source, puis KustomizeController appliquera automatiquement la nouvelle version de l’application sur le cluster Talos, en Zero Downtime. Il nous reste plus qu’un dernier détail à régler : les migrations de la base de données.

Migrations DB

Comme vu précédemment, l’application nécessite une base de données PostgreSQL avec les bonnes migrations appliquées pour fonctionner. Il n’est évidemment pas envisageable de migrer la base de données au démarrage de l’application, du fait du risque de concurrence entre les replicas. Même si EF Core gère bien ce cas en verrouillant la table de migration, il est préférable de séparer les responsabilités.

EF Core nous simplifie bien la vie en supportant la génération d’un bundle de migration exécutable en ligne de commande, parfait pour notre cas d’usage. Nous allons donc modifier le workflow Gitea Action pour générer ce bundle via la commande dotnet ef migrations bundle au moment de la publication de l’application.

1
# ...
2

3
jobs:
4
  build:
5
    runs-on: ubuntu-latest
6
    steps:
7
      # ...
8
      - name: publish
9
        run: |
10
          dotnet publish -c Release -o ./publish --no-restore --no-build
11
          dotnet ef migrations bundle --project Conduit.Business --startup-project Conduit.WebApi

Ne reste plus qu’à inclure cet exécutable dans notre image OCI de production.

1
# ...
2

3
COPY --chown=app:app /efbundle /app/efbundle
4
WORKDIR /app
5

6
# ...

Committer cette modification, le workflow Gitea Action se chargera de reconstruire et pousser la nouvelle image OCI avec le bundle de migration inclus. La partie CD se chargera ensuite du déploiement automatique.

Une fois l’app déployée, il est possible de lancer cet exécutable directement via la commande keti -n ohmytalos deploy/conduit -c conduit -- ./efbundle.

Dans le cadre où nous souhaiterions l’automatiser au démarrage de chaque nouveau déploiement, la mise en place d’un Job Kubernetes reste l’approche recommandée. Ce job s’exécutera une seule fois à chaque mise à jour de l’application.

1
apiVersion: batch/v1
2
kind: Job
3
metadata:
4
  name: conduit
5
  namespace: ohmytalos
6
spec:
7
  backoffLimit: 0
8
  ttlSecondsAfterFinished: 60
9
  template:
10
    spec:
11
      restartPolicy: Never
12
      containers:
13
        - name: conduit
14
          image: gitea.ohmytalos.io/ohmytalos/conduit:main # {"$imagepolicy": "flux-system:image-conduit"}
15
          env:
16
            - name: DB_PASSWORD
17
              valueFrom:
18
                secretKeyRef:
19
                  name: conduit-database
20
                  key: postgres-password
21
            - name: ConnectionStrings__DefaultConnection
22
              value: Host=ohmytalos-dev-rw.postgres;Username=conduit;Password='$(DB_PASSWORD)';Database=conduit;
23
          command:
24
            - /app/efbundle

Ajouter le job :

1
apiVersion: kustomize.config.k8s.io/v1beta1
2
kind: Kustomization
3
resources:
4
  # ...
5
  - job-conduit-migrate.yaml

Puis commiter. À chaque nouvelle mise à jour de l’application, FluxCD déploiera le job de migration qui s’exécutera une seule fois avant de se supprimer automatiquement. Tester un rajout de propriété dans une entité EF Core, générer une nouvelle release Gitea, et observer le bon déroulement du processus de migration automatique.

Pour seeder les données initiales, vous pouvez utiliser keti -n ohmytalos deploy/conduit -c conduit -- ./Conduit.Console.

Run

La CI/CD c’est bien, mais le boulot continue une fois l’application en production. L’observabilité est le dernier aspect crucial à appliquer.

Probes

La première chose à faire est de configurer les probes Kubernetes pour s’assurer que l’application est bien vivante et prête à recevoir du trafic. C’est cet élément qui permettra à Kubernetes de redémarrer un pod en cas de problème, et d’éviter tout trafic vers un pod non prêt, permettant ainsi un déploiement en zero-downtime.

Le plus courant est de mettre à dispo un endpoint healthz dans l’application, qui retournera un code 200 si tout va bien. Nous allons juste installer 2 packages simples pour cela.

dotnet add Conduit.WebApi package Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore

Rajouter les health checks dans le programme principal de l’application.

1
// ...
2

3
builder.Services
4
    // ...
5
    .AddHealthChecks()
6
    .AddDbContextCheck<AppDbContext>();
7

8
// ...
9

10
app.MapHealthChecks("/healthz");
11

12
await app.RunAsync();
13

14
// ...

Plus qu’à rajouter les probes dans le manifest de déploiement.

1
# ...
2
spec:
3
  # ...
4
  template:
5
    # ...
6
    spec:
7
      containers:
8
        - name: conduit
9
          # ...
10
          livenessProbe:
11
            httpGet:
12
              path: /healthz
13
              port: 8080
14
            initialDelaySeconds: 10
15
            periodSeconds: 10
16
          readinessProbe:
17
            httpGet:
18
              path: /healthz
19
              port: 8080
20
            initialDelaySeconds: 10
21
            periodSeconds: 10
22
# ...
23
---
24
apiVersion: traefik.io/v1alpha1
25
# ...
26
spec:
27
  routes:
28
    - match: Host(`conduit.ohmytalos.io`) && !PathRegexp(`^/(healthz|metrics)`)
29
      # ...

Le Zero Downtime est maintenant réellement effectif. Vous pouvez rajouter autant de HealthChecks personnalisé que nécessaire dans l’application pour vérifier l’état de santé des dépendances critiques.

Métriques

Depuis la dernière version .NET 8, ASP.NET fourni des métriques exploitables par Prometheus. De nos jours, il y a 2 façons de faire au choix :

• La méthode classique, en mode pull, qui consiste à exposer un endpoint /metrics compatible Prometheus, scrappable via un CRD ServiceMonitor.
• La méthode télémétrique, beaucoup plus récente, en mode push, qui utilise l’exporter OTLP pour envoyer les métriques vers un collecteur OpenTelemetry, qui se chargera de les exporter vers Prometheus.

À vous de choisir votre préférence. Je présente ici les 2. L’avantage principal de la méthode OTLP est de centraliser toutes les télémétries (métriques, logs, traces) via un collecteur unique sans besoin de configuration supplémentaire avec un ServiceMonitor. C’est l’approche recommandée par OpenTelemetry.

Méthode pull (scraping)

dotnet add Conduit.WebApi package OpenTelemetry.Exporter.Prometheus.AspNetCore --prerelease
dotnet add Conduit.WebApi package OpenTelemetry.Extensions.Hosting
dotnet add Conduit.WebApi package OpenTelemetry.Instrumentation.AspNetCore

1
// ...
2

3
builder.Services
4
    .AddOpenTelemetry()
5
    .WithMetrics(m => m
6
        .AddAspNetCoreInstrumentation()
7
        .AddPrometheusExporter()
8
    );
9

10
var app = builder.Build();
11

12
// ...
13

14
app.MapHealthChecks("/healthz");
15
app.MapPrometheusScrapingEndpoint();
16

17
// ...

Aller sur /metrics pour confirmer puis committer pour déploiement. La dernière étape est de rajouter le CRD ServiceMonitor à notre déploiement pour que prometheus puisse aller scrapper les métriques.

1
# ...
2
---
3
apiVersion: monitoring.coreos.com/v1
4
kind: ServiceMonitor
5
metadata:
6
  name: conduit
7
  namespace: ohmytalos
8
spec:
9
  endpoints:
10
    - port: http
11
  selector:
12
    matchLabels:
13
      app: conduit

Retourner sur les targets Prometheus pour vérifier que le scraping est bien effectif.

Méthode push (OTLP)

Au lieu d’utiliser l’exporter Prometheus, on utilise l’exporter OTLP OpenTelemetryProtocol pour envoyer les métriques vers le collecteur OpenTelemetry Alloy installé précédemment.

dotnet add Conduit.WebApi package OpenTelemetry.Exporter.OpenTelemetryProtocol
dotnet add Conduit.WebApi package OpenTelemetry.Extensions.Hosting
dotnet add Conduit.WebApi package OpenTelemetry.Instrumentation.AspNetCore

1
// ...
2

3
builder.Services
4
    .AddOpenTelemetry()
5
    .UseOtlpExporter()
6
    .ConfigureResource(r => r.AddService(builder.Environment.ApplicationName))
7
    .WithMetrics(m => m
8
        .AddAspNetCoreInstrumentation()
9
    );
10

11
var app = builder.Build();
12

13
// ...

Si besoin utiliser AddConsoleExporter pour tester le fonctionnement puis committer pour déploiement. Enfin, s’agissant d’une méthode push, il faut configurer le service où renvoyer les requêtes OTLP. OpenTelemetry permet de configurer cela via des variables d’environnement, de manière séparée pour chaque niveau de télémétrie (métriques, logs, traces), ou de manière unifiée.

1
# ...
2
spec:
3
  # ...
4
  template:
5
    # ...
6
    spec:
7
      containers:
8
        - # ...
9
          env:
10
            # ...
11
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
12
              value: http://alloy.telemetry:4317
13
            - name: OTEL_EXPORTER_OTLP_PROTOCOL
14
              value: grpc
15
# ...

Si toute la partie collecteur et backend prometheus est bien configurée (ce qui est normalement le cas en suivant scrupuleusement ce guide), il n’y a rien de plus à faire. Vérifier sur prometheus que des métriques remontent bien pour le service Conduit.WebApi.

Bien plus simple que la méthode pull pour le coup, en plus de s’intégrer déjà aux logs et traces que l’on attaquera ensuite.

Dashboard

La team .NET fourni un dashboard Grafana pour visualiser tout ça. Plus qu’à aller sur Grafana puis importer un nouveau dashboard en utilisant l’ID 19924 et admirer.

Le menu Drilldown Metrics permet également de visualiser par mal de métriques intéressantes.

Logs 💝 Traces

Nous allons enfin continuer d’exploiter OpenTelemetry pour centraliser les logs et traces de l’application, toujours en passant par le collecteur Alloy installé précédemment avec ses backends Loki et Tempo. Assurer-vous dans un premier temps d’avoir rajouté les variables d’environnement OTLP nécessaires (cf. ci-dessus) au niveau du déploiement.

On rajoute quelques packages OpenTelemetry supplémentaires dans l’application, dont notamment les télémétries spécifiques aux bases de données. Si pas déjà fait au niveau des métriques, n’oubliez pas de rajouter le package OpenTelemetry.Exporter.OpenTelemetryProtocol.

dotnet add Conduit.WebApi package OpenTelemetry.Instrumentation.EntityFrameworkCore --prerelease
dotnet add Conduit.WebApi package Npgsql.OpenTelemetry

Plus qu’à les activer dans le programme principal de l’application.

1
// ...
2

3
builder.Services
4
    .AddOpenTelemetry()
5
    .UseOtlpExporter()
6
    .ConfigureResource(r => r.AddService(builder.Environment.ApplicationName))
7
    .WithMetrics(m => m
8
        .AddAspNetCoreInstrumentation()
9
        .SetExemplarFilter(ExemplarFilterType.TraceBased)
10
    )
11
    .WithLogging()
12
    .WithTracing(t => t
13
        .AddAspNetCoreInstrumentation()
14
        .AddEntityFrameworkCoreInstrumentation()
15
        .AddNpgsql()
16
    );
17

18
// ...

Enrichissons l’API par quelques logs.

1
namespace Conduit.WebApi.Extensions;
2

3
internal static partial class LoggerExtensions
4
{
5
    [LoggerMessage(LogLevel.Information, "Fetching items with offset {offset} and limit {limit}.")]
6
    public static partial void FetchPaginated(this ILogger logger, int offset, int limit);
7

8
    [LoggerMessage(LogLevel.Information, "Fetched {count} items out of {total} total.")]
9
    public static partial void FetchedPaginated(this ILogger logger, int count, int total);
10

11
    [LoggerMessage(LogLevel.Information, "Fetching item identified by {slug}.")]
12
    public static partial void FetchSlug(this ILogger logger, string slug);
13

14
    [LoggerMessage(LogLevel.Information, "Item fetched with id {id}.")]
15
    public static partial void FetchedSlug(this ILogger logger, int id);
16

17
    [LoggerMessage(LogLevel.Information, "Creating new item.")]
18
    public static partial void CreateItem(this ILogger logger);
19

20
    [LoggerMessage(LogLevel.Information, "New item {id} created.")]
21
    public static partial void CreatedItem(this ILogger logger, int id);
22
}

1
// ...
2

3
public static class ArticlesEndpoints
4
{
5
    public static void MapArticlesEndpoints(this WebApplication app)
6
    {
7
        app.MapGet("/articles", async (AppDbContext dbContext, int offset = 0, int limit = 20) =>
8
        {
9
            app.Logger.FetchPaginated(offset, limit);
10

11
            // ...
12

13
            app.Logger.FetchedPaginated(articles.Count, total);
14

15
            // ...
16
        })
17
        // ...
18

19
        app.MapGet("/articles/{slug}", async (AppDbContext dbContext, string slug) =>
20
        {
21
            app.Logger.FetchSlug(slug);
22

23
            // ...
24

25
            app.Logger.FetchedSlug(article.Id);
26

27
            // ...
28
        })
29
        // ...
30

31

32
        app.MapPost("/articles", async (AppDbContext dbContext, NewArticleDto articleDto, IValidator<NewArticleDto> validator) =>
33
        {
34
            app.Logger.CreateItem();
35

36
            // ...
37

38
            app.Logger.CreatedItem(article.Id);
39

40
            // ...
41
        })
42
        // ...
43
    }
44
}

Et voilà pousser tout ça. Une fois déployé fait de multiples requêtes sur l’API pour générer des logs et traces, puis aller sur Grafana voir si les logs remontent bien pour sur le service Conduit.WebApi, qui est le nom du service définir avec builder.Environment.ApplicationName. Ils devraient être correctement enrichies avec le trace_id (l’intérêt principal d’OTLP).

Cliquer sur le derivated field Tempo pour accéder à la trace associée.

Vous pouvez y visualiser le cheminement complet de la requête, remontant jusqu’au reverse proxy Traefik, et descendant jusqu’aux 2 appels à la base de données (pagination liste + compteur), que ce soit au niveau de l’ORM EF Core et même le driver Npgsql avec la requête SQL brute sous-jacente.

En bonus le graph node est fourni pour visualiser le cheminement entre chaque requête, le tout enrichi de métriques.

Il est aussi possible d’accéder aux traces directement depuis les métriques, si les exemplars sont bien actifs.

Ici, View traces vient du lien défini dans la datasource au chapitre des métriques lors de l’installation de Prometheus, permettant d’accéder directement à la trace associée à cet évenement sur Tempo. Extrêmement pratique pour investiguer les pics de charge dans les métriques pour en naviguant dans le détail d’une requête en particulier.

En dehors des outils de monitoring et de tracing, il existe toujours les outils de visualisation temps réel comme Hubble pour explorer rapidement les requêtes et les dépendances entre les services.

Conclusion

Nous avons vu comment mettre en place une chaîne complète de CI/CD pour une application .NET sur Gitea et FluxCD, en intégrant des outils d’analyse statique de code, de monitoring, de logging et de tracing distribué via OpenTelemetry. Cette approche moderne permet de maintenir au mieux la qualité du code, la fiabilité des déploiements et la bonne observabilité de l’application en production.