En este documento, se describe cómo funcionan los destinos personalizados en Cloud Deploy.
Cloud Deploy incluye compatibilidad integrada con 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 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é incluye un destino personalizado?
Cada destino personalizado consta de los siguientes componentes:
acciones personalizadas, definida en
skaffold.yamlSon similares a la forma en que defines hooks de implementación. En la
skaffold.yaml, debes definircustomActions, en el que cada acción personalizada identifica la imagen de contenedor que se debe usar y los comandos para ejecutar 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
CustomTargetTypees un recurso de Cloud Deploy que identifica las acciones personalizadas (definidas por separado en tuskaffold.yaml) a las que se orienta de este tipo se usan para las actividades de renderización y lanzamiento de lanzamiento.-
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 laCustomTargetType.
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
La guía de inicio rápido Define y usa un tipo de destino personalizado crea un tipo de destino personalizado que incluye comandos simples para ejecutar en un de contenedor, con 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. Esta sección Indica qué entradas y salidas se requieren y cómo se proporcionan.
Cloud Deploy proporciona las entradas necesarias para los procesos de renderización y implementar, como variables de entorno. En las siguientes secciones, se enumeran estas entradas, así como las salidas que deben mostrar tus acciones personalizadas de renderización y de implementación.
Implementa 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.
Los parámetros de implementación previstos como entradas para los destinos personalizados deben comenzar con
customTarget/, por ejemplo, customTarget/vertexAIModel. Cuando se hace referencia a un
implementar el parámetro como una variable de entorno, usa la siguiente sintaxis:
CLOUD_DEPLOY_customTarget_[VAR_NAME]
Donde VAR_NAME es el nombre que sigue a la barra en el
nombre del parámetro de implementación. Por ejemplo, si defines un
el parámetro de implementación llamado customTarget/vertexAIModel, haz referencia a él como
CLOUD_DEPLOY_customTarget_vertexAIModel
Entradas para renderizar acciones
Para las acciones de renderización personalizadas, Cloud Deploy proporciona lo siguiente: las entradas necesarias, como variables de entorno. Para lanzamientos en varias fases (implementaciones de versiones canary), Cloud Deploy proporciona estas variables para cada fase.
CLOUD_DEPLOY_PROJECTEl proyecto de Google Cloud en el que se crea el tipo de destino personalizado.
CLOUD_DEPLOY_LOCATIONLa región de Google Cloud para el tipo de destino personalizado.
CLOUD_DEPLOY_DELIVERY_PIPELINEEl nombre de la canalización de entrega de Cloud Deploy que hace referencia a la como un tipo de segmentación personalizada.
CLOUD_DEPLOY_RELEASEEs el nombre de la versión para la que se invoca la operación de renderización.
CLOUD_DEPLOY_TARGETEl nombre del destino de Cloud Deploy que usa el destino personalizado el tipo de letra.
CLOUD_DEPLOY_PHASELa fase de lanzamiento al que corresponde la renderización.
CLOUD_DEPLOY_REQUEST_TYPEPara la acción de renderización personalizada, siempre es
RENDER.CLOUD_DEPLOY_FEATURESUna lista separada por comas de las funciones de Cloud Deploy a las que que debe admitir el contenedor. 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.
Para las implementaciones estándar, este campo está vacío. Para las implementaciones de versiones canary, el valor es
CANARY. Si el valor que proporciona Cloud Deploy esCANARY, tu acción de renderización se que se puede invocar para cada fase en la versión canary. El porcentaje de versiones canary para cada fase es que se proporciona en la variable de entornoCLOUD_DEPLOY_PERCENTAGE_DEPLOY.CLOUD_DEPLOY_PERCENTAGE_DEPLOYEl porcentaje de implementación asociado con esta operación de renderización. Si el botón La variable de entorno
CLOUD_DEPLOY_FEATURESse estableció enCANARY, se llama a la acción de renderización para cada fase, y esta variable se establece porcentaje de versiones canary para cada fase. Para implementaciones estándar Para las implementaciones de versiones canary que llegaron a la fasestable, esto es100CLOUD_DEPLOY_STORAGE_TYPEEl proveedor de almacenamiento. Siempre
GCS.CLOUD_DEPLOY_INPUT_GCS_PATHLa ruta de Cloud Storage para el archivo de renderización que se escribió cuando se lanzó la versión se creó.
CLOUD_DEPLOY_OUTPUT_GCS_PATHLa 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 renderización acción debe subir un archivo llamado
results.jsonque contenga los resultados de esta una 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, con el nombre
results.json, ubicado en el bucket de Cloud Storage proporcionado por
Cloud Deploy.
Archivos o archivos de configuración renderizados
Un archivo
results.json, que contiene la siguiente información:Una indicación del estado de éxito o fracaso de la acción personalizada.
Los valores válidos son
SUCCEEDEDyFAILED.(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 el contenido del archivo puede ser cualquier cosa, en cualquier formato, siempre que esté que tu acción de implementación personalizada. 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.
Un mapa de los metadatos que quieras incluir (opcional)
Tu destino personalizado crea estos metadatos. Estos metadatos se almacenan versión, 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 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_PROJECTEl proyecto de Google Cloud en el que se crea el destino personalizado.
CLOUD_DEPLOY_LOCATIONLa región de Google Cloud para el tipo de destino personalizado.
CLOUD_DEPLOY_DELIVERY_PIPELINEEl 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_RELEASEEl nombre de la versión para la que se invoca la operación de implementación.
CLOUD_DEPLOY_ROLLOUTEl nombre del lanzamiento de Cloud Deploy para el que se realiza esta implementación.
CLOUD_DEPLOY_TARGETEl nombre del destino de Cloud Deploy que usa el destino personalizado el tipo de letra.
CLOUD_DEPLOY_PHASELa fase de lanzamiento al que corresponde la implementación.
CLOUD_DEPLOY_REQUEST_TYPEPara la acción de implementación personalizada, siempre es
DEPLOY.CLOUD_DEPLOY_FEATURESUna lista separada por comas de las funciones de Cloud Deploy a las que que debe admitir el contenedor. 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.
Para las implementaciones estándar, este campo está vacío. Para las implementaciones de versiones canary, el valor es
CANARY. Si el valor que proporciona Cloud Deploy esCANARY, tu acción de renderización se que se puede invocar para cada fase en la versión canary. El porcentaje de versiones canary para cada fase es que se proporciona en la variable de entornoCLOUD_DEPLOY_PERCENTAGE_DEPLOY.CLOUD_DEPLOY_PERCENTAGE_DEPLOYEl porcentaje de implementación asociado con esta operación de implementación. Si el botón La variable de entorno
CLOUD_DEPLOY_FEATURESse estableció enCANARY, se llama a una acción de implementación para cada fase, y esta variable se establece porcentaje de versiones canary para cada fase. Tu acción de implementación debe ejecutarse para cada fase.CLOUD_DEPLOY_STORAGE_TYPEEl proveedor de almacenamiento. Siempre
GCS.CLOUD_DEPLOY_INPUT_GCS_PATHLa ruta de acceso de Cloud Storage en la que el procesador personalizado escribió el procesamiento de configuración de Terraform.
CLOUD_DEPLOY_SKAFFOLD_GCS_PATHRuta de acceso de Cloud Storage a la configuración renderizada de Skaffold.
CLOUD_DEPLOY_MANIFEST_GCS_PATHRuta de acceso de Cloud Storage al archivo de manifiesto renderizado.
CLOUD_DEPLOY_OUTPUT_GCS_PATHLa ruta de acceso al directorio de Cloud Storage en el que se realizó 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:
SUCCEEDEDFAILEDSKIPPED(para implementaciones de versiones canary en las que se omiten fases de versión canary para ir directamente astable).
(Opcional) Una lista de archivos de artefactos de implementación, en la forma de Rutas de acceso de Cloud Storage
La ruta de acceso es el URI completo. Lo propagas en parte con el valor del
CLOUD_DEPLOY_OUTPUT_GCS_PATHproporcionado por Cloud Deploy.Los archivos que se muestran aquí se propagan en Recursos de ejecución de trabajos como artefactos de implementación.
Un mensaje de error si la acción de implementación personalizada no se realiza correctamente (opcional) (se muestra un estado
FAILED)Este mensaje se usa para propagar
failure_messageen 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 ejecución del 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 del archivo results.json de muestra de una implementación personalizada
acción:
{
"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 objetivos personalizados de tipos de datos.
Cómo ejecutar las acciones personalizadas
Tus acciones de implementación y renderización personalizadas se ejecutan en Cloud Deploy entorno de ejecución. 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. Pero también puedes almacenar
Skaffold config en un repositorio de Git o en un bucket de Cloud Storage y
hacer referencia a ellos desde la definición del tipo de segmentación personalizada.
Esto te permite usar acciones personalizadas definidas y almacenadas en una única
en lugar de incluir las acciones personalizadas con los atributos
skaffold.yaml.
Objetivos personalizados y estrategias de implementación
Los objetivos personalizados son totalmente compatibles estándar.
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 de versiones canary personalizada. Automatización y personalización personalizada no se admiten las versiones canary.
Destinos personalizados e parámetros de implementación
Puedes usar parámetros de implementación con destinos personalizados. Puedes configurarlas en la canalización de entrega stage, en el objetivo que usa un tipo de segmentación personalizada versión.
Los parámetros de implementación se pasan a tus contenedores de renderización personalizada y de implementación, como variables de entorno, además de las que ya se proporcionaron.
Ejemplos de destinos personalizados
El repositorio cloud-deploy-samples contiene un conjunto de implementaciones de destino personalizadas de muestra. Los siguientes ejemplos 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 solicitarlo en un producto de Google Cloud, comunícate con Google Cloud y asistencia.
¿Qué sigue?
Ahora que conoces las orientaciones personalizadas, descubre cómo configurarlos y usarlos.
Prueba la guía de inicio rápido: Define y usa un tipo de destino personalizado.
Obtén más información sobre cómo configurar destinos de Cloud Deploy.
Obtén más información sobre los entornos de ejecución de Cloud Deploy.