🧪 Hands-On Labs
Home

Desafio 9: Fleet Management com kro + ACK + ArgoCD

Objetivo

Implementar uma arquitetura hub-spoke para gerenciamento de fleet de clusters EKS usando as três tecnologias juntas: kro para orquestrar a criação dos clusters, ACK para provisionar os recursos AWS, e ArgoCD EKS Capability para bootstrapar e gerenciar os addons via GitOps.

Contexto

Este é o desafio final - ele integra tudo que foi visto nos desafios anteriores numa arquitetura de produção real.

O exemplo oficial do kro demonstra exatamente esse padrão: um cluster de gerenciamento (hub) com as três EKS Capabilities habilitadas provisiona e bootstrapa clusters de workload (spokes) de forma totalmente declarativa e GitOps.

Arquitetura hub-spoke de fleet management com kro, ACK e ArgoCD

Pré-requisitos

  • Conta AWS de gerenciamento (hub) com AWS Identity Center configurado
  • Uma ou mais contas spoke (pode reusar a mesma conta para testes)
  • GitHub account com token para o repositório GitOps
  • Terraform CLI, AWS CLI v2.32.27+, ArgoCD CLI, GitHub CLI

Fase 1: Preparar o repositório GitOps

Configure as variáveis de ambiente, clone o repositório do kro, crie seu repositório GitOps privado no GitHub e popule com os arquivos do exemplo.

Dica: O WORKING_REPO é referenciado em configs do Terraform e GitOps - mantenha o nome padrão eks-cluster-mgmt.

export KRO_REPO_URL="https://github.com/kubernetes-sigs/kro.git"
export WORKING_REPO="eks-cluster-mgmt"
export MGMT_ACCOUNT_ID=$(aws sts get-caller-identity --output text --query Account)
export AWS_REGION="us-east-1"
export WORKSPACE_PATH="$HOME"
export GITHUB_ORG_NAME="seu-usuario-github"

