Acerca de las orientaciones 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. Pero la lista de tipos de destino admitidos es finito. Con los destinos personalizados, puedes implementar en otros sistemas además de los entornos de ejecución compatibles.

Un destino personalizado es aquel que representa un entorno de salida arbitrario. que no sea un entorno de ejecución compatible con Cloud Deploy.

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

¿Qué se incluye en un objetivo personalizado?

Cada destino personalizado consta de los siguientes componentes:

  • acciones personalizadas, definida en skaffold.yaml

    Son similares a la forma en que defines los hooks de implementación. En el archivo skaffold.yaml, defines customActions, en el que cada acción personalizada identifica una imagen de contenedor para usar y los comandos que se ejecutarán en ese contenedor.

    De este modo, el destino personalizado es simplemente una acción o un conjunto acciones.

    Para cualquier tipo de destino personalizado, debes configurar una acción de renderización personalizada y una acción de implementación. Estas acciones consumen valores proporcionados por Cloud Deploy y debe entregar un conjunto de resultados obligatorios.

    La acción de renderización personalizada es opcional, pero debes crear una, a menos que el destino personalizado funcionará correctamente si lo renderiza skaffold render, que es el predeterminado para Cloud Deploy.

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

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

  • Una definición de objetivo

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

Con esos componentes implementados, puedes usar el destino como lo harías con cualquier objetivo, se lo consulta a partir del progreso de su canalización de entrega y aproveche al máximo funciones de Cloud Deploy, como promoción y aprobación reversiones.

Ejemplo

En la guía de inicio rápido Define y usa un tipo de destino personalizado, se crea un tipo de destino personalizado que incluye comandos simples para ejecutar en una imagen de contenedor: un comando para la renderización y otro para la implementación. Los comandos en este caso, simplemente agrega texto a los archivos de salida requeridos para implementar.

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

Entradas y salidas obligatorias

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

Cloud Deploy proporciona las entradas necesarias, 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 mostrar tus acciones de renderización e implementación personalizadas.

Cómo implementar parámetros como variables de entorno

Además de las variables de entorno enumeradas en esta sección, Cloud Deploy puede pasar a tus contenedores personalizados cualquier implementar los parámetros que estableciste.

Más información

Entradas para renderizar acciones

Para las acciones de renderización personalizadas, Cloud Deploy proporciona las siguientes entradas obligatorias como variables de entorno. Para lanzamientos en varias fases (implementaciones de versiones canary), Cloud Deploy proporciona estas variables para cada fase.

  • CLOUD_DEPLOY_PROJECT

    Es el proyecto de Google Cloud en el que se crea el tipo de objetivo personalizado.

  • CLOUD_DEPLOY_LOCATION

    La región de Google Cloud para el tipo de destino personalizado.

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

    El nombre de la canalización de entrega de Cloud Deploy que hace referencia a la como un tipo de segmentación personalizada.

  • CLOUD_DEPLOY_RELEASE

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

  • CLOUD_DEPLOY_TARGET

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

  • CLOUD_DEPLOY_PHASE

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

  • CLOUD_DEPLOY_REQUEST_TYPE

    Para la acción de 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 publicación.

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

    Para las implementaciones estándar, este campo está vacío. Para las implementaciones Canary, el valor es CANARY. Si el valor que proporciona Cloud Deploy es CANARY, se invoca tu acción de renderización para cada fase del canario. El porcentaje de versiones canary para cada fase es que se proporciona en la variable de entorno CLOUD_DEPLOY_PERCENTAGE_DEPLOY.

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

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

  • CLOUD_DEPLOY_STORAGE_TYPE

    El proveedor de almacenamiento. Siempre GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    Es la ruta de Cloud Storage del archivo de renderización que se escribió cuando se creó la versión.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    La ruta de acceso de Cloud Storage en la que se encuentra el contenedor de renderización personalizada subir 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 que se describe en este sección. La información se debe incluir en el archivo de resultados, llamado results.json, que se encuentra en el bucket de Cloud Storage que proporciona Cloud Deploy.

  • Archivos o 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 acción personalizada.

      Los valores válidos son SUCCEEDED y FAILED.

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

    • La ruta de Cloud Storage para el archivo de configuración renderizado o archivos.

      La ruta de acceso de todos los archivos de configuración renderizados es el URI completo. Tú Complétalo en parte 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 acción de implementación personalizada pueda consumirlo. Recomendamos que este archivo sea humano legibles, para que usted y otros usuarios de su organización puedan ver este en el Inspector de versiones.

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

      Tu destino personalizado 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 el URI de Cloud Storage en los registros de Cloud Build.

