Configura notificaciones para servicios de terceros

Cuando tus compilaciones de Cloud Build cambian de estado, puedes enviar notificaciones sobre estos cambios a través de servicios de mensajería de terceros o por correo electrónico.

Los servicios como Slack ofrecen webhooks entrantes, una manera sencilla de publicar mensajes de aplicaciones en Slack. Cloud Functions es una solución de procesamiento ligero que permite crear funciones individuales y de un solo propósito que respondan a eventos de nube, como compilaciones, sin necesidad de administrar un entorno de servidor o de ejecución. Cuando se produce un evento de la nube, un activador responde mediante la ejecución de una acción, como el envío de un mensaje de Cloud Pub/Sub.

Existen muchos servicios de terceros compilados con la función de mensajería entre aplicaciones, como IFTTT y SendGrid. Puedes usar este instructivo como una plantilla para conectarte con esos servicios.

En este instructivo, se demuestra cómo puedes usar Cloud Functions y Cloud Pub/Sub para enviar notificaciones sobre Cloud Build a través de Slack y Mailgun.

Objetivos

  • Implementa una aplicación de Slack para recibir notificaciones externas de Cloud Build.
  • Escribe una función de Cloud Functions para enviar notificaciones de Pub/Sub a Slack.
  • Configura Mailgun para recibir notificaciones externas de Cloud Build.
  • Escribe una función de Cloud Functions para enviar notificaciones de Pub/Sub a Mailgun.

Costos

En este instructivo, se usan componentes facturables de Cloud Platform, incluidos los siguientes:

  • Cloud Functions
  • Cloud Pub/Sub
  • Cloud Build

Usa la calculadora de precios para generar una estimación de los costos según el uso previsto.

Los usuarios nuevos de Cloud Platform pueden optar por una prueba gratuita.

Antes de comenzar

  1. Accede a tu Cuenta de Google.

    Si todavía no tienes una cuenta, regístrate para obtener una nueva.

  2. Selecciona o crea un proyecto de GCP.

    Ir a la página Administrar recursos

  3. Comprueba que la facturación esté habilitada en tu proyecto.

    Descubre cómo puedes habilitar la facturación

  4. Habilita las Cloud Functions y Cloud Pub/Sub API necesarias.

    Habilita las API

  5. Realiza la instalación y la inicialización del SDK de Cloud.
  6. Actualiza y, luego, instala los componentes de gcloud:
    gcloud components update &&
    gcloud components install Alfa Beta

Notificaciones de Slack

En las siguientes secciones, se te indicará cómo configurar notificaciones de Slack.

Prepara la aplicación de Slack

  1. Descarga Slack para tu computadora. También debes unirte a un espacio de trabajo de Slack; para hacerlo, regístrate con tu correo electrónico o usa una invitación que te envió un administrador del espacio.

  2. Accede a Slack con el nombre de tu espacio de trabajo y tus credenciales de la cuenta de Slack.

  3. Para crear una aplicación de Slack nueva, sigue estos pasos:

    1. Elige el nombre de la aplicación y tu espacio de trabajo de Slack. Haz clic en Crear aplicación (Create App).
    2. En Características (Features), haz clic en Webhooks entrantes (Incoming Webhooks).
    3. Habilita Activar webhooks entrantes (Activate Incoming Webhooks).
    4. Haz clic en Agregar nuevo webhook al espacio de trabajo (Add New Webhook to Workspace). Se abre una página de autorización.
    5. En el menú desplegable, selecciona el canal al que deseas que se envíen las notificaciones.
    6. Haz clic en Instalar (Install).
    7. Se crea un webhook para tu aplicación de Slack. Copia la URL de webhook y guárdala para usarla más tarde.

Escribe la función de Cloud Functions

Crea un directorio nuevo llamado gcb_slack y, luego, usa el comando de cambio de directorio de la siguiente manera:

mkdir ~/gcb_slack
cd ~/gcb_slack

