Cómo crear un segmento personalizado

En este documento, se describe cómo crear un tipo de segmentación personalizado de Cloud Deploy y usarlo como segmentación 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 utilizándolos en tu canalización de entrega:

  1. Crea una aplicación contenedorizada o aplicaciones que incluyan la funcionalidad para implementar en tu destino personalizado y que cumplan con los requisitos de Cloud Deploy para los tipos de destinos personalizados.

  2. Define una acción personalizada en skaffold.yaml que hace referencia a ese contenedor y especifica los comandos que se ejecutarán 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 objetivo nuevo con una propiedad customTarget que identifique tu nuevo tipo de objetivo personalizado.

  5. Haz referencia a ese objetivo desde la progresión de tu canalización de entrega.

  6. 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 que se implementará en tu destino personalizado se define en aplicaciones en contenedores, que le proporcionas a Cloud Deploy haciendo referencia a ellas desde tu archivo skaffold.yaml. Cuándo 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 un tipo de destino personalizado en Skaffold para ejecutar las acciones de renderización y de implementación definido.

Tú decides el comportamiento de tus aplicaciones. Sin embargo, debe consumir variables de entorno de entrada que proporciona Cloud Deploy, y debe devolver los resultados obligatorios

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

Define tus acciones personalizadas en Skaffold

Con las imágenes de contenedor de acción personalizada en su lugar, puedes hacer referencia a ellas desde tu archivo de configuración skaffold.yaml.

Cada acción personalizada para un objetivo personalizado se configura en una estancia customActions. Para cualquier tipo de segmentación personalizada, puedes crear una acción personalizada, en Skaffold, para renderizado y otro para 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 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, ocurre lo siguiente:

  • customActions.name

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

  • La estrofa containers incluye tu referencia y comandos para ejecutar esa 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 estás usando para esta acción. Como práctica recomendada, este nombre de contenedor siempre debe estar calificado como 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 utilizadas en customActions

Define tu tipo de segmentación personalizada

Para definir un destino personalizado, primero crea un tipo de destino personalizado con el Configuración de CustomTargetType. Puedes crear el CustomTargetType en el mismo archivo que tu canalización de entrega. definición, con las definiciones de destino, o en un archivo separado.

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:

Dónde

  • CUSTOM_TARGET_TYPE_NAME

    Es un nombre arbitrario que le asignas a esta definición de tipo de objetivo personalizado. Se hace referencia a este nombre en la definición del objetivo para cualquier objetivo que use el tipo de objetivo personalizado que definas.

  • 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 el 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 el deploy.

  • includeSkaffoldModules

    Es una estrofa opcional para usar si usas configuraciones remotas de Skaffold. El propiedades de esta estrofa se muestran en la sección Usa la configuración remota de Skaffold.

Usa configuraciones remotas de Skaffold

Puedes almacenar los parámetros de configuración de Skaffold en un repositorio público de Git, bucket de Cloud Storage o repositorio de Cloud Build de 2ª gen.. y hacer referencia a esos parámetros de configuración desde la definición del tipo de destino personalizado.

Si usas la configuración remota de Skaffold, implica que el skaffold.yaml que proporciones en la hora de 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:

  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 bucket de Cloud Storage.

  3. En la definición del tipo de segmentación personalizada, agrega un Estrofa customActions.includeSkaffoldModules.

  4. En includeSkaffoldModules, especifica lo siguiente:

    • De manera opcional, uno o más elementos configs:

      - configs: ["name1", "name2"]

      El valor de configs es una lista de cadenas que coinciden con metadata.name. en cada configuración de Skaffold que se incluya. Si se omite, Cloud Deploy toma todas las configuraciones de la ruta de acceso especificada.

    • Una estrofa googleCloudStorage, git o googleCloudBuildRepo.

      Para Cloud Storage:

      googleCloudStorage:
  source: PATH_TO_GCS_BUCKET
  path: FILENAME

      Para Git:

      git:
  repo: REPO_URL
  path: PATH_TO_FILE
  ref: BRANCH_NAME

      Para los repositorios de Cloud Build (2ª gen..):

       googleCloudBuildRepo:
  repository: PATH_TO_GCB_REPO
  path: PATH_TO_FILE
  ref: BRANCH_NAME

      Aquí:

      PATH_TO_GCS_BUCKET es la ruta a un directorio de Cloud Storage. que termina con /*, donde se almacenan los parámetros de configuración de Skaffold. Descargas de Skaffold todos los archivos de este directorio encuentra el archivo de Skaffold relevante con la configuración, según la ruta relativa configurada.

      PATH_TO_GCB_REPO es la ruta de acceso al repositorio de Cloud Build de 2ª gen., en el que se almacenan las configuraciones de Skaffold. La ruta toma la siguiente forma: projects/{project}/locations/{location}/connections/{connection}/repositories/{repository} Skaffold descarga todos los archivos de este directorio y, luego, encuentra el archivo Skaffold según la ruta de acceso relativa configurada.

      FILENAME es el nombre del archivo que incluye los parámetros 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í, el la creación de versiones falla.

      REPO_URL es la URL que dirige al repositorio de Git.

      PATH_TO_FILE es la ruta de acceso en ese repositorio al archivo que contiene las configuraciones de Skaffold.

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

Ejemplo

El siguiente YAML de tipo de destino personalizado es una estrofa customActions con una estrofa includeSkaffoldModules que apunta a parámetros 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 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. El CustomTargetType debe estar en el mismo proyecto que el recurso Target que hace referencia a él. No necesitas especificar 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á este recurso. El CustomTargetType debe estar en la misma región que Target recurso que hace referencia a ella. No necesitas especificar la región si la configuraste como la región predeterminada para la CLI de gcloud.

Ahora que el CustomTargetType se creó como un recurso de Cloud Deploy, Ahora 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 objetivo para un tipo de destino admitido y una definición del destino personalizado es que incluye un Estrofa customTarget. La sintaxis de un customTarget es la siguiente:

customTarget:
  customTargetType: [CUSTOM_TARGET_TYPE_NAME]

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

Agrega tu segmentación a la canalización de publicación

Puedes usar un destino personalizado en una canalización de entrega exactamente como lo harías con un en el tipo de destino admitido. Es decir, no hay diferencia en la progresión de la canalización de publicación entre los objetivos de un tipo de objetivo compatible y los objetivos personalizados.

Todos los destinos de una canalización de publicación deben usar el mismo tipo de destino. Por ejemplo: No puedes tener una canalización de entrega con algunos destinos que se implementan Google Kubernetes Engine y algunos destinos personalizados.

Al igual que con los tipos de destinos admitidos, puede incluir implementar parámetros en la etapa de canalización.

Crea una versión

Con tu tipo de destino personalizado completamente definido y un destino creado para usar ese tipo, ahora 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 la versión, se ejecuta la acción de renderización personalizada para cada destino. de tu canalización de entrega, incluido el procesamiento implementar parámetros 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 personalizado.

Consulta el resultado de tus objetivos personalizados

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

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

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

    Abrir la página Canalizaciones de entrega

  2. 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 tu versión aparece en la pestaña Versiones, en Detalles de la canalización de entrega.

  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, haz clic en la flecha junto a Ver artefactos.

    Se muestran los artefactos renderizados, incluido el skaffold.yaml renderizado y el archivo de manifiesto renderizado que genera el renderizador personalizado. Y puedes haz clic en el vínculo Ubicación de almacenamiento junto a cada uno para ir al de bucket de Cloud Storage para ver esos archivos.

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

¿Qué sigue?