Acerca de los objetivos personalizados

En este documento se describe cómo funcionan los destinos personalizados en Cloud Deploy.

Cloud Deploy incluye compatibilidad integrada con varios entornos de tiempo de ejecución como destinos. Sin embargo, la lista de tipos de segmentación admitidos es finita. Con los segmentos personalizados, puedes implementar en otros sistemas además de los tiempos de ejecución admitidos.

Un destino personalizado es un destino que representa un entorno de salida arbitrario distinto de un tiempo de ejecución compatible con Cloud Deploy.

En la página Crear un destino personalizado se describe el proceso para definir un tipo de destino personalizado e implementarlo como destino en un proceso de distribución.

¿Qué se tiene en cuenta en un objetivo personalizado?

Cada segmentación personalizada consta de los siguientes componentes:

  • Acciones personalizadas, definidas en skaffold.yaml

    Son similares a los hooks de implementación. En el archivo skaffold.yaml, se define customActions, donde cada acción personalizada identifica una imagen de contenedor que se va a usar y los comandos que se van a ejecutar en ese contenedor.

    De esta forma, el objetivo personalizado es simplemente una acción o un conjunto de acciones definidas por el usuario.

    En el caso de los tipos de segmentación personalizados, se configuran una acción de renderización personalizada y una acción de implementación personalizada. Estas acciones consumen los valores proporcionados por Cloud Deploy y deben cumplir un conjunto de resultados obligatorios.

    La acción de renderizado personalizado es opcional, pero debes crear una a menos que tu destino personalizado funcione correctamente si se renderiza con skaffold render, que es el valor predeterminado de Cloud Deploy.

  • Una definición de tipo de segmentación personalizada

    El CustomTargetType es un recurso de Cloud Deploy que identifica las acciones personalizadas (definidas por separado en tu skaffold.yaml) que usan los destinos de este tipo para las actividades de renderización de versiones y de despliegue de lanzamientos.

  • Una definición de objetivo

    La definición de un objetivo personalizado es la misma que la de cualquier tipo de objetivo, excepto que incluye la propiedad customTarget, cuyo valor es el nombre de CustomTargetType.

Con estos componentes, puedes usar el destino como cualquier otro, hacer referencia a él desde la progresión de tu canalización de entrega y aprovechar al máximo las funciones de Cloud Deploy, como la promoción y las aprobaciones, y las restauraciones.

Ejemplo

En la guía de inicio rápido Define y usa un tipo de segmentación personalizada, se crea un tipo de segmentación personalizada que incluye comandos sencillos para ejecutar en una imagen de contenedor: un comando para renderizar y otro para desplegar. En este caso, los comandos solo añaden texto a los archivos de salida necesarios para renderizar y desplegar.

Para ver más ejemplos, consulte Ejemplos de segmentación personalizada.

Entradas y salidas obligatorias

Cualquier tipo de destino personalizado definido para Cloud Deploy debe cumplir los requisitos de entrada y salida, tanto para la renderización como para la implementación. En esta sección se indican las entradas y salidas necesarias, así como la forma de proporcionarlas.

Cloud Deploy proporciona las entradas necesarias, tanto para el renderizado como para el despliegue, como variables de entorno. En las siguientes secciones se enumeran estas entradas, así como las salidas que deben devolver las acciones de renderización e implementación personalizadas.

Desplegar parámetros como variables de entorno

Además de las variables de entorno que se indican en esta sección, Cloud Deploy puede transferir a tus contenedores personalizados cualquier parámetro de implementación que hayas definido.

Más información

Entradas para renderizar acciones

