Manual de Instalação de um novo ambiente

1. Pré-requisitos

Antes de realizar a instalação de um ambiente, certifique-se de que os seguintes pré-requisitos estão atendidos:

Acesso VPN: Caso necessário, para conectar ao cluster do ambiente que será disponibilizado o Citsmart Aura.

Cluster Kubernetes: Um cluster Kubernetes em execução, que pode ser Minikube, GKE, EKS, ou qualquer outra solução Kubernetes compatível.

kubectl: Ferramenta de linha de comando para interagir com o cluster Kubernetes, já configurada para acessar o cluster. Siga as instruções no site oficial do Kubernetes para a instalação.

Banco de Dados: PostgreSQL, no mínimo versão 16, com o usuário e banco de dados criados conforme a seção de configuração do banco de dados.

Domínio: Necessário domínio personalizado configurado e disponibilizado.

CITSmart:

front-manager: @0.34.0-2

backend: front-manager-api:2.10.2

lowcode: hyper-lowcode:1.8.6-RELEASE

citsmart: hyper-itsm-enterprise:CitSmart-CitsmartX-1.7.0

2. Criação do Namespace para o Projeto

Antes de iniciar a implantação dos serviços, é necessário criar um namespace para o projeto. O namespace isola todos os recursos, facilitando o gerenciamento e a organização do ambiente.

2.1 Criando o Namespace

Para criar o namespace, utilize o comando abaixo. Substitua aura-blocks pelo nome desejado para o seu projeto, se preferir outro nome:

kubectl create namespace aura-blocks

Este comando criará o namespace chamado aura-blocks, onde todos os recursos do projeto serão implantados.

Nota: Ao longo deste manual, será utilizado o padrão aura-blocks para facilitar o acompanhamento dos exemplos. Caso você utilize um nome diferente, lembre-se de substituir aura-blocks em todos os comandos e exemplos apresentados.

2.2 Especificando o Namespace nos Manifests

Nos arquivos de manifesto YAML referentes a recursos de namespace, como Deployment, Service, ConfigMap e similares, certifique-se de que todos os recursos possuem o campo namespace com o valor correto. Exemplo esperado nos trechos de YAML:

metadata:
  namespace: aura-blocks

Se tiver escolhido um nome diferente de namespace, substitua aura-blocks pelo nome utilizado em seu ambiente.

Importante: Sempre utilize o mesmo nome de namespace em todos os arquivos de recursos associados ao seu ambiente para garantir que todos os componentes funcionem corretamente.

Dica para Atualizar o Namespace nos Manifestos

Se optar por um nome de namespace diferente de aura-blocks, será necessário atualizar os arquivos de manifesto (*.yaml) para refletir esse novo nome. Você pode automatizar essa tarefa antes de aplicar os manifests, executando o comando a seguir no diretório onde estão armazenados:

NAMESPACE="seu-namespace-aqui" && find . -type f -name "*.yaml" -exec bash -c 'NS="$1"; sed -i"$([[ "$(uname)" == "Darwin" ]] && echo " ")" -E "s/^( *namespace:).*/\1 $NS/" "$2"' _ "$NAMESPACE" {} \;

Substitua seu-namespace-aqui pelo nome que escolheu para o namespace.

Atenção: Nem todos os recursos do Kubernetes utilizam o campo namespace: – por exemplo, arquivos de definição de Namespace, PersistentVolume e recursos do tipo ClusterRole não possuem esse campo ou são de escopo global. Sempre revise seus arquivos YAML, especialmente se estiver usando manifests que abrangem diferentes tipos de recurso.

Para localizar rapidamente onde o campo aparece, use:

Após rodar o comando de substituição, é recomendável revisar os arquivos alterados antes de prosseguir com a aplicação.

grep -r 'namespace:' .

3. Configuração do Banco de Dados

Antes de prosseguir, crie o usuário e o banco de dados no PostgreSQL:

Substitua <user> e <pass> pelas informações necessarias para a criação do usuário.

CREATE USER <user> WITH PASSWORD '<pass>' CREATEDB LOGIN;
CREATE DATABASE aura_blocks OWNER <user>;
GRANT CREATE ON DATABASE aura_blocks TO <user>;

4. Obtendo manifestos

Os manifestos podem ser obtidos no arquivo aura-blocks-manifests.tar.bz2 oferecidos junto ao presente manual.

tar -xf aura-blocks-manifests.tar.bz2

Caso queira, também é possível obter os manifestos originais no repositório oficial do projeto Citsmart Aura:

git clone http://gitlab.centralit.io/aura/infra/kubernetes.git
cd kubernetes/template

