Acerca de las segmentaciones personalizadas

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

Cloud Deploy incluye compatibilidad integrada para varios entornos de ejecución como destinos. Sin embargo, la lista de tipos de objetivos admitidos es finita. Con los destinos personalizados, puedes realizar la implementación en otros sistemas además de los tiempos de ejecución compatibles.

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

En la página Crea un destino personalizado, se describe el proceso para definir un tipo de destino personalizado y, luego, implementarlo como destino en una canalización de entrega.

¿Qué se incluye en un objetivo personalizado?

Cada objetivo personalizado consta de los siguientes componentes:

  • Tareas, que definen cómo renderizar y realizar la implementación para tu tipo de segmentación personalizado

    Tus implementaciones de la renderización personalizada y la implementación personalizada consumen los valores que proporciona Cloud Deploy y deben cumplir con un conjunto de resultados obligatorios.

    La renderización personalizada es opcional, pero debes crear una, a menos que tu destino personalizado funcione correctamente si se renderiza con los renderizadores integrados de Cloud Deploy.

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

    El objeto CustomTargetType es un recurso de Cloud Deploy que identifica las tareas que los destinos de este tipo usan para las actividades de renderización de versiones y de implementación de lanzamientos.

  • Una definición de destino

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

Con esos componentes implementados, 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 reversiones.

Ejemplo

El inicio rápido Define and use a custom target type crea un tipo de destino personalizado que incluye comandos para ejecutar en una imagen de contenedor: un comando para renderizar y otro para implementar. En este caso, los comandos solo agregan texto a los archivos de salida necesarios para la renderización y la implementación.

Para obtener más ejemplos, consulta Ejemplos de objetivos personalizados.

Entradas y salidas requeridas

Cualquier tipo de destino personalizado definido para Cloud Deploy debe satisfacer los requisitos de entrada y salida, tanto para la renderización como para la implementación. En esta sección, se enumeran las entradas y salidas requeridas, y se explica cómo se proporcionan.

Cloud Deploy proporciona las entradas requeridas, tanto para la renderización como para la implementación, como variables de entorno. En las siguientes secciones, se enumeran estas entradas, así como los resultados que deben devolver tu renderización y tu implementación personalizadas.

Implementa parámetros como variables de entorno

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

Obtén más información.

Entradas para renderizaciones personalizadas

Para las renderizaciones personalizadas, Cloud Deploy proporciona las siguientes entradas como variables de entorno. Para las versiones en varias fases (implementaciones de versiones canary), Cloud Deploy proporciona estas variables para cada fase.

  • CLOUD_DEPLOY_PROJECT

    Número de proyecto Google Cloud del proyecto en el que se crea el objetivo personalizado.

  • CLOUD_DEPLOY_PROJECT_ID

    ID del proyecto Google Cloud .

  • CLOUD_DEPLOY_LOCATION

    Es la región Google Cloud para el tipo de segmentación personalizada.

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

    Es el nombre de la canalización de entrega de Cloud Deploy que hace referencia al tipo de destino personalizado.

  • CLOUD_DEPLOY_RELEASE

    Es el nombre de la versión para la que se invoca la operación de renderización.

  • CLOUD_DEPLOY_TARGET

    Es el nombre del destino de Cloud Deploy que usa el tipo de destino personalizado.

  • CLOUD_DEPLOY_PHASE

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

  • CLOUD_DEPLOY_REQUEST_TYPE

    Para la renderización personalizada, siempre es RENDER.

  • CLOUD_DEPLOY_FEATURES

    Es una lista separada por comas de las funciones de Cloud Deploy que debe admitir el contenedor personalizado. Esta variable se propaga en función de las funciones configuradas en tu canalización de entrega.

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

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

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

    Es el porcentaje de implementación asociado a esta operación de renderización. Si la variable de entorno CLOUD_DEPLOY_FEATURES está establecida en CANARY, se llama a tu render personalizado para cada fase, y esta variable se establece en el porcentaje de la versión canary para cada fase. Para las implementaciones estándar y las implementaciones canary que alcanzaron la fase stable, este valor es 100.

  • CLOUD_DEPLOY_STORAGE_TYPE

    Es el proveedor de almacenamiento. Siempre GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    Es la ruta de Cloud Storage para el archivo de renderización escrito cuando se creó la versión.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Es la ruta de Cloud Storage en la que se espera que el contenedor de renderización personalizado suba los artefactos que se usarán para la implementación. Ten en cuenta que la 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 renderización personalizada.

Resultados de la renderización personalizada

Tu render personalizado debe proporcionar la información que se describe en esta sección. La información debe incluirse en el archivo de resultados, llamado results.json, que se encuentra en el bucket de Cloud Storage proporcionado por Cloud Deploy (CLOUD_DEPLOY_OUTPUT_GCS_PATH).

  • Archivos de configuración renderizados

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

    • Es una indicación del estado de éxito o falla de la renderización personalizada.

      Los valores válidos son SUCCEEDED y FAILED.

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

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

      La ruta de acceso para todos los archivos de configuración renderizados es el URI completo. Lo completas parcialmente con el valor de CLOUD_DEPLOY_OUTPUT_GCS_PATH proporcionado por Cloud Deploy.

      Debes proporcionar el archivo de configuración renderizado, incluso si está vacío. El contenido del archivo puede ser cualquier cosa, en cualquier formato, siempre y cuando tu implementación personalizada pueda consumirlo. Recomendamos que este archivo sea legible para las personas, de modo que tú y otros usuarios de tu organización puedan verlo en el inspector de versiones.

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

      Tu segmentación personalizada crea estos metadatos. Estos metadatos se almacenan 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 Cloud Build.

