Guide Platform Engineer

Ce guide vous accompagne dans la création et la gestion des capacités de la plateforme Argy.

Vue d'Ensemble du Rôle

En tant que Platform Engineer, vous êtes responsable de :

• Golden Paths : définir les chemins standards pour les équipes de développement
• Modules : créer des automatisations réutilisables
• Policies : définir les règles de gouvernance
• Intégrations : connecter Argy à vos outils existants

---

Golden Paths

Les Golden Paths sont des chemins pré-approuvés qui guident les développeurs vers les bonnes pratiques.

Créer un Golden Path

1. Allez dans Studio → Golden Paths
2. Cliquez sur Créer un Golden Path
3. Remplissez les informations de base :
   • Nom : ex. nodejs-microservice
   • Description : description détaillée
   • Tags : pour la recherche (ex. backend, nodejs, api)
   • Icône : choisissez une icône

Structure d'un Golden Path

Un Golden Path est défini en YAML :

# golden-path.yaml
apiVersion: argy.cloud/v1
kind: GoldenPath
metadata:
  name: nodejs-microservice
  description: "Microservice Node.js avec Express, TypeScript et tests"
  tags:
    - backend
    - nodejs
    - typescript
    - api

spec:
  # Template de fichiers
  template:
    source: git
    repository: https://github.com/votre-org/templates
    path: nodejs-microservice
    branch: main

  # Variables à remplir par l'utilisateur
  parameters:
    - name: serviceName
      type: string
      description: "Nom du service"
      required: true
      pattern: "^[a-z][a-z0-9-]*$"
    
    - name: port
      type: number
      description: "Port d'écoute"
      default: 3000
      min: 1024
      max: 65535
    
    - name: database
      type: select
      description: "Type de base de données"
      options:
        - postgresql
        - mongodb
        - none
      default: postgresql
    
    - name: enableAuth
      type: boolean
      description: "Activer l'authentification JWT"
      default: true

  # Modules à appliquer automatiquement
  modules:
    - name: create-repo
      params:
        repoName: "{{ serviceName }}"
        template: nodejs-microservice
    
    - name: setup-ci
      params:
        type: github-actions
        tests: true
        lint: true
    
    - name: deploy-k8s
      when: "{{ database != 'none' }}"
      params:
        namespace: "{{ serviceName }}"
        replicas: 2

  # Policies à vérifier
  policies:
    - security-scan
    - code-coverage-80
    - no-secrets-in-code

  # Documentation associée
  docs:
    - title: "Guide de démarrage"
      url: "https://docs.internal/nodejs-microservice"
    - title: "Standards de code"
      url: "https://docs.internal/code-standards"

Template de Fichiers

Créez un repository Git avec la structure de votre template :

nodejs-microservice/
├── .github/
│   └── workflows/
│       └── ci.yml.tpl
├── src/
│   ├── index.ts.tpl
│   ├── config/
│   │   └── index.ts.tpl
│   └── routes/
│       └── health.ts.tpl
├── tests/
│   └── health.test.ts.tpl
├── Dockerfile.tpl
├── package.json.tpl
├── tsconfig.json
└── README.md.tpl

Les fichiers .tpl utilisent la syntaxe de templating :

// src/index.ts.tpl
import express from 'express';
import { config } from './config';

const app = express();
const PORT = {{ port }};

app.get('/health', (req, res) => {
  res.json({ status: 'ok', service: '{{ serviceName }}' });
});

