Documentação · Nuvem

Conectar Oracle Cloud (OCI).

O GrandeTotal lê o custo diário e o detalhamento por serviço dos últimos 30 dias de uma tenancy OCI, pela Usage API. O acesso é feito por um usuário que você cria e controla, com uma única permissão: ler o relatório de uso e custo. A consulta é gratuita.

O que é pedido

Um grupo e um usuário só para isso, sem acesso a recursos.
Uma política no compartimento raiz: read usage-report na tenancy.
Uma chave de API desse usuário (par de chaves RSA gerado pelo console, sem senha).
Cinco valores: Tenancy OCID, User OCID, Fingerprint, região home e a chave privada (arquivo .pem).

Nada além disso. A política abaixo não permite criar, alterar nem apagar recursos, nem ler o conteúdo deles: só os valores do relatório de custo. Não use um usuário administrador.

Antes de começar

Permissão: administrador da tenancy (ou alguém que possa criar grupos, usuários e políticas).
Tempo: cerca de 15 minutos. Políticas novas podem levar alguns minutos para valer.

Passo 1. Descubra a Tenancy OCID e a região home

No console, abra o menu do perfil (canto superior direito) → Tenancy: <nome>. Na página Tenancy details copie o OCID (começa com ocid1.tenancy.oc1..) e anote a Home region. O console mostra o nome (por exemplo, Brazil East (Sao Paulo)); o valor que o painel pede é o identificador da região, como sa-saopaulo-1 ou us-ashburn-1. A lista está em Governance & Administration → Region management, coluna Region identifier.

O GrandeTotal consulta a Usage API na região home, que é onde a tenancy guarda os dados de custo. Se você informar outra região, a consulta falha.

Passo 2. Crie o grupo e o usuário só de leitura

Identity & Security → Domains → seu domínio (normalmente Default) → User management → Groups → Create group. Nome sugerido: GrandeTotalReaders.
Em Users → Create user, crie grandetotal-reader. Use um e-mail seu ou de um grupo de TI: ele recebe um convite de ativação que você pode ignorar, porque esse usuário nunca entra pelo console.
Na página do usuário, Groups → Assign user to groups e escolha GrandeTotalReaders.
Opcional, mas recomendado: em Edit user capabilities deixe marcada só API keys. Assim o usuário não pode entrar no console, nem usar senha, SMTP ou tokens.

Passo 3. Crie a política de leitura de custo

Vá em Identity & Security → Policies. No seletor de compartimento escolha o compartimento raiz (o que tem o nome da tenancy; políticas sobre a tenancy só valem ali) e clique em Create Policy.

Name: grandetotal-leitura-custo
Description: Leitura de custo para o GrandeTotal
Compartment: o raiz (tenancy)
Policy Builder: ative Show manual editor e cole a linha abaixo.

Allow group GrandeTotalReaders to read usage-report in tenancy

Se o grupo não está no domínio Default, qualifique o nome com o domínio, entre aspas simples:

Allow group 'MeuDominio'/'GrandeTotalReaders' to read usage-report in tenancy

Clique em Create. Para conferir, abra a política e veja se a instrução aparece exatamente assim, sem erros de sintaxe. Em tenancies com domínio Default e grupo no mesmo domínio, o primeiro formato é o correto.

Dica de segurança. Use read, nunca manage, e mantenha in tenancy: o relatório de uso é da tenancy inteira, não de um compartimento.

Passo 4. Gere a chave de API do usuário

Abra o usuário grandetotal-reader → API keys → Add API key.
Escolha Generate API key pair. Clique em Download private key e guarde o arquivo .pem. Esta é a única chance de baixá-lo. Não precisa baixar a chave pública.
Clique em Add. A janela Configuration file preview mostra quatro linhas: user, fingerprint, tenancy e region. Copie os valores antes de fechar (você pode vê-los depois na lista de API keys, mas não o arquivo privado).

[DEFAULT]
user=ocid1.user.oc1..aaaa…           ← User OCID
fingerprint=aa:bb:cc:dd:…:99          ← Fingerprint
tenancy=ocid1.tenancy.oc1..aaaa…      ← Tenancy OCID
region=sa-saopaulo-1                  ← região (use a home!)
key_file=<caminho do arquivo .pem>

