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 https //kubernetes io/docs/tasks/tools/ 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 https //gitlab centralit io/aura/infra/kubernetes/ /raw/main/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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type \[ \["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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type attendant/secret yaml o arquivo attendant/secret yaml armazena informações sensíveis utilizadas pelo serviço os dados estão codificados em base64 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 🔐 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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type wanderson/secret yaml o arquivo wanderson/secret yaml armazena informações sensíveis utilizadas pelo serviço, codificadas em base64 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type ⚠️ 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 6 3 5 widget 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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type ⚠️ 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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 🔐 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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type dash/secret yaml o arquivo dash/secret yaml armazena informações sensíveis do serviço, codificadas em base64 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 🔐 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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type proactive/secret yaml o arquivo proactive/secret yaml armazena informações sensíveis utilizadas pelo serviço, codificadas em base64 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 🔐 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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type pgadmin/secret yaml o arquivo pgadmin/secret yaml armazena informações sensíveis utilizadas pelo serviço, codificadas em base64 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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 true left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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 7 1 6 widget 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"