Tutorial: Automatizar clústeres con activadores programados

Crear una cuenta de servicio.

Para crear una cuenta de servicio que sus activadores puedan usar para llamar a la API de administración de Atlas con permisos para su proyecto Atlas Project Owner 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. Haga clic en All Projects en la barra lateral debajo de la sección Identity & Access y seleccione el proyecto que desee.

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

   Se muestra la página Usuarios.

2. Haga clic en.Create Application Service Account

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

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

   • Descripción: (opcional) Descripción de su cuenta de servicio. (por ejemplo, Cuenta de servicio para que las funciones de Atlas llamen a la API de administración de Atlas).

   • Permisos de la cuenta de servicio: Project Owner

4. Haga clic en Create.

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

5. Configurar 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á habilitado para su organización, o si agregó alguna dirección IP a la API Access List de su cuenta de servicio, entonces cada solicitud de API de administración de Atlas debe pasar una verificación de lista de acceso IP.

   Los activadores y funciones de Atlas envían solicitudes HTTP salientes desde un conjunto específico de direcciones IP salientes. Para que sus activadores programados puedan llamar a la API de administración de Atlas y a otros servicios externos, debe agregar estas direcciones IP al API Access List de su cuenta de servicio.

   Para obtener la lista completa de direcciones IP salientes utilizadas por las Funciones de Atlas, consulte Acceso IP saliente de Seguridad de Funciones. Debe agregar cada dirección IP individualmente.

Almacene las credenciales de la cuenta de servicio como valores y secretos.

Cree los siguientes valores y secretos para almacenar las credenciales de su cuenta de servicio:

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

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

• AtlasClientSecret Valor vinculado al secreto. Esto le permite acceder al valor secreto del cliente en sus funciones, manteniéndolo almacenado de forma segura como secreto.

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

2. Vaya a la página Values.

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

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

3. Almacene el ID del cliente en un valor.

   1. Haga clic Create a Value

   2. Introduzca AtlasClientId como Value Name.

   3. Seleccione el tipo Value.

   4. Seleccione la opción Custom Content e ingrese el ID del cliente.

      Nota

      Debe ingresar el ID del cliente como un valor de cadena 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 debe crear un segundo valor que se vincule al secreto.

   1. Haga clic en Create a Value.

   2. Introduzca AtlasClientSecret como Value Name.

   3. Seleccione el tipo Value.

   4. Seleccione la opción Link to Secret.

   5. Ingrese AtlasClientSecret y haga clic en Create "AtlasClientSecret" para nombrar el valor secreto.

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

   6. Haga clic en Save para crear el secreto y el valor.

Crea la getAuthHeaders función.

Para crear una función reutilizable que recupere un token de acceso utilizando las credenciales de la cuenta de servicio y devuelva los encabezados de autenticación adecuados para llamar a la API de administración de Atlas:

1. Vaya 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 de forma predeterminada.

2. Introduzca getAuthHeaders como Name para la función.

3. Establezca Private en true. Esta función solo será invocada por otras funciones en este tutorial.

   Deje las demás opciones de configuración en la pestaña Settings con sus valores predeterminados.

4. Definir el código de función.

   Haga clic en la pestaña Function Editor y pegue 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
   }

Crea la modifyCluster función.

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

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

   La pestaña Settings se muestra de forma predeterminada.

2. Introduzca modifyCluster como Name para la función.

3. Establezca Private en true. Esta función solo será invocada por otras funciones en este tutorial.

   Deje las demás opciones de configuración en la pestaña Settings con sus valores predeterminados.

4. Definir el código de función.

   Haga clic en la pestaña Function Editor y pegue 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

   Código de prueba en el Editor de funciones.

   El Function Editor proporciona automáticamente "Hello world!" como primer argumento al ejecutar 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 su propia entrada, reemplace los siguientes valores de marcador de posición con su 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.

Crea la pauseClusters función.

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

2. Navegar a la página Functions

   1. Haga 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 de forma predeterminada.

3. Introduzca pauseClusters como Name para la función.

4. Establezca Private en true. Esta función solo será invocada por el disparador pauseClusters en este tutorial.

   Deje las demás opciones de configuración en la pestaña Settings con sus valores predeterminados.

5. Definir el código de función.

   Haga clic en la pestaña Function Editor y pegue 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 la matriz projectIDs con sus propios nombres de proyecto y clúster.

   Nota

   Para evitar codificar de forma rígida los nombres de proyectos y clústeres, puede usar las funciones auxiliares al final de este tutorial para recuperar listas de proyectos y clústeres de la API de administración de Atlas y determinar mediante programación qué clústeres pausar y reanudar según un cronograma.

Cree el pauseClusters disparador programado.

1. Desde la página Functions, navegue a la página Triggers haciendo clic en Triggers en la barra lateral debajo del encabezado Build.

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

   Si tiene un disparador existente, haga clic en Add a Trigger

