Tutorial: Automatizar clusters com triggers programados

Crie uma Conta de serviço.

Para criar uma conta de serviço que seus Triggers possam usar para chamar a API de administração do Project Owner Atlas com permissões para seu projeto Atlas existente:

1. No Atlas, acesse a página Users.

   1. Se ainda não estiver exibido, selecione sua organização desejada no Menu Organizations na barra de navegação.

   2. Clique em All Projects na barra lateral abaixo da seção Identity & Access e selecione seu projeto desejado.

   3. Clique em Project Identity & Access na barra lateral abaixo da seção Security.

   A página Usuários é exibida.

2. Clique Create Application Service Account em.

3. Insira as informações da conta de serviço.

   • Nome: nome da sua conta de serviço. (por exemplo, TriggersServiceAccount)

   • Descrição: (opcional) descrição da sua conta de serviço. (por exemplo, conta de serviço para o Atlas Function para chamar a API de administração do Atlas ).

   • Permissões da conta de serviço: Project Owner

4. Clique em Create.

   Isso cria a conta de serviço e a adiciona automaticamente à organização principal do projeto com a Organization Member permissão.

5. Configure o API Access List.

   Adicione endereços IP ao API Access List se você quiser restringir quais endereços IP podem chamar a API de administração do Atlas com essa conta de serviço.

   Observação

   Se Require IP Access List for the Atlas Administration API estiver ativado para sua organização ou se você tiver adicionado endereços IP ao API Access List de sua conta de serviço, todas as solicitações da API de administração do Atlas deverão passar por uma verificação de lista de acesso IP.

   Os Atlas Triggers enviam solicitações HTTP de saída de um conjunto específico de endereços IP de saída. Para habilitar seus Triggers programados para chamar a API de administração do Atlas e outros serviços externos, você deve adicionar esses endereços IP ao API Access List da sua conta de serviço.

   Para obter a lista completa de endereços IP de saída usados pelo Atlas Function, consulte Acesso IP de saída de segurança da função. Você deve adicionar cada endereço IP individualmente.

Armazene credenciais de conta de serviço como Valores e Segredos.

Crie os seguintes Valores e Segredos para armazenar as credenciais da sua conta de serviço:

• AtlasClientId Valor que contém o ID do cliente da sua conta de serviço.

• AtlasClientSecret Segredo que contém o segredo do cliente da sua conta de serviço.

• AtlasClientSecret Valor que vincula ao segredo. Isso permite que você acesse o valor secreto do cliente em suas funções, mantendo-o armazenado com segurança como um segredo.

1. No Atlas, acesse a página Triggers.

   1. Se ainda não tiver sido exibido, selecione a organização que contém seu projeto no menu Organizations na barra de navegação.

   2. Se ainda não estiver exibido, selecione seu projeto no menu Projects na barra de navegação.

   3. Na barra lateral, clique em Triggers sob o título Streaming Data.

   A página Acionadores é exibida.

2. Navegue até a página Values.

   1. Clique no link Linked App Service: Triggers.

   2. Na barra lateral, clique em Values sob o título Build.

3. Armazene o ID do cliente em um Valor.

   1. Clique em Create a Value

   2. Insira AtlasClientId como Value Name.

   3. Selecione o tipo Value.

   4. Selecione a opção Custom Content e insira o ID do cliente .

      Observação

      Você deve inserir o ID do cliente como um valor de string com aspas ("<clientId>").

   5. Clique em Save.

4. Armazene o segredo do cliente em um Segredo e vincule-o a um Valor.

   Observação

   Os valores secretos não podem ser acessados diretamente, então você deve criar um segundo valor que se vincule ao segredo.

   1. Clique em Create a Value.

   2. Insira AtlasClientSecret como Value Name.

   3. Selecione o tipo Value.

   4. Selecione a opção Link to Secret.

   5. Insira AtlasClientSecret e clique em Create "AtlasClientSecret" para nomear o valor Secreto.

      Cole o segredo do cliente no campo Client Secret que aparece abaixo do nome do segredo.

   6. Clique em Save para criar o segredo e o valor.

Crie a getAuthHeaders função .

Para criar uma função reutilizável que recupere um token de acesso usando as credenciais da conta de serviço e retorne os cabeçalhos de autenticação apropriados para chamar a API de administração do Atlas :

1. Navegue até a página Functions.

   1. Na barra lateral, clique em Functions sob o título Build.

   2. Clique em Create a Function.

      A aba Settings é exibida por padrão.

2. Insira getAuthHeaders como Name para a função.