O console mostra a região onde você está navegando. Se ela não for a home, use a home do passo 1.
A chave privada começa com -----BEGIN PRIVATE KEY----- (ou -----BEGIN RSA PRIVATE KEY-----). Se começar com BEGIN PUBLIC KEY, é o arquivo errado.
Cada usuário aceita até 3 chaves de API. Você pode ter uma para o GrandeTotal e outras para outras ferramentas.

Passo 5. Teste antes de conectar (opcional)

Com a CLI da OCI configurada com esses mesmos valores (oci setup config), uma consulta de teste mostra se a política e a região estão certas. Troque as datas por dias recentes:

oci usage-api usage-summary request-summarized-usages \
  --tenant-id <TENANCY_OCID> \
  --granularity DAILY --query-type COST \
  --time-usage-started 2026-10-01T00:00:00Z \
  --time-usage-ended   2026-10-10T00:00:00Z \
  --group-by '["service"]' \
  --region sa-saopaulo-1

Se voltar uma lista de items (mesmo vazia), a conexão vai funcionar. O erro NotAuthorizedOrNotFound aponta para política, grupo ou região (veja Erros comuns).

Passo 6. Cole os valores no painel

Em /painel/conectar, clique em Conectar OCI e preencha:

Tenancy OCID: passo 1 (linha tenancy), como ocid1.tenancy.oc1..aaaa….
User OCID: linha user do passo 4, como ocid1.user.oc1..aaaa….
Fingerprint: linha fingerprint, como aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99.
Região home: passo 1, como sa-saopaulo-1.
Chave privada: o conteúdo inteiro do arquivo .pem, com as linhas BEGIN e END.

Clique em Verificar e conectar. O GrandeTotal assina uma consulta dos últimos dois dias; se a chave, a região e a política estiverem certas, a conexão fica conectada.

Passo 7. Sincronize e confira

Use o botão de sincronizar no painel. A consulta à Usage API é gratuita, mas o GrandeTotal espera alguns minutos entre sincronizações e, se a OCI pedir (429), espera e tenta de novo. Cada atualização traz os últimos 30 dias e, até completar 12 meses de histórico, mais 30 dias de antes (veja o passo a passo em Sincronização, no painel). Os dados vêm com a origem oci_usage_api.

No console, Billing & Cost Management → Cost Analysis (visão por Service, custos em valor): o total dos últimos 30 dias deve bater com o do painel.
Contas novas, em teste gratuito ou só com recursos Always Free podem mostrar custo zero. Isso é correto, e as linhas só aparecem depois que há consumo cobrado. O dado de um dia pode levar algumas horas para aparecer.
A moeda vem da própria OCI (por exemplo, USD ou BRL).

Opcional: custo por dimensão, inventário e tags

Com a política do passo 3, o painel já abre o custo da tenancy por compartimento, região, tipo de uso (SKU), serviço e recurso, em /painel/oci-custos. É a mesma Usage API, gratuita, agrupada por outro campo.

Para ver também o que existe na tenancy (instâncias, discos de bloco e de boot, IPs públicos, bancos DB System e Autonomous, clusters OKE, mesmo os do Always Free com custo zero) e medir as tags dos recursos, acrescente estas instruções, todas de inspect (listar, sem ler o conteúdo dos recursos), na mesma política ou numa segunda:

Allow group GrandeTotalReaders to inspect compartments in tenancy
Allow group GrandeTotalReaders to inspect instance-family in tenancy
Allow group GrandeTotalReaders to inspect volume-family in tenancy
Allow group GrandeTotalReaders to inspect database-family in tenancy
Allow group GrandeTotalReaders to inspect autonomous-database-family in tenancy
Allow group GrandeTotalReaders to inspect cluster-family in tenancy
Allow group GrandeTotalReaders to read virtual-network-family in tenancy

