Como criar cluster EKS via Terraform usando Blueprint

Criar clusters Kubernetes na AWS pode ser algo complicado para iniciantes, visto que o EKS possui diversos recursos e dependências, até termos o cluster totalmente funcional pode ser complexo e demorado, mas com o EKS Blueprint, esse processo se torna mais simples e eficiente. Neste artigo eu vou explicar de forma bem detalhada como configurar clusters Kubernetes usando o EKS Blueprint via Terraform, integrar ferramentas como Grafana, AlertManager e Prometheus, e mostrar um pouco os benefícios dessa abordagem. Se você deseja aprender a subir clusters Kubernetes com muita facilidade e simplicidade, este material vai ajudar demais!

Além disso, o Makefile utilizado nos labs oferece comandos simples para operações como apply, destroy, e port-forward, otimizando ainda mais o processo.

O que é o EKS Blueprint?

O EKS Blueprint é um framework desenvolvido pela AWS que permite criar clusters Amazon EKS de forma padronizada e repetível usando Terraform. Ele oferece:

• Arquitetura de referência pronta para produção
• Integração nativa com serviços AWS
• Gestão simplificada de addons
• Configurações de segurança predefinidas

Ele permite provisionar e configurar clusters do Amazon EKS de forma rápida e eficiente. Ele abstrai a complexidade da criação de clusters Kubernetes na AWS, trazendo um conjunto de modelos pré-configurados e reutilizáveis, fornecendo uma maneira simples e consistente de configurar e gerenciar seus ambientes.

Prós e contras do EKS Blueprint

Vantagens

• Automação: Reduz a complexidade de configurar manualmente clusters Kubernetes.
• Reutilização: Permite o uso de um mesmo blueprint em diferentes ambientes.
• Rapidez: Provisionamento rápido de clusters Kubernetes na AWS.
• Integração:
  • Integração AWS nativa
  • Facilita a integração de ferramentas como Grafana e Prometheus.
• Consistência: Fornece uma maneira padronizada de configurar e gerenciar clusters.
• Cluster é provisionado com todos os componentes necessários para o EKS operar e recursos extras facilitados ao usar Addons, como o AWS Load Balancer Controller, facilitando a proximidade com um ambiente produtivo esperado no dia a dia de trabalho.

Desvantagens

• Menor flexibilidade em personalizações.
• Curva de aprendizado inicial(que é reduzida demais, seguindo o material do meu artigo).
• Dependência de módulos terceiros.
• Troubleshooting complexo em addons(abstração que ele faz, pode acabar atrapalhando nesses momentos de tshoot)

Manual de uso do EKS via Blueprint

Para efetuar os procedimentos, vamos utilizar os manifestos Terraform existentes no meu repositório:

• https://github.com/fernandomullerjr/cluster-eks-via-blueprint

Como podem ver, temos 2 pastas chamadas 001-eks-blueprint e 002-eks-blueprint-com-grafana, contendo respectivamente:

• Projeto do EKS via Blueprint “comum”
• Projeto EKS via Blueprint + RBAC + Addons(AWS Load Balancer Controller, Metrics Server, EBS CSI DRIVER, Stack do Grafana + Prometheus +AlertManager + Dashboards extras).

Pré-requisitos

Antes de seguir, certifique-se de que você tenha todos os requisitos abaixo:

1. Git instalado.
2. kubectl instalado e configurado.
3. O Terraform esteja instalado na sua máquina: terraform -v
4. Você tenha configurado as credenciais da AWS corretamente.
5. O arquivo terraform.tfstate e os módulos estejam configurados no diretório do projeto.

Clonando o repositório

Vamos clonar o repositório do projeto, contendo os laboratórios e todos os manifestos que precisamos.

Para isto, crie uma pasta ou escolha uma pasta existente e execute o comando abaixo para efetuar o clone e depois acesse o diretório criado:

git clone https://github.com/fernandomullerjr/cluster-eks-via-blueprint.git
cd cluster-eks-via-blueprint

Configuração inicial

Neste primeiro momento, vamos efetuar os procedimentos para subir um EKS sem os addons extras, para isto, acesse a pasta do projeto 001-eks-blueprint:

cd 001-eks-blueprint

A configuração inicial utiliza arquivos locals.tf para definir variáveis essenciais, como região, nome do cluster, versão do cluster e account id. Aqui está um exemplo:

locals {

  #name            = basename(path.cwd)
  name            = "eks-lab"
  region          = data.aws_region.current.name
  cluster_version = "1.30"

  account_id          = "312925778543"
  username_1          = "fernando"
  username_2          = "fernando-devops"

  vpc_cidr = "10.0.0.0/16"
  azs      = slice(data.aws_availability_zones.available.names, 0, 3)

  node_group_name = "managed-ondemand"

  tags = {
    Blueprint  = local.name
    GithubRepo = "github.com/aws-ia/terraform-aws-eks-blueprints"
  }
}

