Tutorial: automatiza clústeres con activadores programados

Crea una cuenta de servicio.

Para crear una cuenta de servicio que tus Triggers puedan utilizar para llamar a la API de administración de Atlas con Project Owner permisos en tu proyecto de Atlas existente:

1. En Atlas, ve a Users página.

   1. Si aún no se muestra, selecciona la organización deseada en el menú Organizations de la barra de navegación.

   2. Haz clic en All Projects en la barra lateral debajo de la sección Identity & Access y selecciona el proyecto que desees.

   3. Haz clic en Project Identity & Access en la barra lateral en la sección Security.

   Se muestra la página Usuarios.

2. Haz clic en Create Application Service Account.

3. Ingresar la información de la cuenta de servicio.

   • Nombre: nombre para tu cuenta de servicio. (por ejemplo, TriggersServiceAccount)

   • Descripción: (opcional) Descripción de tu cuenta de servicio. (por ejemplo, cuenta de servicio para que Atlas Functions llame a la API de administración de Atlas).

   • Permisos de cuenta de servicio: Project Owner

4. Haga clic en Create.

   Esto crea la cuenta de servicio y la añade automáticamente a una organización principal del proyecto con el permiso Organization Member.

5. Configure el API Access List.

   Agregue direcciones IP al API Access List si desea restringir qué direcciones IP pueden llamar a la API de administración de Atlas con esta cuenta de servicio.

   Nota

   Si Require IP Access List for the Atlas Administration API está activado para tu organización, o si agregaste alguna dirección IP a API Access List de tu cuenta de servicio, cada solicitud de API de administración de Atlas debe pasar una comprobación de la lista de acceso IP.

   Atlas Triggers y Functions envían solicitudes HTTP salientes desde un conjunto específico de direcciones IP salientes. Para permitir que tus activadores programados llamen a la API de administración de Atlas y a otros servicios externos, debes agregar estas direcciones IP a API Access List de tu cuenta de servicio.

   Para la lista completa de direcciones IP de salida utilizadas por Atlas Functions, consulta Acceso de Salida de IP de Seguridad de Funciones. Debe añadir cada dirección IP individualmente.

Almacena las credenciales de la Cuenta de Servicio como Valores y Secretos.

Crea los siguientes valores y secretos para almacenar las credenciales de tu cuenta de servicio:

• AtlasClientId Valor que contiene el ID de cliente de su cuenta de servicio.

• AtlasClientSecret Secreto que contiene el secreto del cliente de tu cuenta de servicio.

• AtlasClientSecret Valor que se vincula al secreto. Esto le permite acceder al valor secreto del cliente en sus Functions, mientras se mantiene almacenado de forma segura como un Secret.

1. En Atlas, diríjase a la página Triggers.

   1. Si aún no aparece, se debe seleccionar la organización que contiene el proyecto en el menú Organizations de la barra de navegación.

   2. Si aún no se muestra, seleccione su proyecto en el menú Projects de la barra de navegación.

   3. En la barra lateral, haz clic en Triggers en la sección Streaming Data.

   Se muestra la página de Triggers.

2. Navega a la página Values.

   1. Haz clic en el enlace Linked App Service: Triggers.

   2. En la barra lateral, haz clic en Values en la sección Build.

3. Guarde el ID de cliente en un valor.

   1. Haga clic Create a Value

   2. Introduce AtlasClientId como Value Name.

   3. Selecciona el tipo Value.

   4. Selecciona la opción Custom Content e introduce el ID del cliente.

      Nota

      Debes ingresar la ID del cliente como un valor de string entre comillas ("<clientId>").

   5. Haga clic en Save.

4. Almacene el secreto del cliente en un Secreto y vincúlelo a un Valor.

   Nota

   No se puede acceder directamente a los valores secretos, por lo que se debe crear un segundo valor que se vincule al secreto.

   1. Haga clic en Create a Value.

   2. Introduce AtlasClientSecret como Value Name.

   3. Selecciona el tipo Value.

   4. Seleccione la opción Link to Secret.

   5. Introduce AtlasClientSecret y haz clic en Create "AtlasClientSecret" para nombrar el valor secreto.

      Pega el secreto del cliente en el campo Client Secret que aparece debajo del nombre del secreto.

   6. Haga clic en Save para crear tanto el Secreto como el Valor.

Crear la función getAuthHeaders.

Para crear una Function reutilizable que recupere un access token utilizando las credenciales de la cuenta de servicio y devuelva los encabezados de autenticación apropiados para invocar el Atlas Administration API:

1. Navega a la página Functions.

   1. En la barra lateral, haz clic en Functions en la sección Build.

   2. Haga clic en Create a Function.

      La pestaña Settings se muestra por defecto.

2. Ingrese getAuthHeaders como el Name para la Función.

3. Establecer Private a true. Esta función solo será llamada por otras funciones en este tutorial.

   Deja las otras opciones de configuración en la pestaña Settings con sus valores predeterminados.

4. Defina el código de la función.

   Haz clic en la pestaña Function Editor y pega el siguiente código para definir la función:

   1
   /*
   2
    * Generate API request headers with a new Service Account Access Token.
   3
    */
   4
   exports = async function getAuthHeaders() {
   5
   6
     // Get stored credentials
   7
     clientId = context.values.get("AtlasClientId");
   8
     clientSecret = context.values.get("AtlasClientSecret");
   9
   10
     // Throw an error if credentials are missing
   11
     if (!clientId || !clientSecret) {
   12
       throw new Error("Authentication credentials not found. Set AtlasClientId/AtlasClientSecret (service account auth credentials).");
   13
     }
   14
   15
     // Define the argument for the HTTP request to get the access token
   16
     const tokenUrl = "https://cloud.mongodb.com/api/oauth/token";
   17
     const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
   18
   19
     const arg = {
   20
       url: tokenUrl,
   21
       headers: {
   22
         "Authorization": [ `Basic ${credentials}` ],
   23
         "Content-Type": [ "application/x-www-form-urlencoded" ]
   24
       },
   25
       body: "grant_type=client_credentials"
   26
     }
   27
   28
     // The response body is a BSON.Binary object; parse it to extract the access token 
   29
     const response = await context.http.post(arg);
   30
     const tokenData = JSON.parse(response.body.text());
   31
     const accessToken = tokenData.access_token;
   32
   33
     // Define the Accept header with the resource version from env var or default to latest stable
   34
     const resourceVersion = context.environment.ATLAS_API_VERSION || "2025-03-12";
   35
     const acceptHeader = `application/vnd.atlas.${resourceVersion}+json`;
   36
   37
     // Return the access token as headers for future API calls
   38
     return {
   39
      headers: {
   40
        "Authorization": [ `Bearer ${accessToken}` ],
   41
        "Accept": [ acceptHeader ],
   42
        "Accept-Encoding": [ "bzip, deflate" ],
   43
        "Content-Type": [ "application/json" ]
   44
      }
   45
     };
   46
   }

Crear la función modifyCluster.

Para crear una función reutilizable que envuelva el endpoint Actualizar un clúster en un proyecto:

1. Desde la página Functions, haz clic en Create a Function.

   La pestaña Settings se muestra por defecto.

2. Ingrese modifyCluster como el Name para la Función.

3. Establecer Private a true. Esta función solo será llamada por otras funciones en este tutorial.

   Deja las otras opciones de configuración en la pestaña Settings con sus valores predeterminados.

4. Defina el código de la función.

   Haz clic en la pestaña Function Editor y pega el siguiente código para definir la función:

   1
   /*
   2
    * Modifies the cluster as defined by the `body` parameter.
   3
    * See https://www.mongodb.com/es/docs/atlas/reference/api-resources-spec/v2/#tag/Clusters/operation/updateCluster
   4
    */
   5
   exports = async function(projectID, clusterName, body) {
   6
   7
     // Easy testing from the console
   8
     if (projectID === "Hello world!") {
   9
       projectID   = "<projectId>";
   10
       clusterName = "<clusterName>";
   11
       body        = { paused: false };
   12
     }
   13
   14
     // Retrieve headers to authenticate with a new access token, and define the request URL for the Atlas API endpoint
   15
     const authHeaders = await context.functions.execute("getAuthHeaders");
   16
     const requestUrl = `https://cloud.mongodb.com/api/atlas/v2/groups/${projectID}/clusters/${clusterName}`;
   17
   18
     // Build the argument for the HTTP request to the Atlas API to modify the cluster
   19
     const arg = {
   20
       url: requestUrl,
   21
       headers: authHeaders.headers,
   22
       body: JSON.stringify(body)
   23
     };
   24
   25
     // The response body is a BSON.Binary object; parse it and return the modified cluster description
   26
     const response = await context.http.patch(arg);
   27
     if (response.body) {
   28
        return EJSON.parse(response.body.text()); 
   29
     } else {
   30
        throw new Error(`No response body returned from Atlas API. Status code: ${response.status}`);
   31
     }
   32
   };

   Nota

   Probar el código en el Editor de funciones.

   El Function Editor proporciona automáticamente "Hello world!" como primer argumento cuando ejecutas una función en el Testing Console. Este código comprueba esa entrada y proporciona valores a los parámetros cuando se recibe "Hello world!".

   Para probar la función con tus propios datos, reemplaza los siguientes valores de marcador de posición con tu propia información:

   • <projectId>

   • <clusterName>

   • En el parámetro body, proporcione una carga útil que contenga las modificaciones que desea realizar en el clúster. El código de ejemplo incluye una carga útil que pausa un clúster.