git clone $KRO_REPO_URL $WORKSPACE_PATH/kro
gh repo create $WORKING_REPO --private
gh repo clone $WORKING_REPO $WORKSPACE_PATH/$WORKING_REPO
cp -r $WORKSPACE_PATH/kro/examples/aws/eks-cluster-mgmt/* $WORKSPACE_PATH/$WORKING_REPO/

Edite terraform/hub/terraform.tfvars com seu git_org_name e accounts_ids (use o ID da conta de gerenciamento se não tiver contas spoke separadas).

Se quiser usar múltiplas contas spoke, edite também:

# accounts_ids no tfvars aceita lista de IDs das contas spoke
code $WORKSPACE_PATH/$WORKING_REPO/terraform/hub/terraform.tfvars

Commit e push inicial:

cd $WORKSPACE_PATH/$WORKING_REPO
git add . && git commit -s -m "initial commit" && git push

Fase 2: Provisionar o cluster hub com Terraform

Aplique o Terraform para criar o cluster hub com as IAM Roles necessárias para cada Capability. O Terraform não cria as Capabilities - isso é feito na próxima fase via CLI.

Dica: O install.sh executa terraform init, plan e apply. Revise o plan antes de confirmar - ele cria VPC, EKS cluster, IAM roles e mais.

cd $WORKSPACE_PATH/$WORKING_REPO/terraform/hub
./install.sh

# Exportar outputs para as próximas fases
export CLUSTER_NAME=$(terraform output -raw cluster_name)
export ACK_CONTROLLER_ROLE_ARN=$(terraform output -raw ack_controller_role_arn)
export KRO_CONTROLLER_ROLE_ARN=$(terraform output -raw kro_controller_role_arn)
export ARGOCD_CONTROLLER_ROLE_ARN=$(terraform output -raw argocd_controller_role_arn)

echo "Cluster: $CLUSTER_NAME"
echo "ACK Role: $ACK_CONTROLLER_ROLE_ARN"
echo "kro Role: $KRO_CONTROLLER_ROLE_ARN"
echo "ArgoCD Role: $ARGOCD_CONTROLLER_ROLE_ARN"

Configurar kubectl:

aws eks update-kubeconfig --name $CLUSTER_NAME --region $AWS_REGION
kubectl get nodes

Fase 3: Criar as três EKS Capabilities

Habilite ACK, kro e ArgoCD como EKS Capabilities no cluster hub. Cada uma requer a IAM Role criada pelo Terraform na fase anterior.

Dica: O ArgoCD requer AWS Identity Center configurado na conta. Você precisará do ARN da instância IDC e do ID do usuário que terá acesso admin ao ArgoCD.

# ACK
aws eks create-capability \
  --region ${AWS_REGION} \
  --cluster-name ${CLUSTER_NAME} \
  --capability-name ${CLUSTER_NAME}-ack \
  --type ACK \
  --role-arn ${ACK_CONTROLLER_ROLE_ARN} \
  --delete-propagation-policy RETAIN

# kro
aws eks create-capability \
  --region ${AWS_REGION} \
  --cluster-name ${CLUSTER_NAME} \
  --capability-name ${CLUSTER_NAME}-kro \
  --type KRO \
  --role-arn ${KRO_CONTROLLER_ROLE_ARN} \
  --delete-propagation-policy RETAIN

# ArgoCD - obter dados do Identity Center
export IDC_INSTANCE_ARN='arn:aws:sso:::instance/ssoins-XXXXXXXX'
export IDC_USER_ID='XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
export IDC_REGION='us-east-1'

aws eks create-capability \
  --region ${AWS_REGION} \
  --cluster-name ${CLUSTER_NAME} \
  --capability-name ${CLUSTER_NAME}-argocd \
  --type ARGOCD \
  --role-arn ${ARGOCD_CONTROLLER_ROLE_ARN} \
  --delete-propagation-policy RETAIN \
  --configuration '{
    "argoCd": {
      "awsIdc": {
        "idcInstanceArn": "'${IDC_INSTANCE_ARN}'",
        "idcRegion": "'${IDC_REGION}'"
      },
      "rbacRoleMappings": [{
        "role": "ADMIN",
        "identities": [{
          "id": "'${IDC_USER_ID}'",
          "type": "SSO_USER"
        }]
      }]
    }
  }'

Aguardar todas as Capabilities ficarem ACTIVE:

for cap in ack kro argocd; do
  echo -n "${cap}: "
  aws eks describe-capability \
    --region ${AWS_REGION} \
    --cluster-name ${CLUSTER_NAME} \
    --capability-name ${CLUSTER_NAME}-${cap} \
    --query 'capability.status' --output text
done

Fase 4: Configurar ArgoCD e bootstrapar o hub

Obtenha a URL do ArgoCD, gere um token de acesso e registre o repositório GitOps. Em seguida, aplique o App of Apps que inicia toda a automação GitOps.

Dica: O token é gerado na UI do ArgoCD em Settings → Accounts → admin → Generate New Token. A URL do ArgoCD está disponível no EKS Console em Clusters → Capabilities → Argo CD.

# Obter URL do ArgoCD
export ARGOCD_SERVER=$(aws eks describe-capability \
  --cluster-name ${CLUSTER_NAME} \
  --capability-name ${CLUSTER_NAME}-argocd \
  --query 'capability.configuration.argoCd.serverUrl' \
  --output text --region ${AWS_REGION})

export ARGOCD_SERVER=${ARGOCD_SERVER#https://}
export ARGOCD_OPTS="--grpc-web"

echo "ArgoCD URL: https://${ARGOCD_SERVER}"

Gere o token na UI e configure:

export ARGOCD_AUTH_TOKEN="<token-gerado-na-ui>"
export GITHUB_TOKEN="<seu-github-token>"

# Registrar repositório GitOps
argocd repo add https://github.com/$GITHUB_ORG_NAME/$WORKING_REPO.git \
  --username $GITHUB_ORG_NAME \
  --password $GITHUB_TOKEN \
  --upsert --name github

# Aplicar App of Apps - inicia toda a automação
kubectl apply -f $WORKSPACE_PATH/$WORKING_REPO/terraform/hub/bootstrap/applicationsets.yaml

# Verificar ApplicationSets criados
kubectl get applicationsets -n argocd

Fase 5: Provisionar cluster spoke via kro

Configure as contas spoke com as IAM Roles necessárias para o ACK cross-account, declare o cluster spoke no repositório GitOps e observe o kro + ACK provisionando tudo automaticamente.

Dica: Mesmo usando uma única conta, o script create_ack_workload_roles.sh precisa ser executado - ele cria as roles que o ACK usa para provisionar recursos na conta spoke.

Configurar conta spoke:

export AWS_PROFILE=spoke_account1
cd $WORKSPACE_PATH/$WORKING_REPO/scripts
./create_ack_workload_roles.sh

Declarar o cluster spoke no GitOps:

Edite fleet/kro-values/tenants/tenant1/kro-clusters/values.yaml:

workload-cluster1:
  managementAccountId: "MGMT_ACCOUNT_ID"
  accountId: "SPOKE_ACCOUNT_ID"
  tenant: "tenant1"
  k8sVersion: "1.32"
  workloads: "true"
  gitops:
    addonsRepoUrl: "https://github.com/SEU_USUARIO/eks-cluster-mgmt"
    fleetRepoUrl: "https://github.com/SEU_USUARIO/eks-cluster-mgmt"
    platformRepoUrl: "https://github.com/SEU_USUARIO/eks-cluster-mgmt"
    workloadRepoUrl: "https://github.com/SEU_USUARIO/eks-cluster-mgmt"
cd $WORKSPACE_PATH/$WORKING_REPO
git add . && git commit -s -m "add workload-cluster1" && git push

Acompanhar provisionamento:

# kro orquestrando a criação
kubectl get EksClusterwithvpcs -A

# ACK criando recursos AWS
kubectl get vpcs.ec2.services.k8s.aws -A
kubectl get clusters.eks.services.k8s.aws -A

Quando STATE=ACTIVE, conectar ao spoke e validar addons:

export AWS_PROFILE=spoke_account1
aws eks update-kubeconfig --name workload-cluster1 --region us-east-1
kubectl get pods -A

Conclusão

Você implementou uma plataforma completa de fleet management onde um único cluster hub, com três EKS Capabilities gerenciadas pela AWS, provisiona e bootstrapa clusters de workload de forma totalmente declarativa.

O ciclo completo é GitOps do início ao fim: um git push com a declaração de um novo cluster dispara kro para orquestrar, ACK para provisionar na AWS, e ArgoCD para instalar os addons - sem nenhuma intervenção manual após a configuração inicial.

Essa é a arquitetura que times de Platform Engineering usam para escalar de 5 para 50 clusters sem aumentar a equipe.

Recursos Adicionais

Problemas comuns que clientes encontram nessa arquitetura:

Referência oficial: Amazon EKS cluster management using kro & ACK 

Arquitetura hub-spoke de fleet management com kro, ACK e ArgoCD