Luego, crea los archivos index.js y package.json en el directorio gcb_slack de la siguiente manera:

index.js

const { IncomingWebhook } = require('@slack/webhook');
const url = process.env.SLACK_WEBHOOK_URL;

const webhook = new IncomingWebhook(url);

// subscribeSlack is the main function called by Cloud Functions.
module.exports.subscribeSlack = (pubSubEvent, context) => {
  const build = eventToBuild(pubSubEvent.data);

  // Skip if the current status is not in the status list.
  // Add additional statuses to list if you'd like:
  // QUEUED, WORKING, SUCCESS, FAILURE,
  // INTERNAL_ERROR, TIMEOUT, CANCELLED
  const status = ['SUCCESS', 'FAILURE', 'INTERNAL_ERROR', 'TIMEOUT'];
  if (status.indexOf(build.status) === -1) {
    return;
  }

  // Send message to Slack.
  const message = createSlackMessage(build);
  webhook.send(message);
};

// eventToBuild transforms pubsub event message to a build object.
const eventToBuild = (data) => {
  return JSON.parse(Buffer.from(data, 'base64').toString());
}

// createSlackMessage creates a message from a build object.
const createSlackMessage = (build) => {
  const message = {
    text: `Build \`${build.id}\``,
    mrkdwn: true,
    attachments: [
      {
        title: 'Build logs',
        title_link: build.logUrl,
        fields: [{
          title: 'Status',
          value: build.status
        }]
      }
    ]
  };
  return message;
}

SLACK_WEBHOOK_URL es una variable de entorno de Cloud Functions que especifica la URL de webhook que se creó para tu aplicación de Slack. Esta variable de entorno se definirá cuando se implemente la función.

Este programa usa el webhook de Slack para escuchar y recibir mensajes de Cloud Functions. Cuando se activa un evento, se envía un mensaje al webhook y, luego, se transmite a Slack.

La función createSlackMessage se simplificó para este ejemplo. Puedes expandir el mensaje para que incluye mucho más, como los colores del texto, las imágenes y la duración de la compilación.

package.json

{
  "name": "google-container-slack",
  "version": "0.0.1",
  "description": "Slack integration for Google Cloud Build, using Google Cloud Functions",
  "main": "index.js",
  "dependencies": {
    "@slack/webhook": "5.0.1"
  }
}

package.json describe lo siguiente:

  • el nombre, la versión y la descripción del programa
  • sus archivos de entorno de ejecución principales
  • sus dependencias

Este archivo parece simple: puedes agregar más dependencias, requisitos y otra información según sea necesario.

Ahora, deberías tener index.js y package.json en el directorio gcb_slack.

Implementa la función de Cloud Functions

Para implementar la función subscribeSlack con un activador de Cloud Pub/Sub, ejecuta el comando siguiente en el directorio gcb_slack:

gcloud functions deploy subscribeSlack --trigger-topic cloud-builds --runtime nodejs10 --set-env-vars "SLACK_WEBHOOK_URL=https://hooks.slack.com/…"

en el que SLACK_WEBHOOK_URL define la URL de webhook que se creó para tu aplicación de Slack. El formato de la URL es: https://hooks.slack.com/services/T…/B…/….

Deberías ver un resultado similar al que se detalla a continuación:

Deploying function…
availableMemoryMb: 256
entryPoint: subscribeSlack
environmentVariables:
  SLACK_WEBHOOK_URL: https://hooks.slack.com/services/…
eventTrigger:
  eventType: google.pubsub.topic.publish
  failurePolicy: {}
  resource: projects/[PROJECT-ID]/topics/cloud-builds
  service: pubsub.googleapis.com
labels:
  deployment-tool: cli-gcloud
name: projects/[PROJECT-ID]/locations/us-central1/functions/subscribeSlack
runtime: nodejs10
serviceAccountEmail: [PROJECT-ID]@appspot.gserviceaccount.com
sourceUploadUrl: https://storage.googleapis.com/…
status: ACTIVE
timeout: 60s
updateTime: 'YYYY-MM-DDThh:mm:ssZ'
versionId: '1'