{{#if enableAuth}}
import { authMiddleware } from './middleware/auth';
app.use(authMiddleware);
{{/if}}

app.listen(PORT, () => {
  console.log(`{{ serviceName }} listening on port ${PORT}`);
});

Publier un Golden Path

1. Testez votre Golden Path en local :

   argy-code golden-path validate ./golden-path.yaml
   

2. Publiez-le :

   argy-code golden-path publish ./golden-path.yaml
   

3. Ou via l'interface :

   • Allez dans Studio → Golden Paths
   • Cliquez sur votre Golden Path
   • Cliquez sur Publier

---

Modules

Les modules sont des automatisations réutilisables qui encapsulent des actions complexes.

Types de Modules

Type	Description	Exemples
Provisioning	Création de ressources	Repo Git, Namespace K8s, Base de données
Deployment	Déploiement d'applications	Helm, Terraform, ArgoCD
Configuration	Configuration de services	Secrets, ConfigMaps, Variables
Observability	Monitoring et alerting	Dashboards, Alertes, Logs
Security	Sécurité et conformité	Scans, Policies, Certificats

Créer un Module

1. Allez dans Studio → Modules
2. Cliquez sur Créer un module
3. Choisissez le type de module

Structure d'un Module

# module.yaml
apiVersion: argy.cloud/v1
kind: Module
metadata:
  name: create-k8s-namespace
  description: "Crée un namespace Kubernetes avec les ressources de base"
  category: provisioning
  tags:
    - kubernetes
    - namespace

spec:
  # Paramètres d'entrée
  inputs:
    - name: namespaceName
      type: string
      required: true
      description: "Nom du namespace"
      validation:
        pattern: "^[a-z][a-z0-9-]*$"
        maxLength: 63
    
    - name: resourceQuota
      type: select
      description: "Quota de ressources"
      options:
        - small   # 2 CPU, 4Gi RAM
        - medium  # 4 CPU, 8Gi RAM
        - large   # 8 CPU, 16Gi RAM
      default: small
    
    - name: labels
      type: object
      description: "Labels additionnels"
      default: {}

  # Outputs du module
  outputs:
    - name: namespace
      type: string
      description: "Nom du namespace créé"
    - name: kubeconfig
      type: secret
      description: "Kubeconfig pour accéder au namespace"

  # Étapes d'exécution
  steps:
    - name: create-namespace
      action: kubernetes/apply
      params:
        manifest: |
          apiVersion: v1
          kind: Namespace
          metadata:
            name: {{ inputs.namespaceName }}
            labels:
              managed-by: argy
              {{#each inputs.labels}}
              {{ @key }}: {{ this }}
              {{/each}}

    - name: create-resource-quota
      action: kubernetes/apply
      params:
        manifest: |
          apiVersion: v1
          kind: ResourceQuota
          metadata:
            name: default-quota
            namespace: {{ inputs.namespaceName }}
          spec:
            hard:
              {{#if (eq inputs.resourceQuota "small")}}
              requests.cpu: "2"
              requests.memory: 4Gi
              limits.cpu: "4"
              limits.memory: 8Gi
              {{/if}}
              {{#if (eq inputs.resourceQuota "medium")}}
              requests.cpu: "4"
              requests.memory: 8Gi
              limits.cpu: "8"
              limits.memory: 16Gi
              {{/if}}
              {{#if (eq inputs.resourceQuota "large")}}
              requests.cpu: "8"
              requests.memory: 16Gi
              limits.cpu: "16"
              limits.memory: 32Gi
              {{/if}}

    - name: create-network-policy
      action: kubernetes/apply
      params:
        manifest: |
          apiVersion: networking.k8s.io/v1
          kind: NetworkPolicy
          metadata:
            name: default-deny
            namespace: {{ inputs.namespaceName }}
          spec:
            podSelector: {}
            policyTypes:
              - Ingress
              - Egress

    - name: set-outputs
      action: core/set-outputs
      params:
        namespace: "{{ inputs.namespaceName }}"
        kubeconfig: "{{ steps.create-namespace.kubeconfig }}"

  # Rollback en cas d'erreur
  rollback:
    - name: delete-namespace
      action: kubernetes/delete
      params:
        kind: Namespace
        name: "{{ inputs.namespaceName }}"

Actions Disponibles

Catégorie	Actions
kubernetes	apply, delete, patch, exec, logs
terraform	init, plan, apply, destroy
git	clone, commit, push, create-pr
helm	install, upgrade, uninstall, template
shell	exec (sandboxé)
http	request
vault	read, write, delete
core	set-outputs, wait, condition, loop

Tester un Module

# Valider la syntaxe
argy-code module validate ./module.yaml

# Exécuter en mode dry-run
argy-code module run ./module.yaml \
  --input namespaceName=test-ns \
  --input resourceQuota=small \
  --dry-run

# Exécuter réellement
argy-code module run ./module.yaml \
  --input namespaceName=test-ns \
  --input resourceQuota=small

---

Policies

Les policies définissent les règles de gouvernance appliquées automatiquement.

Types de Policies

Type	Description
Validation	Vérifie les configurations avant déploiement
Mutation	Modifie automatiquement les configurations
Audit	Génère des rapports de conformité

Créer une Policy

# policy.yaml
apiVersion: argy.cloud/v1
kind: Policy
metadata:
  name: require-resource-limits
  description: "Tous les containers doivent avoir des limites de ressources"
  severity: high
  category: security

spec:
  # Cibles de la policy
  targets:
    - kind: Deployment
    - kind: StatefulSet
    - kind: DaemonSet

  # Règles de validation
  rules:
    - name: check-cpu-limits
      message: "Le container {{ container.name }} n'a pas de limite CPU"
      expression: |
        spec.template.spec.containers.all(c, 
          has(c.resources) && 
          has(c.resources.limits) && 
          has(c.resources.limits.cpu)
        )

    - name: check-memory-limits
      message: "Le container {{ container.name }} n'a pas de limite mémoire"
      expression: |
        spec.template.spec.containers.all(c, 
          has(c.resources) && 
          has(c.resources.limits) && 
          has(c.resources.limits.memory)
        )

  # Actions en cas de violation
  enforcement:
    mode: deny  # deny, warn, audit
    
  # Exceptions
  exceptions:
    - namespaces:
        - kube-system
        - argy-system
    - labels:
        policy-exempt: "true"

Policy de Mutation

# policy-mutation.yaml
apiVersion: argy.cloud/v1
kind: Policy
metadata:
  name: inject-labels
  description: "Ajoute automatiquement les labels standards"

spec:
  targets:
    - kind: Deployment
    - kind: Service

  mutations:
    - name: add-managed-by-label
      patch:
        metadata:
          labels:
            managed-by: argy
            team: "{{ product.team }}"
            environment: "{{ product.environment }}"

    - name: add-annotations
      patch:
        metadata:
          annotations:
            argy.cloud/product-id: "{{ product.id }}"
            argy.cloud/deployed-at: "{{ now }}"

Appliquer une Policy

1. Via l'interface :

   • Allez dans Studio → Policies
   • Cliquez sur Créer une policy
   • Collez votre YAML
   • Cliquez sur Publier

2. Via CLI :

   argy-code policy apply ./policy.yaml
   

Vérifier la Conformité

# Vérifier un manifest
argy-code policy check ./deployment.yaml

# Vérifier un namespace entier
argy-code policy audit --namespace production

# Générer un rapport
argy-code policy report --format html --output report.html

---

Intégrations

Configurer une Intégration Git

1. Allez dans Administration → Intégrations → Git
2. Cliquez sur Ajouter une connexion
3. Choisissez le provider :
   • GitHub
   • GitLab
   • Azure DevOps
   • Bitbucket

Pour GitHub :

# Permissions requises pour l'App GitHub
permissions:
  contents: write
  pull_requests: write
  workflows: write
  actions: read

Configurer une Intégration Kubernetes

1. Allez dans Administration → Intégrations → Kubernetes
2. Cliquez sur Ajouter un cluster
3. Choisissez la méthode :
   • Agent : déployez l'agent Argy dans le cluster
   • Kubeconfig : uploadez un kubeconfig (moins recommandé)

Via Agent (recommandé) :

# Installer l'agent dans le cluster
helm repo add argy https://charts.argy.cloud
helm install argy-agent argy/agent \
  --namespace argy-system \
  --create-namespace \
  --set token=$ARGY_AGENT_TOKEN

Configurer une Intégration Cloud

AWS :

# IAM Role pour Argy
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::ACCOUNT:oidc-provider/api.argy.cloud"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "api.argy.cloud:sub": "tenant:YOUR_TENANT_ID"
        }
      }
    }
  ]
}

Azure :

1. Créez un Service Principal
2. Assignez les rôles nécessaires
3. Configurez dans Argy avec Client ID et Secret

GCP :

1. Créez un Service Account
2. Configurez Workload Identity Federation
3. Uploadez la clé JSON dans Argy

---

Workflows d'Approbation

Créer un Workflow

# approval-workflow.yaml
apiVersion: argy.cloud/v1
kind: ApprovalWorkflow
metadata:
  name: production-deployment
  description: "Approbation pour les déploiements en production"

spec:
  # Déclencheurs
  triggers:
    - event: deployment
      conditions:
        - environment: production
        - changeType: [create, update]

  # Étapes d'approbation
  stages:
    - name: tech-lead-approval
      description: "Approbation du Tech Lead"
      approvers:
        type: role
        role: tech-lead
        minApprovals: 1
      timeout: 24h
      
    - name: security-review
      description: "Revue sécurité"
      approvers:
        type: team
        team: security
        minApprovals: 1
      timeout: 48h
      conditions:
        - securityScanResult: high

    - name: manager-approval
      description: "Approbation manager"
      approvers:
        type: user
        users:
          - manager@company.com
      timeout: 24h

  # Actions post-approbation
  onApproved:
    - action: notify
      params:
        channel: slack
        message: "Déploiement {{ deployment.name }} approuvé"
    
  onRejected:
    - action: notify
      params:
        channel: slack
        message: "Déploiement {{ deployment.name }} rejeté: {{ rejection.reason }}"

---

Observabilité

Configurer les Métriques

# metrics-config.yaml
apiVersion: argy.cloud/v1
kind: MetricsConfig
metadata:
  name: platform-metrics

spec:
  # Export vers Prometheus
  prometheus:
    enabled: true
    endpoint: /metrics
    
  # Métriques personnalisées
  customMetrics:
    - name: deployments_total
      type: counter
      description: "Nombre total de déploiements"
      labels:
        - product
        - environment
        - status
        
    - name: deployment_duration_seconds
      type: histogram
      description: "Durée des déploiements"
      buckets: [30, 60, 120, 300, 600]

Configurer les Alertes

# alerts.yaml
apiVersion: argy.cloud/v1
kind: AlertRule
metadata:
  name: deployment-failure-rate

spec:
  expression: |
    sum(rate(deployments_total{status="failed"}[5m])) 
    / sum(rate(deployments_total[5m])) > 0.1
  
  for: 5m
  severity: critical
  
  annotations:
    summary: "Taux d'échec des déploiements élevé"
    description: "Plus de 10% des déploiements échouent"
    
  notifications:
    - type: slack
      channel: "#platform-alerts"
    - type: pagerduty
      service: platform-oncall

---

Bonnes Pratiques

1. Versionner les Golden Paths

# Utilisez des tags sémantiques
git tag -a v1.0.0 -m "Initial release"
git push origin v1.0.0

# Référencez la version dans Argy
spec:
  template:
    source: git
    repository: https://github.com/org/templates
    ref: v1.0.0  # Utilisez un tag, pas main

2. Tester les Modules

# module-test.yaml
apiVersion: argy.cloud/v1
kind: ModuleTest
metadata:
  name: test-create-namespace

spec:
  module: create-k8s-namespace
  
  testCases:
    - name: basic-creation
      inputs:
        namespaceName: test-ns
        resourceQuota: small
      assertions:
        - type: exists
          resource: Namespace/test-ns
        - type: exists
          resource: ResourceQuota/default-quota
          
    - name: invalid-name
      inputs:
        namespaceName: "Invalid_Name"
      expectError: true
      errorContains: "pattern"

3. Documenter les Policies

Chaque policy doit avoir :

• Une description claire
• Des exemples de configurations valides/invalides
• Les exceptions documentées
• Un contact pour les questions

4. Monitorer l'Adoption

Suivez les métriques d'adoption :

• Nombre de projets utilisant chaque Golden Path
• Taux de conformité aux policies
• Temps moyen de déploiement
• Satisfaction des développeurs (surveys)

---

Dépannage

Un module échoue

1. Consultez les logs détaillés :

   argy-code module logs --run-id <run-id>
   

2. Vérifiez les permissions de l'agent

3. Testez en mode dry-run

4. Vérifiez les quotas de ressources

Une policy bloque un déploiement légitime

1. Vérifiez si une exception est nécessaire
2. Ajoutez le label policy-exempt: "true" temporairement
3. Créez une exception permanente si justifié
4. Documentez la raison de l'exception

Les Golden Paths ne se mettent pas à jour

1. Vérifiez que le repository Git est accessible
2. Vérifiez les credentials Git
3. Forcez une synchronisation :

   argy-code golden-path sync --force