3. Defina Private como true. Esta função será chamada somente por outras funções neste tutorial.

   Deixe as outras opções de configuração na aba Settings em seus valores padrão.

4. Defina o código da função.

   Clique na aba Function Editor e cole o seguinte código para definir a função:

   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
   }

Crie a modifyCluster função .

Para criar uma função reutilizável que envolva o endpoint Update One Cluster in One Project:

1. Na página Functions, clique em Create a Function.

   A aba Settings é exibida por padrão.

2. Insira modifyCluster como Name para a função.

3. Defina Private como true. Esta função será chamada somente por outras funções neste tutorial.

   Deixe as outras opções de configuração na aba Settings em seus valores padrão.

4. Defina o código da função.

   Clique na aba Function Editor e cole o seguinte código para definir a função:

   1
   /*
   2
    * Modifies the cluster as defined by the `body` parameter.
   3
    * See https://www.mongodb.com/pt-br/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
   };

   Observação

   Código de teste no Editor de funções.

   O Function Editor fornece automaticamente "Hello world!" como o primeiro argumento quando você executa uma Função no Testing Console. Este código testa essa entrada e fornece valores para os parâmetros quando "Hello world!" é recebido.

   Para testar a função com sua própria entrada, substitua os seguintes valores de espaço reservado por suas próprias informações:

   • <projectId>

   • <clusterName>

   • No parâmetro body, forneça uma carga contendo as modificações que você deseja fazer no cluster. O código de exemplo inclui uma carga útil que pausa um cluster.

Crie a pauseClusters função .

1. No Atlas, acesse a página Triggers.

   1. Se ainda não tiver sido exibido, selecione a organização que contém seu projeto no menu Organizations na barra de navegação.

   2. Se ainda não estiver exibido, selecione seu projeto no menu Projects na barra de navegação.

   3. Na barra lateral, clique em Triggers sob o título Streaming Data.

   A página Acionadores é exibida.

2. Navegue até a página Functions

   1. Clique no link Linked App Service: Triggers.

   2. Na barra lateral, clique em Functions sob o título Build.

   3. Clique em Create a Function.

      A aba Settings é exibida por padrão.

3. Insira pauseClusters como Name para a função.

4. Defina Private como true. Esta função só será chamada pelo acionador pauseClusters neste tutorial.

   Deixe as outras opções de configuração na aba Settings em seus valores padrão.

5. Defina o código da função.

   Clique na aba Function Editor e cole o seguinte código para definir a função:

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

   Substitua a array projectIDs pelos seus próprios nomes de projeto e cluster.

   Observação

   Para evitar codificar nomes de projeto e cluster, você pode usar as funções assistente no final deste tutorial para recuperar listas de projetos e clusters da API de administração do Atlas e determinar programaticamente quais clusters pausar e retomar em um cronograma.

Crie o pauseClusters acionador programado .

1. Na página Functions, navegue até a página Triggers clicando em Triggers na barra lateral abaixo do título Build.

2. Clique em Create a Trigger para abrir a página de configuração do trigger.

   Se você tiver um trigger existente, clique em Add a Trigger

3. Definir configurações de trigger.

   No Trigger Details, defina a seguinte configuração:

   Contexto	Valor
   Tipo de trigger	Programado
   Tipo de agendamento	Avançado. Isso permite a você especificar uma expressão CRON para o agendamento. Para executar isso todas as tardes da semana às 6 PM do Leste dos EUA (que é 22:00 UTC), use a seguinte expressão CRON : 0 22 * * 1-5
   Ignorar eventos ao reativar	Ligado. Isso impede que o Trigger seja executado em agendamentos que foram enfileirados enquanto o Trigger estava desativado.
   eventType	Função. Selecione a função pauseClusters no menu suspenso.
   Nome do trigger	pauseClusters

4. Clique em Save para criar o Acionador.

   Seus clusters de teste agora serão pausados automaticamente todas as tardes às 6 da tarde do leste dos EUA.

Crie a resumeClusters função .

1. Duplique a função pauseClusters em uma nova função chamada resumeClusters.

2. Na aba Function Editor, atualize o estado paused para false no código de Função:

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

Crie o resumeClusters acionador programado .

1. Na página Functions, navegue até a página Triggers clicando em Triggers na barra lateral abaixo do título Build.

2. Definir configurações de trigger.

   No Trigger Details, defina a seguinte configuração:

   Contexto	Valor
   Tipo de trigger	Programado
   Tipo de agendamento	Avançado. Isso permite a você especificar uma expressão CRON para o agendamento. Para executar isso todas as manhãs dos dias da semana às 8 da Manhã Leste dos EUA (que é 12:00 UTC), use a seguinte expressão CRON : 0 12 * * 1-5
   Ignorar eventos ao reativar	Ligado. Isso impede que o Trigger seja executado em agendamentos que foram enfileirados enquanto o Trigger estava desativado.
   eventType	Função. Selecione a função resumeClusters no menu suspenso.
   Nome do trigger	resumeClusters

3. Clique em Save para criar o Acionador.

Seus clusters de teste agora serão pausados todas as tardes e retomados automaticamente todas as manhãs dos dias da semana.

Crie a scaleClusterUp função .

1. No Atlas, acesse a página Triggers.

   1. Se ainda não tiver sido exibido, selecione a organização que contém seu projeto no menu Organizations na barra de navegação.

   2. Se ainda não estiver exibido, selecione seu projeto no menu Projects na barra de navegação.

   3. Na barra lateral, clique em Triggers sob o título Streaming Data.

   A página Acionadores é exibida.

2. Navegue até a página Functions

   1. Clique no link Linked App Service: Triggers.

   2. Na barra lateral, clique em Functions sob o título Build.

   3. Clique em Create a Function.

      A aba Settings é exibida por padrão.

3. Insira scaleClusterUp como Name para a função.

4. Defina Private como true. Esta função só será chamada pelo acionador scaleClusterUp neste tutorial.

   Deixe as outras opções de configuração na aba Settings em seus valores padrão.

5. Defina o código da função.

   Na página Create Function, clique na aba Function Editor e cole o seguinte código para definir sua Função:

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

   Substitua os espaços reservados <projectId> e <clusterName> pelo seu próprio ID do projeto e nome de cluster e ajuste a array regionConfigs para sua própria topologia.

   Consulte a documentação do endpoint Update One Cluster in One Project para obter mais detalhes sobre os campos disponíveis que você pode incluir no corpo da solicitação para modificar a configuração do cluster.

Crie o scaleClusterUp acionador programado .

1. Na página Functions, navegue até a página Triggers clicando em Triggers na barra lateral abaixo do título Build.

2. Clique em Create a Trigger para abrir a página de configuração do trigger.

   Se você tiver um trigger existente, clique em Add a Trigger

3. Definir configurações de trigger.

   No Trigger Details, defina a seguinte configuração:

   Contexto	Valor
   Tipo de trigger	Programado
   Tipo de agendamento	Avançado. Isso permite a você especificar uma expressão CRON para o agendamento. Para executar isso todas as manhãs às 8 da Manhã Leste dos EUA (que é 13:00 UTC), use a seguinte expressão CRON : 0 13 * * *
   Ignorar eventos ao reativar	Ligado. Isso impede que o Trigger seja executado em agendamentos que foram enfileirados enquanto o Trigger estava desativado.
   eventType	Função. Selecione a função pauseClusters no menu suspenso.
   Nome do trigger	scaleClusterUp

4. Clique em Save para criar o Acionador.

   Seus clusters de teste agora aumentarão automaticamente todas as manhãs às 8 da Manhã Leste dos EUA.

Crie a scaleClusterDown função .

1. Duplique a função scaleClusterUp em uma nova função chamada scaleClusterDown.

2. Na aba Function Editor, cole e ajuste o seguinte código para reduzir o cluster para a configuração 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
   };

   Substitua os espaços reservados <projectId> e <clusterName> pelo seu próprio ID do projeto e nome de cluster e ajuste a array regionConfigs para sua própria topologia.

   Consulte a documentação do endpoint Update One Cluster in One Project para obter mais detalhes sobre os campos disponíveis que você pode incluir no corpo da solicitação para modificar a configuração do cluster.

Crie o scaleClusterDown acionador programado .

1. Na página Functions, navegue até a página Triggers clicando em Triggers na barra lateral abaixo do título Build.

2. Definir configurações de trigger.

   No Trigger Details, defina a seguinte configuração:

   Contexto	Valor
   Tipo de trigger	Programado
   Tipo de agendamento	Avançado. Isso permite a você especificar uma expressão CRON para o agendamento. Para executar isso todas as tardes às 6 PM US East (que é 22:00 UTC), use a seguinte expressão CRON : 0 22 * * *
   Ignorar eventos ao reativar	Ligado. Isso impede que o Trigger seja executado em agendamentos que foram enfileirados enquanto o Trigger estava desativado.
   eventType	Função. Selecione a função scaleClusterDown no menu suspenso.
   Nome do trigger	scaleClusterDown

3. Clique em Save para criar o Acionador.

Juntos, esses dois gatilhos garantem que o cluster seja executado em maior capacidade durante as horas de maior movimento e reduzido posteriormente.