Crear la función pauseClusters.

1. En Atlas, diríjase a la página Triggers.

   1. Si aún no aparece, se debe seleccionar la organización que contiene el proyecto en el menú Organizations de la barra de navegación.

   2. Si aún no se muestra, seleccione su proyecto en el menú Projects de la barra de navegación.

   3. En la barra lateral, haz clic en Triggers en la sección Streaming Data.

   Se muestra la página de Triggers.

2. Navegar a la página de Functions

   1. Haz clic en el enlace Linked App Service: Triggers.

   2. En la barra lateral, haz clic en Functions en la sección Build.

   3. Haga clic en Create a Function.

      La pestaña Settings se muestra por defecto.

3. Ingrese pauseClusters como el Name para la Función.

4. Establecer Private a true. Esta función solo será llamada por el activador pauseClusters en este tutorial.

   Deja las otras opciones de configuración en la pestaña Settings con sus valores predeterminados.

5. Defina el código de la función.

   Haz clic en la pestaña Function Editor y pega el siguiente código para definir la función:

   1
   /*
   2
    * Iterates over the provided projects and clusters, pausing those clusters.
   3
    */
   4
   exports = async function () {
   5
   6
     // Supply project IDs and cluster names to pause
   7
     const projectIDs = [
   8
       {
   9
         id: "<projectIdA>",
   10
         names: [ "<clusterNameA>", "<clusterNameB>" ]
   11
       },
   12
       {
   13
         id: "<projectIdB>",
   14
         names: [ "<clusterNameC>" ]
   15
       }
   16
     ];
   17
   18
     // Set desired state
   19
     const body = { paused: true };
   20
   21
     // Pause each cluster and log the response
   22
     for (const project of projectIDs) {
   23
       for (const cluster of project.names) {
   24
         const result = await context.functions.execute(
   25
           "modifyCluster",
   26
           project.id,
   27
           cluster,
   28
           body,
   29
         );
   30
         console.log("Cluster " + cluster + ": " + EJSON.stringify(result));
   31
       }
   32
     }
   33
   34
     return "Clusters Paused";
   35
   };

   Reemplace el arreglo projectIDs con los nombres de su propio Proyecto y clúster.

   Nota

   Para evitar escribir manualmente los nombres de Proyecto y clústeres, puedes utilizar las Funciones asistente al final de este tutorial para recuperar listas de Proyectos y clústeres de la API de administración de Atlas y determinar programáticamente qué clústeres pausar y reanudar según un cronograma.

Cree el pauseClusters activador programado.

1. Desde la página Functions, navega hasta la página Triggers haciendo clic en Triggers en la barra lateral bajo el encabezado Build.

2. Haz clic en Create a Trigger para abrir la página de configuración del activador.

   Si tienes un activador existente, haz clic en Add a Trigger

3. Configura los ajustes del activador.

   En Trigger Details, configure lo siguiente:

   Configuración	Valor
   Tipo de activador	Programado
   Tipo de cronograma	Avanzado. Esto te permite especificar una expresión CRON para el cronograma. Para ejecutar esto todas las noches de los días hábiles a las 6 p. m. hora del Este de EE. UU. (que es 22:00 UTC), utiliza la siguiente expresión CRON: 0 22 * * 1-5
   Omitir eventos al reactivar	Encendido. Esto evita que el Activador se ejecute en los cronogramas que estaban en cola mientras el Activador estaba deshabilitado.
   Tipo de evento	Función. Selecciona la función pauseClusters en el menú desplegable.
   Nombre del activador	pauseClusters

4. Hacer clic en Save para crear el activador.

   Tus clústeres de prueba ahora se pausarán automáticamente todas las noches a las 6 PM hora del Este de EE. UU.

Crear la función resumeClusters.