Luego de completar la implementación de la función de Cloud Functions, recibirás una notificación de Slack cuando se produzca un evento de compilación.

Notificaciones por correo electrónico

En las secciones siguientes, se te indicará cómo configurar notificaciones por correo electrónico con la API de Mailgun.

Si recién comienzas a usar Mailgun, consulta su documentación de inicio rápido.

Prepara la configuración de Mailgun

  1. Si aún no lo hiciste, crea una cuenta de Mailgun.
  2. Usa un dominio de zona de pruebas de Mailgun o agrega un dominio nuevo y, luego, sigue las instrucciones de Mailgun.
  3. En la página de dominios, haz clic en tu dominio para abrir la página de configuración.
  4. En API, haz clic en Seleccionar (Select), Node.js, y copia la clave de API del dominio a fin de guardarla para su uso posterior.

También debes contar con lo siguiente:

  • Una dirección de correo electrónico para enviar correos electrónicos. Esta dirección de correo electrónico puede pertenecer al dominio que proporciones. Si no estás seguro de qué dirección de correo electrónico debes usar, consulta con tu proveedor de dominio. También puedes proporcionar un correo electrónico inexistente si no esperas una respuesta del destinatario, como noreply@mydomain.com.
  • Una dirección de correo electrónico para recibir correos electrónicos

Escribe la función de Cloud Functions

Crea un directorio nuevo llamado gcb_email y, luego, usa el comando de cambio de directorio de la siguiente manera:

mkdir ~/gcb_email
cd ~/gcb_email

A continuación, crea los archivos index.js, config.json y package.json en el directorio gcb_email:

index.js

const Mailgun = require('mailgun-js');
const humanizeDuration = require('humanize-duration');
const config = require('./config.json');

const mailgun = Mailgun({
  apiKey: config.MAILGUN_API_KEY,
  domain: config.MAILGUN_DOMAIN,
});

// subscribeMailgun is the main function called by Cloud Functions.
module.exports.subscribeMailgun = (pubSubEvent, context) => {
  const build = eventToBuild(pubSubEvent.data);

  // Skip if the current status is not in the status list.
  const status = ['SUCCESS', 'FAILURE', 'INTERNAL_ERROR', 'TIMEOUT'];
  if (status.indexOf(build.status) === -1) {
    return;
  }

  // Send email.
  const message = createEmail(build);
  mailgun.messages().send(message, (error, body) => console.log(body.message));
};

// eventToBuild transforms pubsub event message to a build object.
const eventToBuild = (data) => {
  return JSON.parse(Buffer.from(data, 'base64').toString());
}

// createEmail creates an email message from a build object.
const createEmail = (build) => {
  const duration = humanizeDuration(new Date(build.finishTime) - new Date(build.startTime));
  const msgText = `Build ${build.id} finished with status ${build.status}, in ${duration}.`;
  let msgHtml = `<p>${msgText}</p><p><a href="${build.logUrl}">Build logs</a></p>`;
  if (build.images) {
    const images = build.images.join(',');
    msgHtml += `<p>Images: ${images}</p>`;
  }
  const message = {
    from: config.MAILGUN_FROM,
    to: config.MAILGUN_TO,
    subject: `Build ${build.id} finished`,
    text: msgText,
    html: msgHtml
  };
  return message;
}

config.json

{
  "MAILGUN_API_KEY":"[API_KEY]",
  "MAILGUN_DOMAIN":"email.com",
  "MAILGUN_FROM":"me@email.com",
  "MAILGUN_TO":"someone@email.com"
}

En este archivo, debes proporcionar la siguiente información:

  • MAILGUN_API_KEY, la clave de API que recopilaste
  • MAILGUN_DOMAIN, el dominio que configuraste
  • MAILGUN_FROM, la dirección de correo electrónico que pertenece al dominio desde el cual se envían los correos electrónicos (incluso uno que no existe)
  • MAILGUN_TO, la dirección de correo electrónico a la que se envía el correo electrónico

