org_id. No ClickHouse — onde vivem os eventos e avaliações de alto volume — isso é respaldado por uma aplicação forte no nível do motor: cada org recebe um usuário ClickHouse dedicado e somente leitura com uma política de linha por org, de modo que mesmo SQL analítico não confiável nunca consegue ler as linhas de outro tenant. No PostgreSQL, a segurança em nível de linha adiciona uma camada de defesa em profundidade no caminho de consulta somente leitura (/queries/run), restringindo o que esse caminho pode ver mesmo que um filtro no nível da aplicação esteja ausente; a própria conexão de escrita do servidor é executada como o proprietário da tabela e, portanto, opera pelo mesmo escopo org_id no nível da aplicação.
O ciclo de vida do tenant é controlado pelo operador, enquanto tudo o que os membros fazem no dia a dia permanece como autoatendimento no dashboard. Organizações e suas associações são criadas e gerenciadas com a CLI agenteye-orgctl, que é distribuída dentro da imagem do servidor e executa dentro do pod do servidor existente. A criação e exclusão de tenants são deliberadamente mantidas fora do dashboard e da API HTTP: não há API HTTP nem botão no dashboard para o ciclo de vida do tenant, portanto ele fica protegido por trás do acesso ao shell do cluster/pod em vez da superfície da aplicação.
Dentro de uma org, os membros trabalham inteiramente no dashboard e na API: eles fazem login, alternam entre as orgs às quais pertencem, gerenciam suas próprias chaves de API, constroem dashboards e consultas salvas, e configuram alertas para sua org. A divisão é clara: operadores provisionam e desativam tenants e seus membros via CLI; membros executam tudo dentro de um tenant pela UI.
Deployments single-tenant não precisam de nada disso. Uma instalação single-tenant funciona sem nenhuma ação do operador. Todos os dados, usuários e chaves vivem em uma organização default integrada que é provisionada automaticamente. Você só precisa deste guia quando decidir adicionar uma segunda org.
Pré-requisitos
Antes de criar sua segunda organização (a orgdefault integrada não precisa de nada):
- PostgreSQL 15+. O esquema de membros da org usa uma chave estrangeira
ON DELETE SET NULLcom lista de colunas que requer PostgreSQL 15+. Faça o upgrade do PostgreSQL antes de provisionar uma segunda org. - Um
ORG_CH_SECRETforte e estável. A senha do ClickHouse de cada org é derivada comoHMAC(ORG_CH_SECRET, org_id), portanto o padrão de desenvolvimento integrado publicamente conhecido resultaria em credenciais por org publicamente deriváveis.agenteye-orgctl org createse recusa a executar enquantoORG_CH_SECRETnão estiver definido ou estiver no padrão de desenvolvimento integrado. Defina seu próprio valor primeiro (consulte Deployment → variáveis de ambiente e, no Kubernetes, §2.6 do guia Kubernetes). Mantenha-o idêntico em todas as réplicas do servidor e não o rotacione casualmente; rotacioná-lo torna órfão o usuário ClickHouse de cada org até que o próximo startup os reprovisionne.
Executando a CLI
agenteye-orgctl é distribuída na mesma imagem que o servidor (junto com agenteye-server). Você não faz deploy de um pod, Job ou Deployment separado para ela; você a executa dentro do pod do servidor que já está em execução, de modo que ela lê o mesmo DATABASE_URL, CLICKHOUSE_URL e ORG_CH_SECRET que o servidor usa.
Kubernetes:
agenteye-orgctl <args> simples por brevidade; prefixe cada um com uma das duas linhas acima que corresponda ao seu deployment.
Referência de comandos
Organizações
| Comando | O que faz |
|---|---|
org create --slug <slug> --name <name> | Cria uma nova organização. Se recusa a executar enquanto ORG_CH_SECRET não estiver definido ou estiver no padrão de desenvolvimento integrado (defina o seu próprio primeiro, veja Pré-requisitos). Provisiona o usuário ClickHouse somente leitura da org + política de linha. |
org list | Lista todas as organizações (slug, nome e estado do ciclo de vida). |
org rename --slug <slug> --name <new name> | Altera o nome de exibição de uma organização. O slug (usado em URLs e chaves) permanece inalterado. |
org delete --slug <slug> | Exclusão suave da org e remoção do seu usuário ClickHouse. Os dados são retidos. Isso revoga o acesso e libera a credencial ClickHouse por org, mas não apaga os eventos. Reversível por ops; primeiro passo seguro antes de uma purga. |
org purge --slug <slug> | Limpeza irreversível de dados. A org já deve ter sido deleted. Nunca permitido na org default integrada. Use somente quando tiver certeza de que os dados do tenant devem ser destruídos. |
Membros
| Comando | O que faz |
|---|---|
member add --org <slug> --email <email> [--set <permission-set>] [--add perm1,perm2] [--remove perm3] [--protected] | Adiciona um membro a uma org. Opcionalmente começa a partir de um conjunto de permissões integrado, depois adiciona/remove permissões individuais. --protected fixa o membro para que o dashboard não possa removê-lo ou rebaixá-lo (veja abaixo). O novo membro recebe um OTP no primeiro login no dashboard. |
member list --org <slug> | Lista os membros da org. As colunas de saída são EMAIL, SET (o conjunto integrado do qual o membro partiu, ou -), PROT (se o membro é protegido) e PERMISSIONS (suas permissões efetivas). Um e-mail exibido com um * no final é um admin da instância; eles têm acesso a todas as orgs. |
member update --org <slug> --email <email> [--set ...] [--add ...] [--remove ...] [--protected | --unprotect] | Altera as permissões e/ou o estado de proteção de um membro. --set substitui a partir de um conjunto integrado; --add / --remove ajustam permissões individuais; --protected / --unprotect alternam a proteção. Passar apenas --protected/--unprotect (sem flags de concessão) altera somente a proteção e deixa as permissões existentes intactas. |
member remove --org <slug> --email <email> | Remove um membro da org. Se recusa se o membro for protegido; use --unprotect primeiro. (Uma pessoa pode ser membro de várias orgs; isso afeta apenas a org especificada.) |
Membros protegidos (um admin da org irremovível)
A proteção garante que uma org nunca possa acidentalmente se bloquear do autogerenciamento. Por padrão, os admins de uma org podem adicionar e remover uns aos outros pela página de usuários de autoatendimento do dashboard, de modo que poderiam remover o último admin e deixar a org sem ninguém capaz de gerenciá-la.
member update --org acme --email owner@acme.example --unprotect primeiro, depois remova ou rebaixe. Isso garante que cada org mantenha pelo menos um admin que seus próprios membros não possam bloquear, ao mesmo tempo que mantém o controle do tenant exclusivamente para operadores. A proteção é por org; proteger alguém em uma org não tem efeito sobre sua associação em outra.
Conjuntos de permissões integrados
--set aceita um dos três conjuntos integrados, aplicados por org:
| Conjunto | Destinado para |
|---|---|
admin | Acesso completo dentro da org, incluindo gerenciamento de chaves de API e usuários da org. |
standard | Uso no dia a dia: leitura + execução de consultas, construção de dashboards, reconhecimento de incidentes. |
read-only | Acesso somente visualização aos dados e dashboards da org. |
--set, depois ajuste com --add / --remove usando os tokens de permissão individuais listados em API Keys. Os próprios tokens de permissão são idênticos aos usados para chaves de API.
Exemplo prático
Provisione um novo tenantacme, adicione seu primeiro admin, deixe-o criar uma chave e, em seguida, desative a org.
1. Crie a org (ORG_CH_SECRET já deve estar definido com um valor forte e estável, não indefinido ou o padrão de desenvolvimento integrado):
/acme/sessions).
3. Crie uma chave de API por org (no dashboard):
O operador não cria chaves de dados por org pela CLI. Alice (ou qualquer membro da org com keys:create) cria chaves de coletor/dashboard para a org acme pela página de Keys do dashboard. Cada chave que ela cria é automaticamente marcada com sua org e só pode ler ou escrever dados da acme. Consulte API Keys.
4. Ajuste um membro posteriormente:
default):
kubectl -n agenteye exec deploy/server -- por docker compose exec server.
Divisão de responsabilidades
Tudo o que um membro da org precisa no dia a dia é autoatendimento no dashboard e na API, com escopo automaticamente para sua org atual:- Chaves de API por org são criadas e gerenciadas por membros da org no dashboard (ou via API de chaves com uma chave que carrega
keys:create). A CLI não cria chaves de dados. Consulte API Keys. - Troca de org está integrada ao dashboard; os membros alternam entre as orgs às quais pertencem pelo seletor de org, e as páginas com escopo de org ficam em
/<org-slug>/…. - Dashboards, consultas salvas, alertas e todo uso de dados acontecem inteiramente na UI e na API, com escopo para a org atual do membro.
agenteye-orgctl, é responsável apenas pelo ciclo de vida da org + membro: criar/renomear/excluir/purgar uma org, e adicionar/listar/atualizar/remover um membro.
Veja também
- Deployment:
ORG_CH_SECRETe o restante do ambiente do servidor. - Kubernetes Deployment: §2.6 cria o Secret
agenteye-org-ch-secretantes da sua primeira org multi-tenant. - API Keys: o modelo de chave por org e os tokens de permissão usados por
--add/--remove. - Troubleshooting: provisionamento multi-tenant e problemas de isolamento do ClickHouse.