Administrar aplicaciones con la entrega de aplicaciones


En esta página, se explica cómo configurar una implementación de NGINX con Application Delivery. La implementación se ejecuta en dos entornos: staging y prod. El entorno prod usa una configuración regular, mientras que staging usa una ligeramente modificada.

Requisitos

Para completar este instructivo, necesitarás lo siguiente:

  • La versión 2.19.2 o una posterior de Git instalada de manera local
  • Una cuenta de GitHub o GitLab con permisos para crear un repositorio privado. Application Delivery solo admite repositorios de GitHub y GitLab
  • Un clúster que ejecute la versión 1.15 de GKE o una versión posterior.
  • Un usuario con privilegios de clusterAdmin
  • Kustomize instalado de forma local. Puedes seguir la guía de instalación.
  • Si deseas validar tus archivos de configuración de Kubernetes en el repositorio de implementación, debes instalar Docker.

Antes de comenzar

Antes de comenzar, asegúrate de haber realizado las siguientes tareas:

  • Asegúrate de que habilitaste la API de Google Kubernetes Engine.
  • Habilitar la API de Google Kubernetes Engine
  • Asegúrate de que instalaste el SDK de Cloud.
  • Establece la configuración predeterminada de la herramienta de línea de comandos de gcloud para tu proyecto mediante uno de los siguientes métodos:
    • Usa gcloud init si deseas ver una explicación sobre cómo configurar los valores predeterminados del proyecto.
    • Usa gcloud config para configurar el ID, la zona y la región del proyecto de manera individual.

    gcloud init

    1. Ejecuta gcloud init y sigue las instrucciones:

      gcloud init

      Si usas SSH en un servidor remoto, usa la marca --console-only para evitar que el comando abra un navegador:

      gcloud init --console-only
    2. Sigue las instrucciones para autorizar a la herramienta de gcloud a usar tu cuenta de Google Cloud.
    3. Crea una configuración nueva o selecciona una existente.
    4. Elige un proyecto de Google Cloud.
    5. Elige una zona de Compute Engine predeterminada.
    6. Elige una región de Compute Engine predeterminada.

    gcloud config

    1. Establece tu ID del proyecto predeterminado:
      gcloud config set project PROJECT_ID
    2. Configura la región de Compute Engine predeterminada (por ejemplo, us-central1):
      gcloud config set compute/region COMPUTE_REGION
    3. Configura la zona de Compute Engine predeterminada (por ejemplo, us-central1-c):
      gcloud config set compute/zone COMPUTE_ZONE
    4. Actualiza gcloud a la versión más reciente:
      gcloud components update

    Cuando configuras las ubicaciones predeterminadas, puedes evitar errores en la herramienta gcloud como el siguiente: One of [--zone, --region] must be supplied: Please specify location.

  • Agrega llaves SSH a tu cuenta de GitHub o GitLab.
  • Prueba tus llaves con ssh:

    GitHub

    sh ssh -T git@github.com

    GitLab

    sh ssh -T git@gitlab.com

    Es posible que se te solicite que confirmes los detalles de conexión o tu frase de contraseña de la clave. Si la conexión se realiza correctamente, se imprimirá un mensaje en la terminal.

Configura Application Delivery

Para usar Application Delivery, debes hacer lo siguiente:

  1. Crea un clúster nuevo con Application Delivery habilitada, o habilítala en un clúster de GKE existente que ejecute la versión 1.15 o superior.
  2. Instala appctl, la herramienta de línea de comandos de entrega de aplicaciones.

Crea un clúster nuevo con Application Delivery

Puedes crear un clúster nuevo con Application Delivery habilitada mediante la herramienta de gcloud o Cloud Console.

gcloud

Crea un clúster:

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

Reemplaza lo siguiente:

  • CLUSTER_NAME: Es el nombre del clúster nuevo.
  • CLUSTER_VERSION: es la versión del clúster nuevo. Debe ser GKE 1.15 o superior.

Console

  1. Ve a la página Google Kubernetes Engine en Cloud Console.

    Ir a Google Kubernetes Engine

  2. Haz clic en Crear.

  3. En la sección Estándar, haz clic en Configurar.

  4. Especifica un Nombre para tu clúster.

  5. Elige una versión del plano de control de 1.15.x o superior.

  6. Configura tu clúster como desees.

  7. En el panel de navegación, en Clúster, haz clic en Funciones.

  8. Selecciona la casilla de verificación Habilitar administrador de aplicaciones.

  9. Haga clic en Crear.

