Crear un destino personalizado

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

A continuación se describe el proceso general para crear un tipo de segmentación personalizado y usarlo en su canal de distribución:

  1. Crea una aplicación contenerizada o aplicaciones que incluyan la funcionalidad para desplegarse en tu destino personalizado y que cumplan los requisitos de Cloud Deploy para los tipos de destino personalizado.

  2. Define una acción personalizada en skaffold.yaml que haga referencia a ese contenedor y especifique los comandos que se van a ejecutar en él.

  3. 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.

  4. Define un nuevo objetivo con una propiedad customTarget que identifique tu nuevo tipo de objetivo personalizado.

  5. Haz referencia a ese objetivo desde tu flujo de procesamiento de entrega progression.

  6. Crea una versión.

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

Crear aplicaciones en contenedores

La función de desplegar en tu destino personalizado se define en aplicaciones contenerizadas, que proporcionas a Cloud Deploy haciendo referencia a ellas desde tu archivo skaffold.yaml. Cuando tu canalización de distribución incluye un destino que usa un tipo de destino personalizado, Cloud Deploy llama a los contenedores de acciones personalizadas definidos para ese tipo de destino personalizado en Skaffold para ejecutar las acciones de renderización y despliegue que hayas definido.

El comportamiento de tus aplicaciones depende de ti. Sin embargo, debe consumir las variables de entorno de entrada proporcionadas por Cloud Deploy y devolver las salidas obligatorias.

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

Definir acciones personalizadas en Skaffold

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

Cada acción personalizada se configura para un destino personalizado en una customActions sección. Para cualquier tipo de destino personalizado, crea una acción personalizada en Skaffold para renderizar y otra para desplegar. La definición CustomTargetType identifica qué acción personalizada se usa para renderizar y cuál para implementar.

A continuación, se muestra la configuración de las acciones de renderización e implementació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:

  • customActions.name

    Es un nombre arbitrario para la acción de renderización o implementación personalizada. La definición de CustomTargetType hace referencia a este nombre en la propiedad renderAction o en la propiedad deployAction.

  • La estrofa containers incluye tu referencia, además de los 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 del contenedor específico que estás usando para esta acción. Como práctica recomendada, el nombre del contenedor siempre debe estar cualificado por SHA.

  • image

    Es la ruta de la imagen del contenedor.

  • command

    Es el comando o los comandos que se van a ejecutar en el contenedor.

  • args

    Es una colección de argumentos de command.

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

Definir un tipo de segmentación personalizada

Para definir un destino personalizado, primero debe 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 canal de distribución, con definiciones de destino o en un archivo independiente.

La definición de CustomTargetType es la siguiente:

# Custom target type config
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:

Dónde

  • CUSTOM_TARGET_TYPE_NAME

    Es un nombre arbitrario que asignas a esta definición de tipo de segmentación personalizada. Este nombre se hace referencia en la definición de destino de 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 render.

  • 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 que se puede usar si utilizas configuraciones de Skaffold remotas. Las propiedades de esta estrofa se muestran en la sección Usar configuraciones de Skaffold remotas.

Usar configuraciones remotas de Skaffold

Puedes almacenar configuraciones de Skaffold en un repositorio de Git público, un segmento de Cloud Storage o un repositorio de segunda generación de Cloud Build, y hacer referencia a esas configuraciones desde la definición de tu tipo de destino personalizado.

Si usas configuraciones de Skaffold remotas, no es necesario que el skaffold.yaml que proporciones en el momento del lanzamiento tenga definidas las acciones personalizadas. Esto permite compartir acciones personalizadas en toda la organización.

