Gérer les applications avec Application Delivery

Cette page décrit la procédure de configuration d'un déploiement de NGINX avec Application Delivery. Le déploiement s'exécute dans deux environnements, staging et prod. L'environnement prod utilise une configuration standard, tandis que l'environnement staging utilise une configuration légèrement modifiée.

Exigences

Pour suivre ce tutoriel, vous devez disposer des éléments suivants :

  • Git 2.19.2 ou version ultérieure installée localement.
  • Un compte GitHub ou GitLab disposant des autorisations nécessaires pour créer un dépôt privé. Application Delivery n'est compatible qu'avec les dépôts GitHub et GitLab.
  • Un cluster exécutant GKE version 1.15 ou ultérieure.
  • Un utilisateur disposant de droits clusterAdmin
  • Kustomize installé en local (Vous pouvez suivre le guide d'installation)
  • Si vous souhaitez valider vos fichiers de configuration Kubernetes dans le dépôt de déploiement, vous devez installer Docker.

Avant de commencer

Avant de commencer, effectuez les tâches suivantes :

  • Activez l'API Google Kubernetes Engine.
    • Activer l'API Google Kubernetes Engine
  • Si vous souhaitez utiliser Google Cloud CLI pour cette tâche, installez puis initialisez gcloud CLI.
  • Ajoutez des clés SSH à votre compte GitHub ou GitLab.

  • Testez vos clés avec ssh :

    GitHub

    sh ssh -T git@github.com

    GitLab

    sh ssh -T git@gitlab.com

    Il se peut que vous soyez invité à confirmer les détails de connexion ou la phrase secrète de votre clé. Si la connexion aboutit, un message s'affiche sur le terminal.

Configurer Application Delivery

Pour utiliser Application Delivery, vous devez procéder comme suit :

  1. Créez un nouveau cluster sur lequel Application Delivery est activé, ou activez-le sur un cluster GKE existant exécutant la version 1.15 ou ultérieure.
  2. Installez appctl, l'outil de ligne de commande d'Application Delivery.

Créer un cluster avec Application Delivery

Vous pouvez créer un cluster sur lequel Application Delivery est activé à l'aide de gcloud CLI ou de la console Google Cloud.

gcloud

Créez un cluster :

gcloud beta container clusters create CLUSTER_NAME \
      --cluster-version CLUSTER_VERSION\
      --addons ApplicationManager

Remplacez les éléments suivants :

  • CLUSTER_NAME : nom de votre nouveau cluster
  • CLUSTER_VERSION : version de votre nouveau cluster Doit être GKE 1.15 ou une version ultérieure.

Console

  1. Accédez à la page Google Kubernetes Engine dans Google Cloud Console.

    Accéder à Google Kubernetes Engine

  2. Cliquez sur Créer.

  3. Dans la section Standard, cliquez sur Configurer.

  4. Spécifiez le nom du cluster.

  5. Choisissez une version du plan de contrôle 1.15.x ou ultérieure.

  6. Configurez le cluster selon vos besoins.

  7. Dans le volet de navigation, sous Cluster, cliquez sur Fonctionnalités.

  8. Cochez la case Activer le gestionnaire d'applications.

  9. Cliquez sur Créer.

Activer Application Delivery sur un cluster existant

Vous pouvez activer Application Delivery sur un cluster existant à l'aide de gcloud CLI ou de la console Google Cloud.

gcloud

Pour activer Application Delivery sur un cluster existant, exécutez la commande suivante :

gcloud beta container clusters update CLUSTER_NAME \
      --update-addons ApplicationManager=ENABLED

Remplacez CLUSTER_NAME par le nom de votre cluster.

Console

  1. Accédez à la page Google Kubernetes Engine dans Google Cloud Console.

    Accéder à Google Kubernetes Engine

  2. Dans la liste des clusters, cliquez sur le nom du cluster que vous souhaitez modifier.

  3. Sous Fonctionnalités, à côté du champ Gestionnaire d'applications, cliquez sur Modifier le gestionnaire d'applications.

  4. Cochez la case Activer le gestionnaire d'applications.

  5. Cliquez sur Save Changes (Enregistrer les modifications).

Confirmer l'installation

Pour vérifier l'état de l'installation d'Application Delivery, procédez comme suit :

  1. Vérifiez l'état du déploiement :

    kubectl get deployment application-controller-manager -n application-system

    Le résultat ressemble à ce qui suit :

    NAME                             READY   UP-TO-DATE   AVAILABLE   AGE
application-controller-manager   2/2     2            2           1h

    Deux pods doivent être disponibles dans ce déploiement application-controller-manager.

  2. Vérifiez l'état de StatefulSet :

    kubectl get statefulset kalm-controller-manager -n kalm-system

    Le résultat ressemble à ce qui suit :

    NAME                      READY   AGE
kalm-controller-manager   1/1     1h

    Un pod doit être prêt dans cet objet StatefulSet kalm-controller-manager.

Installer appctl

Pour installer l'outil de ligne de commande appctl d'Application Delivery, utilisez gCloud CLI pour installer pkg.

gcloud components install pkg

Après avoir activé Application Delivery sur un cluster et installé pkg, vous pouvez déployer votre première application.

Déployer une application

Pour déployer une application, procédez comme suit :

  1. Créez des dépôts Git ou initialisez des dépôts existants
  2. Créez une configuration de base
  3. Créer un ou plusieurs environnements pour le déploiement
  4. (Facultatif) Appliquer des superpositions de configuration aux environnements du dépôt d'application
  5. Créer une version finale sous la forme d'une demande d'extraction ou de fusion
  6. Déployer la version

Créer des dépôts

Créez des dépôts pour Application Delivery sur GitHub ou GitLab avec appctl.

  1. Accédez au répertoire dans lequel vous souhaitez créer le répertoire de l'application.

  2. Créez vos dépôts Application Delivery à l'aide de appctl.

    GitHub

    Exécutez la commande suivante :

    appctl init APP_NAME \
    --app-config-repo=github.com/USERNAME/APP_NAME

    Remplacez les éléments suivants :

    • APP_NAME : nom de votre application.
    • USERNAME : votre nom d'utilisateur GitHub.

    Par exemple, si votre nom d'utilisateur GitHub est octocat et que vous souhaitez créer une application nommée myapp, exécutez la commande suivante :

    appctl init myapp \
    --app-config-repo=github.com/octocat/myapp

    GitLab

    Exécutez la commande suivante :

    appctl init APP_NAME \
    --app-config-repo=gitlab.com/USERNAME/APP_NAME

    Remplacez les éléments suivants :

    • APP_NAME : nom de votre application.
    • USERNAME : votre nom d'utilisateur GitLab.

    Par exemple, si votre nom d'utilisateur GitLab est alice et que vous souhaitez créer une application nommée myapp, exécutez la commande suivante :

    appctl init myapp \
    --app-config-repo=gitlab.com/alice/myapp

  3. appctl vous invite à confirmer vos nouveaux dépôts privés.

appctl crée deux dépôts Git privés distants :

  • Le dépôt d'application github.com/USERNAME/APP_NAME. Ce dépôt est cloné dans le répertoire actif.
  • Le dépôt de déploiement github.com/USERNAME/APP_NAME-deployment. Le dépôt de déploiement local est stocké dans ./APP_NAME/.deployment.

Pour en savoir plus sur le contenu et la structure de ces dépôts, consultez le guide conceptuel Application Delivery.

Initialiser les dépôts existants

Si vous disposez de dépôts existants, vous pouvez les initialiser pour Application Delivery sur GitHub ou GitLab à l'aide de appctl.

  1. Accédez au répertoire dans lequel vous souhaitez créer le répertoire de l'application.

  2. Exécutez la commande appctl init, qui crée un répertoire nommé APP_NAME et clone votre dépôt.

    La commande appctl init initialise une couche de base Kustomize dans les fichiers de configuration stockés dans le répertoire ./config du dépôt. Vous pouvez spécifier un chemin de configuration différent avec l'option --config-path.

    Par défaut, appctl init utilise github.com/USERNAME/APP_NAME-deployment comme URL du dépôt de déploiement. Vous pouvez utiliser l'option --deployment-repo pour spécifier une autre URL. Si le dépôt de déploiement n'existe pas, la commande appctl en crée un.

    GitHub

    appctl init APP_NAME \
      --app-config-repo=github.com/USERNAME/APP_NAME \
      [--config-path=CONFIG_PATH]

    Remplacez les éléments suivants :

    • APP_NAME : nom de votre application.
    • USERNAME : votre nom d'utilisateur GitHub.
    • CONFIG_PATH : chemin d'accès facultatif au répertoire de configuration de votre dépôt. Si aucune valeur n'est spécifiée, la valeur par défaut est ./config.

    Par exemple, si le dépôt de configuration d'application existant est https://github.com/octocat/myapp et que vous pensez que le dépôt de déploiement sera https://github.com/octocat/myapp-deploy, exécutez la commande suivante :

    appctl init myapp \
    --app-config-repo=github.com/octocat/myapp

    GitLab

    appctl init APP_NAME \
    --app-config-repo=gitlab.com/USERNAME/APP_NAME \
    [--config-path=CONFIG_PATH]

    Remplacez les éléments suivants :

    • APP_NAME : nom de votre application.
    • USERNAME : votre nom d'utilisateur GitLab.
    • CONFIG_PATH : chemin d'accès facultatif au répertoire de configuration de votre dépôt. Si aucune valeur n'est spécifiée, la valeur par défaut est ./config.

    Par exemple, si le dépôt de configuration d'application existant est gitlab.com/alice/myapp, exécutez la commande suivante :

    appctl init myapp --app-config-repo=gitlab.com/alice/myapp

Créer une configuration de base

  1. Remplacez votre répertoire de travail par le dépôt d'application.

  2. Créez la configuration de votre charge de travail Kubernetes. Il peut s'agir de n'importe quel déploiement Kubernetes valide.

    La configuration suivante définit une application nommée nginx, qui déploie trois instances dupliquées du conteneur nginx. Copiez la configuration dans le fichier config/base/myapp.yaml. Si vous souhaitez activer un équilibreur de charge, annulez la mise en commentaire de la ligne type: LoadBalancer.

    #myapp/config/base/myapp.yaml

apiVersion: v1
kind: Service
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  # if your cluster supports it, uncomment the following to automatically create
  # an external load-balanced IP for the frontend service.
  # type: LoadBalancer
  ports:
    - port: 80
  selector:
    app: nginx
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.7.9
        ports:
        - containerPort: 80

  3. Configurez Application Delivery pour appliquer cette configuration de base. Collez le code suivant dans le fichier config/base/kustomization.yaml.

    #config/base/kustomization.yaml

resources:
  - myapp.yaml

Tester et transférer la configuration

  1. Dans le répertoire de votre dépôt d'application, testez votre configuration à l'aide de kustomize build :

    kustomize build config/base/

    Si votre configuration est valide, kustomize affiche le code YAML qui sera déployé dans votre cluster lors de son application.

  2. Une fois le code YAML validé, créez et transférez un commit dans le dépôt d'application :

    git add .
git commit -m "Creating APP_NAME"
git push origin master

Ajouter un environnement de version

Application Delivery déploie votre application dans des environnements. Ajoutez des environnements pour vos versions à l'aide de appctl.

  1. Accédez au répertoire racine du dépôt d'application.

  2. Créez l'environnement à l'aide de appctl :

    appctl env add ENVIRONMENT_NAME \
    --cluster=CLUSTER_NAME

    Remplacez les éléments suivants :

    • ENVIRONMENT_NAME : nom de votre nouvel environnement
    • CLUSTER_NAME : nom du cluster

    appctl crée un commit Git contenant une configuration Kustomize échafaudée.

    Vous pouvez spécifier le nom de l'espace de noms pour un environnement de version de cette application à l'aide de --namespace. Si ce n'est pas le cas, le nom de l'espace de noms par défaut est APP_NAME-ENVIRONMENT_NAME :

    Par exemple, pour ajouter les environnements staging et prod au cluster application-cluster à l'aide du nom de l'espace de noms par défaut, exécutez la commande suivante :

    appctl env add staging --cluster=application-cluster
appctl env add prod --cluster=application-cluster

    Pour ajouter l'environnement test de l'espace de noms test au cluster application-cluster, exécutez la commande suivante :

    appctl env add test --cluster=application-cluster --namespace=test

    Lorsque vous ajoutez un environnement, vous devez déterminer si des demandes d'extraction et des révisions de code sont nécessaires dans le dépôt de déploiement correspondant à cet environnement. Les demandes d'extraction sont créées par défaut. Si l'environnement n'est pas critique pour la production et que l'examen du code n'est pas nécessaire, vous pouvez ignorer la création de demandes d'extraction avec --review-required=false.

    Par exemple, pour ajouter l'environnement test, qui ne nécessite pas de demandes d'extraction, exécutez la commande suivante :

    appctl env add test \
    --cluster=application-cluster \
    --review-required=false

  3. Vous pouvez éventuellement afficher les modifications apportées par Application Delivery dans votre dépôt Git à l'aide de git log :

    git log -p *

  4. Transférez la configuration dans le dépôt d'application :

    git push origin master

Facultatif : Vérifier le dépôt du déploiement

Ouvrez la page GitHub ou GitLab de votre dépôt de déploiement. Par exemple, si votre nom d'utilisateur GitHub est octocat et que vous avez créé une application nommée myapp, l'URL est https://github.com/octocat/myapp-deployment. Sur cette page, vous pouvez consulter les branches créées pour chaque environnement.

Déployer un environnement

Pour déployer un environnement avec Application Delivery, procédez comme suit :

  1. Créez une version à l'aide de git tag, puis transférez ce tag :

    git tag VERSION
git push origin VERSION

    Remplacez VERSION par le numéro de version de votre application.

    Par exemple, pour transférer la version v0.1.0, exécutez les commandes suivantes :

    git tag v0.1.0
git push origin v0.1.0
```

  2. Utilisez appctl prepare pour désigner la version active avec tag et générer une demande d'extraction dans le dépôt de déploiement pour examen.

    appctl prepare ENVIRONMENT_NAME

    Par exemple, pour utiliser l'environnement staging, exécutez la commande suivante :

    appctl prepare staging \
    --validate=true

    Cette commande déclenche la fonction de validation kpt gcr.io/kustomize-functions/example-validator pour valider la modification transmise au dépôt de déploiement.

    kpt est installé à l'aide de la commande gcloud components install pkg. Cette fonction de validation exécute kubeval en arrière-plan, ce qui valide les fichiers de configuration Kubernetes à l'aide de schémas de la spécification OpenAPI de Kubernetes.

    Pour exécuter kpt prepare staging --validate, vous devez installer Docker sur votre machine.

    L'option --validate est désactivée par défaut.

    Si appctl a effectué le commit dans le dépôt de déploiement, il imprime une URL dans une demande d'extraction, comme suit :

    Created a "Pull Request": "https://github.com/octocat/myapp-deployment/pull/[Pull_Request_ID]"

  3. Vérifiez et approuvez la demande d'extraction à l'aide de GitHub ou de GitLab.

  4. Une fois la demande d'extraction approuvée, terminez le déploiement à l'aide de appctl apply :

    appctl apply ENVIRONMENT_NAME

    Remplacez ENVIRONMENT_NAME par le nom de votre environnement.

    Par exemple, pour déployer des modifications dans l'environnement staging, exécutez la commande suivante :

    appctl apply staging

  5. Vérifiez que votre application fonctionne avec kubectl ou depuis la console Google Cloud.

    kubectl

    Utilisez kubectl describe pour afficher l'état de votre application :

    kubectl get releasetracks.app.gke.io APP_NAME \
    --n NAMESPACE \
    -w

    Remplacez les éléments suivants :

    • APP_NAME : nom du dépôt de votre application
    • NAMESPACE : nom de l'espace de noms que vous avez spécifié lors de la création de l'environnement. Si vous n'avez pas spécifié de nom d'espace de noms, la valeur par défaut est APP_NAME-ENVIRONMENT_NAME.

    Par exemple, pour vérifier l'état de l'environnement staging de l'application nommée myapp, exécutez la commande suivante :

    kubectl get releasetracks.app.gke.io myapp -n myapp-staging

    Pour vérifier l'état de l'environnement test ajouté précédemment par env add --namespace test, exécutez la commande suivante :

    kubectl get releasetracks.app.gke.io myapp -n test

    Console

    Pour afficher les informations concernant l'état et la version des applications déployées avec Application Delivery, consultez la page Applications de GKE sur la console Google Cloud.

Promouvoir une version

  1. Pour promouvoir la version finale d'un environnement sur un autre, exécutez la commande suivante :

    appctl prepare TARGET_ENVIRONMENT \
    --from-env=SOURCE_ENVIRONMENT

    Remplacez les éléments suivants :

    • TARGET_ENVIRONMENT : nom de l'environnement dans lequel vous souhaitez déployer la version finale
    • SOURCE_ENVIRONMENT : nom de l'environnement actuel

    Par exemple, pour promouvoir l'environnement staging sur prod, exécutez la commande suivante :

    appctl prepare prod --from-env=staging

  2. Vérifiez et approuvez la demande d'extraction à l'aide de GitHub ou de GitLab.

  3. Pour déployer la version finale dans l'environnement cible, exécutez la commande suivante :

    appctl apply TARGET_ENVIRONMENT

    Par exemple, pour la déployer dans l'environnement prod, exécutez la commande suivante :

    appctl apply prod

Afficher les environnements dans la console Google Cloud

Une fois l'application d'un environnement déployée, vous pouvez l'afficher sur la page des applications GKE. Cette page contient une liste d'applications avec leurs environnements indiqués entre parenthèses. Voici une capture d'écran d'une application myapp avec deux environnements staging et prod. L'espace de noms, le cluster et la version de chaque environnement sont également affichés sur cette page.

Capture d'écran de la page de l'application

Pour afficher les détails de l'application, tels que le tag git, les composants et la liste des environnements, cliquez sur le nom de l'application. La capture d'écran suivante montre les détails de myapp.

Capture d'écran de la page de détails de l'application

Modifier la configuration d'un environnement

Dans cette section, nous partons du principe que vous disposez d'un environnement staging configuré comme dans les étapes précédentes. Vous devrez peut-être adapter ces instructions à votre utilisation.

Dans cette section, vous allez modifier les paramètres de l'environnement staging à l'aide d'une superposition Kustomize. Après avoir effectué les modifications, vous allez les transférer et y ajouter des tags dans Git. Application Delivery mettra à jour votre cluster.

  1. Créez un fichier nommé config/envs/staging/patch-replicas.yaml et copiez-y le texte suivant. Cela permet de mettre à jour la configuration dans l'environnement staging afin d'exécuter une instance dupliquée au lieu de trois.

    #config/envs/staging/patch-replicas.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 1

  2. Modifiez le fichier config/envs/staging/kustomization.yaml et ajoutez patch-replicas.yaml à une nouvelle collection nommée patchesStrategicMerge.

    #config/envs/staging/kustomization.yaml
namespace: myapp-staging
bases:
   - ../../base
patchesStrategicMerge:
   - patch-replicas.yaml

    Vous pouvez également ajouter des annotations spécifiques à l'environnement dans cette superposition. L'exemple suivant ajoute une annotation nommée oncall-team pour ajouter toutes les ressources de cet environnement. Pour en savoir plus, consultez la page Kustomize file fields.

    #config/envs/staging/kustomization.yaml

#Don't change the namespace field
namespace: myapp-staging
bases:
   - ../../base
patchesStrategicMerge:
   - patch-replicas.yaml
commonAnnotations:
  oncall-team: staging-oncall@foo.bar

  3. Testez votre configuration à l'aide de kustomize build :

    kustomize build config/envs/staging/

  4. Ajoutez et validez vos modifications.

    git add .
git commit -m "<var>COMMIT_MESSAGE</var>"
git push origin master

    Remplacez COMMIT_MESSAGE par un message décrivant vos modifications.

  5. Créez une version à l'aide de git tag, puis transférez-la.

    git tag VERSION
git push origin VERSION

    Remplacez VERSION par le numéro de version souhaité.

  6. Utilisez appctl prepare pour générer une demande d'extraction dans le dépôt de déploiement pour examen :

    appctl prepare ENVIRONMENT_NAME

  7. Suivez le lien pour créer une demande d'extraction GitHub ou GitLab.

  8. Examinez le contenu de la requête d'extraction. Application Delivery modifie une ligne qui définit la valeur de replicas sur 1.

  9. Approuvez la demande d'extraction avec GitHub ou GitLab.

  10. Utilisez appctl apply pour appliquer les modifications :

    appctl apply staging

Effectuer un rollback des modifications de la configuration

Pour effectuer un rollback vers une version précédente, exécutez la commande suivante :

appctl apply TARGET_ENVIRONMENT \
    --from-tag GIT_TAG

Remplacez les éléments suivants :

  • TARGET_ENVIRONMENT : nom de l'environnement dans lequel vous souhaitez déployer la version.
  • GIT_TAG : nom du tag pour la version

Utiliser appctl dans les scripts

L'outil appctl est interactif et attend une entrée utilisateur par défaut. Si vous souhaitez exécuter appctl dans un script, un conteneur ou des pipelines, définissez la variable d'environnement APPCTL_INTERACTIVE sur false.

Par exemple, dans l'interface système bash, exécutez la commande suivante :

export APPCTL_INTERACTIVE=false

Vous pouvez obtenir des informations sur des commandes appctl spécifiques à l'aide de la commande appctl help command. Par exemple, pour obtenir de l'aide sur appctl prepare, exécutez appctl help prepare.

Désinstaller le gestionnaire d'applications

Pour supprimer l'application exécutée dans votre cluster, vous devez supprimer tous les espaces de noms créés avec de nouveaux environnements.

Répétez les commandes suivantes pour tous vos environnements et clusters :

  1. Basculez vers le cluster d'un environnement donné :

    kubectl config use-context ENVIRONMENT_CLUSTER_NAME

    Remplacez ENVIRONMENT_CLUSTER_NAME par le nom du cluster dans l'environnement sélectionné.

  2. Supprimez l'espace de noms dans lequel l'application de cet environnement est exécutée :

    kubectl delete ns NAMESPACE

    Remplacez NAMESPACE par le nom de l'espace de noms que vous souhaitez supprimer. La valeur par défaut est APP_NAME-ENVIRONMENT_NAME.

  3. Dans GitHub ou GitLab, supprimez les deux dépôts Git créés par appctl.

  4. Supprimez le répertoire d'application local :

    rm -rf myapp/

  5. Vous pouvez désactiver Application Delivery dans votre cluster à partir de gcloud ou de Google Cloud Console :

    gcloud

    gcloud beta container clusters update CLUSTER_NAME \
    --update-addons ApplicationManager=DISABLED

    Console

    1. Accédez à la page Google Kubernetes Engine dans Google Cloud Console.

      Accéder à Google Kubernetes Engine

    2. Dans la liste des clusters, cliquez sur le nom du cluster que vous souhaitez modifier.

    3. Sous Fonctionnalités, à côté du champ Gestionnaire d'applications, cliquez sur Modifier le gestionnaire d'applications.

    4. Décochez la case Activer le gestionnaire d'applications.

    5. Cliquez sur Save Changes (Enregistrer les modifications).

Étape suivante

Apprenez-en plus sur Kustomize.