1. Duplicar la función pauseClusters en una nueva función llamada resumeClusters.

2. En la pestaña Function Editor, actualice el estado paused a false en el código de función:

   1
   /*
   2
    * Iterates over the provided projects and clusters, resuming those clusters.
   3
    */
   4
   exports = async function () {
   5
   6
     // Supply project IDs and cluster names to resume
   7
     const projectIDs = [
   8
       {
   9
         id: "<projectIdA>",
   10
         names: [ "<clusterNameA>", "<clusterNameB>" ]
   11
       },
   12
       {
   13
         id: "<projectIdB>",
   14
         names: [ "<clusterNameC>" ]
   15
       }
   16
     ];
   17
   18
     // Set desired state
   19
     const body = { paused: false };
   20
   21
     // Resume each cluster and log the response
   22
     for (const project of projectIDs) {
   23
       for (const cluster of project.names) {
   24
         const result = await context.functions.execute(
   25
           "modifyCluster",
   26
           project.id,
   27
           cluster,
   28
           body,
   29
         );
   30
         console.log("Cluster " + cluster + ": " + EJSON.stringify(result));
   31
       }
   32
     }
   33
   34
     return "Clusters Resumed";
   35
   };

Cree el resumeClusters activador programado.

1. Desde la página Functions, navega hasta la página Triggers haciendo clic en Triggers en la barra lateral bajo el encabezado Build.

2. Configura los ajustes del activador.

   En Trigger Details, configure lo siguiente:

   Configuración	Valor
   Tipo de activador	Programado
   Tipo de cronograma	Avanzado. Esto te permite especificar una expresión CRON para el cronograma. Para ejecutar esto todos los días de la semana por la mañana a las 8 AM hora del este de EE. UU. (que son las 12:00 UTC), utiliza la siguiente expresión CRON: 0 12 * * 1-5
   Omitir eventos al reactivar	Encendido. Esto evita que el Activador se ejecute en los cronogramas que estaban en cola mientras el Activador estaba deshabilitado.
   Tipo de evento	Función. Selecciona la función resumeClusters en el menú desplegable.
   Nombre del activador	resumeClusters

3. Hacer clic en Save para crear el activador.

Tus clústeres de prueba ahora se pausarán automáticamente cada noche y se reanudarán cada mañana de los días laborables.

Crear la función scaleClusterUp.

1. En Atlas, diríjase a la página Triggers.

   1. Si aún no aparece, se debe seleccionar la organización que contiene el proyecto en el menú Organizations de la barra de navegación.

   2. Si aún no se muestra, seleccione su proyecto en el menú Projects de la barra de navegación.

   3. En la barra lateral, haz clic en Triggers en la sección Streaming Data.

   Se muestra la página de Triggers.

2. Navegar a la página de Functions

   1. Haz clic en el enlace Linked App Service: Triggers.

   2. En la barra lateral, haz clic en Functions en la sección Build.

   3. Haga clic en Create a Function.

      La pestaña Settings se muestra por defecto.

3. Ingrese scaleClusterUp como el Name para la Función.

4. Establecer Private a true. Esta función solo será llamada por el activador scaleClusterUp en este tutorial.

   Deja las otras opciones de configuración en la pestaña Settings con sus valores predeterminados.

5. Defina el código de la función.

   Desde la página Create Function, haz clic en la pestaña Function Editor y pega el siguiente código para definir tu Function:

   1
   /*
   2
    * Scales a single cluster up to a larger instance size.
   3
    * This example scales an AWS cluster up to M30 in region US_EAST_1.
   4
    */
   5
   exports = async function() {
   6
     // Supply project ID and cluster name...
   7
     const projectID   = "<projectId>";
   8
     const clusterName = "<clusterName>";
   9
   10
     // Set the desired instance size and topology...
   11
     const body = {
   12
       replicationSpecs: [
   13
         {
   14
           regionConfigs: [
   15
             {
   16
               electableSpecs: {
   17
                 instanceSize: "M30", // for example, larger tier
   18
                 nodeCount: 3
   19
               },
   20
               priority:     7,
   21
               providerName: "AWS",
   22
               regionName:   "US_EAST_1"
   23
             }
   24
           ]
   25
         }
   26
       ]
   27
     };
   28
   29
     // Scale up the cluster and log the response
   30
     const result = await context.functions.execute(
   31
       "modifyCluster",
   32
       projectID,
   33
       clusterName,
   34
       body
   35
     );
   36
     console.log(EJSON.stringify(result));
   37
   38
     return clusterName + " scaled up";
   39
   };

   Reemplaza los marcadores de posición <projectId> y <clusterName> con tu propio ID del grupo y nombre de clúster, y ajusta el arreglo regionConfigs para tu propia topología.

   Consulta la documentación del endpoint Actualizar un clúster en un proyecto para obtener más detalles sobre los campos disponibles que se pueden incluir en el cuerpo de la solicitud para modificar la configuración del clúster.

