diff --git a/README.md b/README.md index c177cfa..dfa8beb 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ A documentação está organizada para fornecer uma base sólida, garantindo que É uma linguagem de programação criada pelo Google, muito utilizada para desenvolvimento backend, de microserviços, aplicativos CLI, entre outros. -O Go é utilizado tanto no Kubernetes, quanto no ESO, as duas principais tecnologias envolvidas no trabalho. +O Go é necessário no ESO para compilar, executar e contribuir com o código-fonte do projeto. ### Kubernetes @@ -22,25 +22,27 @@ Com o Kubernetes é possível orquestrar de forma mais fácil múltiplos contêi ### External Secrets Operator (ESO) -O ESO, é uma ferramenta que integra segredos (variáveis sensíveis) de provedores externos, como AWS, Google Cloud, entre outros, com um ambiente kubertenes. +O ESO é um operador Kubernetes que tem como função integrar secrets de sistemas externos, como o AWS Secrets Manager, HashiCorp Vault, etc. -Com ele, é possível, pegar senhas salvas em um ambiente AWS, por exemplo, e subir para um contêiner em um cluster Kubernetes. +O objetivo do ESO é sincronizar secrets sensíveis de APIs externas com o Kubernetes, provendo uma maneira mais fácil e segura de lidar com os eles. + +Imagine que você esteja lidando com dados sensíveis como um acesso ao banco de dados que esteja armazenado em um sistema externo. Com o ESO, esses dados são disponibilizados no Kubernetes como secrets, podendo ser consumidos pela aplicação. Além disso, caso as credenciais sejam atualizadas no AWS Secrets Manager, o ESO sincroniza as mudanças automaticamente com o Kubernetes. ## Estrutura do Repositório As pastas deste repositório foram organizadas de forma a facilitar o processo de configuração e uso do External Secrets Operator (ESO), permitindo que você siga os passos necessários de maneira sequencial e eficiente. A estrutura está dividida da seguinte forma: Setup: Contém os arquivos e instruções para a configuração inicial, incluindo a instalação do Kubernetes, ESO e demais pré-requisitos. -[SETUP](https://github.com/frmiza/GCES-ESO-Doc/tree/docs/eso_docs/docs/1-Setup) +[SETUP](https://github.com/FGA-GCES/ESO-Documentacao/tree/main/docs/1-Setup) -Conectando: Orienta sobre como integrar o ESO ao Kubernetes e outras plataformas, incluindo como conectar com clusters kubernets locais ou por meio de ferramentas de computação em nuvem como a AWS, Google cloud e Azure -[CONECTANDO](https://github.com/frmiza/GCES-ESO-Doc/tree/docs/eso_docs/docs/2-Conectando) +Conectando: Orienta sobre como integrar o ESO ao Kubernetes e outras plataformas, incluindo como conectar com clusters kubernetes locais ou por meio de ferramentas de computação em nuvem como a AWS, Google cloud e Azure +[CONECTANDO](https://github.com/FGA-GCES/ESO-Documentacao/tree/main/docs/2-Conectando) Links Externos: Uma coleção de recursos externos úteis, como artigos, fóruns e documentações oficiais, que podem auxiliar durante o desenvolvimento. -[LINKS](https://github.com/frmiza/GCES-ESO-Doc/tree/docs/eso_docs/docs/3-Links) +[LINKS](https://github.com/FGA-GCES/ESO-Documentacao/tree/main/docs/3-Links) Seção com resolução de problemas encontrados durante o setup do projeto: -[COMMON_ISSUES](https://github.com/frmiza/GCES-ESO-Doc/tree/97a27e5594df9a12945dda4746d4dabacd47b30f/eso_docs/docs/4-Common_issues) +[COMMON_ISSUES](https://github.com/FGA-GCES/ESO-Documentacao/tree/main/docs/4-Common_issues) ## Executar a documentação localmente diff --git a/docs/0-Glossario/glossario.md b/docs/0-Glossario/glossario.md new file mode 100644 index 0000000..9be2dba --- /dev/null +++ b/docs/0-Glossario/glossario.md @@ -0,0 +1,228 @@ +# Glossário de Tecnologias Relacionadas ao ESO. + +Este Glossário está organizado em ordem alfabética. + +--- + +??? note "Cluster" + + - **O que é?** + + É um conjunto de nós (computadores) que executam cargas de trabalho no Kubernetes, isto é, executar aplicações em container. + + É uma técnica que agrupa vários recursos computacionais em uma única unidade lógica. Esses recursos são conectados em rede e trabalham em conjunto para executar tarefas, processar dados e armazenar informações de maneira a melhorar o desempenho de aplicações, garantir alta disponibilidade, reduzir custos e aumentar a escalabilidade, já que os recursos podem ser compartilhados e distribuídos de maneira eficiente para atender às demandas da aplicação em tempo real. Cada computador é um “nó”, sendo que não há limites de quantos nós podem ser interligados. + + O cluster é o que proporciona a principal vantagem do Kubernetes: a capacidade de programar e executar containers em um conjunto de máquinas físicas, virtuais, on-premise ou na nuvem. Os containers do Kubernetes não estão vinculados a máquinas individuais. Na verdade, eles são abstraídos em todo o cluster. + + + - **Para que serve?** + O cluster tem a função de agrupar várias máquinas em um sistema único e eficiente, permitindo que aplicações distribuídas sejam executadas com maior desempenho e escalabilidade. No Kubernetes, ele facilita o gerenciamento de containers de forma a reduzir a complexidade, garantir alta disponibilidade e reduzir custos. O cluster Kubernetes geralmente possui um nó principal que gerencia os pods e o ambiente de execução do sistema. + + - **Links úteis:** + - [Introdução aos Clusters](https://kubernetes.io/docs/concepts/cluster-administration/) + - [O que é um cluster do Kubernetes?](https://aws.amazon.com/pt/what-is/kubernetes-cluster/) + - [Kubernetes Clusters: Everything You Need To Know](https://www.atatus.com/blog/kubernetes-clusters-everything-you-need-to-know/) + +--- + +??? note "Docker" + + - **O que é?** + Docker é uma plataforma aberta para o desenvolvimento, envio e execução de aplicações. Ele permite que você separe suas aplicações da infraestrutura, facilitando a entrega de software de forma rápida e eficiente, permitindo criar, compartilhar e executar aplicações e microsserviços containerizados. + + - **Para que serve?** + Possibilita a gestão da infraestrutura ,utilizando suas metodologias para envio, teste e implantação de código. Com isso, é possível reduzir significativamente o tempo entre a escrita do código e a sua execução em produção. + Ele simplifica processos complexos, como mapeamento de portas, preocupações com o sistema de arquivos e outras configurações padrão, permitindo que o foco seja na escrita de código. + Com ele, é possível desenvolver a aplicação e seus componentes de apoio usando containers. Neste contexto, o container se torna a unidade para distribuir e testar a aplicação. Quando estiver pronto, é possível implantar a aplicação no ambiente de produção, seja ele local, na nuvem ou híbrido. + + - **Links úteis:** + - [Documentação oficial](https://docs.docker.com/) + +--- + +??? note "ESO - External Secrets Operator" + + - **O que é?** + É um operador do Kubernetes que integra sistemas de gerenciamento de segredos externos (como AWS Secrets Manager, HashiCorp Vault, Google Secrets Manager, Azure Key Vault, IBM Cloud Secrets Manager, CyberArk Conjur, Pulumi ESC, entre outros). O operador lê informações das APIs externas e injeta automaticamente os valores nos segredos do Kubernetes, permitindo sincronizar dados confidenciais de provedores externos. + + - **Para que serve?** + Automatiza a sincronização de segredos de APIs externas com os clusters Kubernetes, garantindo segurança e eficiência na gestão de credenciais. + O ESO é composto por um conjunto de recursos personalizados de API — ExternalSecret, SecretStore e ClusterSecretStore — que fornecem uma abstração amigável para a API externa que armazena e gerencia o ciclo de vida dos segredos para você. Isso facilita a gestão de segredos no Kubernetes ao integrá-los de maneira automática com os provedores externos de segredos. + + - **Links úteis:** + - [Documentação oficial](https://external-secrets.io/) + +--- + +??? note "Go" + + - **O que é?** + Uma linguagem de programação de código aberto criada pelo Google, conhecida pela simplicidade, desempenho, clareza e concisão. + - **Para que serve?** + Usada no desenvolvimento de aplicativos, sistemas de backend e ferramentas, especialmente em ambientes de cloud e Kubernetes. + É uma linguagem que oferece mecanismos de concorrência que facilitam a escrita de programas capazes de aproveitar ao máximo máquinas com múltiplos núcleos e redes, enquanto seu sistema de tipos inovador permite a construção de programas flexíveis e modulares. Go compila rapidamente para código de máquina e, ao mesmo tempo, oferece conveniência com coleta de lixo e o poder da reflexão em tempo de execução. É uma linguagem compilada, estaticamente tipada, que tem a agilidade de linguagens dinamicamente tipadas e interpretadas. + - **Links úteis:** + - [Documentação oficial](https://go.dev/doc/) + +--- + +??? note "Helm" + + - **O que é?** + Um gerenciador de pacotes para Kubernetes que facilita a implantação e o gerenciamento de aplicações usando templates chamados "charts". + - **Para que serve?** + Simplifica a configuração, instalação e atualização de aplicativos no Kubernetes. + - **Links úteis:** + - [Documentação oficial](https://helm.sh/docs/) + - [GitHub do projeto](https://github.com/helm/helm) + +--- + +??? note "HPA" + + - **O que é?** + Horizontal Pod Autoscaler (HPA) + - **Para que serve?** + É usado para controlar a quantidade de Pods que há em um Deployment. Por exemplo, se o uso de CPU estiver muito alto, o HPA aumentaria a quantidade de pods. Também é possível utilizar o Vertical Pod Autoscaler (VPA), que aumentaria a quantidade de recursos de cada pod em vez de aumentar a quantidade de Pod. + + Fonte: [Leo Michalski](https://github.com/leomichalski/kubernetes-para-devs/blob/main/README.md) + +--- + +??? note "Ingress" + + - **O que é?** + Em um cluster Kubernetes no qual todas as requisições chegam no mesmo IP e na mesma porta, os Ingresses são responsáveis por direcionar (de acordo com o DNS e o endpoint de cada requisição) essas requisições para os Services adequados. Também pode ser usado para outras finalidades. + + Fonte: [Leo Michalski](https://github.com/leomichalski/kubernetes-para-devs/blob/main/README.md) + + - **Para que serve?** + Oferece um ponto de entrada único para rotear tráfego para serviços internos. + - **Links úteis:** + - [Sobre Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) + +--- + +??? note "Issuer" + + - **O que é?** + Um componente em ferramentas como o Cert-Manager para emitir certificados. + - **Para que serve?** + Gerencia a emissão de certificados TLS automáticos para serviços em Kubernetes.Ele que emite o certificado SSL para os Ingresses poderem criptografar (com HTTPS) as requisições que entram e saem, por exemplo. + + - **Links úteis:** + - [Documentação do Cert-Manager](https://cert-manager.io/docs/) + +--- + +??? note "Kind" + + - **O que é?** + É uma ferramenta para executar clusters Kubernetes locais usando contêineres Docker como "nós" do cluster. + - **Para que serve?** + O Kind foi projetado inicialmente para testar o próprio Kubernetes, mas também pode ser utilizado para desenvolvimento local ou integração contínua (CI). Ele permite criar clusters Kubernetes de forma simples em ambientes locais, facilitando testes e desenvolvimento sem a necessidade de infraestrutura complexa. + + - **Links úteis:** + - [Site oficial](https://kind.sigs.k8s.io/) + +