A última instrução (read virtual-network-family) deixa o painel mostrar os IPs públicos, efêmeros e reservados, e a qual instância cada um está ligado. Os discos de boot entram com a instrução inspect volume-family que já existe. Sem a de rede, o inventário lista tudo menos os IPs.

O inventário percorre cada compartimento em cada região assinada pela tenancy (até 10 regiões e 60 compartimentos por leitura). Cada família é lida à parte: se uma instrução faltar, o painel diz qual (por exemplo db-systems ou autonomous-databases) e as outras seguem. O Autonomous Database tem família própria (autonomous-database-family), separada do database-family.
Discos de boot, buckets e funções ainda não entram. As tags automáticas do namespace Oracle-Tags (CreatedBy e CreatedOn) não contam no padrão.
Com o inventário lido, o Especialista em Tags mede a cobertura e entrega o padrão de quatro chaves, as boas práticas da OCI (namespace, cost-tracking, tag defaults) e os comandos da CLI. Veja Tags de custo.

Ainda não validado numa tenancy real. O formato das respostas e o verbo de cada instrução seguem a documentação da Oracle. Na primeira leitura, confira o resultado com o console; se uma instrução for recusada, o painel mostra o erro da OCI.

Onde o GrandeTotal roda

O próprio GrandeTotal é hospedado na OCI: a API e o banco rodam num cluster k3s, numa instância ARM da Oracle Cloud. Isso não muda o que você precisa fazer, porque o GrandeTotal fala com a sua tenancy só pela Usage API e pelas listagens acima, assinadas com a chave do usuário que você criou, e nunca por uma relação de confiança entre contas. A tenancy onde ele roda é separada da sua.

Erros comuns

A OCI não reconheceu a chave (NotAuthenticated): a chave privada não é o par da chave pública cadastrada no usuário, ou o fingerprint, o User OCID ou o Tenancy OCID foram copiados de outro lugar. Gere um novo par (passo 4) e copie os valores da mesma janela.
Sem permissão de custo (NotAuthorizedOrNotFound): confira, nesta ordem: (1) o usuário está no grupo; (2) a política está no compartimento raiz; (3) o nome do grupo na política está igual (com o domínio entre aspas simples, se não for o Default); (4) a região é a home da tenancy; (5) passaram alguns minutos desde a criação da política.
Erro ao criar a política: o console recusa instruções inválidas. Confira a ortografia do verbo e do tipo de recurso (read usage-report), sem espaços extras.
Essa chave privada tem senha: o par gerado pelo console não tem senha. Se você criou a chave com openssl e uma senha, gere outra sem senha e cadastre a pública no usuário.
Não consegui falar com a OCI nessa região: o identificador está errado (use sa-saopaulo-1, não “Sao Paulo”).
Moeda diferente da outra nuvem: os painéis somam as nuvens em uma moeda só. Ainda não convertemos: se a outra nuvem cobra em USD e a OCI em BRL, a sincronização é recusada com um aviso.
“Sem permissão para ler” no inventário: falta uma das instruções inspect da seção opcional acima (o painel lista qual família foi negada). A Usage API continua funcionando sem elas.
Inventário vazio, mas há recursos no console: confira se os recursos estão em regiões assinadas pela tenancy e se a política está no compartimento raiz (in tenancy), não num compartimento filho.
Muitas requisições em pouco tempo: o GrandeTotal espera e tenta de novo sozinho; se o erro aparecer, aguarde alguns minutos.

Como guardamos a chave privada

A chave privada é cifrada no banco antes de ser gravada e nunca volta para a tela nem para a API do painel. Ela só é decifrada, na memória, no instante de assinar a consulta à OCI. Para a análise por IA, só vão custos agregados (nunca a chave, os OCIDs ou o fingerprint). Veja Segurança e acesso.

Trocar ou revogar o acesso

Trocar a chave: adicione uma nova em API keys do usuário, refaça a conexão no painel com a nova e depois apague a antiga.
Revogar: a qualquer momento, apague a chave de API (ou remova o usuário do grupo, ou apague a política). A próxima sincronização falha e a conexão aparece como erro no painel. Não é necessário avisar o GrandeTotal.