Habilita Application Manager en un clúster existente

Puedes habilitar Application Manager en un clúster existente con la herramienta de gcloud o Cloud Console.

gcloud

Para habilitar Application Delivery en un clúster existente, ejecuta el siguiente comando:

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

Reemplaza CLUSTER_NAME por el nombre del clúster existente.

Console

  1. Ve a la página de Google Kubernetes Engine en Cloud Console:

    Ir a Google Kubernetes Engine

  2. En la lista de clústeres, haz clic en el nombre del clúster que deseas modificar.

  3. En Funciones, junto al campo Administrador de aplicaciones, haz clic en Editar administrador de aplicaciones.

  4. Selecciona la casilla de verificación Habilitar administrador de aplicaciones.

  5. Haz clic en Guardar cambios.

Confirma la instalación

Para comprobar el estado de instalación de Application Delivery, realiza lo siguiente:

  1. Verifica el estado de la implementación:

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

    El resultado es similar al siguiente:

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

    Debería haber dos pods disponibles en este Deployment application-controller-manager.

  2. Comprueba el estado del StatefulSet:

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

    El resultado es similar al siguiente:

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

    Debería haber un pod listo en este StatefulSet kalm-controller-manager.

Instala appctl

Para instalar la herramienta de línea de comandos de Application Delivery appctl, usa la herramienta de gcloud a fin de instalar pkg.

gcloud components install pkg

Después de habilitar Application Delivery en un clúster y de instalar pkg, estás listo para implementar tu primera aplicación.

Implementar una aplicación

Para implementar una aplicación, haz lo siguiente:

  1. Crea repositorios de Git nuevos o inicializa repositorios existentes.
  2. Crear una configuración básica
  3. Crear uno o más entornos para la implementación.
  4. También tienes la opción de aplicar superposiciones de configuración a tus entornos en el repositorio de tu aplicación
  5. Crear una versión candidata en forma de solicitud de extracción o combinación
  6. Implementa tu versión.

Crear repositorios nuevos

Crea repositorios para la entrega de aplicaciones en GitHub o GitLab con appctl.

  1. Cambia al directorio en el que deseas crear el directorio de tu aplicación.
  2. Crea tus repositorios de Application Delivery con appctl.

    GitHub

    Ejecuta el siguiente comando:

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

    Reemplaza lo siguiente:

    • APP_NAME: El nombre de tu aplicación.
    • USERNAME: es tu nombre de usuario de GitHub.

    Por ejemplo, si tu nombre de usuario de GitHub es octocat y quieres crear una aplicación llamada myapp, ejecuta lo siguiente:

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

    GitLab

    Ejecuta el siguiente comando:

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

    Reemplaza lo siguiente:

    • APP_NAME: El nombre de tu aplicación.
    • USERNAME: es tu nombre de usuario de GitLab.

    Por ejemplo, si tu nombre de usuario de GitLab es alice y quieres crear una aplicación llamada myapp, ejecuta lo siguiente:

    appctl init myapp \
        --app-config-repo=gitlab.com/alice/myapp
    
  3. appctl te solicita que confirmes tus repositorios privados nuevos.

appctl crea dos repositorios de Git privados remotos:

  • El repositorio de la aplicación github.com/USERNAME/APP_NAME. Este repositorio se clona en el directorio actual.
  • El repositorio de implementación github.com/USERNAME/APP_NAME-deployment. El repositorio de implementación local se almacena en ./APP_NAME/.deployment.

Para obtener más información sobre el contenido y la estructura de estos repositorios, consulta la guía conceptual de Application Delivery.

Inicializa repositorios existentes