3. Configurar los ajustes del disparador.

   En Trigger Details, establezca la siguiente configuración:

   Configuración	Valor
   Tipo de activador	Programado
   Tipo de cronograma	Avanzado. Esto le permite especificar una expresión CRON para la programación. Para ejecutar esto todos los días de la semana por la noche a las 6 p. m., hora del este de EE. UU. (que es 22:00 UTC), use la siguiente expresión CRON: 0 22 * * 1-5
   Omitir eventos al volver a habilitar	Activado. Esto evita que el disparador se ejecute en programaciones que estaban en cola mientras el disparador estaba deshabilitado.
   Tipo de evento	Función. Seleccione la función pauseClusters del menú desplegable.
   Nombre del desencadenador	pauseClusters

4. Haga clic en Save para crear el disparador.

   Sus grupos de pruebas ahora se pausarán automáticamente todas las noches a las 6 p. m., hora del este de EE. UU.

Crea la resumeClusters función.

1. Duplique 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 disparador programado.

1. Desde la página Functions, navegue a la página Triggers haciendo clic en Triggers en la barra lateral debajo del encabezado Build.

2. Configurar los ajustes del disparador.

   En Trigger Details, establezca la siguiente configuración:

   Configuración	Valor
   Tipo de activador	Programado
   Tipo de cronograma	Avanzado. Esto le permite especificar una expresión CRON para la programación. Para ejecutar esto todos los días de la semana por la mañana a las 8 a. m., hora del este de EE. UU. (que es 12:00 UTC), use la siguiente expresión CRON: 0 12 * * 1-5
   Omitir eventos al volver a habilitar	Activado. Esto evita que el disparador se ejecute en programaciones que estaban en cola mientras el disparador estaba deshabilitado.
   Tipo de evento	Función. Seleccione la función resumeClusters del menú desplegable.
   Nombre del desencadenador	resumeClusters

3. Haga clic en Save para crear el disparador.

Ahora sus grupos de pruebas se pausarán todas las noches y se reanudarán automáticamente todas las mañanas de los días laborables.

Crea la scaleClusterUp función.

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

2. Navegar a la página Functions

   1. Haga 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 de forma predeterminada.

3. Introduzca scaleClusterUp como Name para la función.

4. Establezca Private en true. Esta función solo será invocada por el disparador scaleClusterUp en este tutorial.

   Deje las demás opciones de configuración en la pestaña Settings con sus valores predeterminados.

5. Definir el código de función.

   Desde la página Create Function, haga clic en la pestaña Function Editor y pegue el siguiente código para definir su función:

   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
   };

   Reemplace los marcadores de posición <projectId> y <clusterName> con su propio ID de proyecto y nombre de clúster, y ajuste la matriz regionConfigs para su propia topología.

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

Cree el scaleClusterUp disparador programado.

1. Desde la página Functions, navegue a la página Triggers haciendo clic en Triggers en la barra lateral debajo del encabezado Build.

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

   Si tiene un disparador existente, haga clic en Add a Trigger

3. Configurar los ajustes del disparador.

   En Trigger Details, establezca la siguiente configuración:

   Configuración	Valor
   Tipo de activador	Programado
   Tipo de cronograma	Avanzado. Esto le permite especificar una expresión CRON para la programación. Para ejecutar esto todas las mañanas a las 8 AM, hora del este de EE. UU. (que es 13:00 UTC), use la siguiente expresión CRON: 0 13 * * *
   Omitir eventos al volver a habilitar	Activado. Esto evita que el disparador se ejecute en programaciones que estaban en cola mientras el disparador estaba deshabilitado.
   Tipo de evento	Función. Seleccione la función pauseClusters del menú desplegable.
   Nombre del desencadenador	scaleClusterUp

4. Haga clic en Save para crear el disparador.

   Sus clústeres de prueba ahora se ampliarán automáticamente todas las mañanas a las 8 a. m., hora del este de EE. UU.

Crea la scaleClusterDown función.

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

2. En la pestaña Function Editor, pegue y ajuste el siguiente código para reducir la escala de su 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
   };

   Reemplace los marcadores de posición <projectId> y <clusterName> con su propio ID de proyecto y nombre de clúster, y ajuste la matriz regionConfigs para su propia topología.

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

Cree el scaleClusterDown disparador programado.

1. Desde la página Functions, navegue a la página Triggers haciendo clic en Triggers en la barra lateral debajo del encabezado Build.

2. Configurar los ajustes del disparador.

   En Trigger Details, establezca la siguiente configuración:

   Configuración	Valor
   Tipo de activador	Programado
   Tipo de cronograma	Avanzado. Esto le permite especificar una expresión CRON para la programación. Para ejecutar esto todas las noches a las 6 p. m., hora del este de EE. UU. (que es 22:00 UTC), use la siguiente expresión CRON: 0 22 * * *
   Omitir eventos al volver a habilitar	Activado. Esto evita que el disparador se ejecute en programaciones que estaban en cola mientras el disparador estaba deshabilitado.
   Tipo de evento	Función. Seleccione la función scaleClusterDown del menú desplegable.
   Nombre del desencadenador	scaleClusterDown

3. Haga clic en Save para crear el disparador.

Juntos, estos dos activadores garantizan que el clúster funcione a mayor capacidad durante las horas pico y luego se reduzca su capacidad.