En el caso de las acciones de renderización personalizadas, Cloud Deploy proporciona las siguientes entradas como variables de entorno. En las implementaciones por fases (implementaciones canary), Cloud Deploy proporciona estas variables para cada fase.

  • CLOUD_DEPLOY_PROJECT

    El Google Cloud número del proyecto en el que se crea el objetivo personalizado.

  • CLOUD_DEPLOY_PROJECT_ID

    El Google Cloud ID del proyecto.

  • CLOUD_DEPLOY_LOCATION

    La Google Cloud región del tipo de segmentación personalizada.

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

    Nombre del flujo de procesamiento de entrega de Cloud Deploy que hace referencia al tipo de destino personalizado.

  • CLOUD_DEPLOY_RELEASE

    Nombre de la versión para la que se invoca la operación de renderización.

  • CLOUD_DEPLOY_TARGET

    Nombre del destino de Cloud Deploy que usa el tipo de destino personalizado.

  • CLOUD_DEPLOY_PHASE

    La fase de lanzamiento a la que corresponde la renderización.

  • CLOUD_DEPLOY_REQUEST_TYPE

    En el caso de la acción de renderización personalizada, este valor siempre es RENDER.

  • CLOUD_DEPLOY_FEATURES

    Lista separada por comas de las funciones de Cloud Deploy que debe admitir el contenedor personalizado. Esta variable se rellena en función de las funciones configuradas en tu flujo de procesamiento de entrega.

    Si tu implementación no admite las funciones de esta lista, te recomendamos que falle durante el renderizado.

    En las implementaciones estándar, este campo está vacío. En las implementaciones canary, el valor es CANARY. Si el valor proporcionado por Cloud Deploy es CANARY, tu acción de renderizado se invoca para cada fase del lanzamiento canary. El porcentaje de lanzamiento de la versión canary de cada fase se proporciona en la variable de entorno CLOUD_DEPLOY_PERCENTAGE_DEPLOY.

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

    El porcentaje de implementación asociado a esta operación de renderización. Si la variable de entorno CLOUD_DEPLOY_FEATURES se define como CANARY, se llama a tu acción de renderización personalizada en cada fase y esta variable se define como el porcentaje de canary de cada fase. En las implementaciones estándar y en las implementaciones canario que han alcanzado la fase stable, este valor es 100.

  • CLOUD_DEPLOY_STORAGE_TYPE

    El proveedor de almacenamiento. Siempre GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    Ruta de Cloud Storage del archivo de renderización que se escribe cuando se crea la versión.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Ruta de Cloud Storage en la que se espera que el contenedor de renderización personalizado suba los artefactos que se usarán en la implementación. Ten en cuenta que la acción de renderización debe subir un archivo llamado results.json que contenga los resultados de esta operación de renderización. Para obtener más información, consulta Resultados de la acción de renderización.

Resultados de la acción de renderización

Tu acción de renderización personalizada debe proporcionar la información descrita en esta sección. La información debe incluirse en el archivo de resultados, llamado results.json, que se encuentra en el segmento de Cloud Storage proporcionado por Cloud Deploy.

  • Archivo o archivos de configuración renderizados

  • Un archivo results.json que contiene la siguiente información:

    • Una indicación del estado de éxito o de error de la acción personalizada.

      Los valores válidos son SUCCEEDED y FAILED.

    • (Opcional) Cualquier mensaje de error que genere la acción personalizada.

    • Ruta de Cloud Storage del archivo o los archivos de configuración renderizados.

      La ruta de todos los archivos de configuración renderizados es el URI completo. Se rellena parcialmente con el valor de CLOUD_DEPLOY_OUTPUT_GCS_PATH proporcionado por Cloud Deploy.

      Debe proporcionar el archivo de configuración renderizado, aunque esté vacío. El contenido del archivo puede ser cualquier cosa, en cualquier formato, siempre que tu acción de implementación personalizada pueda consumirlo. Te recomendamos que este archivo sea legible para las personas, de forma que tú y otros usuarios de tu organización podáis verlo en el inspector de lanzamientos.

    • (Opcional) un mapa de los metadatos que quieras incluir

      Su segmentación personalizada crea estos metadatos. Estos metadatos se almacenan en la versión, en el campo custom_metadata.