Necessário garantir ajuste nos campos:

• account_id
• username_1
• username_2

Demais campos podem ser personalizados somente se forem necessárias personalizações.

Criando o cluster EKS

Este projeto utiliza um Makefile(clique aqui para saber como funciona um Makefile) para gerenciar a criação e destruição de recursos Terraform de maneira organizada e por etapas. Essa abordagem reduz o risco de problemas relacionados a dependências entre módulos e simplifica a execução dos comandos mais comuns, garantindo um fluxo de trabalho mais eficiente e confiável.

Para facilitar o acompanhamento, o terminal exibe mensagens com cores distintas que indicam o progresso das operações. Mensagens informativas, de sucesso e de alerta são destacadas, proporcionando maior clareza ao usuário e ajudando a identificar rapidamente o estado de cada etapa do processo.

Comandos comuns que ele facilita a execução:

# Criação dos recursos (apply)
apply: apply-vpc apply-eks apply-all
# Destruição dos recursos (destroy)
destroy: destroy-eks destroy-vpc destroy-all

Como já estamos na raíz do projeto 001, basta efetuar o primeiro terraform init e executar o comando make apply, caso você já esteja autenticado na AWS corretamente, e esperar a mágica acontecer:

terraform init
make apply

A criação dos recursos Terraform neste projeto segue um fluxo estruturado em três etapas principais, garantindo maior organização e controle.

1. A primeira etapa é responsável por configurar a infraestrutura de rede (VPC), estabelecendo a base para o ambiente em nuvem.
2. Na sequência, o cluster Kubernetes é provisionado no EKS.
3. Por fim, os recursos adicionais são aplicados, incluindo todas as configurações restantes definidas no Terraform, completando a implementação do ambiente de forma eficiente e organizada.

Resultado esperado:

Finalizou o terraform init, agora ele parte parte a criação dos recursos via Terraform com o make apply:

A cada módulo aplicado, ele vai trazendo mensagens em cores verde ou azul, indicando a etapa que está ocorrendo:

Na imagem acima, finalizando a etapa de criação da VPC e toda estrutura relacionada a ela.

Finalizando a criação do cluster EKS e partindo para a aplicação dos demais recursos:

Ao final do processo, é esperada uma tela igual esta:

E o nosso cluster já está acessível via console na AWS:

Ajustando o Kubeconfig

Depois que todos os recursos forem provisionados com sucesso, o comando a seguir poderá ser usado para atualizar o kubeconfig na sua máquina local e permitir que você interaja com seu cluster EKS usando o kubectl.

aws eks --region <REGION> update-kubeconfig --name <CLUSTER_NAME> --alias <CLUSTER_NAME>

Na saída do make apply, ao final ele traz alguns outputs, sendo um deles o configure_kubectl, contendo um comando aws para ajuste do kubeconfig, já ajustado para o nome do cluster que criamos. No meu caso havia ficado assim:

aws eks --region us-east-1 update-kubeconfig --name eks-lab

Com isto, já conseguimos utilizar comandos diretos no nosso cluster EKS:

kubectl get nodes
kubectl get pods -A

Com isto, temos um cluster EKS totalmente operacional e provisionado com 1 comando praticamente.

Destruindo o cluster EKS

Para destruir o cluster EKS e remover ele e todos os recursos que são criados junto com ele, basta executar o comando make destroy:

make destroy

Na pasta do projeto, temos 2 arquivos contendo detalhes dos comandos make existentes e os comandos terraform por debaixo dos panos:

• https://github.com/fernandomullerjr/cluster-eks-via-blueprint/blob/main/001-eks-blueprint/README.md
• https://github.com/fernandomullerjr/cluster-eks-via-blueprint/blob/main/001-eks-blueprint/comandos.md

Tanto o appy quanto o destroy são realizados de maneira faseada, conforme detalhes contidos em cada um dos materiais acima.

Resultado após executar o make destroy:

Ele começa removendo o cluster EKS e os seus nodes.

Finalizando a destruição do cluster, é iniciada a remoção da VPC e os recursos atrelados:

Depois é iniciada a remoção de demais recursos, caso alguma outra dependência tenha sido gerada:

A destruição dos recursos Terraform é executada de forma ordenada e inversa à criação, para evitar conflitos entre dependências.

O processo começa pela remoção do cluster Kubernetes no EKS, garantindo que os serviços e workloads associados sejam encerrados corretamente.

Em seguida, a infraestrutura de rede (VPC) é desmontada, liberando os recursos alocados.

Por fim, os demais recursos adicionais são eliminados, concluindo a limpeza do ambiente de maneira sistemática e eficiente.

Criando o cluster EKS com Addons

