Documentation Opérationnelle¶

Introduction¶

La documentation opérationnelle est essentielle pour la gestion efficace d'une infrastructure OpenStack. Elle doit être à jour, accessible et couvrir tous les aspects de l'exploitation quotidienne.

Prérequis¶

• Infrastructure OpenStack en production
• Outil de documentation (Wiki, Git, Confluence)
• Processus de revue documentaire
• Runbooks créés

Points à apprendre¶

Structure de la documentation¶

graph TB
    subgraph "Documentation"
        subgraph "Architecture"
            arch1[Diagrammes infra]
            arch2[Flux réseaux]
            arch3[Inventaire]
        end

        subgraph "Procédures"
            proc1[Runbooks]
            proc2[Checklists]
            proc3[Escalade]
        end

        subgraph "Référence"
            ref1[Configurations]
            ref2[Credentials]
            ref3[Contacts]
        end

        subgraph "Incidents"
            inc1[Post-mortems]
            inc2[Known Issues]
            inc3[Lessons Learned]
        end
    end

    arch1 -->|Support| proc1
    proc1 -->|Référence| ref1
    inc1 -->|Amélioration| proc1

Documentation d'architecture¶

# Architecture OpenStack - Production

## Vue d'ensemble

### Informations générales
| Élément | Valeur |
|---------|--------|
| Version OpenStack | 2025.1 (Epoxy) |
| Méthode déploiement | Kolla-Ansible 19.x |
| Date mise en production | 2024-XX-XX |
| Dernière mise à jour doc | 2024-XX-XX |

### Diagramme d'architecture
[Insérer diagramme PlantUML-C4]

### Inventaire des serveurs
| Hostname | IP Management | IP Storage | Rôle | Specs |
|----------|--------------|------------|------|-------|
| controller-1 | 10.0.0.11 | 10.0.1.11 | Control | 32C/128G/500G |
| controller-2 | 10.0.0.12 | 10.0.1.12 | Control | 32C/128G/500G |
| controller-3 | 10.0.0.13 | 10.0.1.13 | Control | 32C/128G/500G |
| compute-1 | 10.0.0.21 | 10.0.1.21 | Compute | 64C/256G/2T |
| ... | ... | ... | ... | ... |

### Réseaux
| Nom | VLAN | Subnet | Gateway | Usage |
|-----|------|--------|---------|-------|
| management | 10 | 10.0.0.0/24 | 10.0.0.1 | API, SSH |
| storage | 20 | 10.0.1.0/24 | - | Ceph cluster |
| tenant | 30 | 10.0.2.0/24 | - | VM traffic (VXLAN) |
| external | 100 | 192.168.1.0/24 | 192.168.1.1 | Floating IPs |

Inventaire des services¶

# services-inventory.yml

openstack_services:
  identity:
    name: Keystone
    version: "25.0.0"
    endpoints:
      public: https://cloud.example.com:5000/v3
      internal: https://internal.cloud.example.com:5000/v3
    database: keystone
    containers:
      - keystone
      - keystone_fernet

  compute:
    name: Nova
    version: "29.0.0"
    endpoints:
      public: https://cloud.example.com:8774/v2.1
    database: nova, nova_api, nova_cell0
    containers:
      - nova_api
      - nova_conductor
      - nova_scheduler
      - nova_novncproxy
      - nova_compute (sur computes)

  network:
    name: Neutron
    version: "24.0.0"
    endpoints:
      public: https://cloud.example.com:9696
    database: neutron
    containers:
      - neutron_server
      - neutron_openvswitch_agent
      - neutron_l3_agent
      - neutron_dhcp_agent
      - neutron_metadata_agent

  # ... autres services

infrastructure_services:
  database:
    type: MariaDB Galera
    version: "10.11"
    cluster_size: 3
    port: 3306

  messaging:
    type: RabbitMQ
    version: "3.12"
    cluster_size: 3
    port: 5672 (AMQP), 5671 (AMQPS)

  loadbalancer:
    type: HAProxy
    version: "2.8"
    vip: 10.0.0.10

  storage:
    type: Ceph
    version: "Squid (19.x)"
    mon_count: 3
    osd_count: 12

Documentation des credentials¶

# Gestion des Credentials

## Politique de sécurité
- Tous les credentials sont stockés dans un gestionnaire de secrets (Vault/Bitwarden)
- Rotation trimestrielle des passwords
- MFA obligatoire pour accès admin

## Accès documentés (références uniquement)

### OpenStack Admin
- **Emplacement:** Vault path: `secret/openstack/admin`
- **Rotation:** Trimestrielle
- **Dernière rotation:** 2024-XX-XX

### Base de données
- **Emplacement:** Vault path: `secret/openstack/database`
- **Utilisateurs:** root, keystone, nova, neutron, ...
- **Rotation:** Semestrielle

### Certificats TLS
- **Emplacement:** `/etc/kolla/certificates/`
- **CA:** Let's Encrypt / Internal CA
- **Expiration:** 2025-XX-XX
- **Alerte:** 30 jours avant expiration