Si necesitas examinar el archivo results.json, por ejemplo, para depurar, puedes encontrar su URI de Cloud Storage en los registros de Cloud Build.

Archivo de resultados de renderización de ejemplo

A continuación, se muestra un ejemplo de archivo results.json generado por una acción de renderización personalizada:

{
  "resultStatus": "SUCCEEDED",
  "manifestFile": "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/manifest.yaml",
  "failureMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

Entradas para desplegar acciones

En el caso de las acciones de despliegue personalizadas, Cloud Deploy proporciona las siguientes entradas como variables de entorno:

  • CLOUD_DEPLOY_PROJECT

    El Google Cloud número del proyecto en el que se crea el objetivo personalizado.

  • CLOUD_DEPLOY_PROJECT_ID

    El Google Cloud ID del proyecto.

  • CLOUD_DEPLOY_LOCATION

    La Google Cloud región del tipo de segmentación personalizada.

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

    Nombre del flujo de procesamiento de entrega de Cloud Deploy que hace referencia al destino que usa el tipo de destino personalizado.

  • CLOUD_DEPLOY_RELEASE

    Nombre de la versión para la que se invoca la operación de implementación.

  • CLOUD_DEPLOY_ROLLOUT

    Nombre del lanzamiento de Cloud Deploy al que corresponde este despliegue.

  • CLOUD_DEPLOY_TARGET

    Nombre del destino de Cloud Deploy que usa el tipo de destino personalizado.

  • CLOUD_DEPLOY_PHASE

    La fase de lanzamiento a la que corresponde la implementación.

  • CLOUD_DEPLOY_REQUEST_TYPE

    En el caso de la acción de implementación personalizada, este valor siempre es DEPLOY.

  • CLOUD_DEPLOY_FEATURES

    Lista separada por comas de las funciones de Cloud Deploy que debe admitir el contenedor personalizado. Esta variable se rellena en función de las funciones configuradas en tu flujo de procesamiento de entrega.

    Si tu implementación no admite las funciones de esta lista, te recomendamos que falle durante el renderizado.

    En las implementaciones estándar, este campo está vacío. En las implementaciones canary, el valor es CANARY. Si el valor proporcionado por Cloud Deploy es CANARY, tu acción de renderizado se invoca para cada fase del lanzamiento canary. El porcentaje de lanzamiento de la versión canary de cada fase se proporciona en la variable de entorno CLOUD_DEPLOY_PERCENTAGE_DEPLOY.

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

    El porcentaje de implementación asociado a esta operación de implementación. Si la variable de entorno CLOUD_DEPLOY_FEATURES se define como CANARY, se llama a tu acción de implementación personalizada en cada fase y esta variable se define como el porcentaje de lanzamiento canary de cada fase. La acción de implementación debe ejecutarse en cada fase.

  • CLOUD_DEPLOY_STORAGE_TYPE

    El proveedor de almacenamiento. Siempre GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    Ruta de Cloud Storage en la que el renderizador personalizado ha escrito los archivos de configuración renderizados.

  • CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

    Ruta de Cloud Storage a la configuración de Skaffold renderizada.

  • CLOUD_DEPLOY_MANIFEST_GCS_PATH

    Ruta de Cloud Storage al archivo de manifiesto renderizado.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Ruta al directorio de Cloud Storage donde se espera que el contenedor de implementación personalizado suba los artefactos de implementación. Para obtener más información, consulta Salidas de la acción de implementación.

Salidas de la acción de implementación

Tu acción de implementación personalizada debe escribir un archivo de salida results.json. Este archivo debe estar ubicado en el segmento de Cloud Storage proporcionado por Cloud Deploy (CLOUD_DEPLOY_OUTPUT_GCS_PATH).

El archivo debe incluir lo siguiente:

  • Indicación del estado de éxito o de error de la acción de implementación personalizada.

    Estos son los estados válidos:

    • SUCCEEDED

    • FAILED

    • SKIPPED

    Esto es para los despliegues canary en los que se omiten las fases canary para pasar directamente a stable.

  • (Opcional) Una lista de archivos de artefactos de implementación, en forma de rutas de Cloud Storage

    La ruta es el URI completo. Se rellena parcialmente con el valor de CLOUD_DEPLOY_OUTPUT_GCS_PATH provided de Cloud Deploy.

    Los archivos que se muestran aquí se rellenan en los recursos de ejecución de trabajos como artefactos de implementación.

  • (Opcional) Un mensaje de error si la acción de implementación personalizada no se realiza correctamente (se devuelve el estado FAILED).

    Este mensaje se usa para rellenar el failure_message en la ejecución del trabajo de esta acción de implementación.

  • (Opcional) Un mensaje de omisión para proporcionar información adicional si la acción devuelve un estado SKIPPED.

  • (Opcional) un mapa de los metadatos que quieras incluir

    Su segmentación personalizada crea estos metadatos. Estos metadatos se almacenan en la ejecución del trabajo y en el lanzamiento, en el campo custom_metadata.

Si necesitas examinar el archivo results.json, por ejemplo, para depurar, puedes encontrar su URI de Cloud Storage en los registros de renderización de la versión de Cloud Build.

Ejemplo de archivo de resultados de la implementación

A continuación, se muestra un ejemplo de salida de archivo results.json de una acción de implementación personalizada:

{
  "resultStatus": "SUCCEEDED",
  "artifactFiles": [
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file1.yaml",
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file2.yaml"
  ],
  "failureMessage": "",
  "skipMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

Más información sobre las acciones personalizadas

A continuación, te indicamos algunos aspectos que debes tener en cuenta al configurar y usar tipos de segmentación personalizados.

Ejecutar las acciones personalizadas

Las acciones de renderización y despliegue personalizadas se ejecutan en el entorno de ejecución de Cloud Deploy. No puedes configurar tus acciones personalizadas para que se ejecuten en un clúster de Google Kubernetes Engine.

Usar configuraciones de Skaffold remotas y reutilizables

Tal como se describe en este documento, debes configurar tu acción personalizada en el archivo skaffold.yaml que se proporciona al crear la versión. Sin embargo, también puedes almacenar configuraciones de Skaffold en un repositorio de Git o en un segmento de Cloud Storage y hacer referencia a ellas desde tu definición de tipo de destino personalizado. De esta forma, puedes usar acciones personalizadas definidas y almacenadas en una única ubicación compartida, en lugar de incluir las acciones personalizadas en el archivo skaffold.yaml de cada lanzamiento.

Objetivos personalizados y estrategias de implementación

Los objetivos personalizados se admiten por completo en las implementaciones estándar.

Cloud Deploy admite implementaciones canary siempre que el renderizador y el implementador personalizados admitan la función canary.

Debes usar una configuración canary personalizada. No se admiten canarios automatizados ni personalizados con segmentaciones personalizadas.

Objetivos personalizados y parámetros de implementación

Puede usar parámetros de implementación con segmentaciones personalizadas. Puede definirlos en la fase de la canalización de entrega, en el destino que usa un tipo de destino personalizado o en la versión.

Los parámetros de implementación se transfieren a tus contenedores de renderización e implementación personalizados como variables de entorno, además de los que ya se proporcionan.

Ejemplos de segmentación personalizada

El repositorio cloud-deploy-samples contiene un conjunto de implementaciones de destino personalizado de muestra. Están disponibles los siguientes ejemplos:

  • GitOps

  • Vertex AI

  • Terraform

  • Infrastructure Manager

  • Helm

Cada ejemplo incluye una guía de inicio rápido.

Estas muestras no son un producto compatible Google Cloud y no están cubiertas por un contrato de asistencia Google Cloud . Para informar de errores o solicitar funciones en un Google Cloud producto, ponte en contacto con el Google Cloudservicio de asistencia.

Siguientes pasos