Si tienes repositorios existentes, puedes inicializar los repositorios para la entrega de aplicaciones en GitHub o GitLab con appctl.

  1. Cambia al directorio donde deseas crear el directorio de tu aplicación.

  2. Ejecuta el comando appctl init, que crea un directorio llamado APP_NAME y clona tu repositorio allí.

    El comando appctl init inicializa una capa base de Kustomize en los archivos de configuración almacenados en el directorio ./config del repositorio. Puedes especificar una ruta de configuración diferente con la marca --config-path.

    De forma predeterminada, appctl init usa github.com/USERNAME/APP_NAME-deployment como la URL del repositorio de implementación. Puedes usar la marca --deployment-repo para especificar una URL diferente. Si el repositorio de implementación no existe, el comando appctl creará uno.

    GitHub

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

    Reemplaza lo siguiente:

    • APP_NAME: El nombre de tu aplicación.
    • USERNAME: es tu nombre de usuario de GitHub.
    • CONFIG_PATH: es la ruta de acceso opcional al directorio de configuración de tu repositorio. Si se omite, el valor predeterminado es ./config.

    Por ejemplo, si el repositorio de configuración de la aplicación existente es https://github.com/octocat/myapp y esperas que el repositorio de implementación sea https://github.com/octocat/myapp-deploy, ejecuta el siguiente comando:

    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]
    

    Reemplaza lo siguiente:

    • APP_NAME: El nombre de tu aplicación.
    • USERNAME: es tu nombre de usuario de GitLab.
    • CONFIG_PATH: es la ruta de acceso opcional al directorio de configuración de tu repositorio. Si se omite, el valor predeterminado es ./config.

    Por ejemplo, si el repositorio de configuración de la aplicación existente es gitlab.com/alice/myapp, ejecuta el siguiente comando:

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

Crea una configuración básica

  1. Cambia tu directorio de trabajo a tu repositorio de aplicaciones.

  2. Crea la configuración para tu carga de trabajo de Kubernetes. Puede ser cualquier implementación de Kubernetes válida.

    La siguiente configuración define una aplicación llamada nginx, que implementa 3 réplicas del contenedor nginx. Copia la configuración en el archivo config/base/myapp.yaml. Si desea habilitar un LoadBalancer, quita el comentario de la línea 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. Configura Application Delivery para aplicar esta configuración a la base. Pega lo siguiente en config/base/kustomization.yaml.

    #config/base/kustomization.yaml
    
    resources:
      - myapp.yaml
    

Prueba y envía tu configuración

  1. En el directorio del repositorio de la aplicación, prueba tu configuración con kustomize build:

    kustomize build config/base/
    

    Si la configuración es válida, kustomize imprime el YAML que se implementará en tu clúster cuando se aplique.

  2. Una vez que hayas validado tu YAML, crea y envía una confirmación en el repositorio de tu aplicación.

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

Agrega un entorno de actualización

Application Delivery implementa tu aplicación en entornos. Puedes agregar entornos para tus actualizaciones con appctl.

  1. Cambia al directorio raíz del repositorio de la aplicación.

  2. Crea tu entorno con appctl:

    appctl env add ENVIRONMENT_NAME \
        --cluster=CLUSTER_NAME
    

    Reemplaza lo siguiente:

    • ENVIRONMENT_NAME: es el nombre de tu entorno nuevo.
    • CLUSTER_NAME: El nombre de tu clúster.

    appctl crea una confirmación de Git que contiene una configuración de Kustomize respaldada.

    Puedes especificar el nombre del espacio de nombres para un entorno de actualización de esta aplicación con --namespace. De lo contrario, el espacio de nombres predeterminado será APP_NAME-ENVIRONMENT_NAME:

    Por ejemplo, para agregar los entornos staging y prod al clúster application-cluster mediante el nombre del espacio de nombres predeterminado, ejecuta el siguiente comando:

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

    Para agregar el entorno test en el espacio de nombres test al clúster application-cluster, ejecuta el siguiente comando:

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

    Cuando agregas un entorno, debes evaluar si se necesitan solicitudes de extracción y revisiones de código en el repositorio de implementación para este entorno. De forma predeterminada, se crean solicitudes de extracción. Si el entorno no es fundamental para la producción y no es necesaria la revisión del código, puedes omitir la creación de solicitudes de extracción con --review-required=false.

    Por ejemplo, para agregar el entorno test, que no requiere solicitudes de extracción, ejecuta el siguiente comando:

    appctl env add test \
        --cluster=application-cluster \
        --review-required=false
    
  3. De manera opcional, visualiza los cambios que realizó Application Delivery en tu repositorio de Git con git log.

    git log -p *
    
  4. Envía la configuración al repositorio de tu aplicación.

    git push origin master
    

Opcional: Comprobar el repositorio de implementación

Abre la página de GitHub o GitLab para tu repositorio de implementación. Por ejemplo, si tu nombre de usuario de GitHub es octocat y creaste una aplicación llamada myapp, la URL es https://github.com/octocat/myapp-deployment. Desde esta página, puedes ver las ramas que se crearon para cada entorno.

Implementa un entorno