Cree el scaleClusterUp activador programado.

1. Desde la página Functions, navega hasta la página Triggers haciendo clic en Triggers en la barra lateral bajo el encabezado Build.

2. Haz clic en Create a Trigger para abrir la página de configuración del activador.

   Si tienes un activador existente, haz clic en Add a Trigger

3. Configura los ajustes del activador.

   En Trigger Details, configure lo siguiente:

   Configuración	Valor
   Tipo de activador	Programado
   Tipo de cronograma	Avanzado. Esto te permite especificar una expresión CRON para el cronograma. Para ejecutar esto cada mañana a las 8 a.m. hora del Este de EE. UU. (lo que equivale a las 13:00 UTC), utiliza la siguiente expresión CRON: 0 13 * * *
   Omitir eventos al reactivar	Encendido. Esto evita que el Activador se ejecute en los cronogramas que estaban en cola mientras el Activador estaba deshabilitado.
   Tipo de evento	Función. Selecciona la función pauseClusters en el menú desplegable.
   Nombre del activador	scaleClusterUp

4. Hacer clic en Save para crear el activador.

   Tus clústeres de prueba ahora se escalarán automáticamente cada mañana a las 8 a. m., hora del este de EE. UU.

Crear la función scaleClusterDown.

1. Duplicar la función scaleClusterUp en una nueva función llamada scaleClusterDown.

2. En la pestaña Function Editor, pega y ajusta el siguiente código para escalar tu clúster a la configuración especificada:

   1
   /*
   2
    * Scales a single cluster down to a smaller instance size.
   3
    * This example scales an AWS cluster down to M10 in region US_EAST_1.
   4
    */
   5
   exports = async function() {
   6
     const projectID   = "<projectId>";
   7
     const clusterName = "<clusterName>";
   8
   9
     const body = {
   10
       replicationSpecs: [
   11
         {
   12
           regionConfigs: [
   13
             {
   14
               electableSpecs: {
   15
                 instanceSize: "M10", // for example, smaller tier
   16
                 nodeCount: 3
   17
               },
   18
               priority:     7,
   19
               providerName: "AWS",
   20
               regionName:   "US_EAST_1"
   21
             }
   22
           ]
   23
         }
   24
       ]
   25
     };
   26
   27
     // Scale down the cluster and log the response
   28
     const result = await context.functions.execute(
   29
       "modifyCluster",
   30
       projectID,
   31
       clusterName,
   32
       body
   33
     );
   34
     console.log(EJSON.stringify(result));
   35
   36
     return clusterName + " scaled down";
   37
   };

   Reemplaza los marcadores de posición <projectId> y <clusterName> con tu propio ID del grupo y nombre de clúster, y ajusta el arreglo regionConfigs para tu propia topología.

   Consulta la documentación del endpoint Actualizar un clúster en un proyecto para obtener más detalles sobre los campos disponibles que se pueden incluir en el cuerpo de la solicitud para modificar la configuración del clúster.

Cree el scaleClusterDown activador programado.

1. Desde la página Functions, navega hasta la página Triggers haciendo clic en Triggers en la barra lateral bajo el encabezado Build.

2. Configura los ajustes del activador.

   En Trigger Details, configure lo siguiente:

   Configuración	Valor
   Tipo de activador	Programado
   Tipo de cronograma	Avanzado. Esto te permite especificar una expresión CRON para el cronograma. Para ejecutar esto todas las noches a las 6 PM, hora del este de EE. UU. (que son las 22:00 UTC), utiliza la siguiente expresión CRON: 0 22 * * *
   Omitir eventos al reactivar	Encendido. Esto evita que el Activador se ejecute en los cronogramas que estaban en cola mientras el Activador estaba deshabilitado.
   Tipo de evento	Función. Selecciona la función scaleClusterDown en el menú desplegable.
   Nombre del activador	scaleClusterDown

3. Hacer clic en Save para crear el activador.

Juntos, estos dos activadores garantizan que el clúster funcione con mayor capacidad durante las horas punta y reduzca la escala posteriormente.