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 finita. Con los destinos personalizados, puedes realizar implementaciones en otros sistemas además de los entornos de ejecución compatibles.
Un destino personalizado es un destino que representa un entorno de salida arbitrario que no es 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 y de implementarlo como destino en una canalización de entrega.
¿Qué incluye una segmentación personalizada?
Cada destino personalizado consta de los siguientes componentes:
Acciones personalizadas, definidas en
skaffold.yaml
Estas son similares a la forma en que defines los hooks de implementación. En el archivo
skaffold.yaml
, definecustomActions
, en el que cada acción personalizada identifica una imagen de contenedor que se usará y los comandos que se ejecutarán en ese contenedor.De esta manera, el destino personalizado es simplemente una acción definida de forma personalizada o un conjunto de acciones.
Para cualquier tipo de destino personalizado, debes configurar una acción de renderización personalizada y una acción de implementación personalizada. Estas acciones consumen valores que proporciona Cloud Deploy y deben cumplir con un conjunto de resultados obligatorios.
La acción de renderización personalizada es opcional, pero debes crear una, a menos que tu destino personalizado funcione correctamente si lo renderiza
skaffold render
, que es la configuración predeterminada de Cloud Deploy.Una definición del tipo de destino personalizado
CustomTargetType
es un recurso de Cloud Deploy que identifica las acciones personalizadas (definidas por separado en tuskaffold.yaml
) que los objetivos de este tipo usan para las actividades de implementación de lanzamiento y renderización de versiones.-
La definición de destino para un destino personalizado es la misma que la de cualquier tipo de destino, excepto que incluye la propiedad
customTarget
, cuyo valor es el nombre deCustomTargetType
.
Con esos componentes en su lugar, puedes usar el destino como lo harías con cualquier objetivo, 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
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 ejecutarlo en una imagen de contenedor: un comando para la renderización y otro para la implementación. Los comandos, en este caso, solo agregan texto a los archivos de salida necesarios para la implementación y el procesamiento.
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 con los requisitos de entrada y salida, tanto para la implementación como para la renderización. En esta sección, se enumeran las entradas y salidas necesarias, y cómo se proporcionan.
Cloud Deploy proporciona las entradas necesarias, para implementar y renderizar, como variables de entorno. En las siguientes secciones, se enumeran estas entradas, así como los resultados que deben mostrar tus acciones de implementación y renderización personalizadas.
Implementa parámetros como variables de entorno
Además de las variables de entorno que se enumeran en esta sección, Cloud Deploy puede pasar a tus contenedores personalizados cualquier parámetro de implementación que hayas configurado.
Los parámetros de implementación diseñados como entradas para los destinos personalizados deben comenzar con customTarget/
, por ejemplo, customTarget/vertexAIModel
. Cuando hagas referencia a un
parámetro de implementación 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 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 las siguientes entradas obligatorias, como variables de entorno. Para los lanzamientos en varias fases (implementaciones de versiones canary), Cloud Deploy proporciona estas variables para cada fase.
CLOUD_DEPLOY_PROJECT
El proyecto de Google Cloud en el que se crea el tipo de destino personalizado.
CLOUD_DEPLOY_LOCATION
Es 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 al tipo de destino personalizado.
CLOUD_DEPLOY_RELEASE
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 tipo de destino personalizado.
CLOUD_DEPLOY_PHASE
La fase de lanzamiento a la que corresponde la renderización.
CLOUD_DEPLOY_REQUEST_TYPE
Para la acción de renderización personalizada, siempre es
RENDER
.CLOUD_DEPLOY_FEATURES
Una lista separada por comas de las funciones de Cloud Deploy que debe admitir el contenedor personalizado. Esta variable se propaga según 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.
Para las implementaciones estándar, está vacío. Para las implementaciones de versiones canary, el valor es
CANARY
. Si el valor que proporciona Cloud Deploy esCANARY
, se invoca tu acción de renderización para cada fase de la versión canary. El porcentaje de versiones canary para cada fase se proporciona en la variable de entornoCLOUD_DEPLOY_PERCENTAGE_DEPLOY
.CLOUD_DEPLOY_PERCENTAGE_DEPLOY
El porcentaje de implementación asociado a esta operación de procesamiento. Si la variable de entorno
CLOUD_DEPLOY_FEATURES
se establece enCANARY
, se llama a tu acción de renderización personalizada para cada fase, y esta variable se establece en el porcentaje de versiones canary para cada fase. Para las implementaciones estándar y para las implementaciones de versiones canary que llegaron a la fasestable
, esto es100
.CLOUD_DEPLOY_STORAGE_TYPE
El proveedor de almacenamiento. Siempre es
GCS
.CLOUD_DEPLOY_INPUT_GCS_PATH
La ruta de Cloud Storage para el archivo de archivo de renderización escrito cuando se creó la versión.
CLOUD_DEPLOY_OUTPUT_GCS_PATH
La ruta de Cloud Storage en la que se espera que el contenedor de renderización personalizada suba artefactos que se usarán para 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 esta sección. La información debe incluirse en el archivo de resultados, llamado results.json
, ubicado en el bucket de Cloud Storage que proporciona Cloud Deploy.
Archivo o archivos de configuración procesados
Un archivo
results.json
que contenga la siguiente información:Una indicación del estado de éxito o falla de la acción personalizada.
Los valores válidos son
SUCCEEDED
yFAILED
.Cualquier mensaje de error que genere la acción personalizada (opcional).
La ruta de Cloud Storage para los archivos de configuración renderizados.
La ruta de acceso de todos los archivos de configuración renderizados es el URI completo. Lo propagas 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 que tu acción de implementación personalizada lo pueda consumir. Recomendamos que este archivo sea legible para que tú y otros usuarios de tu organización puedan verlo en el Inspector de versiones.
Si necesitas examinar el archivo results.json
, por ejemplo, para una depuración, puedes encontrar el URI de Cloud Storage que tiene en los registros de Cloud Build.
Ejemplo de archivo de resultados de renderización
El siguiente es un resultado de archivo results.json
de muestra de una acción de renderización personalizada:
{
resultStatus: "SUCCEEDED"
manifestFile: "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/manifest.yaml"
failureMessage: ""
}
Entradas para implementar acciones
Para las acciones de implementación personalizadas, Cloud Deploy proporciona las siguientes entradas obligatorias, como variables de entorno:
CLOUD_DEPLOY_PROJECT
El proyecto de Google Cloud en el que se crea el destino personalizado.
CLOUD_DEPLOY_LOCATION
Es 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 al destino 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
El nombre del lanzamiento de Cloud Deploy al que corresponde esta implementación.
CLOUD_DEPLOY_TARGET
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
Una lista separada por comas de las funciones de Cloud Deploy que debe admitir el contenedor personalizado. Esta variable se propaga según 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.
Para las implementaciones estándar, está vacío. Para las implementaciones de versiones canary, el valor es
CANARY
. Si el valor que proporciona Cloud Deploy esCANARY
, se invoca tu acción de renderización para cada fase de la versión canary. El porcentaje de versiones canary para cada fase se proporciona en la variable de entornoCLOUD_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 establece enCANARY
, se llama a tu acción de implementación personalizada para cada fase y esta variable se establece en el porcentaje de versiones canary para cada fase. Tu acción de implementación debe ejecutarse para cada fase.CLOUD_DEPLOY_STORAGE_TYPE
El proveedor de almacenamiento. Siempre es
GCS
.CLOUD_DEPLOY_INPUT_GCS_PATH
La ruta de Cloud Storage en la que el procesador personalizado escribió los archivos de configuración renderizados.
CLOUD_DEPLOY_SKAFFOLD_GCS_PATH
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
Es la 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 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 debe estar ubicado en el bucket de Cloud Storage que proporciona Cloud Deploy (CLOUD_DEPLOY_OUTPUT_GCS_PATH
).
El archivo debe incluir lo siguiente:
Una indicación del estado de éxito o falla de la acción de implementación personalizada.
Los siguientes son los estados válidos:
SUCCEEDED
FAILED
SKIPPED
(para implementaciones de versiones canary en las que se omiten las fases de versiones canary para ir directamente astable
)
Una lista de archivos de artefactos de implementación, en forma de rutas de Cloud Storage (opcional)
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.
Un mensaje de error, si la acción de implementación personalizada no funciona (se muestra un estado
FAILED
) (opcional)Este mensaje se usa para propagar el
failure_message
en la ejecución del trabajo de esta acción de implementación.Un mensaje de omisión para proporcionar información adicional si la acción muestra un estado
SKIPPED
(opcional).
Si necesitas examinar el archivo results.json
, por ejemplo, para realizar una depuración, puedes encontrar el URI de Cloud Storage correspondiente a él en los registros de renderización de versiones de Cloud Build.
Archivo de resultados de la implementación de ejemplo
El siguiente es un archivo results.json
de muestra como resultado 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: ""
}
Más información sobre las acciones personalizadas
A continuación, se incluyen algunos aspectos que debes tener en cuenta cuando configuras y usas tipos de destinos personalizados.
Cómo ejecutar las acciones personalizadas
Tus acciones de implementación y renderización 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.
Usa configuraciones de Skaffold remotas y reutilizables
Como se describe en este documento, puedes configurar tu acción personalizada en el archivo skaffold.yaml
proporcionado en la creación de la versión. Sin embargo, también puedes almacenar los archivos de configuración de Skaffold en un repositorio de Git o en un bucket de Cloud Storage y hacer referencia a ellos desde tu definición del tipo de destino personalizado.
Esto te permite usar acciones personalizadas definidas y almacenadas en una única ubicación compartida, en lugar de incluir las acciones personalizadas con el archivo skaffold.yaml
de cada versión.
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 implementador y el procesador personalizados admitan la función de versiones canary.
Debes usar una configuración de versiones canary personalizada. No se admiten las versiones canary automatizadas ni personalizadas.
Destinos personalizados y parámetros de implementación
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 de implementación y renderización personalizados, 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 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 compatible de Google Cloud y no están 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?
Ahora que conoces los destinos personalizados, obtén información sobre 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 la configuración de destinos de Cloud Deploy.
Obtén información sobre los entornos de ejecución de Cloud Deploy.