Para usar configuraciones de Skaffold remotas, sigue estos pasos:

  1. Crea una configuración de Skaffold con tu acción o acciones personalizadas.

  2. Almacena la configuración en un repositorio de Git o en un segmento de Cloud Storage.

  3. En la definición del tipo de segmentación personalizada, añade una estrofa customActions.includeSkaffoldModules.

  4. En includeSkaffoldModules, especifica lo siguiente:

    • De forma 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 de cada configuración de Skaffold que se va a incluir. Si se omite, Cloud Deploy toma todas las configuraciones de la ruta especificada.

    • Una estrofa googleCloudStorage, git o googleCloudBuildRepo.

      En Cloud Storage:

      googleCloudStorage:
  source: PATH_TO_GCS_BUCKET
  path: FILENAME

      Para Git:

      git:
  repo: REPO_URL
  path: PATH_TO_FILE
  ref: BRANCH_NAME

      En Cloud Build Repositories (2.ª gen.):

       googleCloudBuildRepo:
  repository: PATH_TO_GCB_REPO
  path: PATH_TO_FILE
  ref: BRANCH_NAME

      Donde:

      PATH_TO_GCS_BUCKET es la ruta a un directorio de Cloud Storage que termina en /*, donde se almacenan las configuraciones de Skaffold. Skaffold descarga todos los archivos de este directorio y, a continuación, busca el archivo de Skaffold correspondiente con las configuraciones, en función de la ruta relativa configurada.

      PATH_TO_GCB_REPO es la ruta al repositorio de Cloud Build de segunda generación donde se almacenan las configuraciones de Skaffold. La ruta tiene el siguiente formato: projects/{project}/locations/{location}/connections/{connection}/repositories/{repository}. Skaffold descarga todos los archivos de este directorio y, a continuación, busca el archivo Skaffold en función de la ruta relativa configurada.

      FILENAME es el nombre del archivo que incluye las configuraciones de Skaffold. La propiedad path: es opcional. Si no la especificas, Cloud Deploy asigna el valor skaffold.yaml. Si no hay ningún skaffold.yaml o el nombre de archivo que especifiques no existe, no se podrá crear la versión.

      REPO_URL es la URL del repositorio de Git.

      PATH_TO_FILE es la ruta del repositorio al archivo que contiene las configuraciones de Skaffold.

      BRANCH_NAME es el nombre de la rama (por ejemplo, main) de la que se van a tomar las configuraciones de Skaffold.

Ejemplo

El siguiente YAML de tipo de destino personalizado es una sección customActions con una sección includeSkaffoldModules que apunta a las configuraciones de Skaffold almacenadas en un segmento 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 archivo 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

Registrar tu tipo de segmentación personalizada

Una vez que hayas configurado el CustomTargetType, ejecuta el comando gcloud deploy apply para registrar el recurso CustomTargetType en un proyecto Google Cloud :

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

Donde:

FILE es el nombre del archivo en el que has definido este tipo de segmentación personalizada.

PROJECT es el Google Cloud proyecto en el que se creará este recurso. El CustomTargetType debe estar en el mismo proyecto que el recurso Target que lo referencia. No es necesario que especifiques el proyecto si lo has definido como proyecto predeterminado para la CLI de Google Cloud.

REGION es la región (por ejemplo, us-centra1) en la que se va a crear este recurso. El CustomTargetType debe estar en la misma región que el recurso Target que lo referencia. No es necesario que especifiques la región si la has definido como región predeterminada para la CLI de gcloud.

Ahora que el CustomTargetType se ha creado como 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 de un tipo de destino admitido y una definición de destino personalizada es que esta última incluye una estrofa customTarget. La sintaxis de un customTarget es la siguiente:

customTarget:
  customTargetType: [CUSTOM_TARGET_TYPE_NAME]

Donde CUSTOM_TARGET_TYPE_NAME es el valor de la propiedad name definida en tu configuración de tipo de destino personalizado.

.

Añadir el destino a la canalización de entrega

Puedes usar un destino personalizado en una canalización de entrega exactamente igual que un tipo de destino admitido. Es decir, no hay ninguna diferencia en el proceso de entrega entre los objetivos de un tipo de objetivo admitido y los objetivos 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 distribución con algunos destinos que se implementen en Google Kubernetes Engine y otros destinos personalizados.

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

Crear una versión

Una vez que hayas definido por completo el tipo de segmentación personalizado y hayas creado un elemento de segmentación para usar ese tipo, puedes crear una versión de la forma habitual:

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

Cuando se crea una versión, se ejecuta la acción de renderización personalizada para cada destino de tu canal de distribución, incluido el procesamiento de los parámetros de implementación configurados en la versión, los destinos o el canal de distribución. Cloud Deploy proporciona los parámetros de despliegue como entrada al contenedor de renderizado personalizado.

Ver el resultado de los objetivos personalizados

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

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

  1. En la Google Cloud consola, ve a la página de Cloud Deploy Flujos de procesamiento de entrega para ver tu flujo de procesamiento de entrega.

    Abre la página Pipelines de entrega.

  2. Haga clic en el nombre de su canalización de entrega.

    La visualización de la canalización muestra el estado de implementación de la aplicación y tu versión aparece en la pestaña Versiones, en Detalles de la canalización de lanzamiento.

  3. Haz clic en el nombre de la versión.

    Se muestra la página Detalles de la versión.

  4. Haz clic en la pestaña Artefactos.

  5. En Artefactos de destino, haga clic en la flecha situada junto a Ver artefactos.

    Se muestran los artefactos renderizados, incluidos el skaffold.yaml renderizado y el archivo de manifiesto renderizado generado por el renderizador personalizado. También puede hacer clic en el enlace Ubicación de almacenamiento situado junto a cada uno para ir al segmento de Cloud Storage y ver esos archivos.

    También puedes hacer clic en el enlace Ver artefactos para ver esos archivos por lanzamiento, por destino o por fase mediante el inspector de lanzamientos.

Siguientes pasos