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.

Exemplo mínimo

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

configuration:
  runtimeEngine: LAMBDA
  entrypoint: src/index.ts
  runtime: nodejs22.x
  memorySize: 512
  timeout: 900

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: arquivo de entrada do 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;

• vpcConfig.

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.

Diferenças práticas entre CLI e SDK

Hoje, CLI e SDK não expõem exatamente o mesmo subconjunto de campos em seus tipos internos.

Para documentação pública, o mais importante é entender o contrato efetivo:

• o projeto precisa de service.uuid;

• o artefato precisa estar acessível em package.artifact para deploy;

• o runtime precisa estar coerente com configuration.

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 e mantenha tunnelhub.yml na raiz do contexto esperado pelo fluxo.

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.