Ejemplo de archivo de resultados de renderización

El siguiente es un resultado del archivo results.json de muestra de una renderización personalizada acción:

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

Entradas para implementar acciones

Para las acciones de implementación personalizadas, Cloud Deploy proporciona lo siguiente: las entradas necesarias, como variables de entorno:

  • CLOUD_DEPLOY_PROJECT

    El proyecto de Google Cloud en el que se crea el destino personalizado.

  • CLOUD_DEPLOY_LOCATION

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

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

    El nombre de la canalización de entrega de Cloud Deploy que hace referencia a la objetivo que usa el tipo de destino personalizado.

  • CLOUD_DEPLOY_RELEASE

    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

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

  • CLOUD_DEPLOY_REQUEST_TYPE

    Para la acción de 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 los atributos configurados en la 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ándar, esta opción está vacía. Para las implementaciones de versiones canary, el valor es CANARY. Si el valor que proporciona Cloud Deploy es CANARY, tu acción de renderización se que se puede invocar para cada fase en la versión canary. El porcentaje 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 con esta operación de implementación. Si el botón La variable de entorno CLOUD_DEPLOY_FEATURES se estableció en CANARY, se llama a una acción de implementación para cada fase, y esta variable se establece porcentaje de versiones canary para cada fase. La acción de implementación debe ejecutarse para cada fase.

  • CLOUD_DEPLOY_STORAGE_TYPE

    El proveedor de almacenamiento. Siempre GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    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 renderizada de Skaffold.

  • CLOUD_DEPLOY_MANIFEST_GCS_PATH

    La ruta de Cloud Storage al archivo de manifiesto renderizado.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    La ruta de acceso al directorio de Cloud Storage en el que se encuentra la implementación personalizada se espera que el contenedor suba artefactos de implementación. Para obtener más información, consulta Resultados de la acción de implementación.

Resultados de la acción de implementación

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

El archivo debe incluir lo siguiente:

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

    Los siguientes son los estados válidos:

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

    La ruta es el URI completo. La propagas en parte con el valor de CLOUD_DEPLOY_OUTPUT_GCS_PATH que proporciona Cloud Deploy.

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

  • Un mensaje de error si la acción de implementación personalizada no tiene éxito (opcional) (se muestra un estado FAILED)

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

  • Un mensaje de omisión (opcional), para proporcionar información adicional si la acción muestra un Estado de SKIPPED.

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

    Tu destino personalizado crea estos metadatos. Estos metadatos se almacenan en la ejecución de trabajo y en el lanzamiento, en el campo custom_metadata.

Si necesitas examinar el archivo results.json, por ejemplo, para la depuración, puedes hacer lo siguiente: puedes encontrar el URI de Cloud Storage para él en Cloud Build registros de renderización de lanzamiento.

Ejemplo de archivo de resultados de implementación

El siguiente es un resultado de archivo results.json de muestra 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, se incluyen algunos aspectos que debes tener en cuenta cuando configures y uses tipos de segmentación personalizados.

Cómo ejecutar las acciones personalizadas

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

Usa parámetros de configuración de Skaffold reutilizables y remotos

Como se describe en este documento, puedes configurar tu acción personalizada en el Se proporcionó un archivo skaffold.yaml durante la creación de la versión. Sin embargo, también puedes almacenar configuraciones de Skaffold en un repositorio de Git o en un bucket de Cloud Storage, y hacer referencia a ellas desde tu definición de tipo de destino personalizado. Esto te permite usar acciones personalizadas definidas y almacenadas en una sola ubicación compartida, en lugar de incluirlas con el archivo skaffold.yaml de cada versión.

Objetivos y estrategias de implementación personalizados

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

Cloud Deploy admite implementaciones de versiones canary, siempre y cuando el renderizador y el implementador personalizados admiten la función de versión canary.

Debes usar la configuración canary personalizada. No se admiten canarios automáticos ni personalizados.

Destinos personalizados e parámetros de implementación

Puedes usar parámetros de implementación con destinos personalizados. Puedes configurarlos en la etapa de la canalización de publicación, en el objetivo que usa un tipo de objetivo personalizado o en la versión.

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

Ejemplos de destinos personalizados

El repositorio cloud-deploy-samples contiene un conjunto de implementaciones de destinos personalizados de muestra. Los siguientes ejemplos están disponibles:

  • GitOps

  • Vertex AI

  • Terraform

  • Infrastructure Manager

  • Helm

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

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

¿Qué sigue?