Ejemplo de archivo de resultados de renderización

El siguiente es un ejemplo de un archivo results.json generado a partir de una 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 implementaciones personalizadas

Para las implementaciones personalizadas, Cloud Deploy proporciona las siguientes entradas como variables de entorno:

  • CLOUD_DEPLOY_PROJECT

    Número de proyecto Google Cloud del proyecto en el que se crea el objetivo personalizado.

  • CLOUD_DEPLOY_PROJECT_ID

    ID del proyecto Google Cloud .

  • CLOUD_DEPLOY_LOCATION

    Es la región Google Cloud para el tipo de segmentación personalizada.

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

    Es el nombre de la canalización de entrega de Cloud Deploy que hace referencia al destino que usa el tipo de destino personalizado.

  • CLOUD_DEPLOY_RELEASE

    Es el nombre de la versión para la que se invoca la operación de implementación.

  • CLOUD_DEPLOY_ROLLOUT

    Es el nombre del lanzamiento de Cloud Deploy para el que se realiza esta implementación.

  • CLOUD_DEPLOY_TARGET

    Es el nombre del destino de Cloud Deploy que usa el tipo de destino personalizado.

  • CLOUD_DEPLOY_PHASE

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

  • CLOUD_DEPLOY_REQUEST_TYPE

    Para la implementación personalizada, siempre es DEPLOY.

  • CLOUD_DEPLOY_FEATURES

    Es una lista separada por comas de las funciones de Cloud Deploy que debe admitir el contenedor personalizado. Esta variable se propaga en función de las funciones configuradas en tu canalización de entrega.

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

    En el caso de las implementaciones estándares, este campo está vacío. Para las implementaciones de versiones preliminares, el valor es CANARY. Si el valor que proporciona Cloud Deploy es CANARY, se invoca tu implementación para cada fase de la versión canary. El porcentaje de lanzamiento de la versión canary para cada fase se proporciona en la variable de entorno CLOUD_DEPLOY_PERCENTAGE_DEPLOY.

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

    Es el porcentaje de implementación asociado a esta operación de implementación. Si la variable de entorno CLOUD_DEPLOY_FEATURES está establecida en CANARY, se llama a tu implementación personalizada para cada fase, y esta variable se establece en el porcentaje de la versión canary para cada fase. Tu implementación debe ejecutarse para cada fase.

  • CLOUD_DEPLOY_STORAGE_TYPE

    Es el proveedor de almacenamiento. Siempre GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    Es la ruta de Cloud Storage en la que el renderizador personalizado escribió los archivos de configuración renderizados.

  • CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

    Es la ruta de acceso de Cloud Storage a la configuración de Skaffold renderizada. Si proporcionaste una configuración de Skaffold con tu versión

  • CLOUD_DEPLOY_MANIFEST_GCS_PATH

    Ruta de acceso de Cloud Storage al archivo de manifiesto renderizado.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Ruta de acceso al directorio de Cloud Storage en el que 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 implementación personalizada.

Resultados de la implementación personalizada

Tu implementación personalizada debe escribir un archivo de salida results.json. Este archivo debe estar ubicado en el bucket de Cloud Storage que proporciona Cloud Deploy (CLOUD_DEPLOY_OUTPUT_GCS_PATH).

El archivo debe incluir lo siguiente:

  • Es una indicación del estado de éxito o falla de la implementación personalizada.

    Los siguientes son los estados válidos:

    • SUCCEEDED

    • FAILED

    • SKIPPED

    Esto es para las implementaciones de versiones canary en las que se omiten las fases de versión canary para ir directamente a stable.

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

    La ruta de acceso es el URI completo. Lo propagas parcialmente con el valor de CLOUD_DEPLOY_OUTPUT_GCS_PATH proporcionado por Cloud Deploy.

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

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

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

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

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

    Tu 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 Cloud Build.

Ejemplo de archivo de resultados de la implementación

El siguiente es un ejemplo de un archivo results.json que se generó a partir de una 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 los objetivos personalizados

A continuación, se incluyen algunos aspectos que debes tener en cuenta cuando configures y uses tipos de segmentación personalizados.

Cómo ejecutar las tareas

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

Objetivos personalizados y estrategias de implementación

Los destinos personalizados son totalmente compatibles con las implementaciones estándar.

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

Debes usar la configuración de canary personalizada. No se admiten las pruebas canary automatizadas ni las automatizadas personalizadas con destinos personalizados.

Parámetros de implementación y destinos personalizados

Puedes usar parámetros de implementación con destinos personalizados. Puedes establecerlos en la etapa 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 pasan a tus contenedores personalizados de renderización e implementación 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 destinos personalizados de muestra. Están disponibles los siguientes ejemplos:

  • GitOps

  • Vertex AI

  • Terraform

  • Infrastructure Manager

  • Helm

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

Estas muestras no son un producto Google Cloud admitido y no están cubiertas por un Google Cloud contrato de asistencia. Para informar errores o solicitar funciones en un producto de Google Cloud , comunícate con el equipo de asistencia Google Cloud.

¿Qué sigue?