Integration¶

Ce chapitre décrit comment le service documentaire s'articule avec les autres composants du catalogue : gestion de sources, pipeline CI/CD, gestion des identités, réseau, observabilité et messagerie.

Vue d'ensemble des integrations¶

graph LR
    SCM["SCM (Gitea)"] -->|source Markdown| CICD["CI/CD (Gitea Actions)"]
    CICD -->|4 builds| Docs["Documentation"]
    IAM["IAM (Keycloak)"] -->|OIDC| Proxy["Reverse Proxy (Caddy)"]
    Proxy -->|routage| Docs
    DNS["DNS (CoreDNS)"] -->|docs.example.com| Proxy
    Docs -->|logs JSON| Obs["Observabilite (Loki)"]
    Docs -->|metriques| Prom["Prometheus"]

• SCM → CI/CD : declenchement automatique du pipeline sur chaque push.
• CI/CD → Docs : publication du site statique.
• IAM → Proxy : authentification OIDC avant accès au contenu.
• DNS → Proxy : résolution du nom de domaine interne.
• Docs → Observabilité : export des logs et des metriques.
• CI/CD → Messagerie : notifications de publication et d'echec.

SCM (Gitea)¶

Le contenu documentaire est versionne dans un dépôt Gitea. La branche main constitue la source de vérité ; toute modification passe par une pull request soumise a revue.

Un webhook de type push declenche le pipeline CI/CD à chaque fusion sur main :

{
  "secret": "WEBHOOK_SECRET",
  "content_type": "json",
  "url": "https://gitea.example.com/api/v1/repos/org/docs/hooks",
  "events": ["push"],
  "active": true,
  "config": { "branch_filter": "main" }
}

La branche main est protegee avec au moins 1 approbation requise avant fusion, le push direct desactive et les checks CI obligatoires. Configuration : Depot > Parametres > Branches > Regles de protection.

Voir le service SCM : ../../chaîne-logicielle/scm/index.md

CI/CD (Gitea Actions)¶

Le pipeline est defini dans .gitea/workflows/docs.yml (cf. 04-installation). Le cache pip reduit le temps d'installation de MkDocs de 60 a 80 % sur les builds incrementaux :

- name: Cache pip
  uses: actions/cache@v3
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
    restore-keys: |
      ${{ runner.os }}-pip-

En cas d'echec, une notification est envoyee vers Mattermost :

- name: Notifier echec
  if: failure()
  uses: appleboy/mattermost-action@v1
  with:
    url: ${{ secrets.MATTERMOST_WEBHOOK }}
    channel: ops-alertes
    text: |
      **Build documentation echoue**
      Depot : ${{ github.repository }} — Commit : ${{ github.sha }}

Voir le service CI/CD : ../../chaîne-logicielle/cicd/index.md

IAM (Keycloak)¶

L'accès est protège par authentification OIDC déléguée a Keycloak (configuration détaillée dans 04-installation). Un claim doc_classification est ajoute via un mapper de type Group Membership pour refléter le niveau de sensibilite (public, interne, confidentiel).

Flux d'authentification OIDC¶

sequenceDiagram
    participant U as Utilisateur
    participant C as Caddy (Proxy)
    participant K as Keycloak
    participant D as MkDocs (Site)

    U->>C: GET https://docs.example.com/page
    C->>U: 302 Redirect vers Keycloak
    U->>K: Formulaire de connexion
    K-->>U: Authorization Code
    U->>C: GET /callback?code=...
    C->>K: Echange code contre tokens (OIDC)
    K-->>C: access_token + id_token
    C->>C: Verification du claim doc_classification
    C->>D: Requete proxy vers MkDocs
    D-->>C: Page HTML
    C-->>U: Reponse finale

Gestion des sessions¶

Voir le service IAM : ../../production/iam/index.md

DNS (CoreDNS)¶

Le nom docs.example.com est resolu en interne vers l'IP du reverse proxy. Enregistrement CNAME recommande si Caddy sert plusieurs services :

proxy.example.com.  IN  A     10.0.1.50
docs.example.com.   IN  CNAME proxy.example.com.

Extrait du Corefile pour charger la zone interne :

example.com {
    file /etc/coredns/zones/example.com.zone
    log
    errors
}

Voir le service DNS : ../../production/dns/index.md

Observabilité¶

Logs Caddy vers Loki¶

Caddy écrit les logs au format JSON ; Promtail les collecte et les envoie a Loki :

scrape_configs:
  - job_name: caddy
    static_configs:
      - targets: [localhost]
        labels:
          job: caddy
          __path__: /var/log/caddy/access.log
    pipeline_stages:
      - json:
          expressions:
            ts: ts
            status: status
            request_uri: request.uri
      - labels:
          status:
          request_uri:
      - timestamp:
          source: ts
          format: Unix

Metriques Prometheus¶

Caddy expose ses metriques sur le port 2019 (/metrics). Prometheus scrappe ce endpoint :

scrape_configs:
  - job_name: caddy
    static_configs:
      - targets: ['10.0.1.50:2019']

Tableaux de bord Grafana suggeres :

Voir le service observabilité : ../../production/observabilité/index.md

Messagerie (notifications)¶

À chaque publication réussie, le pipeline envoie une notification Mattermost :

- name: Notifier publication
  if: success()
  run: |
    curl -s -X POST "${{ secrets.MATTERMOST_WEBHOOK }}" \
      -H "Content-Type: application/json" \
      -d '{"channel":"docs-publications","text":"Documentation mise a jour — commit ${{ github.sha }}"}'

Une alerte Alertmanager surveille la disponibilité du service en complement :

groups:
  - name: docs
    rules:
      - alert: DocsDown
        expr: up{job="caddy"} == 0
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "Service documentaire injoignable"

Voir le service messagerie : ../messagerie/index.md

Recapitulatif des integrations¶