Além do projeto que utilizamos nas etapas anteriores, existe uma pasta chamada 002-eks-blueprint-com-grafana, onde temos o Projeto 002 contendo o mesmo EKS Blueprint, mas agora adicionando o módulo de kubernetes_addons, contendo alguns recursos que podem ajudar, como o AWS Load Balancer Controller e EBS Driver, além da stack do Grafana com Prometheus e Dashboards extras.

Este projeto utiliza Terraform para criar um Cluster EKS com base no EKS Blueprint, garantindo uma implementação eficiente e padronizada. A configuração inclui a estrutura de RBAC necessária, aplicando os manifestos adequados para gerenciar permissões e acessos dentro do cluster. Além disso, são configurados dois usuários, um com privilégios de root e outro como usuário comum, ambos como administradores. Isso é feito por meio do recurso “Teams”, que simplifica o controle de acesso ao cluster.

A stack kube-prometheus-stack é instalada automaticamente, abrangendo ferramentas essenciais como Prometheus, Grafana, AlertManager e Grafana Dashboards. Diversos dashboards úteis são adicionados ao Grafana, oferecendo uma visão abrangente para monitorar e gerenciar o cluster Kubernetes. Esses recursos otimizam a administração e melhoram a visibilidade do desempenho e da saúde do ambiente.

Recursos recomendados

• Instâncias EC2 t3.medium (mínimo)
  • Ponto de atenção: neste EKS com os Addons, utilizamos uma família de EC2 que não é contemplada pelo free tier da AWS.
• 50GB EBS por node
• Load Balancer para ingress(se for expor para internet)

Para iniciar a criação do cluster EKS com a Stack Grafana, acesse a pasta 002-eks-blueprint-com-grafana a partir da raíz do repositório:

cd 002-eks-blueprint-com-grafana

Editar o arquivo locals.tf conforme necessário:

locals {

  #name            = basename(path.cwd)
  name            = "eks-lab"
  region          = data.aws_region.current.name
  cluster_version = "1.30"

  account_id = "552925778543"
  username_1 = "fernando"
  username_2 = "fernando-devops"

  vpc_cidr = "10.0.0.0/16"
  azs      = slice(data.aws_availability_zones.available.names, 0, 3)

  node_group_name   = "managed-ondemand"
  node_group_name_2 = "managed-ondemand-2"

  tags = {
    Blueprint  = local.name
    GithubRepo = "github.com/aws-ia/terraform-aws-eks-blueprints"
  }
}

Seguir com a execução do terraform init e make apply, após ajustado o arquivo locals.tf:

terraform init
make apply

Vai ser iniciada a criação da VPC e todos os recursos atrelados:

Ele vai efetuar a criação do cluster EKS e já vai criar todos os addons, além da configuração da Stack do Grafana, Prometheus e os Dashboards adicionais:

Autenticando no cluster EKS e verificando os Pods em execução, podemos validar se todos os Pods estão funcionando dentro do esperado:

aws eks --region us-east-1 update-kubeconfig --name eks-lab
kubectl get pods -A

Através da console AWS, podemos visualizar o nosso cluster e os recursos que fazem parte dele:

Acessando o Grafana

O comando make grafana simplifica o processo de executar o port-forward para acessar a interface do Grafana via navegador. Com apenas este comando, o mapeamento da porta é realizado automaticamente, permitindo que você visualize os dashboards do Grafana de forma prática e rápida.

Após executar o comando, o Grafana estará disponível no endereço http://localhost:8080.

Caso esteja utilizando uma máquina virtual, WSL ou container Docker, é importante verificar o endereço IP correspondente para acessar o Grafana a partir da sua máquina hospedeira. Essa abordagem torna o acesso mais direto, facilitando a administração e monitoramento do cluster.

Por padrão, este Grafana vem com os seguintes usuário e senha:

admin
prom-operator

Após entrar com o usuário e senha, é mostrada a tela inicial do Grafana:

Acessando o menu a esquerda e indo em Dashboards, podemos ver que os Dashboards extras foram carregados com sucesso:

Acessando o Dashboard “Kubernetes / Compute Resources / Cluster“:

Acessando o Prometheus

O comando make prometheus facilita a execução do port-forward para acessar a interface do Prometheus diretamente no navegador. Com este comando, o mapeamento da porta é configurado automaticamente, permitindo que você visualize e gerencie métricas de forma ágil e eficiente.

make prometheus

Após a execução, o Prometheus estará disponível no endereço http://localhost:9191, caso esteja utilizando uma máquina virtual, WSL ou container Docker, é essencial identificar o endereço IP correto para acessar a aplicação a partir da máquina hospedeira. :

Executando uma query, para validar que o Prometheus está conseguindo buscar as informações no nosso cluster EKS:

Esse processo simplifica o monitoramento e garante acesso rápido às informações coletadas pelo Prometheus.

