Créer et configurer des Deployment Targets

Ce guide pratique vous montre comment créer et configurer des DeploymentTargets dans la plateforme Atlas.

Prérequis

Avoir un compte sur la plateforme Atlas
Être administrateur de workspace ou avoir les droits nécessaires
Avoir un workspace déjà créé
Avoir accès au dépôt GitOps de votre workspace

Structure du dépôt de workspace

Le dépôt GitOps de votre workspace est structuré de la manière suivante :

resources/ : Dossier contenant les définitions des ressources workspace (buckets, databaseclusters, deploymenttargets)
deployment-targets/<nom-du-deployment-target>/ : Dossiers dédiés à chaque DeploymentTarget, contenant les manifestes Kubernetes à déployer

Note : Dans le dossier resources/, seules les ressources appartenant au groupe workspace.fabrique.social.gouv.fr (comme DeploymentTarget) sont autorisées. Les ressources doivent exister dans l'espace de noms approprié du workspace. Il est recommandé d'omettre le champ metadata.namespace pour utiliser l'espace de noms par défaut.

Note : Dans les dossiers deployment-targets/<nom-du-deployment-target>/, aucune restriction de groupe n'est actuellement appliquée, permettant aux utilisateurs de déployer leurs applications comme ils le souhaitent. Cependant, il existe des discussions en cours concernant la création de CRD spécifiques aux applications dans un nouveau groupe (par exemple apps.fabrique.social.gouv.fr) et la restriction à ces seules ressources.

Note importante sur l'évolution future : Ce dépôt est conçu comme un détail d'implémentation. À terme, toutes les modifications seront effectuées via le portail utilisateur ou par automatisation. Néanmoins, les utilisateurs peuvent manipuler directement le dépôt sous leur propre responsabilité.

Qu'est-ce qu'un DeploymentTarget ?

Un DeploymentTarget représente un "environnement" où les applications peuvent être déployées. Il correspond généralement à un environnement (feature-branch, dev, preprod, prod) et se matérialise concrètement par un namespace Kubernetes dans la zone spécifiée. Ce namespace isolé fournit un espace dédié pour déployer vos applications et services.

Pour chaque DeploymentTarget, une application GitOps unique est créée pour surveiller le dossier dédié dans le dépôt Workspace associé. Toutes les ressources Kubernetes définies dans ce dossier seront déployées dans le namespace correspondant au DeploymentTarget.

Création d'un DeploymentTarget

1. Cloner le dépôt GitOps de votre workspace

git clone <URL du dépôt de votre workspace>
cd <nom du dépôt>

2. Créer un fichier YAML pour le DeploymentTarget

Créez un nouveau fichier YAML dans le dossier resources du dépôt. Nommez-le de manière significative, par exemple mon-app-dev.yaml.

mkdir -p resources
touch resources/mon-app-dev.yaml

Important : Les ressources doivent être déclarées dans le dossier resources/. Seules les ressources appartenant au groupe workspace.fabrique.social.gouv.fr (comme DeploymentTarget) sont autorisées.

3. Définir la configuration du DeploymentTarget

Ouvrez le fichier mon-app-dev.yaml dans votre éditeur préféré et ajoutez la configuration suivante :

apiVersion: workspace.fabrique.social.gouv.fr/v1alpha1
kind: DeploymentTarget
metadata:
  name: mon-app-dev
spec:
  parameters:
    name: "mon-app-dev"
    zoneRef:
      name: "dev"

Assurez-vous de remplacer : - mon-app-dev par un nom significatif pour votre environnement de déploiement - dev par le nom de la zone appropriée (par exemple, dev, prod)

4. Pousser les changements vers le dépôt

git add resources/mon-app-dev.yaml
git commit -m "Ajout du DeploymentTarget pour mon-app-dev"
git push

5. Vérifier la création du DeploymentTarget

Une fois les changements poussés, ArgoCD détectera automatiquement les modifications et créera le DeploymentTarget. Vous pouvez vérifier l'état de la création dans ArgoCD.