### SSH Keys
- **Deploy key:** `/root/.ssh/id_rsa` (deploy node)
- **Service accounts:** Documentés dans Vault

## Procédure de récupération
En cas de perte d'accès:
1. Contacter le responsable sécurité
2. Suivre la procédure RB-015 (Recovery credentials)

Diagramme flux d'incident¶

flowchart TD
    Start([Start]) --> Monitor[Monitoring:<br/>Alerte détectée]

    Monitor --> L1Receive[L1 Support:<br/>Réception alerte]
    L1Receive --> L1Qual[Qualification]

    L1Qual --> Known{Incident<br/>connu?}
    Known -->|Oui| ApplyRunbook[Appliquer runbook]
    ApplyRunbook --> L1Resolved{Résolu?}
    L1Resolved -->|Oui| L1Doc[Documenter]
    L1Doc --> End1([Stop])

    Known -->|Non| L2Escalate[L2 Support:<br/>Escalade]
    L1Resolved -->|Non| L2Escalate

    L2Escalate --> L2Diag[Diagnostic approfondi]
    L2Diag --> L2Resolved{Résolu?}
    L2Resolved -->|Oui| L2Doc[Documenter solution]
    L2Doc --> L2Runbook[Créer/MAJ runbook]
    L2Runbook --> End2([Stop])

    L2Resolved -->|Non| L3Escalate[L3 / Vendor:<br/>Escalade externe]
    L3Escalate --> L3Support[Support vendor]
    L3Support --> L3Resolve[Résolution]

    L3Resolve --> PostMortem[Post-Incident:<br/>Post-mortem]
    PostMortem --> Actions[Actions correctives]
    Actions --> UpdateDoc[MAJ documentation]
    UpdateDoc --> End3([Stop])

Template Post-Mortem¶

# Post-Mortem: [Titre de l'incident]

## Informations générales
| Champ | Valeur |
|-------|--------|
| Date incident | YYYY-MM-DD HH:MM |
| Durée | X heures Y minutes |
| Sévérité | P1/P2/P3/P4 |
| Services impactés | |
| Nombre d'utilisateurs impactés | |

## Chronologie
| Heure | Événement |
|-------|-----------|
| HH:MM | Première alerte |
| HH:MM | Début investigation |
| HH:MM | Cause identifiée |
| HH:MM | Début remédiation |
| HH:MM | Service restauré |
| HH:MM | Incident clos |

## Impact
- **Utilisateurs:** X utilisateurs n'ont pas pu accéder à Y
- **Business:** Perte estimée de Z€
- **SLA:** Objectif de 99.9% impacté

## Cause racine
[Description détaillée de la cause]

## Résolution
[Actions prises pour résoudre]

## Leçons apprises
### Ce qui a bien fonctionné
- Point 1
- Point 2

### Ce qui peut être amélioré
- Point 1
- Point 2

## Actions correctives
| Action | Responsable | Échéance | Status |
|--------|-------------|----------|--------|
| Améliorer monitoring X | @alice | 2024-XX-XX | En cours |
| Créer runbook Y | @bob | 2024-XX-XX | À faire |
| Automatiser Z | @charlie | 2024-XX-XX | À faire |

## Annexes
- Liens vers logs
- Captures d'écran
- Tickets associés

Documentation des changements¶

# Change Log

## 2024-Q4

### [2024-12-15] Upgrade OpenStack 2024.1 → 2025.1
- **Type:** Major upgrade
- **Impact:** Maintenance 4h
- **Responsable:** @ops-team
- **Ticket:** CHG-0042
- **Status:** Succès
- **Notes:** Migration base données +15min vs prévu

### [2024-12-01] Ajout compute-5
- **Type:** Capacity
- **Impact:** Aucun
- **Responsable:** @alice
- **Ticket:** CHG-0041
- **Status:** Succès

### [2024-11-15] Rotation certificats TLS
- **Type:** Security
- **Impact:** Aucun (rolling)
- **Responsable:** @security-team
- **Ticket:** CHG-0040
- **Status:** Succès

Dashboard documentation status¶

graph TB
    subgraph "Architecture"
        a1[Diagrammes: À jour]
        a2[Inventaire: À jour]
        a3[Réseaux: À jour]
    end

    subgraph "Procédures"
        p1[Runbooks: 15/20]
        p2[Checklists: À jour]
        p3[Escalade: À revoir]
    end

    subgraph "Référence"
        r1[Configs: À jour]
        r2[Credentials: Vault]
        r3[Contacts: À jour]
    end

    subgraph "Incidents"
        i1[Post-mortems: 3 en attente]
        i2[Known Issues: À jour]
        i3[Changelog: À jour]
    end

    classDef good fill:#90EE90
    classDef warning fill:#FFFFE0

    class a1,a2,a3,r1,r2,r3 good
    class p1,p2,p3,i1,i2,i3 warning

Note: Dernière revue: 2024-12-01 | Prochaine revue: 2025-01-01

Checklist de documentation¶

# documentation-checklist.yml