package.json

{
  "name": "google-container-email",
  "version": "0.0.1",
  "description": "Email integration for Google Cloud Build, using Google Cloud Functions",
  "main": "index.js",
  "dependencies": {
    "humanize-duration": "3.10.0",
    "mailgun-js": "~0.11.2"
  },
  "devDependencies": {
    "async": "^2.1.5",
    "mocha": "3.2.0",
    "should": "11.2.1"
  }
}

package.json describe lo siguiente:

  • el nombre, la versión y la descripción del programa
  • sus archivos de entorno de ejecución principales
  • sus dependencias

Ahora, deberías tener index.js, config.json y package.json en el directorio gcb_email.

Implementa la función de Cloud Functions

Para implementar la función, ejecuta el comando siguiente en el directorio gcb_email:

gcloud functions deploy subscribeMailgun --trigger-topic cloud-builds --runtime nodejs10

Luego de completar la implementación de la función de Cloud Functions, deberías recibir una notificación por correo electrónico cuando se produce un evento de compilación.

Prueba la función

Después de la configuración, debes probar tu implementación para asegurarte de que funciona según lo esperado. Para realizar la prueba, envía una compilación a Cloud Build.

Crea un directorio nuevo llamado gcb_test y, luego, usa el comando de cambio de directorio de la siguiente manera:

mkdir ~/gcb_test
cd ~/gcb_test

A continuación, crea un archivo llamado request.json que contenga el código siguiente. Esta solicitud activa una compilación mediante la clonación de un repositorio.

request.json

{
  "steps": [
    {
      "name": "gcr.io/cloud-builders/git",
      "args": [
        "clone",
        "https://github.com/GoogleCloudPlatform/cloud-builders"
      ]
    }
  ]
}

Luego, ejecuta el comando siguiente en el directorio gcb_test:

Linux/macOS

curl \
  -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -T request.json \
  https://cloudbuild.googleapis.com/v1/projects/[PROJECT-ID]/builds

PowerShell

(Invoke-WebRequest `
  -Method POST `
  -Headers @{ "Authorization" = "Bearer $(gcloud auth print-access-token)" } `
  -ContentType "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri https://cloudbuild.googleapis.com/v1/projects/[PROJECT-ID]/builds `
).Content

en el que [PROJECT-ID] es el ID de tu proyecto.

Deberías recibir una respuesta similar a la que figura a continuación:

{
  "name": "operations/build/[PROJECT-ID]/…",
  "metadata": {
    "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata",
    "build": {
      "id": "…",
      "status": "QUEUED",
      "createTime": "…",
      "steps": [
        {
          "name": "gcr.io/cloud-builders/git",
          "args": [
            "clone",
            "https://github.com/GoogleCloudPlatform/cloud-builders"
          ]
        }
      ],
…

Si seguiste las instrucciones de Slack, deberías ver una notificación de Slack como la que se presenta a continuación:

Si seguiste las instrucciones de Mailgun, deberías recibir un correo electrónico sobre la compilación.

Realiza una limpieza

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud Platform por los recursos que usaste en este instructivo:

Cómo borrar el proyecto

La manera más fácil de eliminar la facturación es borrar el proyecto que creaste para el instructivo.

Para borrar el proyecto, haz lo siguiente:

  1. En la GCP Console, dirígete a la página Proyectos.

    Ir a la página Proyectos

  2. En la lista de proyectos, selecciona el proyecto que deseas borrar y haz clic en Borrar.
  3. En el cuadro de diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

Borra la función de Cloud Functions

Para borrar las funciones de Cloud Functions que implementaste en este instructivo, ejecuta los comandos siguientes:

gcloud functions delete subscribeMailgun
gcloud functions delete subscribeSlack

También puedes borrar las funciones de Cloud Functions desde Google Cloud Platform Console.

Pasos siguientes

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Documentación de Cloud Build