Criar e testar aplicativos Node.js

Nesta página, explicamos como usar o Cloud Build para criar e testar aplicativos Node.js, armazenar artefatos criados em um repositório npm no Artifact Registry e gerar informações de procedência do build.

O Cloud Build permite que você use qualquer imagem de contêiner disponível publicamente para executar suas tarefas. A imagem pública node do Docker Hub vem pré-instalada com a ferramenta npm. É possível configurar o Cloud Build para criar seu projeto Node.js com essa ferramenta.

Antes de começar

Nas instruções desta página, pressupomos que você está familiarizado com Node.js. Além disso:

• Conheça o npm.
• Tenha seu projeto Node.js em mãos, incluindo arquivos package.json e test.js.
• Verifique se o arquivo package.json inclui um script start e um script test.
• Familiarize-se com a gravação de um arquivo de configuração do Cloud Build.
• Ter um repositório do npm no Artifact Registry. Se você não tiver um, crie um repositório.
• Para executar os comandos gcloud nesta página, instale a Google Cloud CLI.

Como criar com npm

Para executar suas tarefas na imagem node do Docker Hub, especifique o URL da imagem no campo name no arquivo de configuração do Cloud Build. O Cloud Build inicia o contêiner especificado no campo name usando o ponto de entrada padrão da imagem. Para substituir o ponto de entrada padrão e definir como executar a etapa de build quando ela for invocada, adicione um campo entrypoint na etapa de build. A imagem node no Docker Hub vem pré-instalada com a ferramenta npm. Especifique as ferramentas no campo entrypoint para invocá-las como o ponto de entrada da etapa de build.

No seguinte arquivo de configuração de build de exemplo:

• O campo name especifica que a imagem node do Docker Hub é usada pelo Cloud Build para executar a tarefa. Quando você especificar a imagem node, omita a versão do nó para usar :latest como padrão ou especifique uma versão do nó para usar uma versão específica. Por exemplo, name: node usará a versão mais recente do nó, e name: node:12 usará node:12.

• O campo entrypoint especifica que a ferramenta npm é usada quando a imagem node é invocada.

   steps:
   - name: 'node'
     entrypoint: 'npm'
  

Como configurar builds Node.js

1. No diretório raiz do projeto, crie um arquivo de configuração chamado cloudbuild.yaml.

2. Instalar dependências: antes de criar o aplicativo, verifique se todas as dependências do projeto estão instaladas a partir de npm. É possível instalar dependências usando o comando install na etapa de build npm. O campo args de uma etapa de build recebe uma lista de argumentos e os transmite para a imagem referenciada pelo campo de nome. No arquivo de configuração de build, adicione install ao campo args para invocar o comando install:

    steps:
    - name: 'node'
      entrypoint: 'npm'
      args: ['install']
   

3. Adicionar testes: se você tiver definido um script test em package.json, adicione test ao campo args para que Cloud Build execute o script:

    steps:
    - name: 'node'
      entrypoint: 'npm'
      args: ['install']
    - name: 'node'
      entrypoint: 'npm'
      args: ['test']
   

4. Executar comandos personalizados: se package.json tiver comandos personalizados, configure o Cloud Build para executar esse comando. No campo args, adicione run como o primeiro argumento seguido pelo nome do comando personalizado. O arquivo de configuração de build a seguir tem argumentos para executar um comando personalizado chamado build:

    steps:
    - name: 'node'
       entrypoint: 'npm'
       args: ['install']
    - name: 'node'
       entrypoint: 'npm'
       args: ['test']
    - name: 'node'
       entrypoint: 'npm'
       args: ['run', 'build']
   

5. Fazer upload no Artifact Registry:

   No arquivo de configuração, adicione o campo npmPackages e especifique o repositório npm no Registro de artefatos:

    artifacts:
       npmPackages:
       - repository: 'https://LOCATION-npm.pkg.dev/PROJECT-ID/REPOSITORY_NAME'
         packagePath: 'PACKAGE_PATH'
   

   Substitua os seguintes valores:

   • LOCATION: o local do repositório no Artifact Registry.
   • PROJECT_ID: o ID do projeto Google Cloud que contém o repositório do Artifact Registry.
   • REPOSITORY_NAME: o nome do repositório npm no Artifact Registry.
   • PACKAGE_PATH: o caminho do diretório local que contém o pacote npm que você quer enviar ao Artifact Registry. Recomendamos usar um caminho absoluto. O valor PACKAGE_PATH pode ser . para usar o diretório de trabalho atual, mas o campo não pode ser omitido ou deixado em branco. Esse diretório precisa conter um arquivo package.json.

6. Opcional: ativar a geração de origem

   O Cloud Build pode gerar metadados de procedência verificáveis de Níveis da cadeia de suprimentos para artefatos de software (SLSA) para ajudar a proteger seu pipeline de integração contínua.

   Para ativar a geração de procedência, adicione requestedVerifyOption: VERIFIED à seção options no arquivo de configuração.

7. Iniciar o build: manualmente ou usando gatilhos de build.

   Depois que o build for concluído, você poderá acessar os detalhes do repositório no Artifact Registry.

   Também é possível acessar os metadados de procedência do build e validar a procedência.

Como executar testes em várias versões de node

Às vezes, é necessário garantir que o projeto funcione em várias versões de node. É possível criar e configurar gatilhos do Cloud Build de maneira que:

• No arquivo de configuração de build, especifique a versão node como uma variável de substituição.
• Crie um gatilho para cada versão de node usada como referência durante a compilação no aplicativo.
• Em cada uma das configurações do gatilho, use o campo de valor da variável de substituição para indicar a versão de node para o gatilho.

As etapas a seguir explicam como especificar a versão de node usando variáveis de substituição específicas do gatilho:

1. Na raiz do repositório, adicione um arquivo de configuração de build, que especifica a versão node como uma variável de substituição. No exemplo de arquivo de configuração de build abaixo, $_NODE_VERSION é uma variável de substituição definida pelo usuário:

    steps:
    - name: 'node:$_NODE_VERSION'
      entrypoint: 'npm'
      args: ['install']
    - name: 'node:$_NODE_VERSION'
      entrypoint: 'npm'
      args: ['test']
   

2. Para cada versão de node que você quer usada como referência para a build, crie um gatilho de build seguindo estas etapas:

   1. Abra a página Gatilhos no console Google Cloud :

      Abrir a página "Gatilhos"

   2. Selecione o projeto no menu suspenso do seletor de projetos na parte superior da página.

   3. Clique em Abrir.

   4. Clique em Criar gatilho.

      Na página Criar gatilho, especifique as seguintes configurações:

      1. Insira um nome para o gatilho.

      2. Selecione o evento de repositório para iniciar o gatilho.

      3. Selecione o repositório que contém o código-fonte e o arquivo de configuração de build.

      4. Especifique o regex do nome da ramificação ou da tag que iniciará o gatilho.

      5. Configuração: escolha o arquivo de configuração da compilação que você criou anteriormente.

      6. Em Variáveis de substituição, clique em Adicionar variável.

         1. Em Variável, especifique a variável de versão node usada no arquivo de configuração de build e, em Valor, especifique a versão do node. Por exemplo, _NODE_VERSION e 12.

   5. Clique em Criar para salvar o gatilho de compilação.

Use esses gatilhos para criar o código na versão de node que você especificou no gatilho.

A seguir

• Saiba como ver os resultados da build.
• Saiba como proteger builds.
• Saiba como criar imagens de contêiner.
• Saiba como criar aplicativos Go.
• Saiba como realizar implantações azul-verde no Compute Engine.
• Saiba como resolver erros de build.