5. Estrutura dos Diretórios dos Manifestos

Abaixo está a estrutura dos diretórios dos manifestos.

.
├── attendant
│   ├── configmap.yaml
│   ├── deployment.yaml
│   ├── secret.yaml
│   └── service.yaml
├── dash
│   ├── configmap.yaml
│   ├── deployment.yaml
│   ├── secret.yaml
│   └── service.yaml
├── engine
│   ├── configmap.yaml
│   ├── deployment.yaml
│   ├── secret.yaml
│   └── service.yaml
├── ingress.yaml
├── lunaris
│   ├── deployment.yaml
│   └── service.yaml
├── persistentvolumeclaim.yaml
├── proactive
│   ├── configmap.yaml
│   ├── deployment.yaml
│   ├── secret.yaml
│   └── service.yaml
├── proxy
│   ├── configmap.yaml
│   ├── deployment.yaml
│   └── service.yaml
├── teams-server
│   ├── configmap.yaml
│   ├── deployment.yaml
│   └── service.yaml
├── wanderson
│   ├── configmap.yaml
│   ├── deployment.yaml
│   ├── secret.yaml
│   └── service.yaml
└── widget
    ├── configmap.yaml
    ├── deployment.yaml
    ├── secret.yaml
    └── service.yaml

10 directories, 34 files

6. Configuração dos Manifestos do Kubernetes

Nesta seção, detalharemos o que deve ser alterado em cada arquivo para configurar corretamente os serviços.

6.1 Configuração dos Volumes Persistentes (PVC)

Alguns serviços do projeto Citsmart Aura, como lunaris, wanderson, dash, engine e widget requerem armazenamento persistente de dados (ex: logs, workspaces). Para isso, utiliza-se um PersistentVolumeClaim (PVC) que reserva espaço de armazenamento no cluster Kubernetes.

O arquivo persistentvolumeclaim.yaml define a configuração desse volume compartilhado.

⚠️ Atenção: Antes de aplicar o PVC no cluster, é necessário ajustar campos obrigatórios como o storageClassName, o tipo de acesso (accessModes) e o tamanho do volume (storage).

6.1.1 persistentvolumeclaim.yaml

Campo	Descrição
storageClassName	Define a classe de armazenamento que será usada para provisionar o volume. Esse valor depende do provisionador instalado no cluster. Exemplos comuns: "standard", "nfs-client", "balanced", "ssd". Substitua <storageClassName> pelo nome correto de sua configuração.
accessModes	Define o modo de acesso ao volume. Neste caso, o valor ReadWriteMany permite que vários pods acessem o volume simultaneamente em leitura e escrita — necessário para serviços que compartilham espaço como lunaris, wanderson, dash, engine e widget. Verifique se seu StorageClass suporta esse modo.
resources.requests.storage	Define a capacidade mínima de armazenamento a ser reservada para o volume. O valor padrão é 50Gi. Recomenda-se um mínimo de 20Gi, ajustável conforme o ambiente e carga esperada.

Exemplo com os ajustes recomendados:

storageClassName: nfs-client
accessModes:
  - ReadWriteMany
resources:
  requests:
    storage: 50Gi

📦 Recomendação: Para ambientes de produção ou homologação com múltiplos serviços, recomenda-se reservar ao menos 20Gi de espaço, podendo ser ajustado conforme a necessidade (ex: 50Gi, 100Gi, etc.).

Após os ajustes, aplique o PVC com o comando:

kubectl apply -f persistentvolumeclaim.yaml

💡 Você pode verificar se o volume foi corretamente provisionado com:

kubectl get pvc -n aura-blocks

6.2 Configuração da Engine

6.2.1 engine/configmap.yaml

O arquivo engine/configmap.yaml define variáveis de ambiente essenciais para o funcionamento do serviço engine, controlando desde as conexões com o banco de dados até rotas internas de API e autenticação.

Abaixo está a descrição detalhada de cada uma dessas variáveis:

Variável	Descrição
DB_TYPE	Define o tipo de banco de dados utilizado. Valor esperado: postgres.
DB_NAME	Nome do banco de dados utilizado pela aplicação (ex: aura_blocks).
DB_PORT	Porta de comunicação com o banco de dados (ex: "5432" para PostgreSQL).
DB_HOST	Hostname ou IP onde o banco de dados está hospedado. Substitua <db_host> conforme necessário.
DB_USER	Nome de usuário para autenticação no banco de dados. Substitua <db_user> conforme necessário.
HTTP_PORT	Porta HTTP onde o serviço engine será exposto internamente. Valor padrão: "6060".
HTTP_BASE	Prefixo base da API da engine. Deve coincidir com a configuração do Ingress (ex: "/engine/").
DOCS_PATH	Caminho relativo para acesso à documentação do Citsmart Aura (ex: "/docs").
MANUALS_PATH	Caminho relativo para acesso a manuais do Citsmart Aura (ex: "/manuals").
TESTS_PATH	Caminho relativo para acesso ao roteiro de testes Citsmart Aura (ex: "/roteiro_testes").
BASIC_AUTH_USERNAME	Nome de usuário para autenticação básica na rota de documentação (/docs).
ATTACHMENT_PATH	Caminho interno relativo para armazenamento de anexos (ex: "/engine/attachments").
LUNARIS_URL	Caminho interno relativo para integrar com o serviço Lunaris (ex: "/lunaris").
FINAL_URL	URL pública final para acesso à engine (ex: https://domain.com/engine/).
USER	Usuário utilizado para autenticação da API. Valor padrão: "lowcode".
KEYCLOAK_URL	URL para obtenção de informações de usuário via Keycloak. Essa URL inclui o realm e o caminho do endpoint userinfo do OpenID Connect.
DEFAULT_MANIFESTS	Lista padrão de manifestos (em JSON) a serem carregados pela engine ao iniciar. Cada item contém: Nome, URL do manifesto e tipo (Talker, Broker, Event, etc.). Abaixo está a estrutura completa:

[
  ["Máquina de estados", "https://domain.com/wanderson/plugin/manifest", "Talker"],
  ["Questionários e ações", "https://domain.com/lunaris/.well-known/lunaris-configuration", "Talker"],
  ["Botmaker", "https://domain.com/lunaris/get/botmaker/manifest", "Broker"],
  ["Atendimento Humano", "https://domain.com/attendant/manifest", "Talker"],
  ["Gupshup", "https://domain.com/lunaris/get/gupshup/manifest", "Broker"],
  ["Messenger", "https://domain.com/lunaris/get/messenger/manifest", "Broker"],
  ["Positus", "https://domain.com/lunaris/get/positus/manifest", "Broker"],
  ["Slack", "https://domain.com/lunaris/get/slack/manifest", "Broker"],
  ["Teams", "https://domain.com/teams_server/manifest", "Broker"],
  ["Telegram", "https://domain.com/lunaris/get/telegram/manifest", "Broker"],
  ["Twilio", "https://domain.com/lunaris/get/twilio/manifest", "Broker"],
  ["Widget", "https://domain.com/widget/manifest", "Broker"],
  ["OIDC", "https://domain.com/lunaris/get/oidc/manifest", "Event"],
  ["UserInfo", "https://domain.com/lunaris/get/userinfo/manifest", "Userinfo"]
]

⚠️ Atenção: Todos os valores com https://domain.com devem ser substituídos pelo domínio real onde a aplicação será instalada (ex: https://meusistema.empresa.com.br).

6.2.2 engine/secret.yaml

Este arquivo contém variáveis sensíveis utilizadas pelo serviço engine. As informações estão codificadas em Base64 e não devem ser versionadas em repositórios públicos. As variáveis definidas são:

Variável	Descrição
DB_PASS	Senha de acesso ao banco de dados PostgreSQL utilizada pela aplicação.
BASIC_AUTH_PASSWORD	Senha para autenticação básica no acesso à rota /docs da documentação.
PASS	Senha utilizada para autenticação da API.

Substitua senhas codificadas com:

echo -n 'minha_senha' | base64

🔐 Atenção: Todos os valores estão codificados em Base64. Para editar ou revisar, utilize ferramentas para codificar/decodificar com segurança.

Para ambientes sensíveis, considere usar SealedSecrets ou SOPS.

6.2.3 engine/deployment.yaml

O deployment.yaml é responsável por definir o deployment do serviço engine. Certifique-se de que o namespace e as imagens do container estão corretas e que os ConfigMaps e Secrets estão sendo referenciados corretamente.

6.3 Configuração dos Outros Serviços

6.3.1 attendant

attendant/configmap.yaml

O arquivo attendant/configmap.yaml define as variáveis de ambiente utilizadas pelo serviço attendant. Este item refere-se exclusivamente à configuração do ConfigMap. As variáveis disponíveis são:

Variável	Descrição
DB_TYPE	Tipo de banco de dados utilizado (ex: postgres).
DB_NAME	Nome do banco de dados acessado pela aplicação (ex: aura_blocks).
DB_PORT	Porta de comunicação com o banco de dados (ex: "5432" para PostgreSQL).
DB_HOST	Hostname ou serviço interno onde o banco de dados está acessível (ex: postgresql).
DB_USER	Usuário do banco de dados.
HTTP_PORT	Porta HTTP em que o serviço será exposto internamente (ex: "6060").
HTTP_BASE	Caminho base da API do serviço attendant. Deve coincidir com a configuração do Ingress (ex: "/attendant/").
ENGINE_URL	URL do serviço engine utilizado pelo attendant (ex: "https://domain.com/engine/").
BASE_URL	URL base da aplicação (ex: "https://domain.com").
AMBIENTE	URL base do Citsmart, onde será disponibilizada a aplicação. (ex: "https://hml-cocriar.cithyper.click")
SLEEP_TIME	Intervalo (em segundos) para processamento das mensagens das filas de atendimento. Ex: "120" representa 2 minutos.
USER	Usuário utilizado para autenticação da API. Valor padrão: "lowcode".
KEYCLOAK_URL	URL para obtenção de informações do usuário via Keycloak (OpenID Connect - endpoint /userinfo).

attendant/secret.yaml

O arquivo attendant/secret.yaml armazena informações sensíveis utilizadas pelo serviço. Os dados estão codificados em Base64.

Variável	Descrição
PASS	Senha codificada em Base64 para autenticação da API.
DB_PASS	Senha do banco de dados associada ao usuário definido em DB_USER.

🔐 Atenção: As informações armazenadas no Secret devem ser tratadas com confidencialidade. Evite exposição em logs ou repositórios.

6.3.2 lunaris

lunaris/deployment.yaml

O arquivo lunaris/deployment.yaml define o deployment do serviço lunaris. Um dos pontos mais importantes a ser ajustado está no campo command, que define os argumentos utilizados na inicialização do container.

Campo	Descrição
command	Define os parâmetros passados ao iniciar o serviço Lunaris. Os principais valores que precisam ser alterados são: - -u (URL pública do serviço Lunaris): deve ser substituída por uma URL válida do domínio onde o serviço será disponibilizado. - -O (URL do Keycloak para autenticação OpenID Connect): também precisa ser ajustada para refletir o domínio real do ambiente (incluindo o realm).

Exemplo original:

-u https://domain.com/lunaris
-O https://keycloak-domain.com/auth/realms/<realm>/protocol/openid-connect/userinfo

Exemplo com domínio ajustado:

-u https://aura-blocks.centralit.com.br/lunaris
-O https://hml-sso.cithyper.click/auth/realms/hml-cocriar/protocol/openid-connect/userinfo

⚠️ Atenção: Substitua os valores domain.com, keycloak-domain.com e <realm> pelo domínio e realm reais utilizados no ambiente de homologação ou produção.

6.3.3 wanderson

wanderson/configmap.yaml

O arquivo wanderson/configmap.yaml define variáveis de ambiente utilizadas pelo serviço wanderson. Este item refere-se exclusivamente à configuração do ConfigMap.

Variável	Descrição
TZ	Define o fuso horário utilizado no container (ex: "America/Sao_Paulo").
DATABASE_HOST	Hostname do banco de dados. Deve ser substituído por um valor real (ex: postgresql).
DATABASE_PORT	Porta para conexão com o banco de dados (ex: "5432").
DATABASE_USERNAME	Nome do usuário de acesso ao banco de dados.
DATABASE_NAME	Nome do banco de dados utilizado (ex: aura_blocks).
DATABASE_MIN_POOL_SIZE	Tamanho mínimo do pool de conexões.
DATABASE_MAX_POOL_SIZE	Tamanho máximo do pool de conexões.
PORT	Porta interna utilizada pelo serviço (ex: "80").
LOG_LEVELS	Níveis de log habilitados no serviço (ex: '["error", "warn", "log", "debug"]').
CORS_ALLOWED_ORIGIN	Origem permitida para requisições CORS (ex: "*" permite todas).
CORS_ALLOWED_METHODS	Métodos HTTP permitidos via CORS (ex: "*").
CORS_ALLOWED_HEADERS	Headers permitidos via CORS (ex: "*").
CORS_ALLOW_CREDENTIALS	Habilita envio de cookies/autenticação via CORS (ex: "true").

wanderson/secret.yaml

O arquivo wanderson/secret.yaml armazena informações sensíveis utilizadas pelo serviço, codificadas em Base64.

Variável	Descrição
DATABASE_PASSWORD	Senha utilizada em conjunto com DATABASE_USERNAME para autenticação no banco de dados.

wanderson/deployment.yaml

O arquivo deployment.yaml do serviço wanderson define diversos parâmetros do container, incluindo o campo command, que deve ser ajustado conforme o domínio do ambiente.

Parâmetro	Descrição
-O	Define a URL do endpoint userinfo do Keycloak para autenticação via OpenID Connect. Deve ser ajustada para refletir o domínio e o realm corretos do ambiente.
-u	Define a URL pública base do serviço wanderson. Essa URL deve corresponder à configuração de Ingress (por exemplo: https://aura-blocks.centralit.com.br/wanderson/).

Exemplo original:

-O https://keycloak-domain.com/auth/realms/<realm>/protocol/openid-connect/userinfo
-u https://domain.com/wanderson/

Exemplo ajustado:

-O https://hml-sso.cithyper.click/auth/realms/hml-cocriar/protocol/openid-connect/userinfo
-u https://aura-blocks.centralit.com.br/wanderson/

⚠️ Atenção: Ambos os valores — -O (Keycloak) e -u (URL pública) — devem ser substituídos pelo domínio real do ambiente em que o serviço será executado, respeitando o caminho do Ingress e o realm de autenticação.

6.3.4 teams-server

teams-server/configmap.yaml

O arquivo teams-server/configmap.yaml define variáveis de ambiente utilizadas pelo serviço teams-server. Este item refere-se exclusivamente à configuração do ConfigMap.

Variável	Descrição
HTTP_PORT	Porta HTTP utilizada internamente pelo serviço (ex.: "6969").
BASE_URL	URL base pública da aplicação. Deve ser substituída pelo domínio real da aplicação (ex.: "https://aura-blocks.centralit.com.br").
SUBPREFIX	Caminho base da rota do serviço no Ingress (ex.: "/teams_server/").
URL_TO_ENGINE	Endpoint utilizado para repassar mensagens recebidas ao serviço engine. Substitua domain.com pela URL real do engine (ex.: "https://aura-blocks.centralit.com.br/engine").

⚠️ Atenção: Os valores que utilizam domain.com são placeholders e devem ser substituídos pelo domínio oficial da aplicação no ambiente de homologação ou produção.

widget/configmap.yaml

O arquivo widget/configmap.yaml define as variáveis de ambiente utilizadas pelo serviço widget. Este item refere-se exclusivamente à configuração do ConfigMap.

Variável	Descrição
DB_TYPE	Tipo de banco de dados utilizado (ex: postgres).
DB_NAME	Nome do banco de dados utilizado pelo serviço (ex: widget).
DB_PORT	Porta utilizada para conexão com o banco de dados (ex: "5432").
DB_HOST	Hostname do banco de dados. Deve ser substituído por um valor real.
DB_USER	Nome de usuário para autenticação no banco de dados.
HTTP_PORT	Porta HTTP onde o serviço será exposto internamente (ex: "8989").
HTTP_BASE	Caminho base da API do widget (ex: "/widget/"). Deve coincidir com a configuração do Ingress.
BASE_URL	URL base da aplicação para chamadas HTTP. Substituir domain.com pelo domínio real do ambiente.
BASE_WEBSOCKET_URL	URL base para conexões WebSocket (ex: "ws://domain.com"). Substituir pelo domínio correto.
ENGINE_URL	URL do serviço engine para integração (ex: "https://domain.com/engine").
ATTACHMENT_PATH	Caminho relativo para anexos enviados/recebidos (ex: "/attachments").
DOCS_PATH	Caminho interno para a documentação (ex: "../../docs/book").
REF_PATH	Caminho base para referências utilizadas pelo widget (ex: "/ref/").
WIDGETS_PATH	Caminho para os recursos de widgets (ex: "/widgets/").
USER	Nome de usuário utilizado internamente para autenticação da API (ex: "lowcode").
TIME_KEEPALIVE	Tempo em segundos para envio do evento para manter a conexão ativa (ex: "30").

⚠️ Atenção: Todos os campos que contêm domain.com devem ser substituídos pelo domínio oficial da aplicação (HTTP e WebSocket).

widget/secret.yaml

O arquivo widget/secret.yaml armazena informações sensíveis utilizadas pelo serviço, codificadas em Base64.

Variável	Descrição
DB_PASS	Senha utilizada em conjunto com DB_USER para autenticação no banco de dados.
PASS	Senha codificada em Base64, utilizada para autenticação da API.

🔐 Atenção: Nunca armazene os valores decodificados em repositórios. Manipule os segredos com segurança e mantenha-os restritos ao ambiente controlado.

6.3.6 dash

dash/configmap.yaml

O arquivo dash/configmap.yaml define as variáveis de ambiente utilizadas pelo serviço dash, responsável por relatórios e visualizações. Este item refere-se exclusivamente à configuração do ConfigMap.

Variável	Descrição
DB_TYPE	Tipo de banco de dados utilizado (ex: postgres).
DB_NAME	Nome do banco de dados acessado pela aplicação (ex: aura_blocks).
DB_PORT	Porta de conexão com o banco de dados (ex: "5432").
DB_HOST	Hostname onde o banco de dados está disponível (ex: postgresql).
DB_USER	Nome do usuário utilizado na autenticação do banco.
HTTP_PORT	Porta onde o serviço será exposto internamente (ex: "2610").
HTTP_BASE	Caminho base da API do serviço dash (ex: "/dash/"). Deve estar alinhado com a configuração do Ingress.
REPORTS_PATH	Caminho interno utilizado para armazenamento e acesso aos relatórios gerados (ex: "/reports").
GIT_ENABLED	Define se a funcionalidade de integração com repositório Git está habilitada (true ou false). Quando habilitado, o serviço tentará sincronizar relatórios com o repositório definido.
GIT_REPO_URL	URL do repositório Git que será utilizado para armazenar e versionar os relatórios (ex: https://gitlab.com/empresa/relatorios.git).
GIT_BRANCH	Nome do branch padrão no repositório Git onde os relatórios serão sincronizados (ex: main).
GIT_USERNAME	Nome de usuário que será utilizado para autenticação no repositório Git.

dash/secret.yaml

O arquivo dash/secret.yaml armazena informações sensíveis do serviço, codificadas em Base64.

Variável	Descrição
DB_PASS	Senha utilizada em conjunto com DB_USER para autenticação no banco de dados.
GIT_PASSWORD	Senha ou Personal Access Token (PAT) utilizado para autenticação no repositório Git. Devido à segurança, recomenda-se sempre utilizar PAT em vez de senha simples.

🔐 Atenção: Os segredos devem ser tratados com segurança e não devem ser versionados em repositórios públicos.

6.3.7 proactive

proactive/configmap.yaml

O arquivo proactive/configmap.yaml define as variáveis de ambiente utilizadas pelo serviço proactive. Este item refere-se exclusivamente à configuração do ConfigMap.

Variável	Descrição
DB_TYPE	Tipo de banco de dados utilizado (ex: postgres).
DB_NAME	Nome do banco de dados utilizado pelo serviço (ex: aura_blocks).
DB_PORT	Porta utilizada para conexão com o banco de dados (ex: "5432").
DB_HOST	Hostname do banco de dados. Deve ser substituído por um valor real.
DB_USER	Nome de usuário para autenticação no banco de dados.
HTTP_PORT	Porta HTTP onde o serviço será exposto internamente (ex: "8989").
HTTP_BASE	Caminho base da API do proactive (ex: "/proactive/"). Deve coincidir com a configuração do Ingress.
HTTP_USER	Usuário utilizado para autenticação da API. Valor padrão: "lowcode".
GUPSHUP_APIKEY	Chave da API da gupshup. Substituir o valor pela chave real do ambiente
GUPSHUP_APPID	ID do APP da gupshup. Substituir o valor pela chave real do ambiente
GUPSHUP_SOURCE	Telefone vinculado ao workspace na gupshup. Substituir o valor pela chave real do ambiente
GUPSHUP_SRC_NAME	Workspace na gupshup. Substituir o valor pela chave real do ambiente
KEYCLOAK_URL	URL para obtenção de informações de usuário via Keycloak. Essa URL inclui o realm e o caminho do endpoint userinfo do OpenID Connect.

proactive/secret.yaml

O arquivo proactive/secret.yaml armazena informações sensíveis utilizadas pelo serviço, codificadas em Base64.

Variável	Descrição
DB_PASS	Senha utilizada em conjunto com DB_USER para autenticação no banco de dados.
HTTP_PASS	Senha codificada em Base64, utilizada para autenticação da API.

🔐 Atenção: Nunca armazene os valores decodificados em repositórios. Manipule os segredos com segurança e mantenha-os restritos ao ambiente controlado.

6.3.8 pgadmin

pgadmin/configmap.yaml

O arquivo pgadmin/configmap.yaml define as variáveis de ambiente utilizadas pelo serviço pgAdmin, responsável por oferecer uma interface gráfica para administração do banco de dados PostgreSQL.

Variável	Descrição
TZ	Fuso horário do container. Exemplo: "America/Sao_Paulo".
SCRIPT_NAME	Caminho base opcional (prefixo) da aplicação no Ingress. Exemplo: "/pgadmin".
PGADMIN_DEFAULT_EMAIL	E-mail do usuário administrador criado automaticamente no primeiro acesso. Exemplo: "[email protected]".
MAX_LOGIN_ATTEMPTS	Número máximo de tentativas de login antes do bloqueio do usuário. Padrão: 3.
PGADMIN_LISTEN_ADDRESS	Endereço de rede no qual o pgAdmin vai escutar. Normalmente 0.0.0.0 para aceitar todas as conexões.

pgadmin/secret.yaml

O arquivo pgadmin/secret.yaml armazena informações sensíveis utilizadas pelo serviço, codificadas em Base64.

Variável	Descrição
PGADMIN_DEFAULT_PASSWORD	Senha associada ao PGADMIN_DEFAULT_EMAIL para acesso à interface do pgAdmin.

6.4 Configuração do Ingress

O arquivo ingress.yaml define as regras de roteamento HTTP externo para os serviços do projeto aura-blocks, utilizando um Ingress Controller como Traefik ou NGINX. Ele garante que cada caminho (/engine, /widget, etc.) seja corretamente encaminhado para o serviço correspondente dentro do cluster.

⚠️ Atenção: Esse arquivo exige configurações obrigatórias para funcionar corretamente em cada ambiente. A seguir, estão os campos que devem ser ajustados:

6.4.1 ingress.yaml

Campo	Descrição
ingressClassName	Define qual controlador de Ingress será responsável por gerenciar as regras. Deve ser substituído por um valor existente no cluster (ex: "traefik" ou "nginx").
host	Nome do domínio público onde os serviços serão acessados. Substitua domain.com pelo domínio real da aplicação (ex: aura-blocks.centralit.com.br).
paths	Cada caminho HTTP (/engine, /widget, etc.) é roteado para o respectivo serviço Kubernetes com sua porta correspondente. Esses caminhos devem estar alinhados com os valores de HTTP_BASE definidos nos ConfigMaps.
tls.secretName	Nome do Secret que contém o certificado TLS para habilitar HTTPS. O segredo deve estar criado no namespace aura-blocks, com o nome correspondente ao domínio utilizado. Por exemplo: aura-blocks-centralit-tls.
tls.hosts	Lista de domínios que serão protegidos via HTTPS. Deve corresponder ao domínio configurado no campo host.

Exemplo de valores substituídos corretamente:

...
ingressClassName: traefik
rules:
- host: aura-blocks.centralit.com.br
...
tls:
  - secretName: aura-blocks-centralit-tls
    hosts:
      - aura-blocks.centralit.com.br

🔐 Importante: Certifique-se de que o Secret de TLS já exista no namespace aura-blocks, e que tenha sido criado a partir de um certificado válido para o domínio desejado. Isso é essencial para permitir a navegação segura via HTTPS.

Após realizar os ajustes necessários, aplique o Ingress com o comando:

kubectl apply -f ingress.yaml

7. Deployment do Ambiente

Com todas as configurações ajustadas, você pode aplicar os manifestos ao cluster. Navegue até o diretório correto e execute o seguinte comando:

kubectl apply -f <CAMINHO_DO_MANIFESTO_MODIFICADO>

7.1 Aplicando os Manifests de Kubernetes

Agora, aplique os manifestos ao cluster. Repita os seguintes comandos para cada serviço:

7.1.1 engine

kubectl apply -f engine/configmap.yaml
kubectl apply -f engine/secret.yaml
kubectl apply -f engine/deployment.yaml
kubectl apply -f engine/service.yaml

7.1.2 attendant

kubectl apply -f attendant/configmap.yaml
kubectl apply -f attendant/secret.yaml
kubectl apply -f attendant/deployment.yaml
kubectl apply -f attendant/service.yaml

7.1.3 lunaris

kubectl apply -f lunaris/deployment.yaml
kubectl apply -f lunaris/service.yaml

7.1.4 wanderson

kubectl apply -f wanderson/configmap.yaml
kubectl apply -f wanderson/secret.yaml
kubectl apply -f wanderson/deployment.yaml
kubectl apply -f wanderson/service.yaml

7.1.5 teams-server

kubectl apply -f teams-server/configmap.yaml
kubectl apply -f teams-server/deployment.yaml
kubectl apply -f teams-server/service.yaml

kubectl apply -f widget/configmap.yaml
kubectl apply -f widget/secret.yaml
kubectl apply -f widget/deployment.yaml
kubectl apply -f widget/service.yaml

7.1.7 dash

kubectl apply -f dash/configmap.yaml
kubectl apply -f dash/secret.yaml
kubectl apply -f dash/deployment.yaml
kubectl apply -f dash/service.yaml

7.1.8 proactive

kubectl apply -f proactive/configmap.yaml
kubectl apply -f proactive/secret.yaml
kubectl apply -f proactive/deployment.yaml
kubectl apply -f proactive/service.yaml

7.1.9 pgadmin

kubectl apply -f pgadmin/configmap.yaml
kubectl apply -f pgadmin/secret.yaml
kubectl apply -f pgadmin/deployment.yaml
kubectl apply -f pgadmin/service.yaml

8. Verificação do Deployment

Após aplicar todos os manifests, é essencial validar se os recursos foram criados corretamente e estão funcionando como esperado.

8.1 Verificar Recursos Criados no Namespace

kubectl get all -n aura-blocks

Lista pods, services, deployments, replicasets, etc.

Confirme se todos os pods estão com STATUS Running ou Completed e READY como 1/1 ou x/x.

8.2 Verificar Eventos e Condições de Falha

kubectl get events -n aura-blocks --sort-by=.metadata.creationTimestamp

Mostra eventos recentes, como falhas de agendamento, erro de imagem, problemas com PVC, etc.

Use este comando para debug de erros de criação.

8.3 Diagnóstico de um Pod Específico

kubectl describe pod <nome-do-pod> -n aura-blocks

Para listar os nomes dos pods:

kubectl get pods -n aura-blocks

8.4 Verificar o Ingress

kubectl describe ingress -n aura-blocks

Valida se o Ingress está roteando corretamente os caminhos (/engine, /widget, etc).

Verifique:

Address: IP externo ou LoadBalancer configurado

Rules: correspondem aos paths e hosts definidos

TLS: status do certificado

8.5 Validar a URL Pública dos Serviços

curl -I https://aura-blocks.centralit.com.br/engine/manuals/

Verifica se o serviço engine está acessível via HTTPS.

8.6 Verificar Logs dos Pods

Engine:

kubectl logs -l app=engine -n aura-blocks --tail=100

Lunaris:

kubectl logs -l app=lunaris -n aura-blocks --tail=100

8.7 Verificar Volume Persistente

kubectl get pvc -n aura-blocks
kubectl describe pvc <nome-do-pvc> -n aura-blocks

8.8 Consultar Variáveis de Ambiente do Pod

kubectl exec -it <nome-do-pod> -n aura-blocks -- printenv

8.9 Verificar Readiness de Todos os Pods

kubectl get pods -n aura-blocks -o custom-columns="POD:metadata.name,STATUS:status.phase,READY:status.conditions[?(@.type=='Ready')].status"

Manual de Instalação de um novo ambiente

1. Pré-requisitos

2. Criação do Namespace para o Projeto

2.1 Criando o Namespace

2.2 Especificando o Namespace nos Manifests

Dica para Atualizar o Namespace nos Manifestos

3. Configuração do Banco de Dados

4. Obtendo manifestos

5. Estrutura dos Diretórios dos Manifestos

6. Configuração dos Manifestos do Kubernetes

6.1 Configuração dos Volumes Persistentes (PVC)

6.1.1 persistentvolumeclaim.yaml

6.2 Configuração da Engine

6.2.1 engine/configmap.yaml

6.2.2 engine/secret.yaml

6.2.3 engine/deployment.yaml

6.3 Configuração dos Outros Serviços

6.3.1 attendant

attendant/configmap.yaml

attendant/secret.yaml

6.3.2 lunaris

lunaris/deployment.yaml

6.3.3 wanderson

wanderson/configmap.yaml

wanderson/secret.yaml

wanderson/deployment.yaml

Exemplo original:

6.3.4 teams-server

teams-server/configmap.yaml

6.3.5 widget

widget/configmap.yaml

widget/secret.yaml

6.3.6 dash

dash/configmap.yaml

dash/secret.yaml

6.3.7 proactive

proactive/configmap.yaml

proactive/secret.yaml

6.3.8 pgadmin

pgadmin/configmap.yaml

pgadmin/secret.yaml

6.4 Configuração do Ingress

6.4.1 ingress.yaml

7. Deployment do Ambiente

7.1 Aplicando os Manifests de Kubernetes

7.1.1 engine

7.1.2 attendant

7.1.3 lunaris

7.1.4 wanderson

7.1.5 teams-server

7.1.6 widget

7.1.7 dash

7.1.8 proactive

7.1.9 pgadmin

8. Verificação do Deployment

8.1 Verificar Recursos Criados no Namespace

8.2 Verificar Eventos e Condições de Falha

8.3 Diagnóstico de um Pod Específico

8.4 Verificar o Ingress

8.5 Validar a URL Pública dos Serviços

8.6 Verificar Logs dos Pods

Engine:

Lunaris:

8.7 Verificar Volume Persistente

8.8 Consultar Variáveis de Ambiente do Pod

8.9 Verificar Readiness de Todos os Pods