Cómo crear una segmentación personalizada

En este documento, se describe cómo crear un tipo de destino personalizado de Cloud Deploy y usarlo como destino en una canalización de entrega de Cloud Deploy.

El siguiente es el proceso de alto nivel para crear un tipo de destino personalizado y usarlo en tu canalización de entrega:

Crea una aplicación alojada en contenedores o aplicaciones que incluyan la funcionalidad necesaria para implementar en tu destino personalizado y que cumplan con los requisitos de Cloud Deploy para los tipos de destinos personalizados.
Define una acción personalizada en skaffold.yaml que haga referencia a ese contenedor y especifique el comando o los comandos que se ejecutarán en él.
Crea una definición de CustomTargetType que haga referencia a la acción personalizada del paso anterior y regístrala como un recurso de Cloud Deploy.
Define un objetivo nuevo con una propiedad customTarget que identifique tu tipo de destino personalizado nuevo.
Haz referencia a ese destino de la progresión de la canalización de entrega.
Crea una versión.

Cada uno de estos pasos se describe en detalle en el resto de este documento.

Crea tus aplicaciones alojadas en contenedores

La funcionalidad para implementar en tu destino personalizado se define en aplicaciones en contenedores, que proporcionas a Cloud Deploy mediante la referencia de ellas desde tu archivo skaffold.yaml. Cuando tu canalización de entrega incluye un destino que usa un tipo de destino personalizado, Cloud Deploy llama a los contenedores de acción personalizada definidos para ese tipo de destino personalizado, en Skaffold, a fin de ejecutar las acciones de renderización y de implementación que definiste.

El comportamiento de tus aplicaciones depende de ti. Sin embargo, debe consumir las variables de entorno de entrada que proporciona Cloud Deploy y debe mostrar los resultados requeridos.

En la mayoría de los casos, crearás un contenedor para la acción de renderización y otro para la acción de implementación, para cada tipo de destino personalizado que crees. La acción de renderización es opcional, pero si no proporcionas una, Cloud Deploy usa el skaffold render predeterminado.

Define tus acciones personalizadas en Skaffold

Una vez que hayas implementado la imagen o las imágenes del contenedor de acciones personalizadas, puedes hacer referencia a ellas desde el archivo de configuración skaffold.yaml.

Configura cada acción personalizada para un destino personalizado en una estrofa customActions. En cualquier tipo de destino personalizado, debes crear una acción personalizada, en Skaffold, para el procesamiento y otra para la implementación. La definición de CustomTargetType identifica qué acción personalizada se usa para la renderización y cuál se usa para la implementación.

La siguiente es la configuración para las acciones de implementación y renderización personalizadas en skaffold.yaml:

apiVersion: skaffold/v4beta7
kind: Config
customActions:
# custom render action
- name:
  containers:
  - name:
    image:
    command:
    args:
# custom deploy action
- name:
  containers:
  - name:
    image:
    command:
    args:

En esta configuración de Skaffold, sucede lo siguiente:

customActions.name

Es un nombre arbitrario para la acción de implementación o renderización personalizada. La definición CustomTargetType hace referencia a este nombre en la propiedad renderAction o deployAction.
La estrofa containers incluye tu referencia, además de comandos para ejecutar ese contenedor.

La estrofa containers permite más de un contenedor, pero Google recomienda que solo uses uno.
customActions.containers.name

Es un nombre arbitrario para el contenedor específico que usas en esta acción. Como práctica recomendada, este nombre de contenedor siempre debe estar calificado con SHA.
image

Es la ruta de acceso a la imagen del contenedor.
command

Es el comando o los comandos que se ejecutarán en el contenedor.
args

Es una colección de argumentos para command.

Consulta la referencia de YAML de Skaffold para obtener documentación detallada sobre las propiedades de configuración que se usan en customActions.

Define tu tipo de segmentación personalizada

Para definir un destino personalizado, primero debes crear un tipo de destino personalizado mediante la configuración CustomTargetType. Puedes crear el CustomTargetType en el mismo archivo que la definición de tu canalización de entrega, con definiciones de destino o en un archivo independiente.

La definición de CustomTargetType es la siguiente:

# Custom target type config (preview)
apiVersion: deploy.cloud.google.com/v1
kind: CustomTargetType
metadata:
  name: [CUSTOM_TARGET_TYPE_NAME]
  annotations:
  labels:
description:
customActions:
  renderAction: [RENDER_ACTION_NAME]
  deployAction: [DEPLOY_ACTION_NAME]
  includeSkaffoldModules:

¿Por dónde

CUSTOM_TARGET_TYPE_NAME

Es un nombre arbitrario que le asignas a esta definición de tipo de destino personalizado. Se hace referencia a este nombre en la definición de destino para cualquier destino que use el tipo de destino personalizado que estás definiendo.
RENDER_ACTION_NAME

Es el nombre de la acción de renderización personalizada. Este valor es el customAction.name definido en skaffold.yaml para la acción de renderización.
DEPLOY_ACTION_NAME

Es el nombre de la acción de implementación personalizada. Este valor es el customAction.name definido en skaffold.yaml para la acción deploy.
includeSkaffoldModules

Es una estrofa opcional para usar si usas parámetros de configuración remotos de Skaffold. Las propiedades de esta estrofa se muestran en la sección Usa configuraciones remotas de Skaffold.

Usa parámetros de configuración remotos de Skaffold

Puedes almacenar archivos de configuración de Skaffold en un repositorio público de Git o en un bucket de Cloud Storage y hacer referencia a ellos desde tu definición de tipo de destino personalizada.

Usar configuraciones remotas de Skaffold significa que el skaffold.yaml que proporcionas en el momento del lanzamiento no necesita tener definidas las acciones personalizadas. Esto permite compartir acciones personalizadas en toda tu organización.

Para usar configuraciones remotas de Skaffold, haz lo siguiente:

Crea una configuración de Skaffold con tu acción o acciones personalizadas.
Almacenar la configuración en un repositorio de Git o en un bucket de Cloud Storage
En la definición de tu tipo de destino personalizado, agrega una estrofa customActions.includeSkaffoldModules.
En includeSkaffoldModules, especifica lo siguiente:
- De manera opcional, uno o varios elementos configs:
  
  - configs: ["name1", "name2"]
  
  El valor de configs es una lista de cadenas que coinciden con la propiedad metadata.name en cada configuración de Skaffold que se incluirá. Si se omite, Cloud Deploy toma todos los parámetros de configuración en la ruta de acceso especificada.
- Puede ser una estrofa googleCloudStorage o una git.
  
  Para Cloud Storage:
```
googleCloudStorage:
  source: PATH_TO_GCS_BUCKET
  path: FILENAME
```
  Para Git:
```
git:
  repo: REPO_URL
  path: PATH_TO_FILE
  ref: BRANCH_NAME
```
  Aquí:
  
  PATH_TO_GCS_BUCKET es la ruta de acceso a un directorio de Cloud Storage, que termina con /*, en el que se almacenan los archivos de configuración de Skaffold. Skaffold descarga todos los archivos de este directorio y, luego, encuentra el archivo de Skaffold relevante con los parámetros de configuración, según la ruta de acceso relativa configurada.
  
  FILENAME es el nombre del archivo que incluye los archivos de configuración de Skaffold. Esta propiedad path: es opcional. Si no la especificas, Cloud Deploy supone skaffold.yaml. Si no hay skaffold.yaml o si el nombre de archivo que especificas no está allí, fallará la creación de la versión.
  
  REPO_URL es la URL al repositorio de Git.
  
  PATH_TO_FILE es la ruta de acceso en ese repositorio al archivo que contiene los archivos de configuración de Skaffold.
  
  BRANCH_NAME es el nombre de la rama (por ejemplo, main) desde la que se toman los parámetros de configuración de Skaffold.

Ejemplo

El siguiente YAML de tipo de destino personalizado es una estrofa customActions con una estrofa includeSkaffoldModules, que apunta a los archivos de configuración de Skaffold almacenados en un bucket de Cloud Storage:

customActions:
  renderAction: my-custom-action
  deployAction: my-custom-action
  includeSkaffoldModules:
    - configs: ["myConfig"]
      googleCloudStorage:
        source: "gs://my-custom-target-bucket/my-custom/*"
        path: "skaffold.yaml

El siguiente YAML es una configuración de Skaffold, a la que hace referencia la acción personalizada que se muestra:

apiVersion: skaffold/v4beta7
kind: Config
metadata:
  name: myConfig
customActions:
  - name: my-custom-action
    containers:
      - name: my-custom-container
        image: us-east1-docker.pkg.dev/abcdefg/foldername/myimage@sha256:c56fcf6e0a7637ddf0df3d56a0dd23bfce03ceca06a6fc527b0e0e7430e6e9f9

Registra tu tipo de segmentación personalizada

Después de configurar el CustomTargetType, ejecuta el comando gcloud deploy apply para registrar el recurso CustomTargetType en un proyecto de Google Cloud:

gcloud deploy apply --file=[FILE] --project=[PROJECT] --region=[REGION]

Aquí:

FILE es el nombre del archivo en el que definiste este tipo de destino personalizado.

PROJECT es el proyecto de Google Cloud en el que se creará este recurso. CustomTargetType debe estar en el mismo proyecto que el recurso Target que hace referencia a él. No es necesario que especifiques el proyecto si lo configuraste como tu proyecto predeterminado para Google Cloud CLI.

REGION es la región (por ejemplo, us-centra1) en la que se creará el recurso. El CustomTargetType debe estar en la misma región que el recurso Target que hace referencia a él. No es necesario que especifiques la región si la configuraste como la predeterminada para gcloud CLI.

Ahora que se creó CustomTargetType como un recurso de Cloud Deploy, puedes usarlo en una definición de Target para crear tu destino personalizado.

Para obtener más información sobre la definición de CustomTargetType, consulta la referencia del esquema de configuración de Cloud Deploy.

Define tu objetivo

La única diferencia entre una definición de destino para un tipo de destino compatible y una definición de destino personalizado es que la definición de destino personalizado incluye una estrofa customTarget. La sintaxis de un objeto customTarget es la siguiente:

customTarget:
  customTargetType: [CUSTOM_TARGET_TYPE_NAME]

En la que CUSTOM_TARGET_TYPE_NAME es el valor de la propiedad name definida en la configuración del tipo de destino personalizado.

Agrega el destino a la canalización de entrega

Puedes usar un destino personalizado en una canalización de entrega de la misma manera que usarías un tipo de destino compatible. Es decir, no hay diferencia en la progresión de la canalización de entrega entre los destinos de un tipo de destino compatible y los destinos personalizados.

Todos los destinos de una canalización de entrega deben usar el mismo tipo de destino. Por ejemplo, no puedes tener una canalización de entrega con algunos destinos que se implementen en Google Kubernetes Engine y otros destinos personalizados.

Al igual que con los tipos de destino admitidos, puedes incluir parámetros de implementación en la etapa de canalización.

Crea una versión

Con el tipo de destino personalizado completamente definido y un destino creado para usar ese tipo, ahora puedes crear una versión de la manera normal:

gcloud deploy releases create [RELEASE_NAME] \
  --project=[PROJECT_NAME] \
  --region=[REGION] \
  --delivery-pipeline=[PIPELINE_NAME]

Cuando se crea la versión, se ejecuta la acción de renderización personalizada para cada destino de la canalización de entrega, incluidos los parámetros de implementación del procesamiento configurados en la versión, los destinos o la canalización de entrega. Cloud Deploy proporciona los parámetros de implementación como entrada al contenedor de renderización personalizada.

Cómo ver los resultados de tus destinos personalizados

Si tu acción personalizada cumple con los requisitos para los destinos personalizados, puedes usar la consola de Google Cloud para ver los artefactos renderizados.

Sigue estos pasos para ver el resultado de tu acción de renderización personalizada.

En la consola de Google Cloud, navega a la página Canalizaciones de entrega de Cloud Deploy para ver tu canalización de entrega.

Abrir la página Canalizaciones de entrega
Haz clic en el nombre de tu canalización de entrega.

La visualización de la canalización muestra el estado de implementación de la app, y la versión aparece en la pestaña Versiones en Detalles de la canalización de entrega.
Haz clic en el nombre de la versión.

Se mostrará la página Detalles de la versión.
Haz clic en la pestaña Artefactos.
En Artefactos de destino, haz clic en la flecha junto a Ver artefactos.

Se enumeran los artefactos renderizados, incluidos el skaffold.yaml renderizado y el archivo de manifiesto renderizado que genera el procesador personalizado. Además, puedes hacer clic en el vínculo Storage location que se encuentra junto a cada uno para ir al bucket de Cloud Storage y ver esos archivos.

También puedes hacer clic en el vínculo Ver artefactos para ver esos archivos por versión, destino o fase con el Inspector de versiones.

¿Qué sigue?

Prueba la guía de inicio rápido: Define y usa un tipo de destino personalizado
Consulta los tipos de destinos personalizados de muestra disponibles.
Crea una canalización de entrega y destinos.
Obtén más información sobre la configuración de destinos de Cloud Deploy