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 :

Configurez les paramètres gcloud par défaut à l'aide de l'une des méthodes suivantes :

  • Utilisez gcloud init pour suivre les instructions permettant de définir les paramètres par défaut.
  • Utilisez gcloud config pour définir individuellement l'ID, la zone et la région de votre projet.

Utiliser gcloud init

Si le message d'erreur One of [--zone, --region] must be supplied: Please specify location s'affiche, effectuez les tâches ci-dessous.

  1. Exécutez gcloud init et suivez les instructions :

    gcloud init

    Si vous utilisez SSH sur un serveur distant, utilisez l'option --console-only pour empêcher la commande d'ouvrir un navigateur :

    gcloud init --console-only
  2. Suivez les instructions pour autoriser gcloud à utiliser votre compte Google Cloud.
  3. Créez ou sélectionnez une configuration.
  4. Choisissez un projet Google Cloud.
  5. Choisissez une zone Compute Engine par défaut pour les clusters zonaux ou une région pour les clusters régionaux ou Autopilot.

Utiliser gcloud config

  • Définissez votre ID de projet par défaut :
    gcloud config set project PROJECT_ID
  • Si vous utilisez des clusters zonaux, définissez votre zone de calcul par défaut :
    gcloud config set compute/zone COMPUTE_ZONE
  • Si vous utilisez des clusters Autopilot ou régionaux, définissez votre région de calcul par défaut :
    gcloud config set compute/region COMPUTE_REGION
  • Mettez à jour gcloud vers la dernière version :
    gcloud components update
  • Ajoutez des clés SSH à votre compte GitHub ou GitLab.
  • Testez vos clés avec ssh :

    GitHub

    ssh -T git@github.com

    GitLab

    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 effectuer les tâches suivantes :

  1. Créez un cluster sur lequel il 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 avec Application Delivery activé à l'aide de gcloud ou de Cloud Console.

gcloud

Spécifiez un cluster version 1.15.x ou ultérieure :

gcloud beta container clusters create cluster-name \
    --cluster-version cluster-version --addons ApplicationManager

Console

  1. Accédez au menu Google Kubernetes Engine de Cloud Console.

    Accéder au menu Google Kubernetes Engine

  2. Cliquez sur Créer.

  3. Spécifiez le nom du cluster.

  4. Sélectionnez une version maître 1.15 ou ultérieure.

  5. Configurez le cluster selon vos besoins.

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

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

  8. Cliquez sur Créer.

Activer Application Delivery sur un cluster existant

Vous pouvez activer Application Delivery sur un cluster existant à l'aide de gcloud ou de Cloud Console.

gcloud

gcloud beta container clusters update cluster-name \
    --update-addons ApplicationManager=ENABLED

Console

  1. Accédez au menu Google Kubernetes Engine de Cloud Console.

    Accéder au menu 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

Vous devez installer pkg, qui inclut l'outil de ligne de commande Application Delivery appctl, à l'aide de gcloud.

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, vous allez effectuer les tâches suivantes :

  1. Créer des dépôts Git ou initialiser des dépôts existants
  2. Créer 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

    appctl init application-name \
      --app-config-repo=github.com/user-name/application-name

    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

    appctl init application-name \
      --app-config-repo=gitlab.com/user-name/application-name

    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/user-name/application-name. Ce dépôt est cloné dans le répertoire actif.
  • Le dépôt de déploiement github.com/user-name/application-name-deployment. Le dépôt de déploiement local est stocké dans ./application-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é application-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/user-name/application-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 application-name \
        --app-config-repo=github.com/user-name/application-name \
        [--config-path=config-path]

    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 application-name \
      --app-config-repo=gitlab.com/user-name/application-name \
      [--config-path=config-path]

    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. Par exemple, si vous avez utilisé le nom d'application myapp, exécutez la commande suivante :

    cd myapp
  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 application-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 (par exemple, cd myapp).
  2. Créez l'environnement à l'aide de appctl :

    appctl env add environment-name --cluster=cluster-name

    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. Dans le cas contraire, le nom de l'espace de noms par défaut est application-name - environment-name. Par exemple, pour ajouter les environnements staging et prod au cluster application-cluster en utilisant le 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 dans 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 la création de demandes d'extraction.

    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

    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]](https://docs.docker.com/engine/install/){:external} sur votre machine.

    Par défaut, l'option "--validate" est désactivée.

    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

    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 s'exécute avec kubectl ou depuis Cloud Console.

    kubectl

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

     kubectl get releasetracks.app.gke.io application-name -n \
         [application-name-environment-name or customized_namespace`] -w

    Remplacez les éléments suivants :

    • application-name : nom du dépôt de votre application
    • environment-name : nom de votre environnement
    • customized_namespace : nom de l'espace de noms spécifié précédemment dans env add

    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 Cloud Console.

Promouvoir une version

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

    appctl prepare target-environment-name \
        --from-env source-environment-name

    Remplacez les éléments suivants :

    • target-environment-name : nom de l'environnement dans lequel vous souhaitez déployer la version finale
    • source-environment-name : 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-name

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

    appctl apply prod

Afficher les environnements dans Cloud Console

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 "commit-message"
    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
  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-name --from-tag git-tag

Remplacez les éléments suivants :

  • target-environment-name : 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. Par défaut, il attend que l'internaute saisisse les données. 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 ${CONTEXT_OF_ENV_CLUSTER}
  2. Supprimez l'espace de noms dans lequel l'application de cet environnement est exécutée :

     kubectl delete ns [application-name-environment-name or customized_namespace`]

    Remplacez les éléments suivants :

    • application-name : nom du dépôt de votre application
    • environment-name : nom de votre environnement
    • customized_namespace : nom de l'espace de noms spécifié précédemment dans env add
  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 Cloud Console :

    gcloud

    gcloud beta container clusters update cluster-name \
    --update-addons ApplicationManager=DISABLED

    Console

    1. Accédez au menu Google Kubernetes Engine de Cloud Console.

      Accéder au menu 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.