Accédez à ArgoCD via l'interface Atlas
Recherchez l'application correspondant à votre workspace
Vérifiez que le DeploymentTarget a été créé avec succès

Configuration avancée d'un DeploymentTarget

Utilisation de Helm Charts

Vous pouvez spécifier des Helm Charts à déployer avec votre DeploymentTarget. Notez que cette fonctionnalité est expérimentale et peut changer ou être supprimée à l'avenir.

apiVersion: workspace.fabrique.social.gouv.fr/v1alpha1
kind: DeploymentTarget
metadata:
  name: mon-app-dev
spec:
  parameters:
    name: "mon-app-dev"
    zoneRef:
      name: "dev"
    charts:
      - chart: "nginx"
        releaseName: "mon-nginx"
        repoURL: "https://charts.bitnami.com/bitnami"
        version: "19.0.0"
        values:
          replicaCount: 2
          service:
            type: ClusterIP

Note : Il est recommandé d'utiliser le rendered manifest pattern et de pousser la sortie d'un "helm template" dans le dépôt GitOps plutôt que d'utiliser cette fonctionnalité expérimentale.

Exemple d'utilisation de helm template

# Ajouter le repo Helm
helm repo add bitnami https://charts.bitnami.com/bitnami

# Créer le dossier pour les manifestes
mkdir -p deployment-targets/mon-app-dev

# Générer les manifestes avec helm template
helm template mon-nginx bitnami/nginx --version 19.0.0 \
  --set replicaCount=2 \
  --set service.type=ClusterIP \
  > deployment-targets/mon-app-dev/nginx.yaml

Déploiement d'applications dans un DeploymentTarget

Une fois le DeploymentTarget créé, vous pouvez déployer des applications en ajoutant des fichiers YAML dans le dossier deployment-targets/<nom-du-deployment-target>/ du dépôt.

1. Créer le dossier pour les manifestes de l'application

1	`mkdir -p deployment-targets/mon-app-dev`

2. Ajouter les manifestes Kubernetes

Créez les fichiers YAML nécessaires pour votre application dans le dossier deployment-targets/mon-app-dev. Par exemple, pour déployer une application web simple :

touch deployment-targets/mon-app-dev/deployment.yaml
touch deployment-targets/mon-app-dev/service.yaml
touch deployment-targets/mon-app-dev/ingress.yaml

Exemple de deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mon-application
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mon-application
  template:
    metadata:
      labels:
        app: mon-application
    spec:
      containers:
      - name: mon-application
        image: nginx:latest
        ports:
        - containerPort: 80

Exemple de service.yaml

apiVersion: v1
kind: Service
metadata:
  name: mon-application
spec:
  selector:
    app: mon-application
  ports:
  - port: 80
    targetPort: 80
  type: ClusterIP

Exemple de ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: mon-application
  annotations:
    kubernetes.io/ingress.class: nginx
spec:
  rules:
  - host: mon-application.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: mon-application
            port:
              number: 80

3. Pousser les changements vers le dépôt

git add deployment-targets/mon-app-dev/
git commit -m "Ajout des manifestes pour mon-application"
git push

4. Vérifier le déploiement

Une fois les changements poussés, ArgoCD détectera automatiquement les modifications et déploiera votre application. Vous pouvez vérifier l'état du déploiement dans ArgoCD.

Modification d'un DeploymentTarget

La modification d'un DeploymentTarget se fait en modifiant le fichier YAML correspondant dans le dépôt du workspace.

