**Ajudar a melhorar esta página**
Para contribuir com este guia de usuário, escolha o link **Editar esta página no GitHub**, disponível no painel direito de cada página.
# Implantação de recursos da AWS usando o Kubernetes com o AWS Controllers for Kubernetes (ACK)
O AWS Controllers for Kubernetes (ACK) permite definir e gerenciar recursos de serviços da AWS diretamente do Kubernetes. Com o AWS Controllers for Kubernetes (ACK), é possível gerenciar recursos de workloads e de infraestrutura de nuvem por meio de recursos personalizados do Kubernetes, juntamente com as workloads das aplicações, usando APIs e ferramentas conhecidas do Kubernetes.
Com as funcionalidades do EKS, o ACK é totalmente gerenciado pela AWS, o que remove a necessidade de instalar, fazer a manutenção e escalar os controladores do ACK em seus clusters.
## Funcionamento do ACK
O ACK converte especificações de recursos personalizados do Kubernetes em chamadas de API da AWS. Quando você cria, atualiza ou exclui um recurso personalizado do Kubernetes que representa um recurso de serviço da AWS, o ACK realiza as chamadas de API da AWS necessárias para criar, atualizar ou excluir o recurso da AWS.
Cada recurso da AWS compatível com o ACK conta com sua própria definição de recurso personalizado (CRD, na sigla em inglês), que define o esquema da API do Kubernetes para especificar a configuração. Por exemplo, o ACK fornece CRDs para o S3, incluindo buckets, políticas de bucket e outros recursos do S3.
O ACK realiza a reconciliação contínua entre o estado atual dos seus recursos da AWS e o estado desejado especificado nos recursos personalizados do Kubernetes Se um recurso se desviar do estado desejado, o ACK detecta essa divergência e executa ações corretivas para restabelecer o alinhamento. As alterações nos recursos do Kubernetes são refletidas imediatamente no estado dos recursos da AWS, enquanto a detecção passiva de desvios e a correção de alterações diretamente nos recursos da AWS podem demorar até dez horas (o período de ressincronização), embora normalmente ocorram muito antes.
**Exemplo de manifesto de recurso do bucket do S3**
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-ack-bucket
spec:
name: my-unique-bucket-name
```
Ao aplicar esse recurso personalizado ao cluster, o ACK cria um bucket do Amazon S3 na sua conta, se ele ainda não existir. As alterações posteriores nesse recurso, por exemplo, a definição de uma camada de armazenamento diferente da camada padrão ou a adição de uma política, serão aplicadas ao recurso do S3 na AWS. Quando esse recurso é excluído do cluster, o bucket do S3 na AWS é excluído por padrão.
## Benefícios do ACK
O ACK disponibiliza o gerenciamento de recursos da AWS de forma nativa no Kubernetes, permitindo que você gerencie recursos da AWS com as mesmas APIs e ferramentas do Kubernetes usadas pelas suas aplicações. Essa abordagem unificada simplifica o fluxo de trabalho de gerenciamento da infraestrutura, eliminando a necessidade de alternar entre diferentes ferramentas ou de aprender sistemas distintos de infraestrutura como código. Seus recursos da AWS são definidos declarativamente em manifestos do Kubernetes, permitindo fluxos de trabalho de GitOps e práticas de infraestrutura como código que se integram perfeitamente aos processos de desenvolvimento existentes.
O ACK realiza a reconciliação contínua entre o estado desejado e o estado atual dos recursos da AWS, corrigindo desvios e garantindo a consistência em toda a infraestrutura. Essa reconciliação contínua garante que alterações imperativas realizadas de forma externa aos recursos da AWS sejam revertidas automaticamente para o estado definido em sua configuração, preservando a integridade da infraestrutura como código. É possível configurar o ACK para gerenciar recursos em diversas contas e regiões da AWS, possibilitando arquiteturas complexas em várias contas sem a necessidade de ferramentas adicionais.
Para organizações que estão no processo de migração de outras ferramentas de gerenciamento de infraestrutura, o ACK oferece suporte à adoção de recursos, permitindo que você traga recursos da AWS existentes para o gerenciamento do ACK sem precisar recriá-los. O ACK ainda disponibiliza recursos somente para leitura, permitindo a observação de recursos da AWS sem permissão para modificá-los, além de anotações para, opcionalmente, reter recursos da AWS mesmo quando o recurso do Kubernetes é excluído do cluster.
Para saber mais informações e começar a usar a funcionalidade do EKS para o ACK, consulte [Conceitos do ACK](ack-concepts.md) e [Considerações sobre o ACK para o EKS](ack-considerations.md).
## Serviços da AWS compatíveis
O ACK oferece suporte a uma ampla variedade de serviços da AWS, incluindo, mas não se limitando a:
+ Amazon EC2
+ Amazon S3
+ Amazon RDS
+ Amazon DynamoDB
+ Amazon ElastiCache
+ Amazon EKS
+ Amazon SQS
+ Amazon SNS
+ AWS Lambda
+ IAM da AWS
Todos os serviços da AWS listados como disponíveis para o público geral na origem são compatíveis com a funcionalidade do EKS para o ACK. Consulte a [lista completa de serviços da AWS compatíveis](https://aws-controllers-k8s.github.io/community/docs/community/services/) para obter mais detalhes.
## Integração com outras funcionalidades gerenciadas do EKS
O ACK pode ser integrado a outras funcionalidades gerenciadas do EKS.
+ **Argo CD**: use o Argo CD para gerenciar a implantação de recursos do ACK em diversos clusters, possibilitando fluxos de trabalho de GitOps para a infraestrutura da AWS.
+ Embora o ACK aproveite os benefícios de GitOps quando combinado com o Argo CD, ele não depende de integração com o Git.
+ **kro (Kube Resource Orchestrator)**: use o kro para combinar recursos complexos a partir de recursos do ACK, criando abstrações de nível superior que simplificam o gerenciamento de recursos.
+ Com o kro, é possível criar recursos personalizados compostos que definem tanto recursos do Kubernetes quanto recursos da AWS. Esses recursos personalizados podem ser usados pelos membros da equipe para implantar aplicações complexas de forma rápida.
## Conceitos básicos do ACK
Para começar a usar a funcionalidade do EKS para o ACK:
1. Crie e configure um perfil do IAM da funcionalidade com as permissões necessárias para que o ACK gerencie recursos da AWS em seu nome.
1. [Crie um recurso da funcionalidade do ACK](create-ack-capability.md) em seu cluster do EKS por meio do Console da AWS, da AWS CLI ou da ferramenta de infraestrutura como código de sua preferência.
1. Aplique os recursos personalizados do Kubernetes no cluster para começar a gerenciar os recursos da AWS diretamente no Kubernetes.
# Criação de uma funcionalidade do ACK
Este capítulo explica como criar uma funcionalidade do ACK no cluster do Amazon EKS.
## Pré-requisitos
Antes de criar uma funcionalidade do ACK, certifique-se de ter:
+ Um cluster do Amazon EKS
+ Um perfil do IAM para a funcionalidade com permissões para o ACK gerenciar recursos da AWS
+ Permissões do IAM suficientes para criar recursos de funcionalidades em clusters de EKS
+ A ferramenta de CLI apropriada instalada e configurada, ou o acesso ao console do EKS
Para obter instruções sobre como criar o perfil do IAM para a funcionalidade, consulte [Perfil do IAM para a funcionalidade do Amazon EKS](capability-role.md).
**Importante**
O ACK é uma funcionalidade de gerenciamento de infraestrutura que concede a capacidade de criar, modificar e excluir recursos da AWS. Trata-se de uma funcionalidade de escopo de administrador que deve ser controlada cuidadosamente. Qualquer pessoa com permissão para criar recursos do Kubernetes no cluster pode, efetivamente, criar recursos da AWS por meio do ACK, sujeito às permissões do perfil do IAM para a funcionalidade. O perfil do IAM para a funcionalidade que você fornece determina quais recursos da AWS o ACK pode criar e gerenciar. Para obter orientações sobre como criar um perfil apropriado com permissões de privilégio mínimo, consulte [Perfil do IAM para a funcionalidade do Amazon EKS](capability-role.md) e [Considerações sobre segurança para funcionalidades do EKS](capabilities-security.md).
## Escolha da ferramenta
É possível criar uma funcionalidade do ACK por meio do Console de gerenciamento da AWS, da AWS CLI ou do eksctl:
+ [Criação de uma funcionalidade do ACK por meio do Console](ack-create-console.md): use o Console para obter uma experiência guiada
+ [Criação de uma funcionalidade do ACK por meio da AWS CLI](ack-create-cli.md): use a AWS CLI para obter scripts e automação
+ [Criação de uma funcionalidade do ACK por meio do eksctl](ack-create-eksctl.md): use o eksctl para obter uma experiência nativa do Kubernetes
## O que ocorre durante a criação de uma funcionalidade do ACK
Ao criar uma funcionalidade do ACK:
1. O EKS cria o serviço da funcionalidade do ACK e o configura para monitorar e gerenciar recursos no cluster
1. As definições de recursos personalizados (CRDs, na sigla em inglês) são instaladas no cluster
1. Uma entrada de acesso é criada automaticamente para seu perfil de funcionalidade do IAM com políticas de entrada de acesso específicas de recursos que concedem permissões básicas do Kubernetes (consulte [Considerações sobre segurança para funcionalidades do EKS](capabilities-security.md))
1. A funcionalidade assume o perfil do IAM para a funcionalidade, que foi fornecido por você
1. O ACK começa a monitorar os recursos personalizados no cluster
1. O status da funcionalidade é alterado de `CREATING` para `ACTIVE`
Assim que estiver ativa, será possível criar recursos personalizados do ACK no cluster para gerenciar recursos da AWS
**nota**
A entrada de acesso criada automaticamente inclui a `AmazonEKSACKPolicy` que concede permissões ACK para gerenciar recursos da AWS. Alguns recursos do ACK que fazem referência a segredos do Kubernetes (como bancos de dados do RDS com senhas) exigem políticas adicionais de entrada de acesso. Para saber mais sobre entradas de acesso e como configurar permissões adicionais, consulte [Considerações sobre segurança para funcionalidades do EKS](capabilities-security.md).
## Próximas etapas
Após criar a funcionalidade do ACK:
+ [Conceitos do ACK](ack-concepts.md): entenda os conceitos do ACK e comece a usar o serviço com os recursos da AWS
+ [Conceitos do ACK](ack-concepts.md): saiba mais sobre reconciliação, exportações de campos e padrões de adoção de recursos
+ [Configuração das permissões do ACK](ack-permissions.md): configure permissões do IAM e padrões para várias contas
# Criação de uma funcionalidade do ACK por meio do Console
Este tópico descreve como criar uma funcionalidade do AWS Controllers for Kubernetes (ACK) usando o Console de gerenciamento da AWS.
## Criação da funcionalidade do ACK
1. Abra o console do Amazon EKS em https://console.aws.amazon.com/eks/home\$1/clusters.
1. Selecione o nome do cluster para abrir a página de detalhes do cluster.
1. Escolha a guia **Funcionalidades**.
1. No painel de navegação à esquerda, escolha **AWS Controllers for Kubernetes (ACK)**.
1. Escolha **Criar uma funcionalidade do AWS Controllers for Kubernetes**.
1. No **perfil da funcionalidade do IAM**:
+ Se você já tiver um perfil da funcionalidade do IAM, selecione-o no menu suspenso
+ Se a criação de um perfil for necessária, escolha **Criar perfil de administrador**
Isso abre o console do IAM em uma nova guia com a política de confiança preenchida previamente e a política gerenciada `AdministratorAccess`. É possível desmarcar esta política e adicionar outras permissões, se preferir.
Após criar o perfil, retorne ao console do EKS e o perfil será selecionado automaticamente.
**Importante**
A política `AdministratorAccess` sugerida concede permissões abrangentes e destina-se a simplificar as etapas iniciais do uso do serviço. Para ambientes de produção, substitua essa política por uma personalizada que forneça somente as permissões exigidas pelos serviços específicos da AWS que você pretende gerenciar usando o ACK. Para obter orientações sobre como criar políticas de privilégio mínimo, consulte [Configuração das permissões do ACK](ack-permissions.md) e [Considerações sobre segurança para funcionalidades do EKS](capabilities-security.md).
1. Escolha **Criar**.
O processo de criação da funcionalidade é iniciado.
## Verificação da ativação da funcionalidade
1. Na guia **Funcionalidades**, visualize o status da funcionalidade do ACK.
1. Aguarde até que o status mude de `CREATING` para `ACTIVE`.
1. Assim que estiver com o status ativo, a funcionalidade estará pronta para uso.
Para obter informações sobre os status das funcionalidades e sobre a solução de problemas, consulte [Como trabalhar com recursos de funcionalidade](working-with-capabilities.md).
## Verificação da disponibilidade de recursos personalizados
Após a funcionalidade estar ativa, verifique se os recursos personalizados do ACK estão disponíveis no cluster.
**Utilizar o console**
1. Navegue até o cluster no console do Amazon EKS
1. Escolha a guia **Recursos**
1. Escolha **Extensões**
1. Escolha **CustomResourceDefinitions**
Você deverá visualizar várias CRDs listadas para os recursos da AWS.
**Uso do kubectl**
```
kubectl api-resources | grep services.k8s.aws
```
Você deverá visualizar várias APIs listadas para os recursos da AWS.
**nota**
A funcionalidade do AWS Controllers for Kubernetes instalará diversas CRDs para vários tipos de recursos da AWS.
## Próximas etapas
+ [Conceitos do ACK](ack-concepts.md): entenda os conceitos do ACK e comece a usar o serviço
+ [Configuração das permissões do ACK](ack-permissions.md): configure as permissões do IAM para outros serviços da AWS
+ [Como trabalhar com recursos de funcionalidade](working-with-capabilities.md): gerencie os recursos da funcionalidade do ACK
# Criação de uma funcionalidade do ACK por meio da AWS CLI
Este tópico descreve como criar uma funcionalidade do AWS Controllers for Kubernetes (ACK) usando a AWS CLI.
## Pré-requisitos
+ **AWS CLI**: versão `2.12.3` ou em versões posteriores. Para verificar a versão, execute `aws --version`. Para obter mais informações, consulte [Instalação](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) no Guia do Usuário da Interface de Linha de Comando AWS.
+ ** `kubectl` ** – uma ferramenta de linha de comando para trabalhar com clusters do Kubernetes. Para obter mais informações, consulte [Configurar o `kubectl` e o `eksctl`](install-kubectl.md).
## Etapa 1: criação de um perfil da funcionalidade do IAM
Crie um arquivo de política de confiança:
```
cat > ack-trust-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "capabilities.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}
EOF
```
Crie o perfil do IAM:
```
aws iam create-role \
--role-name ACKCapabilityRole \
--assume-role-policy-document file://ack-trust-policy.json
```
Anexe a política gerenciada `AdministratorAccess` ao perfil:
```
aws iam attach-role-policy \
--role-name ACKCapabilityRole \
--policy-arn arn:aws:iam::aws:policy/AdministratorAccess
```
**Importante**
A política `AdministratorAccess` sugerida concede permissões abrangentes e destina-se a simplificar as etapas iniciais do uso do serviço. Para ambientes de produção, substitua essa política por uma personalizada que forneça somente as permissões exigidas pelos serviços específicos da AWS que você pretende gerenciar usando o ACK. Para obter orientações sobre como criar políticas de privilégio mínimo, consulte [Configuração das permissões do ACK](ack-permissions.md) e [Considerações sobre segurança para funcionalidades do EKS](capabilities-security.md).
## Etapa 2: criação da funcionalidade do ACK
Crie o recurso da funcionalidade do ACK no cluster. Substitua *region-code* pela região AWS em que seu cluster se encontra e substitua *my-cluster* pelo nome do seu cluster.
```
aws eks create-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-ack \
--type ACK \
--role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/ACKCapabilityRole \
--delete-propagation-policy RETAIN
```
O comando é concluído de imediato, mas a funcionalidade demora algum tempo para se tornar ativa, conforme o EKS cria a infraestrutura e os componentes necessários para a funcionalidade. O EKS instalará as definições de recursos personalizados do Kubernetes relacionadas a essa funcionalidade no cluster durante o processo de criação.
**nota**
Caso ocorra um erro indicando a inexistência do cluster ou falta de permissões, verifique o seguinte:
Se o nome do cluster está correto
Se a AWS CLI está configurada para a região correta
Se você tem as permissões do IAM obrigatórias
## Etapa 3: verificação da ativação da funcionalidade
Aguarde até que a funcionalidade se torne ativa. Substitua *region-code* pela região AWS em que seu cluster se encontra e substitua *my-cluster* pelo nome do seu cluster.
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-ack \
--query 'capability.status' \
--output text
```
A funcionalidade estará pronta assim que o status mostrar `ACTIVE`. Não prossiga para a próxima etapa até que o status seja `ACTIVE`.
Também é possível visualizar os detalhes completos da funcionalidade:
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-ack
```
## Etapa 4: verificação da disponibilidade de recursos personalizados
Após a funcionalidade estar ativa, verifique se os recursos personalizados do ACK estão disponíveis no cluster:
```
kubectl api-resources | grep services.k8s.aws
```
Você deverá visualizar várias APIs listadas para os recursos da AWS.
**nota**
A funcionalidade do AWS Controllers for Kubernetes instalará diversas CRDs para vários tipos de recursos da AWS.
## Próximas etapas
+ [Conceitos do ACK](ack-concepts.md): entenda os conceitos do ACK e comece a usar o serviço
+ [Configuração das permissões do ACK](ack-permissions.md): configure as permissões do IAM para outros serviços da AWS
+ [Como trabalhar com recursos de funcionalidade](working-with-capabilities.md): gerencie os recursos da funcionalidade do ACK
# Criação de uma funcionalidade do ACK por meio do eksctl
Este tópico descreve como criar uma funcionalidade do AWS Controllers for Kubernetes (ACK) usando o eksctl.
**nota**
Para realizar as etapas seguintes, você deve estar utilizando o eksctl na versão `0.220.0` ou em versões posteriores. Para verificar a versão, execute `eksctl version`.
## Etapa 1: criação de um perfil da funcionalidade do IAM
Crie um arquivo de política de confiança:
```
cat > ack-trust-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "capabilities.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}
EOF
```
Crie o perfil do IAM:
```
aws iam create-role \
--role-name ACKCapabilityRole \
--assume-role-policy-document file://ack-trust-policy.json
```
Anexe a política gerenciada `AdministratorAccess` ao perfil:
```
aws iam attach-role-policy \
--role-name ACKCapabilityRole \
--policy-arn arn:aws:iam::aws:policy/AdministratorAccess
```
**Importante**
A política `AdministratorAccess` sugerida concede permissões abrangentes e destina-se a simplificar as etapas iniciais do uso do serviço. Para ambientes de produção, substitua essa política por uma personalizada que forneça somente as permissões exigidas pelos serviços específicos da AWS que você pretende gerenciar usando o ACK. Para obter orientações sobre como criar políticas de privilégio mínimo, consulte [Configuração das permissões do ACK](ack-permissions.md) e [Considerações sobre segurança para funcionalidades do EKS](capabilities-security.md).
**Importante**
Esta política concede permissões para o gerenciamento de buckets do S3 com `"Resource": "*"`, o que permite operações em todos os buckets do S3.
Para uso em ambientes de produção: \$1 Restrinja o campo `Resource` a ARNs de buckets específicos ou padrões de nomes \$1 Use chaves de condição do IAM para limitar o acesso por etiquetas de recurso \$1 Conceda apenas as permissões mínimas necessárias para o seu caso de uso
Para uso com outros serviços da AWS, consulte [Configuração das permissões do ACK](ack-permissions.md).
Anexe a política à função:
```
aws iam attach-role-policy \
--role-name ACKCapabilityRole \
--policy-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):policy/ACKS3Policy
```
## Etapa 2: criação da funcionalidade do ACK
Crie a funcionalidade do ACK por meio do eksctl. Substitua *region-code* pela região AWS em que seu cluster se encontra e substitua *my-cluster* pelo nome do seu cluster.
```
eksctl create capability \
--cluster [.replaceable]`my-cluster` \
--region [.replaceable]`region-code` \
--name ack \
--type ACK \
--role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/ACKCapabilityRole \
--ack-service-controllers s3
```
**nota**
O sinalizador `--ack-service-controllers` é opcional. Se omitido, o ACK habilita todos os controladores disponíveis. Para otimizar a performance e a segurança, recomendamos habilitar somente os controladores necessários. É possível definir vários controladores ao mesmo tempo: `--ack-service-controllers s3,rds,dynamodb`
O comando é executado de forma imediata, mas a funcionalidade demora algum tempo para se tornar ativa.
## Etapa 3: verificação da ativação da funcionalidade
Verifique o status da funcionalidade:
```
eksctl get capability \
--cluster [.replaceable]`my-cluster` \
--region [.replaceable]`region-code` \
--name ack
```
A funcionalidade estará pronta assim que o status mostrar `ACTIVE`.
## Etapa 4: verificação da disponibilidade de recursos personalizados
Após a funcionalidade estar ativa, verifique se os recursos personalizados do ACK estão disponíveis no cluster:
```
kubectl api-resources | grep services.k8s.aws
```
Você deverá visualizar várias APIs listadas para os recursos da AWS.
**nota**
A funcionalidade do AWS Controllers for Kubernetes instalará diversas CRDs para vários tipos de recursos da AWS.
## Próximas etapas
+ [Conceitos do ACK](ack-concepts.md): entenda os conceitos do ACK e comece a usar o serviço
+ [Configuração das permissões do ACK](ack-permissions.md): configure as permissões do IAM para outros serviços da AWS
+ [Como trabalhar com recursos de funcionalidade](working-with-capabilities.md): gerencie os recursos da funcionalidade do ACK
# Conceitos do ACK
O ACK gerencia recursos da AWS usando APIs do Kubernetes, por meio da reconciliação contínua entre o estado desejado definido em seus manifestos e o estado atual na AWS. Ao criar ou atualizar um recurso personalizado do Kubernetes, o ACK faz as chamadas de API da AWS necessárias para criar ou modificar o recurso correspondente na AWS, monitorando-o em seguida para detectar desvios e atualizando o status no Kubernetes para refletir o estado atual. Esta abordagem possibilita o gerenciamento da infraestrutura por meio de ferramentas e fluxos de trabalho conhecidos do Kubernetes, ao mesmo tempo em que garante a conformidade entre o cluster e a AWS.
Este tópico explica os conceitos fundamentais sobre como o ACK realiza a gestão de recursos da AWS por meio de APIs do Kubernetes.
## Conceitos básicos do ACK
Após criar a funcionalidade do ACK (consulte [Criação de uma funcionalidade do ACK](create-ack-capability.md)), você pode começar a gerenciar recursos da AWS no seu cluster usando manifestos do Kubernetes.
Como exemplo, crie este manifesto de bucket do S3 em `bucket.yaml`, definindo um nome exclusivo para o seu bucket.
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-test-bucket
namespace: default
spec:
name: my-unique-bucket-name-12345
```
Aplique o manifesto:
```
kubectl apply -f bucket.yaml
```
Verifique o status:
```
kubectl get bucket my-test-bucket
kubectl describe bucket my-test-bucket
```
Verifique se o bucket foi criado na AWS:
```
aws s3 ls | grep my-unique-bucket-name-12345
```
Exclua o recurso do Kubernetes:
```
kubectl delete bucket my-test-bucket
```
Verifique se o bucket foi excluído da AWS:
```
aws s3 ls | grep my-unique-bucket-name-12345
```
O bucket não deve mais aparecer na lista, demonstrando que o ACK gerencia todo o ciclo de vida dos recursos da AWS.
Para obter mais informações sobre os conceitos básicos do ACK, consulte [Getting Started with ACK](https://aws-controllers-k8s.github.io/community/docs/user-docs/getting-started/).
## Ciclo de vida e reconciliação de recursos
O ACK usa um ciclo contínuo de reconciliação para assegurar que os recursos da AWS estejam em conformidade com o estado desejado estabelecido nos manifestos do Kubernetes.
**Funcionamento da reconciliação**:
1. Você cria ou atualiza um recurso personalizado do Kubernetes (por exemplo, um bucket do S3)
1. O ACK detecta a alteração e compara o estado desejado com o estado real na AWS
1. Se houver divergência, o ACK faz chamadas de API da AWS para reconciliar a diferença
1. O status do recurso no Kubernetes é atualizado pelo ACK para refletir o estado atual
1. Esse ciclo se repete de forma contínua, geralmente em intervalos de algumas horas
O processo de reconciliação ocorre ao criar um novo recurso no Kubernetes, ao atualizar o campo `spec` de um recurso já existente ou caso o ACK detecte divergências na AWS causadas por alterações manuais realizadas fora do controle do ACK. Além disso, o ACK executa a reconciliação periódica com um intervalo de sincronização de dez horas. As alterações nos recursos do Kubernetes acionam a reconciliação imediata, enquanto a detecção passiva de desvios em alterações de recursos da AWS em suas versões originais ocorre durante a sincronização periódica.
Ao seguir o exemplo de introdução acima, o ACK executa estas etapas:
1. Verifica se o bucket existe na AWS
1. Se não existir, faz a chamada `s3:CreateBucket`
1. Atualiza o status no Kubernetes com o ARN e o estado do bucket
1. Continua o monitoramento para detectar desvios
Para saber mais sobre como o ACK funciona, consulte [ACK Reconciliation](https://aws-controllers-k8s.github.io/community/docs/user-docs/reconciliation/).
## Condições de status
Os recursos do ACK usam condições de status para informar seus estados. Compreender essas condições ajuda você a solucionar problemas e entender a integridade do recurso.
+ **Ready**: indica que o recurso está pronto para uso (condição padrão do Kubernetes).
+ **ACK.ResourceSynced**: indica que a especificação do recurso corresponde ao estado do recurso na AWS.
+ **ACK.Terminal**: indica a ocorrência de um erro irrecuperável.
+ **ACK.Adopted**: indica que o recurso foi importado de um recurso da AWS já existente, não sendo uma nova criação.
+ **ACK.Recoverable**: indica um erro passível de recuperação que pode ser solucionado sem alterar a especificação.
+ **ACK.Advisory**: fornece informações consultivas sobre o recurso.
+ **ACK.LateInitialized**: indica se a inicialização tardia dos campos foi concluída.
+ **ACK.ReferencesResolved**: Indica se todos os campos de `AWSResourceReference` foram resolvidos.
+ **ACK.IAMRoleSelected**: Indica se um IAMRoleSelector foi selecionado para gerenciar este recurso.
Verifique o status do recurso:
```
# Check if resource is ready
kubectl get bucket my-bucket -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}'
# Check for terminal errors
kubectl get bucket my-bucket -o jsonpath='{.status.conditions[?(@.type=="ACK.Terminal")]}'
```
Status de exemplo:
```
status:
conditions:
- type: Ready
status: "True"
lastTransitionTime: "2024-01-15T10:30:00Z"
- type: ACK.ResourceSynced
status: "True"
lastTransitionTime: "2024-01-15T10:30:00Z"
- type: ACK.Terminal
status: "True"
ackResourceMetadata:
arn: arn:aws:s3:::my-unique-bucket-name
ownerAccountID: "111122223333"
region: us-west-2
```
Para saber mais sobre o status e as condições do ACK, consulte [ACK Conditions](https://aws-controllers-k8s.github.io/community/docs/user-docs/conditions/).
## Políticas de exclusão
A política de exclusão do ACK controla o que acontece com os recursos da AWS quando você exclui o recurso do Kubernetes.
**Exclusão (padrão)**
O recurso da AWS é excluído quando você exclui o recurso do Kubernetes. Este é o comportamento padrão.
```
# No annotation needed - this is the default
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: temp-bucket
spec:
name: temporary-bucket
```
A exclusão deste recurso exclui o bucket do S3 na AWS.
**Manter**
O recurso da AWS é mantido quando você exclui o recurso do Kubernetes:
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: important-bucket
annotations:
services.k8s.aws/deletion-policy: "retain"
spec:
name: production-data-bucket
```
A exclusão deste recurso o remove do Kubernetes, mas mantém o bucket do S3 na AWS.
A política `retain` é útil para bancos de dados de produção que devem existir além do ciclo de vida do recurso do Kubernetes, recursos compartilhados que são usados por diversas aplicações, recursos com dados importantes que não devem ser excluídos acidentalmente ou casos de uso em que o ACK é usado apenas para configurar o recurso e, depois, o libera de volta para o gerenciamento manual.
Para saber mais sobre a política de exclusão do ACK, consulte [ACK Deletion Policy](https://aws-controllers-k8s.github.io/community/docs/user-docs/deletion-policy/).
## Adoção de recursos
A adoção permite que você traga recursos existentes da AWS para o gerenciamento do ACK, sem a necessidade de recriá-los.
Situações para o uso da adoção:
+ Ao migrar a infraestrutura atual para ser gerenciada pelo ACK
+ Ao recuperar recursos da AWS que ficaram “órfãos” em caso de exclusão acidental do recurso no Kubernetes
+ Ao importar recursos que foram gerados por outras ferramentas, como Terraform ou CloudFormation
Funcionamento da adoção:
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: existing-bucket
annotations:
services.k8s.aws/adoption-policy: "adopt-or-create"
spec:
name: my-existing-bucket-name
```
Ao criar este recurso:
1. O ACK verifica se um bucket com esse nome existe na AWS
1. Se encontrado, o ACK o adota (sem realizar chamadas de API para criação)
1. O ACK importa as configurações atuais da AWS
1. O ACK atualiza o status no Kubernetes para refletir o estado real
1. A partir daí, novas alterações seguem o fluxo de reconciliação comum
Após a adoção, o gerenciamento de recursos funciona como em qualquer outro recurso do ACK. Isso significa que remover o recurso do Kubernetes apagará o recurso na AWS, exceto se a política de deleção estiver configurada como `retain`.
Ao adotar recursos, o recurso da AWS já deve existir e o ACK precisa de permissões de leitura para localizá-lo. A política `adopt-or-create` faz a adoção se o recurso for localizado ou a criação automática se ele não existir. Isso é útil quando você deseja um fluxo de trabalho declarativo que funcione independentemente da existência prévia do recurso.
Para saber mais sobre a adoção de recursos no ACK, consulte [ACK Resource Adoption](https://aws-controllers-k8s.github.io/community/docs/user-docs/adopted-resource/).
## Recursos entre contas e entre regiões
O ACK pode gerenciar recursos em diferentes contas e regiões da AWS usando um único cluster.
**Anotações para recursos entre regiões**
É possível especificar a região de um recurso da AWS utilizando uma anotação:
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: eu-bucket
annotations:
services.k8s.aws/region: eu-west-1
spec:
name: my-eu-bucket
```
Você também pode especificar a região de todos os recursos da AWS criados em um determinado namespace:
**Anotações para namespace**
Define uma região padrão para todos os recursos dentro de um namespace:
```
apiVersion: v1
kind: Namespace
metadata:
name: production
annotations:
services.k8s.aws/default-region: us-west-2
```
Os recursos criados sob este namespace seguirão essa região, exceto se houver uma anotação específica no próprio recurso que a sobreponha.
**Entre contas**
Use os seletores de perfil do IAM para vincular perfis específicos do IAM a determinados namespaces:
```
apiVersion: services.k8s.aws/v1alpha1
kind: IAMRoleSelector
metadata:
name: target-account-config
spec:
arn: arn:aws:iam::444455556666:role/ACKTargetAccountRole
namespaceSelector:
names:
- production
```
Os recursos criados no namespace mapeado usam automaticamente o perfil especificado.
Para saber mais sobre os seletores de perfil do IAM, consulte [ACK Cross-Account Resource Management](https://aws-controllers-k8s.github.io/docs/guides/cross-account). Para obter detalhes sobre a configuração entre contas, consulte [Configuração das permissões do ACK](ack-permissions.md).
## Tratamento de erros e comportamento de novas tentativas
O ACK trata automaticamente os erros transitórios, repetindo operações com falhas.
Estratégia de novas tentativas:
+ Erros transitórios (por exemplo, limite de taxa, problemas temporários no serviço e permissões insuficientes) acionam automaticamente novas tentativas
+ O recuo exponencial é usado para não sobrecarregar as APIs da AWS
+ O número máximo de tentativas varia de acordo com o tipo de erro
+ Erros permanentes (por exemplo parâmetros inválidos e conflitos de nome de recurso) não geram novas tentativas
Verifique os detalhes do erro no status do recurso utilizando `kubectl describe`:
```
kubectl describe bucket my-bucket
```
Verifique as condições de status em busca de mensagens de erro, eventos que apresentam tentativas de reconciliação recentes e o campo `message`, que detalha o motivo das falhas nas condições de status. Erros comuns incluem permissões do IAM insuficientes, conflitos de nomes de recursos na AWS, valores de configuração inválidos na `spec` e cotas de serviço da AWS excedidas.
Para solucionar erros comuns, consulte [Solução de problemas em funcionalidades do ACK](ack-troubleshooting.md).
## Composição de recursos com o kro
Para compor e conectar diversos recursos do ACK entre si, empregue a funcionalidade do EKS para o kro (Kube Resource Orchestrator). Com o kro, você define grupos de recursos de forma declarativa, permitindo a troca de configurações entre os recursos para simplificar o gerenciamento de arquiteturas complexas.
Para obter exemplos detalhados de como criar composições personalizadas de recursos com recursos do ACK, consulte [Conceitos do kro](kro-concepts.md).
## Próximas etapas
+ [Considerações sobre o ACK para o EKS](ack-considerations.md): acesse padrões específicos do EKS e estratégias de integração
# Configuração das permissões do ACK
O ACK precisa de permissões do IAM para realizar a criação e o gerenciamento de recursos da AWS em seu nome. Este tópico explica como o IAM funciona com o ACK e fornece orientações sobre como configurar permissões para diferentes casos de uso.
## Funcionamento do IAM com o ACK
O ACK usa perfis do IAM para se autenticar na AWS e executar ações em seus recursos. Existem duas maneiras de fornecer permissões ao ACK:
**Perfil da funcionalidade**: consiste no perfil do IAM que você fornece ao criar a funcionalidade do ACK. Este perfil é usado por padrão para todas as operações do ACK.
**Seletores de perfil do IAM**: consistem em perfis adicionais do IAM que podem ser mapeados para namespaces ou recursos específicos. Esses perfis substituem o perfil da funcionalidade para recursos dentro de seu escopo.
Quando o ACK precisa criar ou gerenciar um recurso, ele determina qual perfil do IAM deve usar:
1. Verifica se um “IAMRoleSelector” corresponde ao namespace do recurso
1. Se uma correspondência for encontrada, assume esse perfil do IAM
1. Caso contrário, usa o perfil da funcionalidade
Esta abordagem possibilita um gerenciamento de permissões flexível, desde configurações simples de perfil único até configurações complexas de diversas contas e várias equipes.
## Conceitos básicos: configuração simples de permissões
Para ambientes de desenvolvimento, testes ou casos de uso simples, você pode adicionar todas as permissões de serviço necessárias diretamente ao perfil da funcionalidade.
Essa abordagem é ideal quando:
+ Você está começando a usar o ACK
+ Todos os recursos estão na mesma conta da AWS
+ Uma única equipe gerencia todos os recursos do ACK
+ Você confia que todos os usuários do ACK tenham as mesmas permissões
## Prática recomendada para ambientes de produção: seletores de perfil do IAM
Para ambientes de produção, use os seletores de perfil do IAM para implementar o acesso de privilégio mínimo e o isolamento em nível de namespace.
Ao usar seletores de perfil do IAM, o perfil da funcionalidade precisa apenas das permissões `sts:AssumeRole` e `sts:TagSession` para assumir os perfis específicos de cada serviço. Não é necessário adicionar nenhuma permissão de serviço da AWS (como S3 ou RDS) ao perfil da funcionalidade em si, pois essas permissões são concedidas aos perfis individuais do IAM que o perfil da funcionalidade assume.
**Escolha do modelo de permissões**:
Use **permissões diretas**, com a adição de permissões de serviço ao perfil da funcionalidade, quando:
+ Você está começando a usar o serviço e deseja a configuração mais simples
+ Todos os recursos estão na mesma conta que o cluster
+ Você tem requisitos de permissão administrativos para todo o cluster
+ Todas as equipes podem compartilhar as mesmas permissões
Use **seletores de perfil do IAM** quando:
+ Gerenciar recursos em várias contas da AWS
+ Diferentes equipes ou namespaces precisarem de permissões distintas
+ Você precisar de controle de acesso granular por namespace
+ Você desejar seguir as práticas de segurança de privilégio mínimo
É possível começar com permissões diretas e migrar para os seletores de perfil do IAM posteriormente, conforme suas necessidades evoluem.
**Vantagens de usar seletores de perfil do IAM em ambientes produção:**
+ **Privilégio mínimo**: cada namespace recebe apenas as permissões de que necessita
+ **Isolamento de equipes**: a Equipe A não pode usar as permissões da Equipe B por engano
+ **Auditoria facilitada**: mapeamento claro de qual namespace usa cada perfil
+ **Suporte entre contas**: necessário para gerenciar recursos em várias contas
+ **Separação de responsabilidades**: diferentes serviços ou ambientes usam perfis distintos
### Configuração básica do seletor de perfil do IAM
**Etapa 1: criação de um perfil do IAM específico para o serviço**
Crie um perfil do IAM com permissões para serviços específicos da AWS:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:*"
],
"Resource": "*"
}
]
}
```
Configure a política de confiança para permitir que o perfil da funcionalidade o assuma:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/ACKCapabilityRole"
},
"Action": ["sts:AssumeRole", "sts:TagSession"]
}
]
}
```
**Etapa 2: concessão da permissão AssumeRole ao perfil da funcionalidade**
Adicione permissão ao perfil da funcionalidade para assumir o perfil específico do serviço:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["sts:AssumeRole", "sts:TagSession"],
"Resource": "arn:aws:iam::111122223333:role/ACK-S3-Role"
}
]
}
```
**Etapa 3: criação do IAMRoleSelector**
Mapeie o perfil do IAM para um namespace:
```
apiVersion: services.k8s.aws/v1alpha1
kind: IAMRoleSelector
metadata:
name: s3-namespace-config
spec:
arn: arn:aws:iam::111122223333:role/ACK-S3-Role
namespaceSelector:
names:
- s3-resources
```
**Etapa 4: criação de recursos no namespace mapeado**
Os recursos no namespace `s3-resources` usam automaticamente o perfil especificado:
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-bucket
namespace: s3-resources
spec:
name: my-production-bucket
```
## Gerenciamento de várias contas
Use seletores de perfil do IAM para gerenciar recursos em várias contas da AWS.
**Etapa 1: criação do perfil do IAM entre contas**
Na conta de destino (444455556666), crie um perfil que confie no perfil da funcionalidade da conta de origem:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/ACKCapabilityRole"
},
"Action": ["sts:AssumeRole", "sts:TagSession"]
}
]
}
```
Anexe permissões específicas de serviço a este perfil.
**Etapa 2: concessão da permissão AssumeRole**
Na conta de origem (111122223333), permita que o perfil da funcionalidade assuma o perfil da conta de destino:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["sts:AssumeRole", "sts:TagSession"],
"Resource": "arn:aws:iam::444455556666:role/ACKTargetAccountRole"
}
]
}
```
**Etapa 3: criação do IAMRoleSelector**
Mapeie o perfil entre contas para um namespace:
```
apiVersion: services.k8s.aws/v1alpha1
kind: IAMRoleSelector
metadata:
name: production-account-config
spec:
arn: arn:aws:iam::444455556666:role/ACKTargetAccountRole
namespaceSelector:
names:
- production
```
**Etapa 4: criação de recursos**
Os recursos no namespace `production` são criados na conta de destino:
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-bucket
namespace: production
spec:
name: my-cross-account-bucket
```
## Tags de sessão
A funcionalidade ACK do EKS define automaticamente as tags de sessão em todas as solicitações de API da AWS. Essas tags permitem ter controle de acesso e auditoria, identificando a origem de cada solicitação.
### Tags de sessão disponíveis
As tags de sessão a seguir estão incluídas em todas as chamadas de API da AWS feitas pelo ACK:
| Chave de tag | Descrição |
| --- | --- |
| `eks:eks-capability-arn` | O ARN da funcionalidade EKS que faz a solicitação |
| `eks:kubernetes-namespace` | O namespace do Kubernetes do recurso gerenciado |
| `eks:kubernetes-api-group` | O grupo do recurso de API do Kubernetes (por exemplo, `s3.services.k8s.aws`) |
### Uso de tags de sessão para controle de acesso
É possível usar essas tags de sessão nas condições da política do IAM para restringir quais recursos o ACK pode gerenciar. Isso fornecerá uma camada adicional de segurança além dos seletores de perfil do IAM baseados em namespace.
**Exemplo: restringir por namespace**
Permitir que o ACK crie buckets do S3 somente quando a solicitação for originada do namespace `production`:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:CreateBucket",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:PrincipalTag/eks:kubernetes-namespace": "production"
}
}
}
]
}
```
**Exemplo: restringir por funcionalidade**
Permitir ações somente a partir de um recurso do ACK específico:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:PrincipalTag/eks:eks-capability-arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/ack/my-ack"
}
}
}
]
}
```
**nota**
As tags de sessão são uma diferença do ACK autogerenciado, que não define essas tags por padrão. Isso permite um controle de acesso mais granular com o recurso gerenciado.
## Padrões avançados de seletores de perfil do IAM
Para obter configurações avançadas, incluindo selecionadores de rótulos, mapeamento de perfis específicos para recursos e exemplos adicionais, consulte a [documentação relacionada ao IRSA para o ACK](https://aws-controllers-k8s.github.io/community/docs/user-docs/irsa/).
## Próximas etapas
+ [Conceitos do ACK](ack-concepts.md): compreenda os conceitos do ACK e o ciclo de vida dos recursos
+ [Conceitos do ACK](ack-concepts.md): saiba mais sobre as políticas de adoção e exclusão de recursos
+ [Considerações sobre segurança para funcionalidades do EKS](capabilities-security.md): compreenda as práticas recomendadas de segurança para as funcionalidades
# Considerações sobre o ACK para o EKS
Este tópico aborda considerações importantes para o uso da funcionalidade do EKS para o ACK, incluindo a configuração do IAM, os padrões para várias contas e a integração com outras funcionalidades do EKS.
## Padrões de configuração do IAM
A funcionalidade do ACK usa um perfil de funcionalidade do IAM para se autenticar na AWS. Escolha o padrão do IAM mais adequado às suas necessidades.
### Simples: um único perfil de funcionalidade
Para ambientes de desenvolvimento, testes ou casos de uso simples, atribua todas as permissões necessárias diretamente ao perfil de funcionalidade.
**Quando utilizar**:
+ Conceitos básicos do ACK
+ Implantações em uma única conta
+ Todos os recursos são gerenciados por uma única equipe
+ Ambientes de desenvolvimento e de teste
**Exemplo**: adicione permissões do S3 e do RDS ao seu perfil de funcionalidade com condições de marcação de recursos:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:*"],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": ["us-west-2", "us-east-1"]
}
}
},
{
"Effect": "Allow",
"Action": ["rds:*"],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": ["us-west-2", "us-east-1"]
},
}
}
]
}
```
Este exemplo restringe as operações do S3 e do RDS a regiões específicas e requer que os recursos do RDS tenham uma etiqueta `ManagedBy: ACK`.
### Produção: seletores de perfil do IAM
Para ambientes de produção, use os seletores de perfil do IAM para implementar o acesso de privilégio mínimo e o isolamento em nível de namespace.
**Quando utilizar**:
+ Ambientes de produção
+ Clusters gerenciados por várias equipes
+ Gerenciamento de recursos em várias contas
+ Requisitos de segurança de privilégio mínimo
+ Diferentes serviços que necessitam de permissões distintas
**Benefícios**:
+ Cada namespace recebe apenas as permissões de que necessita
+ Isolamento de equipes, portanto, a Equipe A não pode usar as permissões da Equipe B
+ Auditoria e conformidade facilitadas
+ Obrigatório para o gerenciamento de recursos entre contas
Para obter a configuração detalhada do seletor de perfil do IAM, consulte [Configuração das permissões do ACK](ack-permissions.md).
## Integração com outras funcionalidades do EKS
### GitOps com Argo CD
Empregue a funcionalidade do EKS para o Argo CD a fim de implantar recursos do ACK de repositórios do Git, permitindo fluxos de trabalho do GitOps para o gerenciamento de infraestrutura.
**Considerações**:
+ Armazene os recursos do ACK junto aos manifestos da aplicação para um GitOps de ponta a ponta
+ Organize por ambiente, serviço ou tipo de recurso com base na estrutura da sua equipe
+ Use a sincronização automática do Argo CD para reconciliação contínua
+ Habilite a supressão para remover automaticamente recursos excluídos
+ Considere o uso de padrões hub-and-spoke para o gerenciamento da infraestrutura de vários clusters
O GitOps oferece trilhas de auditoria, funcionalidades de reversão e gerenciamento declarativo da infraestrutura. Para saber mais sobre o Argo CD, consulte [Como trabalhar com o Argo CD](working-with-argocd.md).
### Composição de recursos com o kro
Use a funcionalidade do EKS para o kro (Kube Resource Orchestrator) para compor vários recursos do ACK em abstrações de nível superior e APIs personalizadas.
**Situações para o uso do kro com o ACK**:
+ Criação de padrões reutilizáveis para pilhas de infraestrutura comuns (banco de dados \$1 backup \$1 monitoramento)
+ Desenvolvimento de plataformas de autoatendimento com APIs simplificadas para as equipes destinadas ao trabalho com APIs aplicação
+ Gerenciamento de dependências de recursos e transferência de valores entre recursos (como o ARN de um bucket do S3 para uma função do Lambda)
+ Padronização das configurações de infraestrutura entre as equipes
+ Redução da complexidade ao ocultar detalhes de implementação atrás de recursos personalizados
**Padrões de exemplo**:
+ Pilha da aplicação: bucket do S3 \$1 fila do SQS \$1 configuração de notificação
+ Configuração do banco de dados: instância do RDS \$1 grupo de parâmetros \$1 grupo de segurança \$1 segredos
+ Rede: VPC \$1 sub-redes \$1 tabelas de rotas \$1 grupos de segurança
O kro gerencia a ordenação de dependências, a propagação de status e o gerenciamento do ciclo de vida dos recursos compostos. Para saber mais sobre o kro, consulte [Conceitos do kro](kro-concepts.md).
## Organização dos recursos
Organize os recursos do ACK usando namespaces do Kubernetes e etiquetas de recursos da AWS para obter melhor gerenciamento, controle de acesso e rastreamento de custos.
### Organização de namespaces
Use namespaces do Kubernetes para a separação lógica de recursos do ACK por ambiente (por exemplo, produção, preparação e desenvolvimento), equipe (como plataforma, dados e ML) ou aplicação.
**Benefícios**:
+ RBAC com escopo de namespace para controle de acesso
+ Definição de regiões padrão por namespace usando anotações
+ Gerenciamento e limpeza de recursos facilitados
+ Separação lógica alinhada à estrutura organizacional
### Marcação de recursos
A funcionalidade ACK do EKS aplica automaticamente as tags padrão a todos os recursos da AWS que ele cria. Essas tags diferem do ACK autogerenciado e fornecem rastreabilidade aprimorada.
**Tags padrão aplicadas pela funcionalidade**:
| Chave de tag | Descrição |
| --- | --- |
| `eks:controller-version` | A versão do controlador ACK |
| `eks:kubernetes-namespace` | O namespace do Kubernetes do recurso ACK |
| `eks:kubernetes-resource-name` | O nome do recurso do Kubernetes |
| `eks:kubernetes-api-group` | O grupo de API do Kubernetes (por exemplo, `s3.services.k8s.aws`) |
| `eks:eks-capability-arn` | O ARN da funcionalidade ACK do EKS |
**nota**
O ACK autogerenciado usa tags padrão diferentes: `services.k8s.aws/controller-version` e `services.k8s.aws/namespace`. As tags da funcionalidade usam o prefixo `eks:` para manter a consistência com outros recursos do EKS.
**Tags adicionais recomendadas**:
Adicione tags personalizadas para alocação de custos, rastreamento de propriedade e fins organizacionais.
+ Ambiente (por exemplo, produção, preparação e desenvolvimento)
+ Propriedade da equipe ou do departamento
+ Centro de custo para alocação de faturamento
+ Nome da aplicação ou do serviço
## Migração de outras ferramentas de infraestrutura como código
Muitas organizações estão encontrando valor na padronização do Kubernetes além da orquestração de suas workloads. Migrar a infraestrutura e o gerenciamento de recursos da AWS para o ACK permite que você padronize o gerenciamento da infraestrutura utilizando as APIs do Kubernetes em conjunto com as workloads da aplicação.
**Benefícios da padronização no Kubernetes para infraestrutura**:
+ **Fonte única de verdade**: gerencie tanto aplicações quanto infraestrutura no Kubernetes, permitindo uma prática de GitOps de ponta a ponta
+ **Ferramentas unificadas**: as equipes usam recursos e ferramentas do Kubernetes em vez de aprender diversas ferramentas e frameworks
+ **Reconciliação consistente**: o ACK reconcilia continuamente os recursos da AWS assim como o Kubernetes faz com as workloads, detectando e corrigindo desvios em comparação com ferramentas imperativas
+ **Composições nativas**: com o kro e o ACK juntos, referencie recursos da AWS diretamente nos manifestos da aplicação e de recursos, transferindo strings de conexão e ARNs entre os recursos
+ **Operações simplificadas**: um único ambiente de gerenciamento para implantações, reversões e observabilidade em todo o sistema
O ACK permite a adoção de recursos da AWS já existentes sem recriá-los, possibilitando migrações sem tempo de inatividade provenientes do CloudFormation, do Terraform ou de recursos externos ao cluster.
**Adote um recurso existente**:
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: existing-bucket
annotations:
services.k8s.aws/adoption-policy: "adopt-or-create"
spec:
name: my-existing-bucket-name
```
Após a adoção, o recurso passa a ser gerenciado pelo ACK e pode ser atualizado por meio de manifestos do Kubernetes. É possível realizar a migração de forma incremental, adotando recursos conforme necessário, enquanto mantém as ferramentas de IaC existentes para outros recursos.
O ACK também oferece suporte a recursos somente de leitura. Para recursos gerenciados por outras equipes ou ferramentas que você deseja referenciar, mas não modificar, combine a adoção com a política de exclusão `retain` e conceda permissões somente de leitura no IAM. Isso permite que as aplicações localizem infraestruturas compartilhadas (por exemplo, VPCs, perfis de funcionalidade do IAM e chaves do KMS) por meio das APIs do Kubernetes, sem o risco de modificações acidentais.
Para obter mais informações sobre a adoção de recursos, consulte [Conceitos do ACK](ack-concepts.md).
## Políticas de exclusão
As políticas de exclusão controlam o que acontece com os recursos da AWS quando você exclui o recurso correspondente no Kubernetes. Escolha a política adequada com base no ciclo de vida do recurso e em seus requisitos operacionais.
### Exclusão (padrão)
O recurso da AWS é excluído quando você exclui o recurso correspondente no Kubernetes. Isso mantém a consistência entre o cluster e a AWS, garantindo que não ocorra o acúmulo de recursos.
**Situações para o uso da exclusão**:
+ Ambientes de desenvolvimento e de teste nos quais a limpeza é importante
+ Recursos efêmeros vinculados ao ciclo de vida da aplicação (por exemplo, bancos de dados de teste e buckets temporários)
+ Recursos que não devem existir sem a aplicação (por exemplo filas do SQS e clusters do ElastiCache)
+ Otimização de custos com a limpeza automática de recursos não utilizados
+ Ambientes gerenciados com GitOps, nos quais a remoção do recurso no Git deve excluir a infraestrutura
A política de exclusão padrão alinha-se ao modelo declarativo do Kubernetes, ou seja, o que está no cluster corresponde ao que existe na AWS.
### Reter
O recurso da AWS é mantido quando você exclui o recurso correspondente no Kubernetes. Esta opção protege dados críticos e permite que os recursos permaneçam ativos mesmo após a remoção da representação no Kubernetes.
**Situações para o uso da retenção**:
+ Bancos de dados de produção com dados críticos que devem ser mantidos apesar de mudanças no cluster
+ Buckets de armazenamento de longo prazo com requisitos de conformidade ou auditoria
+ Recursos compartilhados usados por diversas aplicações ou equipes
+ Recursos em processo de migração para diferentes ferramentas de gerenciamento
+ Cenários de recuperação de desastres em que você deseja preservar a infraestrutura
+ Recursos com dependências complexas que exigem uma desativação cuidadosa
```
apiVersion: rds.services.k8s.aws/v1alpha1
kind: DBInstance
metadata:
name: production-db
annotations:
services.k8s.aws/deletion-policy: "retain"
spec:
dbInstanceIdentifier: prod-db
# ... configuration
```
**Importante**
Recursos retidos continuam a gerar custos na AWS e devem ser excluídos manualmente da AWS quando não forem mais necessários. Use a marcação de recursos para rastrear recursos retidos para limpeza posterior.
Para saber mais sobre as políticas de exclusão, consulte [Conceitos do ACK](ack-concepts.md).
## Documentação original
Para obter informações detalhadas sobre o uso do ACK:
+ [Guia de uso do ACK](https://aws-controllers-k8s.github.io/community/docs/user-docs/usage/): criação e gerenciamento de recursos
+ [Referência da API do ACK](https://aws-controllers-k8s.github.io/community/reference/): documentação completa da API para todos os serviços
+ [Documentação do ACK](https://aws-controllers-k8s.github.io/community/docs/): documentação abrangente para o usuário
## Próximas etapas
+ [Configuração das permissões do ACK](ack-permissions.md): configure permissões do IAM e padrões para várias contas
+ [Conceitos do ACK](ack-concepts.md): compreenda os conceitos do ACK e o ciclo de vida dos recursos
+ [Solução de problemas em funcionalidades do ACK](ack-troubleshooting.md): solucione problemas do ACK
+ [Como trabalhar com o Argo CD](working-with-argocd.md): implante recursos do ACK com GitOps
+ [Conceitos do kro](kro-concepts.md): componha recursos do ACK em abstrações de nível superior
# Solução de problemas em funcionalidades do ACK
Este tópico fornece orientações para a solução de problemas à funcionalidade do EKS para o ACK, incluindo verificações de integridade da funcionalidade, verificação do status dos recursos e problemas relacionados à permissão do IAM.
**nota**
As funcionalidades do EKS são totalmente gerenciadas e executadas de forma externa ao cluster. Você não tem acesso aos logs do controlador nem aos namespaces do controlador. A solução de problemas se concentra na integridade da funcionalidade, no status dos recursos e na configuração do IAM.
## Funcionalidade está no status ACTIVE, mas os recursos não estão sendo criados
Se a sua funcionalidade do ACK apresentar o status `ACTIVE`, mas os recursos não estiverem sendo criados na AWS, verifique a integridade da funcionalidade, o status dos recursos e as permissões do IAM.
**Verifique a integridade da funcionalidade**:
É possível visualizar problemas de integridade e de status da funcionalidade no console do EKS ou usando a AWS CLI.
**Console do**:
1. Abra o console do Amazon EKS em https://console.aws.amazon.com/eks/home\$1/clusters.
1. Selecione o nome do seu cluster.
1. Escolha a guia **Observabilidade**.
1. Escolha **Monitorar cluster**.
1. Escolha a guia **Funcionalidades** para visualizar a integridade e o status de todas as funcionalidades.
** AWS CLI**:
```
# View capability status and health
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-ack
# Look for issues in the health section
```
**Causas comuns**:
+ **Ausência de permissões do IAM**: o perfil da funcionalidade não conta com permissões para o serviço da AWS
+ **Namespace incorreto**: recursos criados em um namespace sem o IAMRoleSelector adequado
+ **Especificação de recurso inválida**: é necessário verificar as condições de status do recurso para encontrar erros de validação
+ **Controle de utilização da API**: os limites de taxa da API da AWS foram atingidos
+ **Webhooks de admissão**: os webhooks de admissão estão impedindo o controlador de atualizar o status do recurso
**Verifique o status do recurso**:
```
# Describe the resource to see conditions and events
kubectl describe bucket my-bucket -n default
# Look for status conditions
kubectl get bucket my-bucket -n default -o jsonpath='{.status.conditions}'
# View resource events
kubectl get events --field-selector involvedObject.name=my-bucket -n default
```
**Verifique as permissões do IAM**:
```
# View the Capability Role's policies
aws iam list-attached-role-policies --role-name my-ack-capability-role
aws iam list-role-policies --role-name my-ack-capability-role
# Get specific policy details
aws iam get-role-policy --role-name my-ack-capability-role --policy-name policy-name
```
## Recursos são criados na AWS, mas que não aparecem no Kubernetes
O ACK rastreia apenas os recursos criados por meio de manifestos do Kubernetes. Para gerenciar recursos existentes da AWS com o ACK, empregue o recurso de adoção.
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: existing-bucket
annotations:
services.k8s.aws/adoption-policy: "adopt-or-create"
spec:
name: my-existing-bucket-name
```
Para obter mais informações sobre a adoção de recursos, consulte [Conceitos do ACK](ack-concepts.md).
## Recursos entre contas não estão sendo criados
Se os recursos não estiverem sendo criados em uma conta de destino da AWS ao usar os seletores de perfil do IAM, verifique a relação de confiança e a configuração do IAMRoleSelector.
**Verifique a relação de confiança**:
```
# Check the trust policy in the target account role
aws iam get-role --role-name cross-account-ack-role --query 'Role.AssumeRolePolicyDocument'
```
A política de confiança deve permitir que o perfil da funcionalidade da conta de origem a assuma.
**Confirme a configuração do IAMRoleSelector**:
```
# List IAMRoleSelectors (cluster-scoped)
kubectl get iamroleselector
# Describe specific selector
kubectl describe iamroleselector my-selector
```
**Verifique o alinhamento do namespace**:
Os IAMRoleSelectors são recursos de escopo do cluster, mas operam em namespaces específicos. Certifique-se de que os recursos do ACK estejam em um namespace que corresponda ao selecionador de namespace do IAMRoleSelector:
```
# Check resource namespace
kubectl get bucket my-cross-account-bucket -n production
# List all IAMRoleSelectors (cluster-scoped)
kubectl get iamroleselector
# Check which namespace the selector targets
kubectl get iamroleselector my-selector -o jsonpath='{.spec.namespaceSelector}'
```
**Verifique a condição IAMRoleSelected**:
Verifique se o IAMRoleSelector foi correspondido com sucesso ao seu recurso, consultando a condição `ACK.IAMRoleSelected`:
```
# Check if IAMRoleSelector was matched
kubectl get bucket my-cross-account-bucket -n production -o jsonpath='{.status.conditions[?(@.type=="ACK.IAMRoleSelected")]}'
```
Se a condição for `False` ou estiver ausente, o selecionador de namespace do IAMRoleSelector não corresponde ao namespace do recurso. Verifique se o `namespaceSelector` do seletor corresponde aos rótulos de namespace do seu recurso.
**Verifique as permissões do perfil da funcionalidade**:
O perfil de funcionalidade precisa das permissões `sts:AssumeRole` e `sts:TagSession` para o perfil da conta de destino:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["sts:AssumeRole", "sts:TagSession"],
"Resource": "arn:aws:iam::[.replaceable]`444455556666`:role/[.replaceable]`cross-account-ack-role`"
}
]
}
```
Para obter informações detalhadas sobre a configuração entre contas, consulte [Configuração das permissões do ACK](ack-permissions.md).
## Próximas etapas
+ [Considerações sobre o ACK para o EKS](ack-considerations.md): acesse considerações e práticas recomendadas do ACK
+ [Configuração das permissões do ACK](ack-permissions.md): configure permissões do IAM e padrões para várias contas
+ [Conceitos do ACK](ack-concepts.md): compreenda os conceitos do ACK e o ciclo de vida dos recursos
+ [Solução de problemas das funcionalidades do EKS](capabilities-troubleshooting.md): acesse orientações gerais para solução de problemas de funcionalidades
# Comparação da funcionalidade do EKS para o ACK em relação ao ACK autogerenciado
A funcionalidade do EKS para o ACK é equivalente à dos controladores do ACK autogerenciados, porém apresenta vantagens operacionais significativas. Para obter uma comparação geral das funcionalidades do EKS em relação às soluções autogerenciadas, consulte [Considerações sobre as funcionalidades do EKS](capabilities-considerations.md). Este tópico se concentra nas diferenças específicas do ACK.
## Diferenças em relação à versão original do ACK
A funcionalidade do EKS para o ACK se baseia na versão original dos controladores do ACK, porém apresenta diferenças na integração com o IAM.
**Perfil da funcionalidade do IAM**: a funcionalidade usa um perfil do IAM dedicado com uma política de confiança que permite o serviço `capabilities.eks.amazonaws.com` da entidade principal, e não o IRSA (perfis do IAM para contas de serviços). É possível anexar políticas do IAM diretamente ao perfil da funcionalidade, sem a necessidade de criar ou anotar contas de serviços do Kubernetes ou configurar provedores OIDC. Uma prática recomendada para casos de uso em ambientes de produção é configurar permissões de serviços usando o `IAMRoleSelector`. Consulte [Configuração das permissões do ACK](ack-permissions.md) para obter mais detalhes.
**Tags de sessão**: o recurso gerenciado define automaticamente as tags de sessão em todas as solicitações da AWS API, permitindo controle de acesso e auditoria refinados. As tags incluem `eks:eks-capability-arn`, `eks:kubernetes-namespace` e `eks:kubernetes-api-group`. Isso difere do ACK autogerenciado, que não define essas tags por padrão. Consulte [Configuração das permissões do ACK](ack-permissions.md) para obter detalhes sobre o uso de tags de sessão nas políticas do IAM.
**Tags de recursos**: a funcionalidade aplica tags padrão diferentes aos recursos da AWS do ACK autogerenciado. O recurso usa tags prefixadas `eks:` (como`eks:kubernetes-namespace`, `eks:eks-capability-arn`) em vez das tags `services.k8s.aws/` usadas pelo ACK autogerenciado. Consulte [Considerações sobre o ACK para o EKS](ack-considerations.md) para obter a lista completa das tags de recursos padrão.
**Compatibilidade de recursos**: os recursos personalizados do ACK funcionam de forma idêntica à versão original do ACK, sem a necessidade de alterações nos arquivos YAML de recursos do ACK. A funcionalidade usa as mesmas APIs do Kubernetes e CRDs, portanto, ferramentas como o `kubectl` funcionam de maneira semelhante. Todos os controladores e recursos em disponibilidade geral (GA, na sigla em inglês) da versão original do ACK são compatíveis.
Para obter a documentação completa do ACK e os guias específicos dos serviços, consulte a [documentação do ACK](https://aws-controllers-k8s.github.io/community/).
## Caminho de migração
É possível migrar de um ACK autogerenciado para a funcionalidade gerenciada sem tempo de inatividade:
1. Atualize o controlador do ACK autogerenciado para usar `kube-system` para concessões de eleição de líder, por exemplo:
```
helm upgrade --install ack-s3-controller \
oci://public.ecr.aws/aws-controllers-k8s/s3-chart \
--namespace ack-system \
--set leaderElection.namespace=kube-system
```
Isso transfere a concessão do controlador para o `kube-system`, permitindo que a funcionalidade gerenciada se coordene com ele.
1. Crie a funcionalidade do ACK no cluster (consulte [Criação de uma funcionalidade do ACK](create-ack-capability.md))
1. A funcionalidade gerenciada reconhece os recursos da AWS gerenciados pelo ACK existentes e assume a reconciliação
1. Reduza gradualmente a escala verticalmente ou remova as implantações dos controladores autogerenciados:
```
helm uninstall ack-s3-controller --namespace ack-system
```
Com essa abordagem, ambos os controladores podem coexistir com segurança durante a migração. A funcionalidade gerenciada assume automaticamente os recursos que antes eram gerenciados pelos controladores autogerenciados, assegurando reconciliação contínua sem gerar conflitos.
## Próximas etapas
+ [Criação de uma funcionalidade do ACK](create-ack-capability.md): crie um recurso de funcionalidade do ACK
+ [Conceitos do ACK](ack-concepts.md): compreenda os conceitos do ACK e o ciclo de vida dos recursos
+ [Configuração das permissões do ACK](ack-permissions.md): configure o IAM e as permissões