Imagem 2 - kind - Kubernetes no Docker

 + + ![pods](../assets/pictures/Glossario2.png) + +

Fonte: Kind

+ +--- + +??? note "Kubectl" + + - **O que é?** + O kubectl é uma ferramenta de linha de comando para se comunicar com o plano de controle de um cluster Kubernetes, utilizando a API do Kubernetes. + - **Para que serve?** + Executa operações no Kubernetes, como criar pods e monitorar o status do cluster. + Permite que você interaja com o cluster Kubernetes, realizando operações como criação, gerenciamento e visualização de recursos. Ele busca um arquivo de configuração chamado config no diretório $HOME/.kube, que contém as informações sobre como se conectar ao cluster. + + - **Links úteis:** + - [Documentação oficial - Kubernetes](https://kubernetes.io/docs/reference/kubectl/) + +--- + +??? note "Kubernetes" + - **O que é?** + Uma plataforma de orquestração de contêineres que automatiza a implantação, escala e gerenciamento de aplicativos. É Open Source. + - **Para que serve?** + Garante alta disponibilidade, escalabilidade e monitoramento de aplicações em contêineres. + - **Links úteis:** + - [Documentação oficial](https://kubernetes.io/docs/) + - [GitHub do projeto](https://github.com/kubernetes/kubernetes) + +--- + +??? note "Nginx" + - **O que é?** + É um servidor web HTTP de código aberto que também pode funcionar como proxy reverso, balanceador de carga, cache de conteúdo, servidor proxy TCP/UDP e servidor proxy de e-mail. É amplamente utilizado devido à sua alta performance e capacidade de gerenciar grandes volumes de tráfego. + + - **Para que serve?** + O Nginx é utilizado para servir conteúdos web, gerenciar tráfego de rede e balancear a carga entre servidores, além de atuar como proxy reverso e cache de conteúdo. Ele pode ser usado para melhorar a escalabilidade e a performance de aplicações web, distribuindo eficientemente as requisições entre múltiplos servidores. + Possui um processo principal que gerencia a configuração e vários processos de trabalho que fazem o processamento das requisições. Ele distribui as requisições de forma eficiente, e o número de processos de trabalho pode ser ajustado de acordo com o número de núcleos do processador. + + - **Links úteis:** + - [Documentação oficial](https://nginx.org/en/docs/) + +--- + + +??? note "Lint" + - **O que é?** + Um processo de análise estática do código para identificar erros, problemas de estilo e inconformidades com as melhores práticas de codificação. + - **Para que serve?** + Serve para garantir a qualidade, consistência e a conformidade do código com padrões predefinidos, ajudando a identificar erros de sintaxe, problemas de formatação e más práticas de desenvolvimento antes da execução do código. Ele contribui para a manutenção de um código limpo, legível e eficiente. + - **Links úteis:** + - [Introdução ao linting](https://eslint.org/) + +--- + +??? note "Pods" + - **O que é?** + A menor unidade de computação em Kubernetes, que agrupa um ou mais contêineres. + - **Para que serve?** + Gerencia contêineres que compartilham recursos e atuam como uma única entidade em um cluster. + - **Links úteis:** + - [Sobre Pods](https://kubernetes.io/docs/concepts/workloads/pods/) + +

Imagem 3 - Organização dos Pods em um cluster

 + + ![pods](../assets/pictures/Glossario1.png) + +

Fonte: [Armosec blog](https://www.armosec.io/blog/kubernetes-security-best-practices//)

 + +--- + +??? note "Secrets" + - **O que é?** + São os dados sensíveis que queremos armazenar, gerenciar e utilizar usando o ESO. + +--- + +??? note "Tilt" + - **O que é?** + Uma ferramenta que ajuda no desenvolvimento local para Kubernetes, permitindo visualizar e gerenciar rapidamente alterações em aplicativos. + - **Para que serve?** + Facilita o fluxo de desenvolvimento em Kubernetes, atualizando o estado do cluster automaticamente com base nas mudanças no código. Ele tem uma interface e automatiza muitas coisas que teríamos que fazer manualmente também! + - **Links úteis:** + - [Site oficial](https://tilt.dev/) + - [Documentação](https://docs.tilt.dev/) + +--- + +??? note "yq" + - **O que é?** + Uma ferramenta que vamos instalar para manipular arquivos YAML em linha de comando, semelhante ao jq para JSON. + - **Para que serve?** + Edita, transforma e consulta arquivos YAML. São nos arquivos YAML que vamos escrever como vai ser a configuração das aplicações, serviços ou clusters. + - **Links úteis:** + - [GitHub do yq](https://github.com/mikefarah/yq) + +--- + + + diff --git a/docs/1-Setup/1-Pre_requisitos.md b/docs/1-Setup/1-Pre_requisitos.md index 33df196..a9cf7f2 100644 --- a/docs/1-Setup/1-Pre_requisitos.md +++ b/docs/1-Setup/1-Pre_requisitos.md @@ -1,37 +1,446 @@ # Pré-requisitos -## Instalar golang +Para colaborar com o projeto [External Secrets Operator (ESO)](https://external-secrets.io/latest/), é necessário instalar algumas ferramentas no computador. Neste guia, será explicado o que é cada ferramenta, por que é necessária, a versão recomendada e como instalá-la no sistema operacional correspondente. -- Instalar golang seguindo os passos em [link instalação golang](https://go.dev/doc/install). +## Sistemas Operacionais Suportados -## Instalar helm +Para colaborar com o projeto **External Secrets Operator (ESO)**, é recomendado utilizar sistemas operacionais baseados em Unix, como **Linux** e **macOS**. O ambiente de desenvolvimento do ESO é principalmente voltado para esses sistemas, e muitas das ferramentas e scripts utilizados no desenvolvimento são projetados para funcionar neles. -```bash -curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 +### É possível desenvolver no Windows? -chmod 700 get_helm.sh +É possível utilizar o Windows para o desenvolvimento, mas há considerações importantes a serem feitas. Como o ambiente de desenvolvimento do ESO não é otimizado para o Windows, podem surgir pro blemas de incompatibilidade com ferramentas como **Make**, **Tilt** e scripts shell. Os scripts de automação e comandos presentes no projeto são escritos para ambientes Unix, utilizando bash scripting, o que pode não ser compatível com o Windows sem adaptações. Este tutorial não cobrirá a instalação e configuração de ferramentas no Windows devido à complexidade e falta de testes. -./get_helm.sh -``` +--- -- Outras opções de download checar [link](https://helm.sh/docs/intro/install/). +## Instalar Go (Golang) + +
+ Sobre o Golang +

O que é Go?

+

Go, também conhecido como Golang, é uma linguagem de programação criada pelo Google. É conhecida por ser eficiente, fácil de aprender e excelente para desenvolver aplicativos rápidos e escaláveis.

+

Por que é necessário Go?

+

No projeto External Secrets Operator, Go é utilizado para desenvolver partes fundamentais do código. É necessário para compilar, executar e contribuir com o código-fonte do projeto.

+
+ +
+ Instalação do Golang +

Versão Necessária

+

Versão mínima: Go 1.20 ou superior.

+

Versão recomendada: Go 1.23.3

+
Durante o desenvolvimento deste guia, a versão mais recente do Go é a 1.23.3, a qual funcionou perfeitamente com o projeto External Secrets Operator. Versões anteriores apresentaram falhas nos testes da aplicação. Antes de testar o projeto, verifique sua versão do Go.
+ +

Como Instalar Go

+ +
+ Instalação no Linux +

1. Baixar o arquivo de instalação do Go:

+

Acesse o site oficial ou use o comando abaixo:

+ 
wget https://golang.org/dl/go1.23.3.linux-amd64.tar.gz
+

2. Remover instalações anteriores do Go:

+ 
sudo rm -rf /usr/local/go
+

3. Extrair o novo arquivo do Go para `/usr/local`:

+ 
sudo tar -C /usr/local -xzf go1.23.3.linux-amd64.tar.gz
+

4. Atualizar o PATH adicionando `/usr/local/go/bin`:

+

Edite o arquivo `~/.profile` ou `/etc/profile` e adicione:

+ 
export PATH=$PATH:/usr/local/go/bin
+

Ou execute diretamente no terminal para a sessão atual:

+ 
export PATH=$PATH:/usr/local/go/bin
+

5. Aplicar as alterações do PATH imediatamente:

+ 
source ~/.profile
+

6. Verificar a instalação do Go e se está na versão suportada:

+ 
go version
+
Nota: Para Debian/Ubuntu, é possível instalar o Go utilizando o Snap: + 
sudo snap install --classic go
+
+ +
+ Instalação no macOS +

1. Baixar o arquivo de instalação do Go:

+ Apple macOS (ARM64), macOS 11 ou superior + Apple macOS (Intel), macOS 10.15 ou superior +

2. Executar o arquivo baixado e seguir as instruções de instalação.

+

O pacote instala a distribuição do Go em `/usr/local/go`. O instalador deve adicionar o diretório `/usr/local/go/bin` à variável de ambiente `PATH`. Pode ser necessário reiniciar qualquer sessão aberta do Terminal para que a alteração entre em vigor.

+

3. Verificar a instalação do Go e se está na versão suportada:

+ 
go version
+
+ +

Quaisquer dúvidas ou problemas com a instalação do Go, consulte a documentação oficial.

+ +
+ +## Instalar Helm + +
+ Sobre o Helm +

O que é o Helm?

+

O Helm é um gerenciador de pacotes para Kubernetes, a plataforma que automatiza a implantação, escalonamento e gerenciamento de aplicativos em contêineres.

+ +

Por que é necessário o Helm?

+

No projeto External Secrets Operator, o Helm é utilizado para simplificar a instalação e gerenciamento de aplicações dentro do Kubernetes, automatizando processos complexos de configuração e implantação.

+
+ +
+ Instalação do Helm +

Versão Necessária

+

Versão recomendada: Helm 3 (versão mais recente do Helm 3).

+

Como Instalar o Helm

+ +
+ Instalação no Linux +

1. Baixar o script de instalação:

+ 
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
+

2. Tornar o script executável:

+ 
chmod 700 get_helm.sh
+

3. Executar o script de instalação:

+ 
./get_helm.sh
+

4. Verificar a instalação do Helm:

+ 
helm version
+
+ +
+ Instalação no macOS +

1. Usando o Homebrew:

+ 
brew install helm
+

2. Verificar a instalação do Helm:

+ 
helm version
+
+ +

Para outras opções de instalação e mais detalhes, consulte o guia oficial de instalação do Helm.

+
+ +--- ## Instalar yq -- Instalar binario do yq pelo [link](https://github.com/mikefarah/yq/releases/tag/v4.44.3) e descompactar. +
+ Sobre o yq +

O que é o yq?

+

O yq é uma ferramenta de linha de comando para ler, manipular e escrever arquivos YAML, amplamente utilizados para configurações.

+ +

Por que é necessário o yq?

+

No projeto External Secrets Operator, o yq é utilizado para automatizar a edição de arquivos de configuração YAML, facilitando ajustes e implementações.

+
+ +
+ Instalação do yq +

Versão Necessária

+

Versão recomendada: yq v4.44.3 ou superior.

+ +

Como Instalar o yq

+ +
+ Instalação no Linux +

1. Baixar o binário do yq:

+ 
wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64.tar.gz
+

2. Extrair o arquivo baixado:

+ 
tar xvf yq_linux_amd64.tar.gz
+

3. Mover o binário para /usr/local/bin e tornar executável:

+ 
sudo mv yq_linux_amd64 /usr/local/bin/yq
+ 
sudo chmod +x /usr/local/bin/yq
+

4. Verificar a instalação do yq:

+ 
yq --version
+
+ Alternativa: Caso encontre problemas, instale via Snap: + 
sudo snap install yq
+
+
+ +
+ Instalação no macOS +

1. Usando o Homebrew:

+ 
brew install yq
+

2. Verificar a instalação do yq:

+ 
yq --version
+
+ +

Para outras opções de instalação e mais detalhes, consulte o repositório oficial do yq.

+
+ +--- + +## Instalar jq + +
+ Sobre o jq +

O que é o jq?

+

O jq é uma ferramenta de linha de comando para processar e manipular dados em formato JSON.

+ +

Por que é necessário o jq?

+

No projeto External Secrets Operator, o jq é essencial para trabalhar com dados JSON, permitindo filtrar e transformar informações de forma eficiente.

+
+ +
+ Instalação do jq +

Versão Necessária

+

Versão recomendada: jq 1.6 ou superior.

+ +

Como Instalar o jq

+ +
+ Instalação no Linux +

1. Para Debian/Ubuntu:

+ 
sudo apt-get install jq
+

2. Para Fedora:

+ 
sudo dnf install jq
+

3. Verificar a instalação do jq:

+ 
jq --version
+
+ +
+ Instalação no macOS +

1. Usando o Homebrew:

+ 
brew install jq
+

2. Verificar a instalação do jq:

+ 
jq --version
+
+ +

Para outras opções de instalação e mais detalhes, consulte o site oficial do jq.

+
+ + +--- + +## Instalar Docker + +
+ Sobre o Docker +

O que é o Docker?

+

O Docker é uma plataforma que permite criar, implantar e executar aplicativos em contêineres. Os contêineres permitem empacotar uma aplicação com todas as suas dependências em uma unidade padrão para desenvolvimento e implantação.

+ +

Por que é necessário o Docker?

+

No projeto External Secrets Operator, o Docker é usado para criar imagens de contêineres e executar serviços em ambientes isolados. É essencial para o desenvolvimento, teste e implantação da aplicação dentro de um ambiente Kubernetes.

+
+ +
+ Instalação do Docker +

Como Instalar o Docker

+ +
+ Instalação no Linux +

1. Atualizar os pacotes existentes:

+ 
sudo apt-get update
+

2. Instalar pacotes necessários:

+ sudo apt-get install \ + ca-certificates \ + curl \ + gnupg \ + lsb-release +

3. Adicionar a chave GPG oficial do Docker:

+ 
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
+

4. Adicionar o repositório do Docker:

+ 
echo \
+"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \
+https://download.docker.com/linux/ubuntu \
+$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+
+

5. Instalar o Docker Engine:

+ 
sudo apt-get update
+sudo apt-get install docker-ce docker-ce-cli containerd.io
+

6. Verificar a instalação do Docker:

+ 
sudo docker run hello-world
+
+ +
+ Instalação no macOS +

1. Baixar o Docker Desktop para macOS:

+

Acesse o site oficial e baixe o Docker Desktop:

+ +

2. Instalar o Docker Desktop:

+
    +
  1. Abra o arquivo Docker.dmg.
    2. +
  2. Arraste o ícone do Docker para a pasta Applications.
    3. +
  3. Inicie o Docker Desktop a partir da pasta Applications.
    4. +
+

3. Verificar a instalação do Docker:

+ 
docker --version
+
+ +

Para outras opções de instalação e mais detalhes, consulte a documentação oficial do Docker.

+
+ +
+ Configuração necessária no Docker +

Configurar Docker para Uso sem Root

+

Por padrão, o Docker requer privilégios de superusuário (root) para executar. Para facilitar o uso, é recomendado adicionar o usuário atual ao grupo docker para executar comandos sem sudo.

+ +
+ Passos para configurar o Docker sem root no Linux +

1. Criar o grupo docker (se não existir):

+ 
sudo groupadd docker
+

2. Adicionar o usuário atual ao grupo docker:

+ 
sudo usermod -aG docker $USER
+

3. Aplicar as alterações de grupo sem fazer logout:

+ 
newgrp docker
+

4. Verificar se é possível executar o Docker sem sudo:

+ 
docker run hello-world
+

Se o comando funcionar sem erros, a configuração foi bem-sucedida.

+
+
+ +--- + +## Instalar kubectl + +
+ Sobre o kubectl +

O que é o kubectl?

+

O kubectl é a ferramenta de linha de comando para gerenciar clusters Kubernetes. Permite executar comandos no cluster, gerenciar recursos e depurar aplicações.

+

Por que é necessário o kubectl?

+

No projeto External Secrets Operator, o kubectl é usado para interagir com o cluster Kubernetes local ou remoto, aplicar configurações e verificar o estado dos recursos implantados.

+
+ +
+ Instalação do kubectl +

Versão Necessária

+

Versão compatível com a versão do Kubernetes instalada (geralmente a versão estável mais recente).

+

Como Instalar o kubectl

+
+ Instalação no Linux +

1. Baixar a versão mais recente do kubectl:

+ 
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
+

2. Tornar o binário executável:

+ 
chmod +x kubectl
+

3. Mover o binário para o PATH:

+ 
sudo mv kubectl /usr/local/bin/
+

4. Verificar a instalação do kubectl:

+ 
kubectl version --client
+
+ +
+ Instalação no macOS +

1. Usando o Homebrew:

+ 
brew install kubectl
+

2. Verificar a instalação do kubectl:

+ 
kubectl version --client
+
+ +

Para outras opções de instalação e mais detalhes, consulte a documentação oficial do kubectl.

+
+ +--- + +## Instalar ctlptl e criar um cluster Kind com registro local + +
+ Sobre o ctlptl +

O que é o ctlptl?

+

O ctlptl (Control Plane Tool) é uma ferramenta para gerenciar clusters locais de desenvolvimento Kubernetes. Ele facilita a criação e gerenciamento de clusters como o Kind (Kubernetes in Docker) e a configuração de registros locais de contêiner.

+

Por que é necessário o ctlptl?

+

No projeto External Secrets Operator, o ctlptl é usado para criar e gerenciar um cluster Kubernetes local usando o Kind, além de configurar um registro local de contêiner para armazenar imagens Docker durante o desenvolvimento.

+
+ +
+ Instalação do ctlptl +

Versão Necessária

+

Versão mais recente disponível do ctlptl.

+ +

Como Instalar o ctlptl

+ +
+ Instalação no Linux +

1. Instalar o ctlptl:

+

Use o comando abaixo para instalar a versão 0.8.36 do ctlptl diretamente em /usr/local/bin. Substitua 0.8.36 por outra versão, se necessário.

+ 

+CTLPTL_VERSION="0.8.36"
+curl -fsSL https://github.com/tilt-dev/ctlptl/releases/download/v$CTLPTL_VERSION/ctlptl.$CTLPTL_VERSION.linux.x86_64.tar.gz | sudo tar -xzv -C /usr/local/bin ctlptl
+
+ +

2. Verificar a instalação do ctlptl:

+ 

+ctlptl version
+
+
+ +
+ Instalação via Go +

1. Certifique-se de que o Go está instalado:

+

Se o Go não estiver instalado, siga as instruções no site oficial do Go.

+ +

2. Instale o ctlptl via Go:

+ 

+go install github.com/tilt-dev/ctlptl/cmd/ctlptl@latest
+
+ +

3. Adicione o diretório $GOPATH/bin ao PATH (se necessário):

+ 

+export PATH=$PATH:$(go env GOPATH)/bin
+
+ +

4. Verifique a instalação do ctlptl:

+ 

+ctlptl version
+
+
+ +
+ Instalação no macOS +

1. Usando o Homebrew:

+ 
brew install tilt-dev/tap/ctlptl
+

2. Verificar a instalação do ctlptl:

+ 
ctlptl version
+
+
+ +

Criar um Cluster Kind com Registro Local

+ +
+ Sobre o Kind +

O Kind (Kubernetes in Docker) é uma ferramenta para executar clusters Kubernetes locais usando contêineres Docker como nós do cluster.

+
+ +
+ Como Criar um Cluster Kind com Registro Local +

1. Criar um registro local de contêiner:

+ 
docker run -d --restart=always -p "5000:5000" --name kind-registry registry:2
+

2. Criar um cluster Kind usando o ctlptl e conectá-lo ao registro local:

+ 
ctlptl create cluster kind --registry=kind-registry
+

Isso criará um cluster Kind configurado para usar o registro local em localhost:5000.

+

3. Verificar se o cluster está funcionando:

+ 
kubectl cluster-info --context kind-kind
+

4. Listar os clusters gerenciados pelo ctlptl:

+ 
ctlptl get clusters
+
+ +--- -- Problemas podem ocorrer instalando pelo binário, caso ocorram tente instalar pelo homebrew ou snap com os comandos: +## Instalar Tilt -```bash -brew install yq +
+ Sobre o Tilt +

O que é o Tilt?

+

O Tilt é uma ferramenta que agiliza o desenvolvimento em ambientes Kubernetes. Automatiza a construção, implantação e monitoramento do código, permitindo um ciclo de desenvolvimento mais rápido.

+

Por que é necessário o Tilt?

+

No projeto External Secrets Operator, o Tilt é utilizado para desenvolver e testar alterações no código de forma eficiente, refletindo mudanças quase instantaneamente no ambiente Kubernetes local.

+
-ou +
+ Instalação do Tilt +

Versão Necessária

+ -snap install yq -``` +

Como Instalar o Tilt

-Para mais opções de download checar [repositório oficial yq.](https://github.com/mikefarah/yq) +
+ Instalação no Linux +

1. Baixar e executar o script de instalação:

+ 
curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash
+

2. Verificar a instalação do Tilt:

+ 
tilt version
+
-## Instalar tilt +
+ Instalação no macOS +

1. Usando o Homebrew:

+ 
brew install tilt-dev/tap/tilt
+

2. Verificar a instalação do Tilt:

+ 
tilt version
+
-- Instalar tilt para poder desenvolver e verificar modificações no código seguindo o [link](https://tilt.dev/). \ No newline at end of file +

Para outras opções de instalação e mais detalhes, consulte o guia oficial de instalação do Tilt.

+
\ No newline at end of file diff --git a/docs/1-Setup/3-Configurar_ESO.md b/docs/1-Setup/3-Configurar_ESO.md index a79ca0a..cd41840 100644 --- a/docs/1-Setup/3-Configurar_ESO.md +++ b/docs/1-Setup/3-Configurar_ESO.md @@ -1,5 +1,7 @@ # Configurar o External Secrets Operator +Aqui será feita a configuração e utilização do ESO. Para conseguir acompanhar, é preciso ter seguido os passos de configuração inicial dos [pré requisitos](https://github.com/FGA-GCES/ESO-Documentacao/blob/main/docs/1-Setup/1-Pre_requisitos.md). + ## Clonar o repositório ```bash diff --git a/docs/2-Conectando/Local.md b/docs/2-Conectando/Local.md index 0ce86a7..7f3cffd 100644 --- a/docs/2-Conectando/Local.md +++ b/docs/2-Conectando/Local.md @@ -6,15 +6,21 @@ Aqui será mostrado como criar um POD e fazer a conexão com o ESO. Para fazer t ### Ver pods existentes no namespace "default" +Para executar o comando abaixo, é necessário estar no mesmo repositório onde o seu kubeconfig está. Após fazer essa verificação, execute o comando: + ```bash kubectl get pods --namespace default --kubeconfig kubeconfig ``` +O comando é usado para listar todos os pods no namespace "default" de um cluster Kubernetes. A opção --kubeconfig kubeconfig especifica o arquivo de configuração a ser usado para se conectar ao cluster. ### Criar o Pod definido no arquivo `pod.yaml` +Para executar o comando abaixo, certifique-se de que o caminho para o arquivo `pod.yml` especificado no comando está correto. + ```bash -kubectl apply -f config/pod.yaml --namespace default --kubeconfig kubeconfig +kubectl apply -f ../parte01/pod.yaml --namespace default --kubeconfig kubeconfig ``` +O comando cria ou atualiza os recursos definidos no arquivo `pod.yml` no namespace default, utilizando o arquivo de configuração kubeconfig para se conectar ao cluster. ### Testar acesso ao Postgres diff --git a/docs/4-Common_issues/make-docker_issue.md b/docs/4-Common_issues/make-docker_issue.md new file mode 100644 index 0000000..39ddf58 --- /dev/null +++ b/docs/4-Common_issues/make-docker_issue.md @@ -0,0 +1,29 @@ +# Problemas enquanto executa "make docker.build IMAGE_NAME=external-secrets IMAGE_TAG=latest" + +## Problema 1: + +### ERRO: + test -s /home/meu-user/Área de Trabalho/GCES/external-secrets/bin/tilt || curl -fsSL https://github.com/tilt-dev/tilt/releases/download/v0.33.10/tilt.0.33.10.linux.x86_64.tar.gz | tar -xz -C /home/meu-user/Área de Trabalho/GCES/external-secrets/bin tilt + /bin/bash: linha 1: test: número excessivo de argumentos + tar: de: Não foi encontrado no arquivo-tar + tar: Trabalho/GCES/external-secrets/bin: Não foi encontrado no arquivo-tar + tar: Saindo com status de falha em razão de erros anteriores + make: *** [Makefile:355: de] Erro 2 + + +### Solução e explicação: +Esse "número excessivo de argumentos" era sobre literalmente o nome do diretório "Área de Trabalho". A solução felizmente foi fácil: Colocar a pasta, nesta caso "GCES" em outro diretório como "Documentos" por exemplo. Depois que organizar isso, tente novamente rodar "make docker.build IMAGE_NAME=external-secrets IMAGE_TAG=latest" na pasta do external-secrets no novo diretório. + +--- + +## Problema 2: + +### ERRO: + ./hack/crd.generate.sh: linha 19: jq: comando não encontrado + make: *** [Makefile:136: generate] Erro 127 + + +### Solução e explicação: +Esse erro aconteceu antes da documentação desse repositório estar atualizada, então é improvável que ele volte a acontecer. Se você é sortudo e aconteceu com você, esse comando resolve rapidinho. Depois que ele executar, tente novamente rodar "make docker.build IMAGE_NAME=external-secrets IMAGE_TAG=latest" na pasta do external-secrets. + + sudo apt install jq \ No newline at end of file diff --git a/assets/pictures/ESO_make_issue_1.png b/docs/assets/pictures/ESO_make_issue_1.png similarity index 100% rename from assets/pictures/ESO_make_issue_1.png rename to docs/assets/pictures/ESO_make_issue_1.png diff --git a/assets/pictures/ESO_make_issue_2.png b/docs/assets/pictures/ESO_make_issue_2.png similarity index 100% rename from assets/pictures/ESO_make_issue_2.png rename to docs/assets/pictures/ESO_make_issue_2.png diff --git a/assets/pictures/ESO_make_issue_3.png b/docs/assets/pictures/ESO_make_issue_3.png similarity index 100% rename from assets/pictures/ESO_make_issue_3.png rename to docs/assets/pictures/ESO_make_issue_3.png diff --git a/assets/pictures/ESO_make_issue_4.png b/docs/assets/pictures/ESO_make_issue_4.png similarity index 100% rename from assets/pictures/ESO_make_issue_4.png rename to docs/assets/pictures/ESO_make_issue_4.png diff --git a/assets/pictures/ESO_make_issue_5.png b/docs/assets/pictures/ESO_make_issue_5.png similarity index 100% rename from assets/pictures/ESO_make_issue_5.png rename to docs/assets/pictures/ESO_make_issue_5.png diff --git a/assets/pictures/ESO_make_issue_6.png b/docs/assets/pictures/ESO_make_issue_6.png similarity index 100% rename from assets/pictures/ESO_make_issue_6.png rename to docs/assets/pictures/ESO_make_issue_6.png diff --git a/assets/pictures/ESO_make_issue_7.png b/docs/assets/pictures/ESO_make_issue_7.png similarity index 100% rename from assets/pictures/ESO_make_issue_7.png rename to docs/assets/pictures/ESO_make_issue_7.png diff --git a/assets/pictures/ESO_make_issue_8.png b/docs/assets/pictures/ESO_make_issue_8.png similarity index 100% rename from assets/pictures/ESO_make_issue_8.png rename to docs/assets/pictures/ESO_make_issue_8.png diff --git a/docs/assets/pictures/Glossario1.png b/docs/assets/pictures/Glossario1.png new file mode 100644 index 0000000..dc0a98e Binary files /dev/null and b/docs/assets/pictures/Glossario1.png differ diff --git a/docs/assets/pictures/Glossario2.png b/docs/assets/pictures/Glossario2.png new file mode 100644 index 0000000..69bd9d9 Binary files /dev/null and b/docs/assets/pictures/Glossario2.png differ diff --git a/mkdocs.yml b/mkdocs.yml index 65dd92d..0d10162 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,7 +4,15 @@ site_url: https://eso-docs.github.io/ESO-Documentacao theme: name: material +plugins: + - search + +markdown_extensions: + - admonition + - pymdownx.details + nav: + - Glossário: ./0-Glossario/glossario.md - Setup: - Pre-Requisitos: ./1-Setup/1-Pre_requisitos.md - Configurar-Kubernetes: ./1-Setup/2-Configurar_Kubernetes.md @@ -16,3 +24,4 @@ nav: - Links Importantes: ./3-Links/Links.md - Common_issues: - Problema Específico Debian: ./4-Common_issues/Make_issue.md + - Problemas ao conectar o ESO: ./4-Common_issues/make-docker_issue.md