Para implementar un entorno con la entrega de aplicaciones, realiza lo siguiente:

  1. Crea una versión con git tag y envía esa etiqueta.

    git tag VERSION
    git push origin VERSION
    

    Reemplaza VERSION por el número de versión de la aplicación.

    Por ejemplo, para enviar la versión v0.1.0, ejecuta los siguientes comandos:

    git tag v0.1.0
    git push origin v0.1.0
    ```
    
  2. Usa appctl prepare a fin de nominar la versión etiquetada y generar una solicitud de extracción en el repositorio de implementación para revisión.

    appctl prepare ENVIRONMENT_NAME
    

    Por ejemplo, para usar el entorno staging, ejecuta el siguiente comando:

    appctl prepare staging \
        --validate=true
    

    Este comando activa la función de validación de kpt gcr.io/kustomize-functions/example-validator para validar el cambio que se envía al repositorio de implementación.

    gcloud components install pkg instala kpt. Esta función de validación ejecuta kubeval de forma interna, lo que valida los archivos de configuración de Kubernetes mediante esquemas de la especificación de OpenAPI de Kubernetes.

    Para ejecutar kpt prepare staging --validate, debes instalar Docker en tu máquina.

    De forma predeterminada, la marca --validate está inhabilitada.

    Si appctl completó la confirmación en el repositorio de implementación, imprime una URL en una solicitud de extracción, como la que se muestra a continuación:

    Created a "Pull Request": "https://github.com/octocat/myapp-deployment/pull/[Pull_Request_ID]"
    
  3. Usa GitHub o GitLab para revisar y aprobar la solicitud de extracción.

  4. Una vez que se apruebe la solicitud de extracción, usa appctl apply para completar la implementación.

    appctl apply ENVIRONMENT_NAME
    

    Reemplaza ENVIRONMENT_NAME por el nombre del clúster.

    Por ejemplo, para implementar los cambios en el entorno staging, ejecuta el siguiente comando:

    appctl apply staging
    
  5. Confirma que tu aplicación se esté ejecutando con kubectl o desde Cloud Console.

    kubectl

    Usa kubectl describe para ver el estado de tu aplicación.

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

    Reemplaza lo siguiente:

    • APP_NAME: Es el nombre del repositorio de tu aplicación.
    • NAMESPACE: es el nombre del espacio de nombres que especificaste cuando creaste el entorno. Si no especificaste un nombre del espacio de nombres, el valor predeterminado es APP_NAME-ENVIRONMENT_NAME.

    Por ejemplo, para verificar el estado del entorno staging de la aplicación llamada myapp, ejecuta el siguiente comando:

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

    Para verificar el estado del entorno test que env add --namespace test agregó antes, ejecuta el siguiente comando:

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

    Console

    Para ver el estado y la información de la versión de las aplicaciones implementadas con Application Delivery, consulta la página de aplicaciones de GKE en Cloud Console.

Promueve una actualización

  1. Para promover una versión candidata de un entorno a otro, ejecuta el siguiente comando:

    appctl prepare TARGET_ENVIRONMENT \
        --from-env=SOURCE_ENVIRONMENT
    

    Reemplaza lo siguiente:

    • TARGET_ENVIRONMENT: es el nombre del entorno en el que deseas implementar la versión candidata para el lanzamiento.
    • SOURCE_ENVIRONMENT: Es el nombre del entorno actual.

    Por ejemplo, para promover staging a prod ejecuta lo siguiente:

    appctl prepare prod --from-env=staging
    
  2. Usa GitHub o GitLab para revisar y aprobar la solicitud de extracción.

  3. Para implementar la versión candidata en el entorno de destino, ejecuta el siguiente comando:

    appctl apply TARGET_ENVIRONMENT
    

    Por ejemplo, para implementar en el entorno prod, ejecuta el siguiente comando:

    appctl apply prod
    

Visualiza entornos en Cloud Console

Una vez que se implementa la aplicación de un entorno, puedes verla en la página Aplicaciones de GKE. Esta página contiene una lista de aplicaciones con sus entornos marcados entre paréntesis. A continuación, se muestra una captura de pantalla de una aplicación myapp con dos entornos staging y prod. El espacio de nombres, el clúster y la versión de cada entorno también se muestran en esta página.

Una captura de pantalla de la página de la aplicación.

Para ver los detalles de la aplicación, como la etiqueta git, los componentes y la lista de entornos, haz clic en el nombre de la aplicación. La siguiente captura de pantalla muestra los detalles de myapp.

Una captura de pantalla de la página de detalles de la aplicación.

Cambia la configuración de un entorno

En esta sección, se supone que tienes un entorno staging configurado como en los pasos anteriores. Es posible que debas adaptar estas instrucciones para tu situación.

En esta sección, se cambian los parámetros del entorno staging mediante una superposición kustomize. Después de realizar el cambio, envía y etiqueta tus cambios en Git. Application Delivery actualizará tu clúster.

  1. Crea un archivo llamado config/envs/staging/patch-replicas.yaml y copia el siguiente texto en él. Esto actualiza la configuración en el entorno staging para ejecutar una réplica en lugar de tres.

    #config/envs/staging/patch-replicas.yaml
    
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: nginx
    spec:
      replicas: 1
    
  2. Edita el archivo config/envs/staging/kustomization.yaml y agrega patch-replicas.yaml a una colección nueva llamada patchesStrategicMerge.

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

    También puedes agregar anotaciones específicas del entorno en esta superposición. En el siguiente ejemplo, se agrega una anotación llamada oncall-team para incorporar todos los recursos de este entorno. Para obtener más información, consulta Campos del archivo de Kustomize.

    #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. Prueba tu configuración con kustomize build:

    kustomize build config/envs/staging/
    
  4. Agrega y confirma tus cambios.

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

    Reemplaza COMMIT_MESSAGE con un mensaje que describa tus cambios.

  5. Crea una versión con git tag y envíala.

    git tag VERSION
    git push origin VERSION
    

    Reemplaza VERSION por el número de versión que desees.

  6. Usa appctl prepare a fin de generar una solicitud de extracción en el repositorio de implementación para revisión.

    appctl prepare ENVIRONMENT_NAME
    
  7. Sigue el vínculo para crear una solicitud de extracción de GitHub o GitLab.

  8. Revisa el contenido de tu solicitud de extracción. Application Delivery realiza un cambio de una línea que establece el valor de replicas en 1.

  9. Aprueba la solicitud de extracción con GitHub o GitLab.

  10. Usa appctl apply para aplicar los cambios:

    appctl apply staging
    

Revierte los cambios de configuración

Para revertir a una versión anterior, ejecuta el siguiente comando:

appctl apply TARGET_ENVIRONMENT \
    --from-tag GIT_TAG

Reemplaza lo siguiente:

  • TARGET_ENVIRONMENT: es el nombre del entorno en el que deseas implementar la versión.
  • GIT_TAG: Es el nombre de la etiqueta para la versión.

Usa appctl en secuencias de comandos

La herramienta appctl es interactiva y espera la entrada del usuario de forma predeterminada. Si desea ejecutar appctl en una secuencia de comandos, un contenedor o canalizaciones, establece la variable de entorno APPCTL_INTERACTIVE en false.

Por ejemplo, en el shell Bash, ejecuta el siguiente comando.

export APPCTL_INTERACTIVE=false

La información sobre comandos appctl específicos está disponible con appctl help command. Por ejemplo, para obtener ayuda con appctl prepare, ejecuta appctl help prepare.

Desinstala Application Manager

Para quitar la aplicación que se ejecuta en tu clúster, borra todos los espacios de nombres creados con entornos nuevos.

Para todos tus entornos y clústeres, repite los siguientes comandos:

  1. Cambiar al clúster a un entorno determinado

    kubectl config use-context ENVIRONMENT_CLUSTER_NAME
    

    Reemplaza ENVIRONMENT_CLUSTER_NAME por el nombre del clúster en el entorno seleccionado.

  2. Borrar el espacio de nombres en que se ejecuta tu aplicación para este entorno

    kubectl delete ns NAMESPACE
    

    Reemplaza NAMESPACE por el nombre del espacio de nombres que deseas borrar. El predeterminado es APP_NAME-ENVIRONMENT_NAME.

  3. En GitHub o GitLab, borra los dos repositorios de Git creados por appctl.

  4. Borra el directorio de tu aplicación local:

    rm -rf myapp/
    
  5. Puedes inhabilitar Application Delivery en tu clúster desde gcloud o Cloud Console:

    gcloud

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

    Console

    1. Ve a la página de Google Kubernetes Engine en Cloud Console:

      Ir a Google Kubernetes Engine

    2. En la lista de clústeres, haz clic en el nombre del clúster que deseas modificar.

    3. En Funciones, junto al campo Administrador de aplicaciones, haz clic en Editar administrador de aplicaciones.

    4. Desactiva la casilla de verificación Habilitar el administrador de aplicaciones.

    5. Haz clic en Guardar cambios.

¿Qué sigue?

Obtén más información sobre Kustomize.