Proxy inverso para Docker Swarm
O Apiary encaminha HTTP, TCP e UDP para os seus serviços Swarm, renova os certificados HTTPS sozinho e mantém o seu estado replicado entre as réplicas. Sem base de dados para gerir, sem entregar o socket do Docker.
A interface de administração
Cada alteração diz em quantas réplicas foi aplicada. Cada ação arriscada diz o que continua a funcionar e o que para. Claro e escuro, pensada para o teclado, concebida para a WCAG 2.2 AA.
As réplicas acordam cada alteração com o algoritmo de consenso Raft e guardam a sua própria cópia cifrada do estado. Sem etcd, Consul, Redis ou Postgres ao lado.
Perca a maior parte do cluster e cada réplica que resta continua a encaminhar com as últimas rotas e certificados. Só as alterações param, e a interface di-lo claramente: “As alterações estão em pausa.”
docker stack deploy.Crie a chave raiz uma vez. Os certificados das réplicas, a autoridade de certificação do cluster e as chaves de dados rodam sozinhos. Instalar, atualizar e escalar é um ficheiro de stack e docker stack deploy.
Aceder à API do Docker é ser root nos seus servidores, por isso o Apiary não o pede. As rotas chegam pela interface, pela sua API, pelos seus agentes de IA ou pelos seus ficheiros de stack, através do seu pipeline.
Declare as rotas como etiquetas no ficheiro de stack. O apiary apply envia-as a partir do seu pipeline numa única escrita, tudo ou nada, com uma simulação para os merge requests. Os campos definidos por etiquetas ficam bloqueados na interface.
Um servidor MCP incluído, com o Apiary como o seu próprio servidor de autorização OAuth. Os agentes iniciam sessão como si e recebem o seu perfil. Chaves privadas e cópias de segurança nunca passam por eles.
Endereços de loopback, link-local e de metadados da nuvem, e as portas do próprio Apiary, são recusados. Verifica o endereço a que cada ligação chega de facto, por isso o DNS rebinding também não passa.
Uma alteração e o seu registo de auditoria são escritos na mesma entrada Raft, por isso nada muda sem ficar registado: quem, de onde, pela interface, por um agente ou por um pipeline.
Se a maior parte das réplicas se perder de vez, uma recuperação forçada escolhe a sobrevivente mais recente, mostra o que se pode perder antes de começar e termina todas as sessões, para que uma revogação perdida não devolva acessos.
Alta disponibilidade
O Apiary corre uma réplica por cada nó de entrada. Umas votam as alterações e as restantes seguem-nas, servindo tráfego sem atrasar as escritas. Eis o que acontece quando algo corre mal, com três réplicas.
| O que acontece | Tráfego | Alterações |
|---|---|---|
| Uma atualização gradual | Continua | Pausas breves |
| Falha um nó | Continua | Aceites |
| Falha a líder | Continua | Esperam 2 a 3 segundos por uma nova líder |
| Falha a maioria das réplicas | Continua, com as últimas rotas | Em pausa até voltarem |
| A rede divide-se | Continua, talvez com rotas mais antigas de um dos lados | Aceites do lado da maioria |
Os certificados renovam-se semanas antes de expirarem, por isso um cluster que não aceite alterações durante algum tempo ainda tem tempo para recuperar. Leia os modos de falha (em inglês)
Funcionalidades
Para além de encaminhar: o que, de outra forma, teria de programar, acrescentar ou lembrar-se de fazer.
Certificados do Let’s Encrypt, pedidos por uma réplica de cada vez e validados por qualquer uma, para que um nó atrasado nunca falhe uma verificação. As falhas esperam cada vez mais, para respeitar os limites do Let’s Encrypt, e o registo de renovações diz o que correu mal. Carregue os seus para wildcards ou uma CA interna.
Divida uma rota entre versões por peso, envie quem testa para a nova com um cabeçalho ou cookie, e mantenha cada visitante na versão a que chegou primeiro com sessões persistentes.
curl -H 'X-Canary: true' https://shop.example.com/
As etiquetas de cada serviço declaram as suas rotas, redirecionamentos e rotas TCP e UDP. O seu pipeline corre apiary apply logo a seguir a docker stack deploy, e o Apiary mostra cada aplicação com o seu commit e pipeline.
services: web: image: registry.example.com/shop/web:2.4.0 networks: [apiary] deploy: labels: apiary.project: Shop apiary.route.site.host: shop.example.com apiary.route.site.port: "8080" apiary.route.api.host: shop.example.com apiary.route.api.path: /api apiary.route.api.port: "8081"Ligue o Claude Code com um comando, ou qualquer cliente MCP com um endereço. O agente inicia sessão pelo seu navegador e age com o seu perfil, e cada ação que faz fica no registo de auditoria com o seu nome.
Inicie sessão com fornecedores OpenID Connect como o Entra ID ou o Keycloak, com os perfis atribuídos a partir de grupos. As contas locais ficam como acesso de emergência, cada uma com uma aplicação autenticadora obrigatória.
Indique os seus proxies de confiança, e as listas de endereços permitidos, os limites de pedidos e os registos usam o endereço real de quem visita. Experimente um pedido na própria página para ver que endereço e esquema o Apiary vai usar.
Quando é o Apiary a responder em vez de um site, para uma manutenção, uma palavra-passe ou uma rota inexistente, mostra uma página pequena com a sua marca e sem scripts. Proteja pré-visualizações com uma palavra-passe partilhada ou uma ligação de acesso.
Rodar a chave raiz é um novo segredo Swarm e um único docker stack deploy. As réplicas passam uma a uma, a interface mostra o progresso e o Apiary esquece a chave antiga sozinho.
E o resto
Com redirecionamento de HTTP para HTTPS.
Bases de dados, MQTT, SMTP. Vários serviços TLS numa porta, escolhidos por SNI sem decifrar.
De um nome ou de um caminho, 308 por defeito. Ciclos e redirecionamentos que escondam uma rota são recusados.
Agendadas por rota, em UTC, com a sua mensagem.
Por rota, IPv4 e IPv6. Os restantes recebem um 403.
Por visitante, com o IPv6 contado por rede /64, para que mudar de endereço não ajude.
30 MB por defeito, até 100 GB, ou sem limite. Os envios passam em fluxo, nunca em memória.
Desligados por defeito e ligados de propósito, porque cada um pode correr mal.
Verificada a cada 15 segundos por todas as réplicas. Um veredicto errado nunca tira um site do ar por si só.
Métricas e traces por OTLP, e um endereço /metrics na porta de administração.
Linhas JSON, sem query strings, e uma opção para encurtar os endereços IP.
Quando quiser, a partir da interface. Restaure para um novo cluster.
Agrupe rotas, redirecionamentos e certificados, cada projeto com a sua marca.
Observador, Operador e Administrador, para pessoas e agentes.
Começar
Num manager do Swarm, com três nós virados para a internet. O guia completo trata das firewalls, do DNS e do ficheiro de stack. Leia o guia de instalação (em inglês)
O Apiary corre uma réplica em cada nó com esta etiqueta.
docker node update --label-add apiary.edge=true <node>Depois, copie-a para o seu cofre de segredos e apague o ficheiro. É o único segredo que vai gerir.
(umask 077 && docker run --rm datapointsoftware/apiary:1.0.0-beta.4 secrets init > apiary_root_key_1)docker secret create apiary_root_key_1 apiary_root_key_1Parta do ficheiro de stack do repositório e indique a sua rede de administração e o email para o Let’s Encrypt.
APIARY_VERSION=1.0.0-beta.4 docker stack deploy -c stack.yaml apiarySó a partir da sua rede de administração, na porta 9443. A primeira visita cria o primeiro administrador, com uma aplicação autenticadora.
https://<edge-node>:9443Só quer ver? Experimente no seu portátil com o Docker Compose:
git clone https://github.com/datapoint-software/apiary.git && cd apiarydocker compose -f deploy/compose.yaml up --buildO Apiary está em beta. Tem todas as funcionalidades, e algum comportamento ainda pode mudar antes da 1.0.0. Experimente-o num Swarm de desenvolvimento antes de depender dele. Desde a 1.0.0-beta.1, cada versão atualiza a anterior no lugar.
Licença
AGPL-3.0
Use, altere e partilhe o Apiary sem custos. Se oferecer uma versão modificada a outros, incluindo através de uma rede, oferece-lhes também o seu código, com a mesma licença.
Sob consulta
Para organizações que integram o Apiary no seu próprio produto ou serviço, ou que preferem não assumir as obrigações da AGPL.
ou escreva para hello@datapoint.software
O Apiary está em beta e tem todas as funcionalidades. As decisões tomadas durante o desenvolvimento ainda estão a ser revistas, por isso algum comportamento pode mudar antes da 1.0.0. Desde a 1.0.0-beta.1, cada versão atualiza no lugar o estado da anterior.
Para alta disponibilidade, sim: três ou mais réplicas num Swarm. A mesma imagem também corre num Swarm de um só nó, que pode crescer para três réplicas mais tarde sem mover dados, ou com o Docker Compose numa única máquina.
As alterações precisam de uma maioria de votantes. Duas réplicas não toleram mais falhas do que uma, e as alterações param se qualquer delas falhar. Três toleram uma falha, cinco toleram duas.
Sim. O Apiary publica as suas portas no modo host do Swarm, por isso vê os endereços reais dos clientes, e envia-os em X-Forwarded-For. Atrás de um balanceador ou de uma CDN, indique-o como proxy de confiança.
Na porta 9443 de cada nó de entrada, que nunca pode estar acessível a partir da internet. Está protegida pela firewall da sua rede, por uma lista de endereços permitidos dentro do Apiary e por um início de sessão com segundo fator.
.NET 10 e o YARP da Microsoft para o proxy, o Raft do DotNext para a replicação, e Angular para a interface. Uma imagem, datapointsoftware/apiary, no Docker Hub.
A Datapoint Software, uma empresa de software nos Açores, desde 2017. Usamos o Apiary à frente dos nossos próprios sites.
Dúvidas sobre a licença comercial, o suporte ou uma instalação? Teremos todo o gosto em conversar.