1. Cloner le dépôt GitOps de votre workspace (si ce n'est pas déjà fait)

git clone <URL du dépôt de votre workspace>
cd <nom du dépôt>

2. Modifier le fichier YAML du DeploymentTarget

Ouvrez le fichier resources/mon-app-dev.yaml dans votre éditeur préféré et modifiez la configuration selon vos besoins.

3. Pousser les changements vers le dépôt

git add resources/mon-app-dev.yaml
git commit -m "Modification du DeploymentTarget pour mon-app-dev"
git push

4. Vérifier la mise à jour du DeploymentTarget

Une fois les changements poussés, ArgoCD détectera automatiquement les modifications et mettra à jour le DeploymentTarget. Vous pouvez vérifier l'état de la mise à jour dans ArgoCD.

Suppression d'un DeploymentTarget

La suppression d'un DeploymentTarget se fait en supprimant le fichier YAML correspondant du dépôt du workspace.

Attention : La suppression d'un DeploymentTarget entraînera également la suppression de toutes les ressources déployées dans cet environnement. Assurez-vous de sauvegarder toutes les données importantes avant de supprimer un DeploymentTarget.

1. Cloner le dépôt GitOps de votre workspace (si ce n'est pas déjà fait)

git clone <URL du dépôt de votre workspace>
cd <nom du dépôt>

2. Supprimer le fichier YAML du DeploymentTarget

git rm resources/mon-app-dev.yaml
git commit -m "Suppression du DeploymentTarget pour mon-app-dev"
git push

3. Vérifier la suppression du DeploymentTarget

Une fois les changements poussés, ArgoCD détectera automatiquement les modifications et supprimera le DeploymentTarget. Vous pouvez vérifier l'état de la suppression dans ArgoCD.

Livraison de secrets aux DeploymentTargets

Les DeploymentTargets sont utilisés comme cibles pour la livraison des secrets des ressources comme les Buckets et les DatabaseClusters. Lorsque vous créez ces ressources, vous pouvez spécifier les DeploymentTargets auxquels livrer les secrets.

Exemple de configuration d'un Bucket avec livraison de secrets

apiVersion: workspace.fabrique.social.gouv.fr/v1alpha1
kind: Bucket
metadata:
  name: mon-bucket
spec:
  parameters:
    name: "mon-app-bucket-unique-name"
    acl: "private"
    versioned: false
    forceDestroy: false
    tags: {}
    zoneRef:
      name: "dev"
    secretDeliveryTargets:
      - kind: "DeploymentTarget"
        name: "mon-app-dev"

Exemple de configuration d'un DatabaseCluster avec livraison de secrets

apiVersion: workspace.fabrique.social.gouv.fr/v1alpha1
kind: DatabaseCluster
metadata:
  name: ma-db-dev
spec:
  parameters:
    name: "ma-db-dev"
    implementation: "cnpg"
    version: "15"
    diskSize: 10
    replicas: 1
    cnpg:
      resources:
        limits:
          cpu: "500m"
          memory: "512Mi"
        requests:
          cpu: "100m"
          memory: "256Mi"
    zoneRef:
      name: "dev"
    secretDeliveryTargets:
      - kind: "DeploymentTarget"
        name: "mon-app-dev"

Bonnes pratiques

Nommage : Utilisez des noms significatifs pour vos DeploymentTargets, qui reflètent l'environnement qu'ils représentent (dev, preprod, prod, etc.).
Organisation : Organisez vos manifestes de manière logique dans le dossier deployment-targets/<nom-du-deployment-target>/.
Versionnement : Utilisez Git pour versionner vos DeploymentTargets et suivre les changements.
Environnements multiples : Créez des DeploymentTargets distincts pour chaque environnement (dev, preprod, prod) pour isoler les déploiements.
Helm Charts : Préférez l'utilisation de helm template pour générer des manifestes plutôt que d'utiliser la fonctionnalité expérimentale des charts dans les DeploymentTargets.

Résolution des problèmes courants

Le DeploymentTarget n'apparaît pas dans ArgoCD

Vérifiez que vous avez bien poussé les changements vers le dépôt
Vérifiez que le fichier YAML est correctement formaté
Vérifiez que vous avez les droits nécessaires pour créer un DeploymentTarget

Erreur lors de la création du DeploymentTarget

Vérifiez les logs dans ArgoCD pour identifier l'erreur
Assurez-vous que la zone référencée existe
Contactez l'administrateur de la plateforme si le problème persiste

Les applications ne se déploient pas dans le DeploymentTarget

Vérifiez que le DeploymentTarget a été créé avec succès
Vérifiez que les manifestes sont correctement formatés
Vérifiez les logs dans ArgoCD pour identifier l'erreur