architecture:
  - item: "Diagramme infrastructure globale"
    status: done
    last_update: "2024-12-01"

  - item: "Inventaire serveurs"
    status: done
    last_update: "2024-12-15"

  - item: "Documentation réseaux"
    status: done
    last_update: "2024-11-01"

  - item: "Flux de données"
    status: todo
    owner: "@network-team"

procedures:
  - item: "Runbook ajout compute"
    status: done

  - item: "Runbook remplacement OSD"
    status: done

  - item: "Runbook upgrade OpenStack"
    status: in_progress
    owner: "@ops-team"

  - item: "Procédure PRA"
    status: done
    last_test: "2024-06-01"

reference:
  - item: "Liste des credentials"
    status: done
    location: "Vault"

  - item: "Contacts escalade"
    status: done
    last_update: "2024-12-01"

  - item: "Contrats support"
    status: done
    expiration: "2025-12-31"

monitoring:
  - item: "Liste des alertes"
    status: done

  - item: "Seuils et justifications"
    status: in_progress

  - item: "Dashboard inventory"
    status: done

Processus de mise à jour¶

flowchart TD
    Start([Start]) --> Trigger[Trigger:<br/>Changement infrastructure<br/>Ajout serveur, upgrade, incident...]

    Trigger --> Identify[Rédaction:<br/>Identifier sections impactées]
    Identify --> Write[Rédiger modifications]
    Write --> Commit[Commit dans Git]

    Commit --> PR[Review:<br/>Pull Request]
    PR --> PeerReview[Review par pair]

    PeerReview --> Approved{Approuvé?}
    Approved -->|Non| Revisions[Révisions]
    Revisions --> PR
    Approved -->|Oui| Merge[Merge]

    Merge --> Build[Publication:<br/>Build documentation]
    Build --> Deploy[Déploiement wiki/site]
    Deploy --> Notify[Notification équipe]

    Notify --> Monthly[Maintenance:<br/>Revue mensuelle planifiée]
    Monthly --> Archive[Archivage versions]

    Archive --> End([Stop])

Exemples pratiques¶

Script de génération doc automatique¶

#!/bin/bash
# generate-docs.sh

OUTPUT_DIR="/var/www/docs/openstack"
DATE=$(date +%Y%m%d)

mkdir -p $OUTPUT_DIR

# 1. Générer inventaire serveurs
echo "# Inventaire Serveurs - $DATE" > $OUTPUT_DIR/inventory.md
echo "" >> $OUTPUT_DIR/inventory.md
echo "| Hostname | IP | Role | Status |" >> $OUTPUT_DIR/inventory.md
echo "|----------|-----|------|--------|" >> $OUTPUT_DIR/inventory.md

for host in $(ansible-inventory -i /etc/kolla/inventory --list | jq -r '.all.children[]' 2>/dev/null); do
    ansible-inventory -i /etc/kolla/inventory --host $host 2>/dev/null | \
        jq -r '"| \(.inventory_hostname) | \(.ansible_host) | \(.role // "compute") | UP |"' >> $OUTPUT_DIR/inventory.md
done

# 2. Générer status services
echo "# Services Status - $DATE" > $OUTPUT_DIR/services.md
openstack service list -f json | jq -r '.[] | "- \(.Name): \(.Type)"' >> $OUTPUT_DIR/services.md

# 3. Générer métriques Ceph
echo "# Ceph Status - $DATE" > $OUTPUT_DIR/ceph.md
ceph -s >> $OUTPUT_DIR/ceph.md
ceph df >> $OUTPUT_DIR/ceph.md

# 4. Générer changelog récent
echo "# Recent Changes" > $OUTPUT_DIR/changelog.md
git -C /etc/kolla log --oneline -20 >> $OUTPUT_DIR/changelog.md

echo "Documentation generated in $OUTPUT_DIR"

Structure de dossiers recommandée¶

docs/
├── architecture/
│   ├── overview.md
│   ├── network-diagram.md
│   ├── storage-design.md
│   └── security-architecture.md
├── operations/
│   ├── runbooks/
│   │   ├── RB-001-add-compute.md
│   │   ├── RB-002-replace-osd.md
│   │   └── ...
│   ├── checklists/
│   │   ├── daily-checks.md
│   │   ├── weekly-maintenance.md
│   │   └── monthly-review.md
│   └── troubleshooting/
│       ├── vm-issues.md
│       ├── network-issues.md
│       └── storage-issues.md
├── reference/
│   ├── inventory.md
│   ├── services.md
│   ├── endpoints.md
│   └── contacts.md
├── incidents/
│   ├── post-mortems/
│   │   └── 2024-12-01-db-outage.md
│   └── known-issues.md
└── changelog.md

Ressources¶

• Google SRE Book - Documentation
• Write the Docs
• Docs as Code

Checkpoint¶

• Structure documentation définie
• Architecture documentée avec diagrammes
• Inventaire serveurs à jour
• Runbooks créés et testés
• Credentials dans gestionnaire sécurisé
• Processus de mise à jour établi
• Revue périodique planifiée
• Équipe formée sur la documentation