Addons

Os addons são extensões que podem ser adicionadas a um cluster Kubernetes para fornecer funcionalidades adicionais. O EKS Blueprint fornece suporte para addons, como o Cluster Autoscaler e o CoreDNS.

Após seguir com os passos do Projeto 002 e subir o cluster EKS com toda a stack do Grafana e demais complementos, podemos ver via console a existência do EBS CSI DRIVER na aba Add-ons:

O EKS Blueprint suporta diversos addons cruciais para operação do cluster:

module "kubernetes_addons" {
  source = "github.com/aws-ia/terraform-aws-eks-blueprints?ref=v4.32.1/modules/kubernetes-addons"
  
  eks_cluster_id = module.eks_blueprints.eks_cluster_id
  
  # Addons Essenciais
  enable_amazon_eks_vpc_cni    = true
  enable_amazon_eks_coredns    = true
  enable_amazon_eks_kube_proxy = true
  
  # Addons de Monitoramento
  enable_aws_load_balancer_controller = true
  enable_metrics_server              = true
  enable_aws_cloudwatch_metrics      = true
  enable_kube_prometheus_stack       = true
  
  # Addons de Storage
  enable_aws_ebs_csi_driver = true
  
  # Addons de Segurança
  enable_cert_manager = true
  enable_external_dns = true
  
  depends_on = [
    module.eks_blueprints
  ]
}

Para o nosso projeto, foi utilizada a configuração abaixo para o bloco que trata dos Addons:

module "kubernetes_addons" {
  source = "github.com/aws-ia/terraform-aws-eks-blueprints?ref=v4.32.1/modules/kubernetes-addons"

  eks_cluster_id = module.eks_blueprints.eks_cluster_id

  enable_aws_load_balancer_controller  = true
  enable_amazon_eks_aws_ebs_csi_driver = true
  enable_metrics_server                = true
  enable_kube_prometheus_stack         = true # (Opcional) O namespace para instalar a release.

  kube_prometheus_stack_helm_config = {
    name = "kube-prometheus-stack" # (Obrigatório) Nome da release.
    #repository = "https://prometheus-community.github.io/helm-charts" # (Opcional) URL do repositório onde localizar o chart solicitado.
    chart     = "kube-prometheus-stack" # (Obrigatório) Nome do chart a ser instalado.
    namespace = "kube-prometheus-stack" # (Opcional) O namespace para instalar a release.
    values = [templatefile("${path.module}/values-stack.yaml", {
      operating_system = "linux"
    })]
  }

  depends_on = [
    module.eks_blueprints
  ]
}

Configuração de timeouts

Para evitar problemas durante a instalação, em alguns casos podem ser necessários ajustes no timeout, para que todos os recursos sejam provisionados conforme o esperado:

timeouts {
  create = "30m"
  delete = "30m"
}

helm_config = {
  timeout = 1800  # 30 minutos
  retry   = 2
}

Verificação de status dos addons

# Listar addons instalados
kubectl get pods -A | grep -E 'aws-load-balancer|metrics-server|prometheus'

# Verificar status de instalação
kubectl get deployments -A

# Checar logs
kubectl logs -n kube-system -l app=aws-load-balancer-controller

Destruindo o cluster EKS com Addons

Para efetuar o destroy do cluster EKS com Addons, o procedimento é exatamente o mesmo que o EKS com Blueprint “comum”, basta executar o comando make destroy e aguardar os comandos serem executados:

make destroy

Aqui a diferença é que o Terraform vai remover os addons instalados, garantindo que dependências relacionadas ao cluster EKS, como AWS Load Balancer Controller, EBS CSI DRIVER, Prometheus, Grafana e Metrics Server, sejam removidas antes de deletar o cluster EKS.

Conclusão

O EKS Blueprint é uma ótima opção para provisionar e configurar clusters Kubernetes na AWS de forma rápida e eficiente. Com a integração do Grafana, é possível monitorar seu cluster em tempo real e garantir a disponibilidade e o desempenho dos seus aplicativos. Além disso, o EKS Blueprint fornece suporte para addons, permitindo que você estenda as funcionalidades do cluster de acordo com suas necessidades. No entanto, é importante ter em mente as particularidades e os prós e contras do EKS Blueprint antes de começar a usá-lo em produção.

Se o objetivo é gerenciar um ambiente AWS-native, escalável e padronizado, o EKS Blueprints é uma escolha sólida. Para testes locais onde não existe necessidade de comunicação ou integração com recursos AWS, vá de Minikube, e se precisar de um controle completo, opte por um módulo comum no Terraform. A decisão depende diretamente do equilíbrio entre simplicidade, flexibilidade e escalabilidade necessárias ao seu projeto.

Imagem de capa de gstudioimagen no Freepik