tunnelhub.yml

tunnelhub.yml é o manifesto local usado pelos fluxos de scaffold, build e deploy de projetos TunnelHub.

Em geral, ele responde três perguntas:

• qual recurso esse projeto representa;

• como o artefato deve ser gerado ou publicado;

• qual configuração de runtime acompanha a automação.

Fonte de verdade pública

Use esta página como referência prática e o schema publicado no SchemaStore como referência estrutural:

• https://json.schemastore.org/tunnelhub.json

Se você usa editor com suporte a JSON Schema em YAML, vale associar esse schema ao arquivo para ganhar validação e autocomplete. Alguns campos recém-lançados podem aparecer nesta documentação antes da atualização do schema publicado.

Exemplo mínimo

service:
  type: automation
  uuid: 11111111-2222-3333-4444-555555555555

configuration:
  runtimeEngine: LAMBDA
  entrypoint: index.handler
  runtime: nodejs22.x
  memorySize: 512
  timeout: 30

package:
  artifact: dist/artifact.zip

Exemplo com campos opcionais

service:
  type: automation
  uuid: 11111111-2222-3333-4444-555555555555
  region: us-east-1

configuration:
  runtimeEngine: LAMBDA
  entrypoint: index.handler
  runtime: nodejs22.x
  memorySize: 1024
  timeout: 120
  lambdaLayers:
    - arn:aws:lambda:us-east-1:123456789012:layer:shared-lib:1
  environmentVariables:
    LOG_LEVEL: info
  vpcConfig:
    subnetIds:
      - subnet-aaaa1111
    securityGroupIds:
      - sg-bbbb2222
    assignPublicIp: false

package:
  artifact: dist/artifact.zip

Bloco service

Esse bloco identifica o tipo de recurso e o vínculo com a plataforma.

Campos mais importantes:

• type: normalmente automation no fluxo público atual;

• uuid: UUID da automação no TunnelHub;

• region: opcional em cenários que precisam declarar região explicitamente.

Durante create-automation, a CLI escreve service.uuid automaticamente no template baixado.

Bloco configuration

Esse bloco orienta o runtime do projeto.

Campos mais comuns:

• runtimeEngine: como LAMBDA ou ECS_FARGATE;

• entrypoint: função ou arquivo de entrada esperado pelo bundle;

• runtime: runtime Node.js alvo;

• memorySize: memória esperada;

• timeout: tempo máximo de execução.

Também podem aparecer campos opcionais, como:

• lambdaLayers;

• environmentVariables;

• runInVpc;

• sqlTables;

• vpcConfig.

O schema publicado é a melhor referência para validar combinações e tipos desses campos.

Tabelas de Apoio

Para usar Tabelas de Apoio em automações, habilite o bloco sqlTables:

configuration:
  runtimeEngine: LAMBDA
  entrypoint: index.handler
  runtime: nodejs24.x
  memorySize: 1024
  timeout: 60
  runInVpc: true
  sqlTables:
    enabled: true

Quando sqlTables.enabled é true, a automação precisa usar runtime: nodejs24.x, runInVpc: true e runtimeEngine: LAMBDA ou ECS_FARGATE.

Nota: a documentação deste campo pode preceder a atualização do schema publicado no SchemaStore. Até que tunnelhub.json seja atualizado, editores podem não validar ou autocompletar configuration.sqlTables.

Bloco package

Esse bloco é especialmente importante para o deploy da CLI.

Campo crítico:

• artifact: caminho do artefato ZIP que será enviado para a plataforma.

Sem esse valor, deploy-automation não consegue concluir o fluxo de publicação.

Quem usa cada parte do arquivo

• CLI scaffold: preenche service.uuid.

• CLI deploy: lê service.uuid e package.artifact.

• SDK build tooling: usa configuration para empacotar o projeto corretamente.

O que é obrigatório na prática

Para o fluxo público atual de automações, o contrato mínimo é:

• service.type;

• service.uuid;

• configuration.runtimeEngine;

• configuration.entrypoint;

• configuration.runtime;

• configuration.memorySize;

• package.artifact.

Erros comuns

• tunnelhub.yml ausente: execute o deploy na raiz do projeto correto.

• service.uuid ausente: recrie o projeto com create-automation ou informe --automation no deploy.

• package.artifact ausente: configure o caminho do ZIP antes do deploy.

• artefato em caminho errado: confirme se o arquivo realmente existe no caminho configurado.

• bundle incompleto: garanta que o artefato gerado contenha o que o runtime precisa.

Relação com o fluxo de trabalho

O ciclo mais comum é:

1. create-automation gera o projeto e grava service.uuid;

2. o projeto gera o artefato configurado;

3. deploy-automation lê tunnelhub.yml e publica a nova versão.

Consulte também Comandos e referência e Criando sua primeira automação.