**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.
# Funcionalidades do EKS
**dica**
Conceitos básicos: [Criação de funcionalidades do ACK](create-ack-capability.md) \$1 [Criação de funcionalidades do Argo CD](create-argocd-capability.md) \$1 [Criação de funcionalidades do kro](create-kro-capability.md)
As funcionalidades do Amazon EKS são um conjunto, em camadas. de recursos de cluster totalmente gerenciados que auxiliam a aumentar a produtividade dos desenvolvedores e a reduzir a complexidade de desenvolvimento e de escalabilidade com o Kubernetes. As funcionalidades do EKS são recursos nativos do Kubernetes para implantação contínua declarativa, gerenciamento de recursos da AWS e criação e orquestração de recursos do Kubernetes, tudo totalmente gerenciado pela AWS. Com as funcionalidades do EKS, é possível concentrar-se mais na criação e na escalabilidade das workloads, transferindo a carga operacional desses serviços fundamentais de plataforma para a AWS. Essas funcionalidades são executadas no próprio EKS, e não em seus clusters, dispensando a instalação, a manutenção e a escalabilidade de componentes essenciais de plataforma nos nós de processamento.
Para começar a usar, você pode criar uma ou mais funcionalidades do EKS em um cluster do EKS novo ou já existente. Para realizar essa ação, é possível usar a AWS CLI, o Console de gerenciamento da AWS, as APIs do EKS, o eksctl ou suas ferramentas preferidas de infraestrutura como código. Apesar das funcionalidades do EKS serem desenvolvidas para operar em conjunto, elas são recursos de nuvem independentes, permitindo que você realize a escolha de acordo com as necessidades e o caso de uso da sua aplicação.
Todas as versões do Kubernetes com suporte por parte do EKS são compatíveis com as funcionalidades do EKS.
**nota**
As funcionalidades do EKS estão disponíveis para uso em todas as regiões comerciais da AWS nas quais o Amazon EKS está disponível. Para obter uma lista das regiões com suporte, consulte [Endpoints e cotas do Amazon EKS](https://docs.aws.amazon.com/general/latest/gr/eks.html) na Referência geral da AWS.
## Capacidades disponíveis
### AWS Controlllers for Kubernetes (ACK)
O ACK viabiliza o gerenciamento de recursos da AWS por meio de APIs do Kubernetes, permitindo a criação e o gerenciamento de buckets do S3, bancos de dados do RDS, perfis do IAM e outros recursos da AWS utilizando recursos personalizados do Kubernetes. O ACK faz a reconciliação contínua entre o estado desejado e o estado atual na AWS, corrigindo qualquer desvio ao longo do tempo para manter a integridade do sistema e dos recursos configurados conforme especificado. É possível gerenciar recursos da AWS juntamente com as workloads do Kubernetes usando as mesmas ferramentas e fluxos de trabalho, com suporte para mais de 50 serviços da AWS, incluindo o S3, o RDS, o DynamoDB e o Lambda. O ACK fornece suporte para o gerenciamento de recursos entre contas e entre regiões, permitindo arquiteturas complexas de gerenciamento de sistemas com várias contas e vários clusters. O ACK é compatível com recursos somente leitura e a adoção somente leitura, facilitando a migração de outras ferramentas de infraestrutura como código para os sistemas baseados em Kubernetes.
[Saiba mais sobre o ACK →](ack.md)
### Argo CD
O Argo CD aplica o modelo de implantação contínua baseada em GitOps para as aplicações, utilizando repositórios do Git como a fonte da verdade para as workloads e para o estado do sistema. O Argo CD faz a sincronização automática de recursos de aplicações para os clusters com base em repositórios do Git, identificando e corrigindo desvios para assegurar que as aplicações implantadas estejam alinhadas ao estado desejado. É possível implantar e gerenciar aplicações em vários clusters de uma única instância do Argo CD, com a implantação automatizada de repositórios do Git sempre que alterações forem confirmadas. O uso conjunto do Argo CD e do ACK fornece um sistema de GitOps fundamental, simplificando o gerenciamento de dependências das workloads, além de fornecer suporte a projetos de sistemas completos, incluindo o gerenciamento de clusters e de infraestrutura em grande escala. O Argo CD se integra ao Centro de Identidade da AWS para autenticação e autorização, e fornece uma interface do usuário do Argo hospedada para a visualização da integridade das aplicações e do status de implantação.
[Saiba mais sobre o Argo CD →](argocd.md)
### kro (Kube Resource Orchestrator)
O kro possibilita a criação de APIs personalizadas do Kubernetes que compõem vários recursos em abstrações de nível superior, permitindo que as equipes responsáveis pela plataforma definam padrões reutilizáveis para combinações comuns de recursos, os blocos de criação da nuvem. Com o kro, você pode compor recursos do Kubernetes e da AWS em abstrações unificadas, usando uma sintaxe simplificada que viabiliza configurações dinâmicas e o uso de lógica condicional. O kro permite que as equipes responsáveis pela plataforma disponibilizem funcionalidades de autoatendimento com as devidas barreiras de proteção, possibilitando que os desenvolvedores provisionem infraestruturas complexas por meio de APIs simples e especializadas, enquanto preservam os padrões e as práticas recomendadas da organização. Os recursos do kro nada mais são do que recursos do Kubernetes, definidos em manifestos do Kubernetes, que podem ser armazenados no Git ou enviados para registros compatíveis com OCI, como o Amazon ECR, para facilitar a distribuição por toda a organização.
[Saiba mais sobre o kro →](kro.md)
## Benefícios das funcionalidades do EKS
As funcionalidades do EKS são totalmente gerenciadas pela AWS, o que dispensa a instalação, a manutenção e a escalabilidade de serviços essenciais do cluster. A AWS lida com a aplicação de patches de segurança, atualizações e gerenciamento operacional, permitindo que as equipes concentrem esforços no desenvolvimento na AWS e não nas operações de cluster. Ao contrário dos complementos convencionais do Kubernetes que consomem recursos do cluster, as funcionalidades são executadas no EKS, e não em nós de processamento. Essa abordagem libera capacidade e recursos do cluster para as workloads, enquanto minimiza a carga operacional necessária para o gerenciamento de controladores internos do cluster e de outros componentes de plataforma.
Com as funcionalidades do EKS, é possível gerenciar implantações, recursos da AWS, recursos personalizados do Kubernetes e composições usando APIs nativas do Kubernetes e ferramentas como o `kubectl`. Todas as funcionalidades funcionam no contexto dos clusters, identificando e corrigindo automaticamente desvios de configuração em recursos de aplicações e de infraestrutura de nuvem. Você pode implantar e gerenciar recursos em vários clusters, contas da AWS e regiões usando um único ponto de controle, simplificando as operações em ambientes distribuídos de alta complexidade.
As funcionalidades do EKS são projetadas para fluxos de trabalho de GitOps, o que fornece um gerenciamento declarativo e com versionamento de aplicações e de infraestrutura. As alterações seguem do Git para todo o sistema, fornecendo trilhas de auditoria, funcionalidades de reversão e fluxos de trabalho colaborativos que se integram às práticas de desenvolvimento existentes. Esta abordagem nativa do Kubernetes dispensa o uso de diversas ferramentas ou o gerenciamento de sistemas de infraestrutura como código externos aos clusters, garantindo a existência de uma única fonte de verdade como referência. O estado desejado, definido em configurações declarativas do Kubernetes com versionamento, é continuamente aplicado em todo o seu ambiente.
## Preços
Com as funcionalidades do EKS, não há compromissos antecipados nem taxas mínimas. A cobrança é feita por recurso da funcionalidade e se baseia em cada hora de atividade do recurso no cluster do Amazon EKS. Os recursos específicos do Kubernetes, gerenciados pelas funcionalidades do EKS, também são faturados a uma taxa horária.
Para obter informações atualizadas sobre preços, consulte a [página de preços do Amazon EKS](https://aws.amazon.com/eks/pricing/).
**dica**
É possível empregar o Explorador de Custos da AWS e os Relatórios de Custos e Uso para monitorar os custos das funcionalidades de forma isolada de outros custos do EKS. Você pode marcar as funcionalidades com o nome do cluster, tipo de funcionalidade e outros detalhes para fins de alocação de custos.
## Funcionamento das funcionalidades do EKS
Cada funcionalidade constitui um recurso da AWS criado no cluster do EKS. Após a criação, a funcionalidade é executada no EKS e é totalmente gerenciada pela AWS.
**nota**
É possível criar apenas um recurso da funcionalidade de cada tipo, nomeadamente, Argo CD, ACK e kro, por cluster. Não é possível criar mais de um recurso da funcionalidade do mesmo tipo em um único cluster.
A interação com as funcionalidades do cluster é feita por meio de APIs e ferramentas nativas do Kubernetes:
+ Use o `kubectl` para aplicar recursos personalizados do Kubernetes
+ Use os repositórios do Git como a fonte da verdade para fluxos de trabalho de GitOps
Algumas funcionalidades oferecem suporte a ferramentas adicionais. Por exemplo:
+ Use a CLI do Argo CD para configurar e gerenciar repositórios e clusters na funcionalidade do Argo CD
+ Use a interface do usuário do Argo CD para visualizar e gerenciar aplicações controladas pela funcionalidade do Argo CD
Embora concebidas para operar de forma integrada, as funcionalidades são independentes, e você escolhe quais deseja ativar. Você pode habilitar uma, duas ou todas as três funcionalidades, de acordo com a sua demanda, ajustando a configuração à medida que suas necessidades mudarem.
Todos os tipos de computação do EKS são compatíveis com o uso das funcionalidades do EKS. Para obter mais informações, consulte [Gerenciar recursos computacionais usando nós](eks-compute.md).
Para obter configurações de segurança e detalhes sobre os perfis do IAM, consulte [Considerações sobre segurança para funcionalidades do EKS](capabilities-security.md). Para obter padrões de arquitetura de vários clusters, consulte [Considerações sobre as funcionalidades do EKS](capabilities-considerations.md).
## Casos de uso comuns
**GitOps aplicado a aplicações e infraestrutura**
Use o Argo CD na implantação de aplicações e de componentes operacionais, e o ACK para o gerenciamento de configurações de cluster e para o provisionamento de infraestrutura, empregando repositórios do Git como fonte para ambos. Toda a sua pilha, que é composta por aplicações, bancos de dados, armazenamento e rede, é definida como código e implantada automaticamente.
Exemplo: uma equipe de desenvolvimento envia alterações para o Git. O Argo CD realiza a implantação da aplicação atualizada, enquanto o ACK provisiona um novo banco de dados do RDS com a configuração adequada. Todas as alterações são passíveis de auditoria e de reversão, e mantêm a consistência em diferentes ambientes.
**Engenharia de plataforma com autoatendimento**
Use o kro para criar APIs personalizadas que compõem recursos do ACK e do Kubernetes. As equipes responsáveis pela plataforma definem padrões aprovados com barreiras de proteção. As equipes responsáveis pela aplicação usam APIs simplificadas de alto nível para realizar o provisionamento de pilhas inteiras.
Exemplo: uma equipe responsável pela plataforma cria uma API de “WebApplication” para provisionar automaticamente os recursos Deployment, Service e Ingress, e um bucket do S3. Os desenvolvedores usam essa API sem a necessidade de compreender a complexidade subjacente ou as permissões da AWS.
**Gerenciamento de aplicações em vários clusters**
Use o Argo CD para implantar aplicações em vários clusters do EKS distribuídos em diferentes regiões ou contas. Gerencie todas as implantações com uma única instância do Argo CD, empregando políticas e fluxos de trabalho consistentes.
Exemplo: implante a mesma aplicação em clusters de desenvolvimento, preparação e produção distribuídos por diversas regiões. O Argo CD assegura a sincronização de cada ambiente com a ramificação correspondente no Git.
**Gerenciamento de vários clusters**
Use o ACK para definir e provisionar clusters do EKS, o kro para personalizar as configurações dos clusters de acordo com os padrões organizacionais, e o Argo CD para gerenciar o ciclo de vida e a configuração do cluster. Essa abordagem garante o gerenciamento integral do cluster, abrangendo desde o provisionamento inicial até a operação cotidiana.
Exemplo: defina clusters do EKS usando o ACK e o kro para provisionar e gerenciar a infraestrutura de clusters, definindo padrões organizacionais para rede, políticas de segurança, complementos e outras configurações. Empregue o Argo CD para a criação e para o gerenciamento contínuo de clusters, configurações e atualizações de versões do Kubernetes em toda a frota, fazendo uso de padrões consistentes e do gerenciamento de ciclo de vida automatizado.
**Migrações e modernização**
Simplifique a migração para o EKS com o provisionamento de recursos de nuvem nativos e fluxos de trabalho de GitOps. Use o ACK para adotar recursos existentes da AWS sem a necessidade de recriá-los, e o Argo CD para operacionalizar as implantações de workloads a partir do Git.
Exemplo: uma equipe em processo de migração do EC2 para o EKS integra bancos de dados do RDS e buckets do S3 utilizando o ACK, e usa o Argo CD para realizar a implantação de aplicações conteinerizadas do Git. O caminho de migração é bem definido e os processos operacionais são padronizados desde o início.
**Inicialização de contas e de regiões**
Automatize a implementação da infraestrutura entre contas e regiões usando o Argo CD e o ACK de forma integrada. Defina a infraestrutura como código no Git e permita que as funcionalidades gerenciem a implantação e o gerenciamento.
Exemplo: uma equipe responsável pela plataforma mantém repositórios do Git que definem configurações padrão de conta, incluindo VPCs, perfis do IAM, instâncias do RDS e pilhas de monitoramento. O Argo CD implanta essas configurações em novas contas e regiões automaticamente, garantindo a consistência e reduzindo o tempo de configuração manual de dias para minutos.
# Como trabalhar com recursos de funcionalidade
Este tópico descreve operações comuns para o gerenciamento de recursos de funcionalidade em todos os tipos de funcionalidades.
## Recursos de funcionalidade do EKS
As funcionalidades do EKS são recursos da AWS que permitem funcionalidades gerenciadas no cluster do Amazon EKS. As funcionalidades são executadas no EKS, eliminando a necessidade de instalar e manter controladores e outros componentes operacionais em seus nós de processamento. As funcionalidades são criadas para um cluster específico do EKS e permanecem vinculadas a esse cluster durante todo o ciclo de vida.
Cada recurso de funcionalidade conta com:
+ Um nome exclusivo em seu cluster
+ Um tipo de funcionalidade (ACK, ARGOCD ou KRO)
+ Um nome do recurso da Amazon (ARN), especificando o nome e o tipo
+ Um perfil do IAM da funcionalidade
+ Um status que indica seu estado atual
+ Configuração, tanto genérica quanto específica ao tipo de funcionalidade
## Noções básicas sobre o status da funcionalidade
Os recursos de funcionalidade contam com um status que indica o estado atual. É possível visualizar o status e a integridade 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 **Funcionalidades** para visualizar o status de todas as funcionalidades.
1. Para obter informações detalhadas sobre a integridade, escolha a guia **Observabilidade**, depois **Monitorar cluster** e, em seguida, a guia **Funcionalidades**.
** AWS CLI**:
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-capability-name
```
### Status da funcionalidade
**CREATING**: a funcionalidade está sendo configurada. É possível sair do console e a funcionalidade continuará sendo criada em segundo plano.
**ACTIVE**: a funcionalidade está em execução e pronta para uso. Se os recursos não estiverem funcionando conforme esperado, verifique o status do recurso e as permissões de IAM. Para obter orientações, consulte [Solução de problemas das funcionalidades do EKS](capabilities-troubleshooting.md).
**UPDATING**: as alterações de configuração estão sendo aplicadas. Aguarde até que o status retorne para `ACTIVE`.
**DELETING**: a funcionalidade está sendo removida do cluster.
**CREATE\$1FAILED**: a configuração encontrou um erro. As causas comuns incluem:
+ Política de confiança do perfil do IAM incorreta ou ausente
+ O perfil do IAM não existe ou não está acessível
+ Problemas de acesso ao cluster
+ Parâmetros de configuração inválidos
Verifique a seção de integridade da funcionalidade para obter detalhes específicos do erro.
**UPDATE\$1FAILED**: a atualização da configuração falhou. Verifique a seção de integridade da funcionalidade para obter detalhes e valide as permissões do IAM.
**dica**
Para obter orientações detalhadas sobre solução de problemas, consulte:
[Solução de problemas das funcionalidades do EKS](capabilities-troubleshooting.md): soluções de problemas gerais para problemas de funcionalidades
[Solução de problemas em funcionalidades do ACK](ack-troubleshooting.md): problemas específicos do ACK
[Solução de problemas em funcionalidades do Argo CD](argocd-troubleshooting.md): problemas específicos do Argo CD
[Solução de problemas em funcionalidades do kro](kro-troubleshooting.md): problemas específicos do kro
## Criação de funcionalidades
Para criar uma funcionalidade em seu cluster, consulte os seguintes tópicos:
+ [Criação de uma funcionalidade do ACK](create-ack-capability.md): crie uma funcionalidade do ACK para gerenciar recursos da AWS usando APIs do Kubernetes
+ [Criar um recurso Argo CD](create-argocd-capability.md): crie uma funcionalidade do Argo CD para entrega contínua de GitOps
+ [Criação de uma funcionalidade do kro](create-kro-capability.md): crie uma funcionalidade do kro para composição e orquestração de recursos
## Listagem de funcionalidades
É possível listar todos os recursos da funcionalidade de um cluster.
### Console
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. Visualize os recursos de funcionalidade em **Funcionalidades gerenciadas**.
### AWS CLI
Use o comando `list-capabilities` para visualizar todas as funcionalidades em seu 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 list-capabilities \
--region region-code \
--cluster-name my-cluster
```
```
{
"capabilities": [
{
"capabilityName": "my-ack",
"arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/ack/my-ack/abc123",
"type": "ACK",
"status": "ACTIVE",
"createdAt": "2025-11-02T10:30:00.000000-07:00",
"modifiedAt": "2025-11-02T10:32:15.000000-07:00",
},
{
"capabilityName": "my-kro",
"arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/kro/my-kro/abc123",
"type": "KRO",
"status": "ACTIVE",
"version": "v0.6.3",
"createdAt": "2025-11-02T10:30:00.000000-07:00",
"modifiedAt": "2025-11-02T10:32:15.000000-07:00",
},
{
"capabilityName": "my-argocd",
"arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/argocd/my-argocd/abc123",
"type": "ARGOCD",
"status": "ACTIVE",
"version": "3.1.8-eks-1",
"createdAt": "2025-11-21T08:22:28.486000-05:00",
"modifiedAt": "2025-11-21T08:22:28.486000-05:00"
}
]
}
```
## Descrição de uma funcionalidade
Obtenha informações detalhadas sobre uma funcionalidade específica, incluindo a configuração e o status.
### Console
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. Em **Funcionalidades gerenciadas**, escolha a funcionalidade que deseja visualizar.
1. Visualize os detalhes da funcionalidade, incluindo o status, a configuração e o horário de criação.
### AWS CLI
Use o comando `describe-capability` para visualizar informações detalhadas. Substitua *region-code* pela região da AWS em que o seu cluster está, substitua *my-cluster* pelo nome do seu cluster e substitua *capability-name* pelo nome da funcionalidade (ack, argocd ou kro).
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name capability-name
```
**Resultado do exemplo:**
```
{
"capability": {
"capabilityName": "my-ack",
"capabilityArn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/ack/my-ack/abc123",
"clusterName": "my-cluster",
"type": "ACK",
"roleArn": "arn:aws:iam::111122223333:role/AmazonEKSCapabilityACKRole",
"status": "ACTIVE",
"configuration": {},
"tags": {},
"health": {
"issues": []
},
"createdAt": "2025-11-19T17:11:30.242000-05:00",
"modifiedAt": "2025-11-19T17:11:30.242000-05:00",
"deletePropagationPolicy": "RETAIN"
}
}
```
## Atualização da configuração de uma funcionalidade
É possível atualizar alguns aspectos da configuração de uma funcionalidade após ela ter sido criada. As opções de configuração específicas variam conforme o tipo de funcionalidade.
**nota**
Os recursos da funcionalidade do EKS são totalmente gerenciados, incluindo a aplicação de patches e as atualizações de versão. A atualização de uma funcionalidade atualizará a configuração do recurso e não resultará em atualizações de versão dos componentes da funcionalidade gerenciada.
### AWS CLI
Use o comando `update-capability` para modificar uma funcionalidade:
```
aws eks update-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name capability-name \
--role-arn arn:aws:iam::[.replaceable]111122223333:role/NewCapabilityRole
```
**nota**
Algumas propriedades de uma funcionalidade não permitem atualização após a sua criação. Consulte a documentação específica da funcionalidade para obter detalhes sobre o que pode ser modificado.
## Exclusão de uma funcionalidade
Se uma funcionalidade não for mais necessária no seu cluster, é possível realizar a exclusão do recurso da funcionalidade.
**Importante**
**Exclua os recursos do cluster antes de excluir a funcionalidade.**
A exclusão de um recurso da funcionalidade não exclui automaticamente os recursos criados por meio dessa funcionalidade:
Todas as definições de recursos personalizados (CRDs, na sigla em inglês) do Kubernetes permanecem instaladas em seu cluster.
Os recursos do ACK permanecem em seu cluster, e os recursos correspondentes da AWS permanecem em sua conta.
As Applications do Argo CD e seus recursos do Kubernetes permanecem em seu cluster.
As ResourceGraphDefinitions e instâncias do kro permanecem em seu cluster.
É necessário excluir esses recursos antes de excluir a funcionalidade para evitar recursos órfãos.
Opcionalmente, você pode optar por reter os recursos da AWS associados aos recursos do Kubernetes e do ACK. Consulte [Considerações sobre o ACK](ack-considerations.md).
### Console
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. Selecione a funcionalidade que deseja excluir na lista de **Funcionalidades gerenciadas**.
1. Escolha **Excluir funcionalidade**.
1. No diálogo de confirmação, digite o nome da funcionalidade para confirmar a exclusão.
1. Escolha **Excluir**.
### AWS CLI
Use o comando `delete-capability` para excluir um recurso de funcionalidade:
Substitua *region-code* pela região da AWS em que o seu cluster está, substitua *my-cluster* pelo nome do seu cluster e substitua *capability-name* pelo nome da funcionalidade que deseja excluir.
```
aws eks delete-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name capability-name
```
## Próximas etapas
+ [Recursos da funcionalidade do Kubernetes](capability-kubernetes-resources.md): saiba mais sobre os recursos do Kubernetes fornecidos por cada tipo de funcionalidade
+ [Conceitos do ACK](ack-concepts.md): compreenda os conceitos do ACK e o ciclo de vida dos recursos
+ [Como trabalhar com o Argo CD](working-with-argocd.md): saiba como trabalhar com funcionalidades do Argo CD para fluxos de trabalho de GitOps
+ [Conceitos do kro](kro-concepts.md): compreenda os conceitos do kro e a composição de recursos
# Recursos da funcionalidade do Kubernetes
Após habilitar uma funcionalidade no cluster, você passará a interagir com ela principalmente por meio da criação e do gerenciamento de recursos personalizados do Kubernetes no cluster. Cada funcionalidade fornece seu próprio conjunto de definições de recursos personalizados (CRDs, na sigla em inglês) que ampliam a API do Kubernetes com funcionalidades específicas.
## Recursos do Argo CD
Quando você habilita a funcionalidade do Argo CD, torna-se possível criar e gerenciar os seguintes recursos do Kubernetes:
**Aplicação**
Define a implantação de um repositório do Git para um cluster de destino. Os recursos do tipo `Application` especificam o repositório de origem, o namespace de destino e a política de sincronização. É possível criar até mil recursos do tipo `Application` para cada instância da funcionalidade do Argo CD.
**ApplicationSet**
Gera diversos recursos do tipo `Application` baseados em modelos, permitindo implantações em vários clusters e diversos ambientes. Os recursos do tipo `ApplicationSet` utilizam geradores para criar recursos do tipo `Application` dinamicamente com base em listas de clusters, diretórios do Git ou outras fontes.
**AppProject**
Fornece agrupamento lógico e controle de acesso para recursos do tipo `Application`. Os recursos do tipo `AppProject` definem quais repositórios, clusters e namespaces os recursos do tipo `Application` podem usar, permitindo multilocação e limites de segurança.
Exemplo de recurso do tipo `Application`:
```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/org/repo
targetRevision: main
path: manifests
destination:
server: https://kubernetes.default.svc
namespace: production
```
Para obter mais informações sobre recursos e conceitos do Argo CD, consulte [Conceitos do Argo CD](argocd-concepts.md).
## Recursos do kro
Quando você habilita a funcionalidade do kro, torna-se possível criar e gerenciar os seguintes recursos do Kubernetes:
**ResourceGraphDefinition (RGD)**
Define uma API personalizada que compõe diversos recursos do Kubernetes e da AWS em uma abstração de nível superior. As equipes responsáveis pela plataforma criam recursos do tipo `ResourceGraphDefinition` para disponibilizar padrões reutilizáveis com barreiras de proteção.
**Instâncias de recursos personalizados**
Após criar um recurso do tipo `ResourceGraphDefinition`, você pode criar instâncias da API personalizada definida por `ResourceGraphDefinition`. O kro cria e gerencia automaticamente os recursos especificados na `ResourceGraphDefinition`.
Exemplo de recurso do tipo `ResourceGraphDefinition`:
```
apiVersion: kro.run/v1alpha1
kind: ResourceGraphDefinition
metadata:
name: web-application
spec:
schema:
apiVersion: v1alpha1
kind: WebApplication
spec:
name: string
replicas: integer
resources:
- id: deployment
template:
apiVersion: apps/v1
kind: Deployment
# ... deployment spec
- id: service
template:
apiVersion: v1
kind: Service
# ... service spec
```
Exemplo de instância do tipo `WebApplication`:
```
apiVersion: v1alpha1
kind: WebApplication
metadata:
name: my-web-app
namespace: default
spec:
name: my-web-app
replicas: 3
```
Ao aplicar esta instância, o kro cria automaticamente os recursos `Deployment` e `Service` definidos na `ResourceGraphDefinition`.
Para obter mais informações sobre recursos e conceitos do kro, consulte [Conceitos do kro](kro-concepts.md).
## Recursos do ACK
Quando você habilita a funcionalidade do ACK, torna-se possível criar e gerenciar recursos da AWS por meio de recursos personalizados do Kubernetes. O ACK fornece mais de 200 CRDs para mais de 50 serviços da AWS, permitindo definir recursos da AWS em conjunto com workloads do Kubernetes e gerenciar recursos dedicados de infraestrutura da AWS com o Kubernetes.
Exemplos de recursos do ACK:
**Bucket do S3**
Os recursos do tipo `Bucket` realizam a criação e o gerenciamento de buckets do Amazon S3 com políticas de ciclo de vida, criptografia e versionamento.
**DBInstance do RDS**
Os recursos do tipo `DBInstance` realizam o provisionamento e o gerenciamento de instâncias de bancos de dados do Amazon RDS com janelas de manutenção e backups automáticos.
**Tabela do DynamoDB**
Os recursos do tipo `Table` realizam a criação e o gerenciamento de tabelas do DynamoDB com capacidade sob demanda ou provisionada.
**Perfil do IAM**
Os recursos do tipo `Role` definem os perfis do IAM com as políticas de confiança e de permissão para acesso aos serviços da AWS.
**Função do Lambda**
Os recursos do tipo `Function` realizam a criação e o gerenciamento de funções do Lambda, incluindo a configuração de código, runtime e perfil de execução.
Exemplo de especificação para um recurso do tipo `Bucket`:
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-app-bucket
spec:
name: my-unique-bucket-name-12345
versioning:
status: Enabled
encryption:
rules:
- applyServerSideEncryptionByDefault:
sseAlgorithm: AES256
```
Para obter mais informações sobre recursos e conceitos do ACK, consulte [Conceitos do ACK](ack-concepts.md).
## Limites de recurso
As funcionalidades EKS têm os seguintes limites de recursos:
**Limites de uso do Argo CD**:
+ Máximo de mil recursos do tipo `Application` por instância da funcionalidade do Argo CD
+ Máximo de cem clusters remotos configurados por instância da funcionalidade do Argo CD
**Limites de configuração de recursos**:
+ Máximo de 150 recursos do Kubernetes por recurso do tipo `Application` no Argo CD
+ Máximo de 64 recursos do Kubernetes por `ResourceGraphDefinition` no kro
**nota**
Estes limites são válidos para a quantidade de recursos gerenciados por cada instância de funcionalidade. Caso necessite de limites superiores, é possível fazer a implantação das funcionalidades em diversos clusters.
## Próximas etapas
Para realizar tarefas específicas de cada funcionalidade e acessar configurações avançadas, consulte os seguintes tópicos:
+ [Conceitos do ACK](ack-concepts.md): compreenda os conceitos do ACK e o ciclo de vida dos recursos
+ [Como trabalhar com o Argo CD](working-with-argocd.md): saiba como trabalhar com funcionalidades do Argo CD para fluxos de trabalho de GitOps
+ [Conceitos do kro](kro-concepts.md): compreenda os conceitos do kro e a composição de recursos
# Considerações sobre as funcionalidades do EKS
Este tópico aborda considerações importantes para o uso das funcionalidades do EKS, incluindo o planejamento do controle de acesso, a escolha entre as funcionalidades do EKS e as soluções autogerenciadas, os padrões de arquitetura para implantações em vários clusters e as práticas recomendadas de operação.
## Perfis do IAM para a funcionalidade e controle de acesso RBAC do Kubernetes
Cada recurso de funcionalidade do EKS tem um perfil do IAM para a funcionalidade configurado. O perfil da funcionalidade é usado para conceder permissões de serviços da AWS às funcionalidades do EKS para agirem em seu nome. Por exemplo, para usar a funcionalidade do EKS para o ACK gerenciar buckets do Amazon S3, você concederá permissões administrativas de buckets do S3 à funcionalidade, permitindo que ela crie e gerencie buckets.
Após a configuração da funcionalidade, é possível criar e gerenciar recursos do S3 na AWS usando recursos personalizados do Kubernetes no cluster. O RBAC do Kubernetes atua como um mecanismo de controle de acesso no cluster, definindo quais usuários e grupos têm permissão para criar e gerenciar esses recursos personalizados. Por exemplo, conceda a usuários e grupos específicos do RBAC do Kubernetes permissões para criar e gerenciar recursos de `Bucket` nos namespaces que você escolher.
Assim, o IAM e o RBAC do Kubernetes atuam como duas metades de um sistema de controle de acesso completo, que gerencia as permissões vinculadas às funcionalidades do EKS e aos seus recursos. É fundamental definir a combinação adequada de permissões do IAM e de políticas de acesso do RBAC para atender ao seu caso de uso.
Para obter informações adicionais sobre perfis do IAM de funcionalidades e permissões do Kubernetes, consulte [Considerações sobre segurança para funcionalidades do EKS](capabilities-security.md).
## Padrões de arquitetura de vários clusters
Ao implantar funcionalidades em vários clusters, considere estes padrões arquiteturais comuns:
**Modelo hub-and-spoke com gerenciamento centralizado**
Execute todas as três funcionalidades em um cluster com gerenciamento centralizado para orquestrar workloads e gerenciar a infraestrutura de nuvem em vários clusters de workload.
+ O Argo CD, no cluster de gerenciamento, implanta aplicações nos clusters de workload em diferentes regiões ou contas.
+ O ACK, no cluster de gerenciamento, provisiona recursos da AWS (como RDS, S3 e IAM) para todos os clusters.
+ O kro, no cluster de gerenciamento, cria abstrações de plataforma portáveis que funcionam em todos os clusters.
Esse padrão centraliza o gerenciamento de workloads e da infraestrutura de nuvem, podendo simplificar as operações para organizações que gerenciam muitos clusters.
**GitOps descentralizadas**
As workloads e a infraestrutura de nuvem são gerenciadas pelas funcionalidades no mesmo cluster em que as workloads estão sendo executadas.
+ O Argo CD gerencia os recursos de aplicações no cluster local
+ Os recursos do ACK são usados para atender às necessidades do cluster e das workloads.
+ As abstrações de plataforma do kro são instaladas e orquestram recursos locais.
Esse padrão descentraliza as operações, com equipes responsáveis pelo gerenciamento dos próprios serviços de plataforma dedicados a um ou mais clusters.
**Modelo hub-and-spoke com implantação híbrida do ACK**
Combine modelos centralizados e descentralizados, com implantações de aplicações centralizadas e gerenciamento de recursos baseado em escopo e em propriedade.
+ Cluster de hub:
+ Argo CD gerencia implantações de GitOps no cluster local e em todos os clusters de workload remotos.
+ O ACK é usado no cluster de gerenciamento para recursos de escopo administrativo (como bancos de dados de produção, perfis do IAM e VPCs).
+ O kro é usado no cluster de gerenciamento para abstrações de plataforma reutilizáveis.
+ Clusters de spoke:
+ As workloads são gerenciadas por meio do Argo CD no cluster centralizado do hub.
+ O ACK é usado localmente para recursos de escopo da workload (como buckets do S3, instâncias do ElastiCache e filas do SQS).
+ O kro é usado localmente para composições de recursos e padrões de blocos de criação.
Esse padrão separa responsabilidades: equipes responsáveis pela plataforma gerenciam a infraestrutura crítica de forma centralizada nos clusters de gerenciamento (opcionalmente incluindo clusters de workload), enquanto equipes responsáveis pela aplicação definem e administram recursos de nuvem juntamente com as workloads.
**Escolha de um padrão**
Considere estes fatores ao selecionar uma arquitetura:
+ **Estrutura organizacional**: equipes responsáveis pela plataforma centralizadas geralmente optam por padrões de hub, enquanto equipes descentralizadas podem preferir funcionalidades por cluster
+ **Escopo dos recursos**: recursos de escopo administrativo, como bancos de dados e perfis do IAM, costumam se beneficiar de um gerenciamento centralizado; recursos de workload, por sua vez, como buckets e filas, podem ser administrados localmente
+ **Autoatendimento**: equipes responsáveis pela plataforma centralizadas podem desenvolver e distribuir recursos personalizados prescritivos, possibilitando o autoatendimento seguro de recursos de nuvem para demandas comuns de workloads
+ **Gerenciamento da frota de clusters**: clusters de gerenciamento centralizados fornecem um ambiente de gerenciamento de propriedade do cliente para o gerenciamento da frota de clusters do EKS, juntamente com outros recursos de escopo administrativo
+ **Requisitos de conformidade**: algumas organizações requerem controle centralizado para fins de auditoria e governança
+ **Complexidade operacional**: menos instâncias de funcionalidades simplificam as operações, mas podem gerar gargalos
**nota**
É possível começar a usar um padrão e migrar para outro à medida que a plataforma se desenvolve. As funcionalidades são independentes, permitindo que você as implante de formas diferentes em clusters distintos, de acordo com suas necessidades.
## Comparação entre funcionalidades do EKS e soluções autogerenciadas
As funcionalidades do EKS oferecem experiências totalmente gerenciadas para ferramentas e controladores populares do Kubernetes que são executadas no EKS. Isso difere das soluções autogerenciadas, que precisam ser instaladas e gerenciadas diretamente no cluster.
### Principais diferenças
**Implantação e gerenciamento**
As funcionalidades do EKS são totalmente gerenciadas pela AWS, sem necessidade de instalação, configuração ou manutenção do software dos componentes. A AWS instala e gerencia automaticamente todas as definições de recursos personalizados (CRDs, na sigla em inglês) do Kubernetes necessárias no cluster.
Com soluções autogerenciadas, você instala e configura o software do cluster usando charts do Helm, kubectl ou outros operadores. Nas soluções autogerenciadas, você mantém controle total sobre o ciclo de vida do software e a configuração do runtime, possibilitando personalizações em todas as camadas da solução.
**Operações e manutenção**
A AWS gerencia a aplicação de patches e outras operações do ciclo de vida do software para as funcionalidades do EKS, com atualizações automáticas e patches de segurança. As funcionalidades do EKS são integradas aos recursos da AWS para configurações simplificadas, oferecem alta disponibilidade e tolerância a falhas incorporadas e eliminam a necessidade de solução de problemas de workloads de controladores dentro do cluster.
As soluções autogerenciadas requerem que você monitore a integridade dos componentes e dos logs, aplique patches de segurança e atualizações de versão, configure alta disponibilidade com várias réplicas e budgets de interrupção de pods, realize a solução e a correção de problemas em workloads de controladores, e gerencie lançamentos e versões. Você tem controle total sobre as implantações, mas isso geralmente exige soluções sob medida para acesso a clusters privados e outras integrações, que devem estar alinhadas aos padrões organizacionais e aos requisitos de conformidade da segurança.
**Consumo de recursos**
As funcionalidades do EKS são executadas no EKS e de forma externa aos clusters, liberando tanto recursos de nós quanto recursos de cluster. As funcionalidades não usam recursos de workloads do cluster, não consomem CPU ou memória nos nós de processamento, escalam automaticamente e têm impacto mínimo no planejamento de capacidade do cluster.
As soluções autogerenciadas executam controladores e outros componentes nos nós de processamento, consumindo diretamente recursos desses nós, IPs do cluster e outros recursos do cluster. O gerenciamento de serviços do cluster exige planejamento de capacidade para as workloads, além de planejamento e configuração de solicitações e limites de recursos para atender aos requisitos de escalabilidade e de alta disponibilidade.
**Suporte a recursos**
Por serem recursos de serviço totalmente gerenciados, as funcionalidades do EKS são naturalmente opinativas quando comparadas às soluções autogerenciadas. Apesar de as funcionalidades oferecerem suporte à maior parte dos recursos e casos de uso, a abrangência será diferente quando comparadas às soluções autogerenciadas.
Com as soluções autogerenciadas, você tem controle total sobre a configuração, os recursos opcionais e outros aspectos da funcionalidade do software. É possível executar imagens personalizadas próprias, ajustar todos os aspectos da configuração e manter controle completo sobre a funcionalidade da solução autogerenciada.
**Considerações sobre custos**
Cada recurso da funcionalidade do EKS tem um custo horário relacionado, que varia conforme o tipo de funcionalidade. Os recursos do cluster gerenciados por essa funcionalidade também têm custo horário próprio, com precificação separada. Para obter mais informações, consulte [Preços do Amazon EKS](https://aws.amazon.com/eks/pricing/).
As soluções autogerenciadas não têm custos diretos relacionados a cobranças da AWS, mas é necessário pagar pelos recursos de computação do cluster consumidos por controladores e workloads relacionados. Além do consumo de recursos de nós e de cluster, o custo total de propriedade das soluções autogerenciadas inclui despesas operacionais e com manutenção, solução de problemas e suporte.
### Como escolher entre funcionalidades do EKS e soluções autogerenciadas
**Funcionalidades do EKS** Considere esta opção quando desejar reduzir a sobrecarga operacional e se concentrar em valor diferenciado no software e nos sistemas, em vez de nas operações de plataforma do cluster para requisitos fundamentais. Use as funcionalidades do EKS quando desejar minimizar a carga operacional de patches de segurança e o gerenciamento do ciclo de vida do software, liberar recursos de nós e do cluster para workloads de aplicação, simplificar a configuração e o gerenciamento de segurança, e se beneficiar da abrangência de suporte da AWS. As funcionalidades do EKS são adequadas para a maioria dos casos de uso em ambientes de produção e constituem a abordagem recomendada para novas implantações.
**Soluções autogerenciadas** Considere esta opção quando precisar de versões específicas da API de recursos do Kubernetes, desenvolvimentos personalizados de controladores, tiver automação e ferramentas existentes voltadas a implantações autogerenciadas, ou necessitar de um nível avançado de personalização das configurações de runtime dos controladores. Nas soluções autogerenciadas, é possível obter flexibilidade para casos de uso específicos, mantendo controle total sobre a implantação e a configuração de runtime.
**nota**
As funcionalidades do EKS podem coexistir com soluções autogerenciadas em seu cluster, permitindo que migrações sejam feitas de forma gradual.
### Comparações específicas por funcionalidade
Para comparações detalhadas, incluindo funcionalidades específicas de cada funcionalidade, diferenças na versão original e caminhos de migração, consulte:
+ [Comparação da funcionalidade do EKS para o ACK em relação ao ACK autogerenciado](ack-comparison.md)
+ [Comparação da funcionalidade do EKS para o Argo CD em relação ao Argo CD autogerenciado](argocd-comparison.md)
+ [Comparação da funcionalidade do EKS para o kro em relação ao kro autogerenciado](kro-comparison.md)
# 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
# Implantação contínua com o Argo CD
O Argo CD é uma ferramenta de entrega contínua declarativa e baseada em GitOps para Kubernetes. Com o Argo CD, você pode automatizar a implantação e o gerenciamento do ciclo de vida de suas aplicações em vários clusters e ambientes. O Argo CD oferece suporte a vários tipos de origem, incluindo repositórios do Git, registros do Helm (HTTP e OCI) e imagens OCI, proporcionando flexibilidade para organizações com requisitos de segurança e conformidade distintos.
Com as funcionalidades do EKS, o Argo CD é totalmente gerenciado pela AWS, o que elimina a necessidade de instalação, manutenção e escalabilidade dos controladores do Argo CD e de suas dependências nos clusters.
## Funcionamento do Argo CD
O Argo CD segue o padrão de GitOps, no qual a origem da sua aplicação (por exemplo, repositório do Git, registro do Helm ou imagem OCI) é a fonte da verdade para definir o estado desejado da aplicação. Ao criar um recurso `Application` do Argo CD, você especifica a origem que contém os manifestos da aplicação e o cluster e o namespace do Kubernetes de destino. O Argo CD monitora continuamente tanto a origem quanto o estado em execução no cluster, sincronizando automaticamente quaisquer alterações para garantir que o estado do cluster corresponda ao estado desejado.
**nota**
Com a funcionalidade do EKS para o Argo CD, o software do Argo CD é executado no ambiente de gerenciamento da AWS, e não em seus nós de processamento. Isso significa que os nós de processamento não precisam de acesso direto a repositórios do Git ou a registros do Helm, pois a funcionalidade gerencia o acesso à origem a partir da conta da AWS.
O Argo CD fornece três tipos de recursos primários:
+ **Application**: define uma implantação proveniente de um repositório do Git para um cluster de destino
+ **ApplicationSet**: gera diversas Applications usando modelos para implantações em vários clusters
+ **AppProject**: fornece agrupamento lógico e controle de acesso para as Applications
**Exemplo: criação de uma Application do Argo CD**
O exemplo a seguir mostra como criar um recurso `Application` do Argo CD:
```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: guestbook
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/argoproj/argocd-example-apps.git
targetRevision: HEAD
path: guestbook
destination:
name: in-cluster
namespace: guestbook
syncPolicy:
automated:
prune: true
selfHeal: true
```
**nota**
Use `destination.name` com o nome do cluster utilizado ao registrar o cluster (como `in-cluster` para o cluster local). O campo `destination.server` também funciona com ARNs de cluster de EKS, mas o uso de nomes de cluster é recomendado para melhor legibilidade.
## Benefícios do Argo CD
O Argo CD implementa um fluxo de trabalho de GitOps no qual você define as configurações da aplicação em repositórios do Git e o Argo CD sincroniza automaticamente as aplicações para corresponderem ao estado desejado. Essa abordagem centrada no Git fornece uma trilha de auditoria completa de todas as alterações, permite reversões fáceis e integra-se naturalmente aos seus processos existentes de revisão e aprovação de código. O Argo CD detecta e reconcilia automaticamente o desvio entre o estado desejado no Git e o estado real nos clusters, garantindo que as implantações permaneçam consistentes com a configuração declarada.
Com o Argo CD, é possível implantar e gerenciar aplicações em vários clusters usando uma única instância do Argo CD, simplificando as operações em ambientes com vários clusters e diversas regiões. A interface do usuário do Argo CD fornece funcionalidades de visualização e monitoramento, permitindo que você visualize o status da implantação, a integridade e o histórico das aplicações. A interface do usuário se integra ao Centro de Identidade da AWS (anteriormente AWS SSO) para autenticação e autorização simplificadas, permitindo que você controle o acesso com a infraestrutura de gerenciamento de identidades existente.
Como parte das funcionalidades gerenciadas do EKS, o Argo CD é totalmente gerenciado pela AWS, eliminando a necessidade de instalar, configurar e manter a infraestrutura do Argo CD. A AWS cuida da escalabilidade, da aplicação de patches e do gerenciamento operacional, permitindo que as equipes se concentrem na entrega de aplicações em vez da manutenção de ferramentas.
## Integração com o Centro de Identidade da AWS
As funcionalidades gerenciadas do EKS fornecem integração direta entre o Argo CD e o Centro de Identidade da AWS, permitindo autenticação e autorização simplificadas para os usuários. Ao habilitar a funcionalidade do Argo CD, é possível configurar a integração com o Centro de Identidade da AWS para mapear grupos e usuários do Centro de Identidade para perfis de RBAC do Argo CD, permitindo controlar quem pode acessar e gerenciar aplicações no Argo CD.
## Integração com outras funcionalidades gerenciadas do EKS
O Argo CD pode ser integrado a outras funcionalidades gerenciadas do EKS.
+ **AWS Controllers for Kubernetes (ACK)**: 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.
+ **kro (Kube Resource Orchestrator)**: use o Argo CD para implantar composições do kro em vários clusters, possibilitando uma composição de recursos consistente em todo o seu ambiente do Kubernetes.
## Conceitos básicos do Argo CD
Para começar a usar a funcionalidade do EKS para o Argo CD:
1. Crie e configure um perfil da funcionalidade do IAM com as permissões necessárias para que o Argo CD acesse suas fontes e gerencie aplicações
1. [Crie um recurso da funcionalidade do Argo CD](create-argocd-capability.md) em seu cluster de EKS por meio do Console da AWS, da AWS CLI ou da ferramenta de infraestrutura como código de sua preferência.
1. Configure o acesso ao repositório e registre os clusters para a implantação de aplicações.
1. Crie recursos de Application para implantar suas aplicações usando fontes declarativas.
# Criar um recurso Argo CD
Este tópico explica como criar uma funcionalidade do Argo CD no cluster do Amazon EKS.
## Pré-requisitos
Antes de criar uma funcionalidade do Argo CD, certifique-se de ter:
+ Um cluster do Amazon EKS existente executando uma versão compatível do Kubernetes (há suporte para todas as versões nos períodos de suporte padrão e estendido)
+ **Centro de Identidade da AWS configurado**: necessário para a autenticação do Argo CD (não há suporte para usuários locais)
+ Um perfil do IAM da funcionalidade com permissões para o Argo CD
+ Permissões do IAM suficientes para criar recursos de funcionalidades em clusters de EKS
+ `kubectl` configurado para o estabelecimento de comunicação com o cluster
+ (Opcional) A CLI do Argo CD instalada para facilitar o gerenciamento de clusters e repositórios
+ (Para a CLI ou o eksctl) A ferramenta de CLI apropriada instalada e configurada
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). Para obter a configuração do Centro de Identidade, consulte [Conceitos básicos do Centro de Identidade da AWS](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html).
**Importante**
O perfil do IAM para a funcionalidade que você fornece determina quais recursos da AWS o Argo CD pode acessar. Isso inclui o acesso a repositórios do Git por meio do CodeConnections e a segredos no Secrets Manager. 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 Argo CD por meio do Console de gerenciamento da AWS, da AWS CLI ou do eksctl:
+ [Criação de uma funcionalidade do Argo CD por meio do Console](argocd-create-console.md): use o Console para obter uma experiência guiada
+ [Criação de uma funcionalidade do Argo CD por meio da AWS CLI](argocd-create-cli.md): use a AWS CLI para obter scripts e automação
+ [Criação de uma funcionalidade do Argo CD por meio do eksctl](argocd-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 Argo CD
Ao criar uma funcionalidade do Argo CD:
1. O EKS cria o serviço da funcionalidade do Argo CD no ambiente de gerenciamento da AWS
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. O Argo CD começa a monitorar os recursos personalizados (ApplicationSets, AppProjects)
1. O status da funcionalidade é alterado de `CREATING` para `ACTIVE`
1. A interface de usuário do Argo CD torna-se acessível por meio de seu URL
Uma vez ativa, será possível criar Applications do Argo CD no seu cluster para realizar implantações a partir das suas fontes declarativas.
**nota**
A entrada de acesso criada automaticamente não concede permissões para implantar aplicações em clusters. Para implantar aplicações, é necessário configurar permissões de RBAC adicionais do Kubernetes para cada cluster de destino. Consulte [Registro de clusters de destino](argocd-register-clusters.md) para obter detalhes sobre como registrar clusters e configurar o acesso.
## Próximas etapas
Após criar a funcionalidade do Argo CD:
+ [Conceitos do Argo CD](argocd-concepts.md): aprenda sobre os princípios de GitOps, as políticas de sincronização e os padrões para vários clusters
+ [Como trabalhar com o Argo CD](working-with-argocd.md): configure o acesso ao repositório, registre os clusters de destino e crie Applications
+ [Considerações sobre o Argo CD](argocd-considerations.md): conheça os padrões de arquitetura de vários clusters e a configuração avançada
# Criação de uma funcionalidade do Argo CD por meio do Console
Este tópico descreve como criar uma funcionalidade do Argo CD usando o Console de gerenciamento da AWS.
## Pré-requisitos
+ **Centro de Identidade da AWS configurado**: o Argo CD requer o Centro de Identidade da AWS para autenticação. Não há suporte para usuários locais. Se você não tiver o Centro de Identidade da AWS configurado, consulte [Conceitos básicos do Centro de Identidade da AWS](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html) para criar uma instância do Centro de Identidade, e [Adicionar usuários](https://docs.aws.amazon.com/singlesignon/latest/userguide/addusers.html) e [Adicionar grupos](https://docs.aws.amazon.com/singlesignon/latest/userguide/addgroups.html) para criar usuários e grupos para acesso ao Argo CD.
## Criação da funcionalidade do Argo CD
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. Na barra de navegação à esquerda, selecione **Argo CD**.
1. Escolha **Criar funcionalidade do Argo CD**.
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 do Argo CD**
Isso abre o console do IAM em uma nova guia com a política de confiança preenchida previamente e fornece acesso total de leitura ao Secrets Manager. Nenhuma outra permissão é adicionada por padrão, mas você pode adicioná-las se necessário. Se você planeja usar repositórios do CodeCommit ou outros serviços da AWS, adicione as permissões adequadas antes de criar o perfil.
Após criar o perfil, retorne ao console do EKS e o perfil será selecionado automaticamente.
**nota**
Se você planeja usar as integrações opcionais com o AWS Secrets Manager ou o AWS CodeConnections, precisará adicionar permissões ao perfil. Para obter exemplos da política do IAM e de orientações de configuração, consulte [Gerenciamento de segredos de aplicações com o AWS Secrets Manager](integration-secrets-manager.md) e [Estabelecimento de conexão com repositórios do Git usando o AWS CodeConnections](integration-codeconnections.md).
1. Configure a integração com o Centro de Identidade da AWS:
1. Selecione **Habilitar integração com o Centro de Identidade da AWS**.
1. Escolha sua instância do Centro de Identidade no menu suspenso.
1. Configure os mapeamentos de perfil para RBAC atribuindo usuários ou grupos aos perfis do Argo CD (ADMIN, EDITOR ou VIEWER).
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 Argo CD.
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).
## Acesso à interface do usuário do Argo CD
Depois que a funcionalidade estiver ativa, você poderá acessar a interface do usuário do Argo CD:
1. Na página da funcionalidade do Argo CD, escolha **Abrir interface do usuário do Argo CD**.
1. A interface do usuário do Argo CD será aberta em uma nova guia do navegador.
1. Em seguida, você pode criar Applications e gerenciar implantações por meio da interface do usuário.
## Próximas etapas
+ [Como trabalhar com o Argo CD](working-with-argocd.md): configure repositórios, registre clusters e crie Applications
+ [Considerações sobre o Argo CD](argocd-considerations.md): acesse a arquitetura de vários clusters e a configuração avançada
+ [Como trabalhar com recursos de funcionalidade](working-with-capabilities.md): gerencie os recursos da funcionalidade do Argo CD
# Criação de uma funcionalidade do Argo CD por meio da AWS CLI
Este tópico descreve como criar uma funcionalidade do Argo CD 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).
+ **Centro de Identidade da AWS configurado**: o Argo CD requer o Centro de Identidade da AWS para autenticação. Não há suporte para usuários locais. Se você não tiver o Centro de Identidade da AWS configurado, consulte [Conceitos básicos do Centro de Identidade da AWS](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html) para criar uma instância do Centro de Identidade, e [Adicionar usuários](https://docs.aws.amazon.com/singlesignon/latest/userguide/addusers.html) e [Adicionar grupos](https://docs.aws.amazon.com/singlesignon/latest/userguide/addgroups.html) para criar usuários e grupos para acesso ao Argo CD.
## Etapa 1: criação de um perfil da funcionalidade do IAM
Crie um arquivo de política de confiança:
```
cat > argocd-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 ArgoCDCapabilityRole \
--assume-role-policy-document file://argocd-trust-policy.json
```
**nota**
Se você planeja usar as integrações opcionais com o AWS Secrets Manager ou o AWS CodeConnections, precisará adicionar permissões ao perfil. Para obter exemplos da política do IAM e de orientações de configuração, consulte [Gerenciamento de segredos de aplicações com o AWS Secrets Manager](integration-secrets-manager.md) e [Estabelecimento de conexão com repositórios do Git usando o AWS CodeConnections](integration-codeconnections.md).
## Etapa 2: criação da funcionalidade do Argo CD
Crie o recurso da funcionalidade do Argo CD no cluster.
Primeiro, defina as variáveis de ambiente para a sua configuração do Centro de Identidade:
```
# Get your Identity Center instance ARN (replace region if your IDC instance is in a different region)
export IDC_INSTANCE_ARN=$(aws sso-admin list-instances --region [.replaceable]`region` --query 'Instances[0].InstanceArn' --output text)
# Get a user ID for RBAC mapping (replace with your username and region if needed)
export IDC_USER_ID=$(aws identitystore list-users \
--region [.replaceable]`region` \
--identity-store-id $(aws sso-admin list-instances --region [.replaceable]`region` --query 'Instances[0].IdentityStoreId' --output text) \
--query 'Users[?UserName==`your-username`].UserId' --output text)
echo "IDC_INSTANCE_ARN=$IDC_INSTANCE_ARN"
echo "IDC_USER_ID=$IDC_USER_ID"
```
Crie a funcionalidade com integração ao Centro de Identidade. Substitua *region-code* pela região da AWS em que seu cluster está localizado e *my-cluster* pelo nome do seu cluster e *idc-region-code* pelo código da região em que seu Centro de Identidade do IAM foi configurado:
```
aws eks create-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-argocd \
--type ARGOCD \
--role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/ArgoCDCapabilityRole \
--delete-propagation-policy RETAIN \
--configuration '{
"argoCd": {
"awsIdc": {
"idcInstanceArn": "'$IDC_INSTANCE_ARN'",
"idcRegion": "'[.replaceable]`idc-region-code`'"
},
"rbacRoleMappings": [{
"role": "ADMIN",
"identities": [{
"id": "'$IDC_USER_ID'",
"type": "SSO_USER"
}]
}]
}
}'
```
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-cod*e pela região da AWS em que seu cluster está localizado e *my-cluster* pelo nome do seu cluster.
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-argocd \
--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-argocd
```
## Etapa 4: verificação da disponibilidade de recursos personalizados
Após a funcionalidade estar ativa, verifique se os recursos personalizados do Argo CD estão disponíveis no cluster:
```
kubectl api-resources | grep argoproj.io
```
Os tipos de recursos `Application` e `ApplicationSet` devem aparecer na lista apresentada.
## Próximas etapas
+ [Como trabalhar com o Argo CD](working-with-argocd.md): configure repositórios, registre clusters e crie Applications
+ [Considerações sobre o Argo CD](argocd-considerations.md): acesse a arquitetura de vários clusters e a configuração avançada
+ [Como trabalhar com recursos de funcionalidade](working-with-capabilities.md): gerencie os recursos da funcionalidade do Argo CD
# Criação de uma funcionalidade do Argo CD por meio do eksctl
Este tópico descreve como criar uma funcionalidade do Argo CD usando o eksctl.
**nota**
Para realizar as etapas seguintes, é necessário 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 > argocd-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 ArgoCDCapabilityRole \
--assume-role-policy-document file://argocd-trust-policy.json
```
**nota**
Para esta configuração básica, não são necessárias políticas do IAM adicionais. Se você planeja usar o Secrets Manager para credenciais de repositório ou para o CodeConnections, precisará adicionar permissões ao perfil. Para obter exemplos da política do IAM e de orientações de configuração, consulte [Gerenciamento de segredos de aplicações com o AWS Secrets Manager](integration-secrets-manager.md) e [Estabelecimento de conexão com repositórios do Git usando o AWS CodeConnections](integration-codeconnections.md).
## Etapa 2: obtenção da configuração do Centro de Identidade da AWS
Obtenha o ARN da instância do Centro de Identidade e o ID do usuário para a configuração de RBAC:
```
# Get your Identity Center instance ARN
aws sso-admin list-instances --query 'Instances[0].InstanceArn' --output text
# Get a user ID for admin access (replace 'your-username' with your Identity Center username)
aws identitystore list-users \
--identity-store-id $(aws sso-admin list-instances --query 'Instances[0].IdentityStoreId' --output text) \
--query 'Users[?UserName==`your-username`].UserId' --output text
```
Anote esses valores. Você precisará deles na próxima etapa.
## Etapa 3: criação de um arquivo de configuração do eksctl
Crie um arquivo chamado `argocd-capability.yaml` com o conteúdo a seguir. Substitua os valores com espaços reservados pelo nome do seu cluster, região, ARN do perfil do IAM, ARN da instância do Centro de Identidade, região do Centro de Identidade e ID do usuário:
```
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
name: my-cluster
region: cluster-region-code
capabilities:
- name: my-argocd
type: ARGOCD
roleArn: arn:aws:iam::[.replaceable]111122223333:role/ArgoCDCapabilityRole
deletePropagationPolicy: RETAIN
configuration:
argocd:
awsIdc:
idcInstanceArn: arn:aws:sso:::instance/ssoins-123abc
idcRegion: idc-region-code
rbacRoleMappings:
- role: ADMIN
identities:
- id: 38414300-1041-708a-01af-5422d6091e34
type: SSO_USER
```
**nota**
É possível adicionar vários usuários ou grupos aos mapeamentos de RBAC. Para grupos, use `type: SSO_GROUP` e forneça o ID do grupo. Os perfis disponíveis são `ADMIN`, `EDITOR` e `VIEWER`.
## Etapa 4: criação da funcionalidade do Argo CD
Aplique o arquivo de configuração:
```
eksctl create capability -f argocd-capability.yaml
```
O comando é executado de forma imediata, mas a funcionalidade demora algum tempo para se tornar ativa.
## Etapa 5: verificação da ativação da funcionalidade
Verifique o status da funcionalidade. Substitua *region-code* pela região AWS em que seu cluster se encontra e substitua *my-cluster* pelo nome do seu cluster.
```
eksctl get capability \
--region region-code \
--cluster my-cluster \
--name my-argocd
```
A funcionalidade estará pronta assim que o status mostrar `ACTIVE`.
## Etapa 6: verificação da disponibilidade de recursos personalizados
Após a funcionalidade estar ativa, verifique se os recursos personalizados do Argo CD estão disponíveis no cluster:
```
kubectl api-resources | grep argoproj.io
```
Os tipos de recursos `Application` e `ApplicationSet` devem aparecer na lista apresentada.
## Próximas etapas
+ [Como trabalhar com o Argo CD](working-with-argocd.md): aprenda a criar e gerenciar Applications do Argo CD
+ [Considerações sobre o Argo CD](argocd-considerations.md): configure o SSO e o acesso a vários clusters
+ [Como trabalhar com recursos de funcionalidade](working-with-capabilities.md): gerencie os recursos da funcionalidade do Argo CD
# Conceitos do Argo CD
O Argo CD implementa o GitOps ao tratar o Git como a única fonte de verdade para as implantações da aplicação. Este tópico apresenta um exemplo prático e, em seguida, explica os conceitos fundamentais que você precisa entender ao trabalhar com a funcionalidade do EKS para o Argo CD.
## Conceitos básicos do Argo CD
Após criar a funcionalidade do Argo CD (consulte [Criar um recurso Argo CD](create-argocd-capability.md)), é possível começar a implantar as aplicações. Este exemplo demonstra o registro de um cluster e a criação de uma Application.
### Etapa 1: Configurar
**Registrar o cluster** (obrigatório)
Registre o cluster no local em que você deseja implantar aplicações. Para este exemplo, registraremos o mesmo cluster em que o Argo CD está sendo executado (você pode usar o nome `in-cluster` para obter compatibilidade com a maioria dos exemplos do Argo CD):
```
# Get your cluster ARN
CLUSTER_ARN=$(aws eks describe-cluster \
--name my-cluster \
--query 'cluster.arn' \
--output text)
# Register the cluster using Argo CD CLI
argocd cluster add $CLUSTER_ARN \
--aws-cluster-name $CLUSTER_ARN \
--name in-cluster \
--project default
```
**nota**
Para obter informações sobre a configuração da CLI do Argo CD para trabalho com a funcionalidade do Argo CD no EKS, consulte [Uso da CLI do Argo CD com a funcionalidade gerenciada](argocd-comparison.md#argocd-cli-configuration).
Como alternativa, registre o cluster usando um Kubernetes Secret (consulte [Registro de clusters de destino](argocd-register-clusters.md) para obter mais detalhes).
**Configurar o acesso ao repositório** (opcional)
Este exemplo utiliza um repositório público do GitHub, portanto, nenhuma configuração de repositório é necessária. Para repositórios privados, configure o acesso usando o AWS Secrets Manager, o CodeConnections ou o Kubernetes Secrets (consulte [Configuração do acesso ao repositório](argocd-configure-repositories.md) para obter mais detalhes).
No caso de serviços da AWS (como ECR para charts do Helm, CodeConnections e CodeCommit), é possível referenciá-los diretamente nos recursos da Application sem precisar criar um Repository. O perfil da funcionalidade deve ter as permissões do IAM necessárias. Para mais detalhes, consulte [Configuração do acesso ao repositório](argocd-configure-repositories.md).
### Etapa 2: criar um aplicativo
Crie este manifesto da Application em `my-app.yaml`:
```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: guestbook
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/argoproj/argocd-example-apps.git
targetRevision: HEAD
path: guestbook
destination:
name: in-cluster
namespace: guestbook
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
```
Aplique a Application:
```
kubectl apply -f my-app.yaml
```
Após aplicar esta Application, o Argo CD: 1. Sincroniza a aplicação do Git com o cluster (implantação inicial) 2. Monitora o repositório do Git em busca de alterações 3. Sincroniza automaticamente as alterações posteriores com o seu cluster 4. Detecta e corrige qualquer desvio em relação ao estado desejado 5. Fornece o status da integridade e o histórico de sincronização na interface do usuário
Visualize o status da aplicação:
```
kubectl get application guestbook -n argocd
```
Também é possível visualizar a aplicação usando a CLI do Argo CD ou a interface do usuário do Argo CD (que é acessível a partir do console do EKS, na guia Funcionalidades do seu cluster).
**nota**
Ao usar a CLI do Argo CD com o recurso gerenciado, especifique as aplicações com o prefixo do namespace: `argocd app get argocd/guestbook`.
**nota**
Use o nome do cluster em `destination.name` (o nome que você utilizou ao registrar o cluster). A funcionalidade gerenciada não oferece suporte ao padrão local “in-cluster” (`kubernetes.default.svc`).
## Conceitos principais
### Princípios de GitOps e tipos de origem
O Argo CD implementa o GitOps, no qual a origem da sua aplicação é a única fonte de verdade para as implantações:
+ **Declarativo**: o estado desejado é declarado usando manifestos no formato YAML, charts do Helm ou sobreposições do Kustomize
+ **Versionado**: cada alteração é rastreada com uma trilha de auditoria completa
+ **Automatizado** o Argo CD monitora continuamente as origens e sincroniza as alterações automaticamente
+ **Autorreparação**: detecta e corrige desvios entre o estado desejado e o estado atual do cluster
**Tipos de origem com suporte**:
+ **Repositórios do Git**: GitHub, GitLab, Bitbucket, CodeCommit (HTTPS, SSH ou CodeConnections)
+ **Registros do Helm**: registros HTTP (como `https://aws.github.io/eks-charts`) e registros OCI (como `public.ecr.aws`)
+ **Imagens OCI**: imagens de contêiner contendo manifestos ou charts do Helm (como `oci://registry-1.docker.io/user/my-app`)
Essa flexibilidade permite que as organizações escolham origens que atendam aos seus requisitos de segurança e conformidade. Por exemplo, organizações que restringem o acesso ao Git proveniente de clusters podem usar o ECR para charts do Helm ou imagens OCI.
Para obter mais informações, consulte [Application Sources](https://argo-cd.readthedocs.io/en/stable/user-guide/application-sources/) na documentação do Argo CD.
### Sincronização e reconciliação
O Argo CD monitora continuamente as origens e os clusters para detectar e corrigir diferenças:
1. Realiza a verificação de alterações nas origens (padrão: a cada seis minutos)
1. Compara o estado desejado com o estado do cluster
1. Marca as aplicações como `Synced` ou `OutOfSync`
1. Sincroniza as alterações automaticamente (se configurado) ou aguarda aprovação manual
1. Monitora a integridade do recurso após a sincronização
Os **ciclos de sincronização** controlam a ordem de criação de recursos usando anotações:
```
metadata:
annotations:
argocd.argoproj.io/sync-wave: "0" # Default if not specified
```
Os recursos são aplicados na ordem do ciclo (com números menores primeiro, incluindo números negativos como `-1`). O ciclo `0` é o padrão, caso não seja especificado. Isso permite a criação de dependências, como namespaces (ciclo `-1`) antes das implantações (ciclo `0`) antes dos serviços (ciclo `1`).
A **autorreparação** reverte automaticamente as alterações manuais:
```
spec:
syncPolicy:
automated:
selfHeal: true
```
**nota**
A funcionalidade gerenciada usa o rastreamento de recursos baseado em anotações (em vez de empregar o rastreamento baseado em rótulos) para obter melhor compatibilidade com as convenções do Kubernetes e com as outras ferramentas.
Para obter informações detalhadas sobre as fases de sincronização, os hooks e os padrões avançados, consulte a [documentação de sincronização do Argo CD](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/).
### Integridade da aplicação
O Argo CD monitora a integridade de todos os recursos da aplicação:
**Status de integridade**: \$1 **Íntegro**: todos os recursos estão sendo executados conforme o esperado \$1 **Em progresso**: os recursos estão sendo criados ou atualizados \$1 **Degradado**: alguns recursos não estão íntegros (por exemplo, pods falhando e trabalhos com erros) \$1 **Suspenso**: a aplicação está pausada intencionalmente \$1 **Ausente**: os recursos definidos no Git não estão presentes no cluster
O Argo CD conta com verificações de integridade integradas para recursos comuns do Kubernetes (por exemplo, Deployments, StatefulSets, Jobs e outros) e oferece suporte a verificações de integridade personalizadas para CRDs.
A saúde da aplicação é determinada por todos os seus recursos. Dessa forma, se qualquer recurso estiver no estado `Degraded`, a aplicação será considerada `Degraded`.
Para obter mais informações, consulte [Resource Health](https://argo-cd.readthedocs.io/en/stable/operator-manual/health/) na documentação do Argo CD.
### Padrões de diversos clusters
O Argo CD é compatível com dois padrões principais de implantação:
**Hub-and-spoke**: execute o Argo CD em um cluster de gerenciamento dedicado que realiza a implantação para diversos clusters de workloads: \$1 Controle e visibilidade centralizados \$1 Políticas consistentes em todos os clusters \$1 Apenas uma instância do Argo CD para gerenciamento \$1 Separação clara entre o ambiente de gerenciamento e as workloads
**Por cluster**: execute o Argo CD em cada cluster, gerenciando apenas as aplicações daquele cluster específico: \$1 Isolamento de clusters (portanto, uma falha não afeta os demais) \$1 Rede simplificada (sem necessidade de comunicação entre clusters) \$1 Configuração inicial simplificada (sem necessidade de registro de clusters)
Escolha o modelo hub-and-spoke para equipes de plataformas que gerenciam muitos clusters ou o modelo por cluster para equipes independentes ou quando os clusters precisarem de isolamento total.
Para obter configurações detalhadas de diversos clusters, consulte [Considerações sobre o Argo CD](argocd-considerations.md).
### Projetos
Os Projects fornecem agrupamento lógico e controle de acesso para as Applications:
+ **Restrições de origem**: limitam quais repositórios do Git podem ser utilizados
+ **Restrições de destino**: limitam quais clusters e namespaces podem ser destinos de implantação
+ **Restrições de recursos**: limitam quais tipos de recursos do Kubernetes podem ser implantados
+ **Integração com o RBAC**: mapeia projetos para IDs de usuários e de grupos do Centro de Identidade da AWS
As Applications pertencem a um único projeto. Se não for especificado, elas utilizarão o projeto `default`, que não conta com restrições por padrão. Para uso em produção, edite o projeto `default` para restringir o acesso e criar novos projetos com as restrições apropriadas.
Para obter as configurações de projetos e os padrões de RBAC, consulte [Configuração das permissões do Argo CD](argocd-permissions.md).
### Opções de sincronização
Realize um ajuste fino do comportamento de sincronização com estas opções conhecidas:
+ `CreateNamespace=true`: cria automaticamente o namespace de destino
+ `ServerSideApply=true`: usa o Server-Side Apply para obter uma melhor resolução de conflitos
+ `SkipDryRunOnMissingResource=true`: ignora a simulação quando as CRDs ainda não existem (sendo útil para instâncias do kro)
```
spec:
syncPolicy:
syncOptions:
- CreateNamespace=true
- ServerSideApply=true
- SkipDryRunOnMissingResource=true
```
Para obter uma lista completa de opções de sincronização, consulte a [documentação de opções de sincronização do Argo CD](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/).
## Próximas etapas
+ [Configuração do acesso ao repositório](argocd-configure-repositories.md): configure o acesso ao repositório do Git
+ [Registro de clusters de destino](argocd-register-clusters.md): registre os clusters de destino para a implantação
+ [Criação de Applications](argocd-create-application.md): crie sua primeira Application
+ [Considerações sobre o Argo CD](argocd-considerations.md): acesse os padrões específicos para EKS, a integração com o Centro de Identidade e a configuração de diversos clusters
+ [Documentação do Argo CD](https://argo-cd.readthedocs.io/en/stable/): acesse a documentação abrangente do Argo CD, incluindo hooks de sincronização, verificações de integridade e padrões avançados
# Configuração das permissões do Argo CD
A funcionalidade gerenciada do Argo CD se integra ao Centro de Identidade da AWS para autenticação e usa perfis de RBAC integrados para autorização. Este tópico explica como configurar permissões para usuários e equipes.
## Funcionamento de permissões com o Argo CD
A funcionalidade do Argo CD usa o Centro de Identidade da AWS para autenticação e fornece três perfis de RBAC integrados para autorização.
Quando um usuário acessa o Argo CD:
1. A autenticação é realizada por meio do Centro de Identidade da AWS (que pode ser federado ao seu provedor de identidades corporativo)
1. O Centro de Identidade da AWS fornece informações de usuários e grupos ao Argo CD
1. O Argo CD mapeia usuários e grupos para perfis de RBAC com base na sua configuração
1. Os usuários visualizam somente as aplicações e os recursos aos quais têm permissão de acessar
## Perfis de RBAC integrados
A funcionalidade do Argo CD fornece três perfis integrados que você mapeia para usuários e grupos do Centro de Identidade da AWS. Esses são **perfis com escopo global** que controlam o acesso aos recursos do Argo CD, como projetos, clusters e repositórios.
**Importante**
Os perfis globais controlam o acesso ao próprio Argo CD, não aos recursos do escopo do projeto, como Applications. Os usuários EDITOR e VIEWER não podem ver nem gerenciar Applications por padrão, eles precisam de perfis no projeto para acessar os recursos do escopo do projeto. Consulte [Perfis do projeto e acesso ao escopo do projeto](#project-roles) para obter detalhes sobre como conceder acesso a Applications e outros recursos do escopo do projeto.
**ADMIN**
Acesso total a todos os recursos e configurações do Argo CD:
+ Criação, atualização e exclusão de Applications e ApplicationSets
+ Gerenciamento da configuração do Argo CD
+ Registro e gerenciamento de clusters de destino para implantação
+ Configuração do acesso ao repositório
+ Crie e gerencie projetos.
+ Visualização do status e do histórico de todas as aplicações
+ Liste e acesse todos os clusters e repositórios
**EDITOR**
Pode atualizar projetos e configurar perfis do projeto, mas não pode alterar as configurações globais do Argo CD:
+ Atualize projetos existentes (não é possível criar ou excluir projetos)
+ Configure perfis e permissões de projetos.
+ Visualize chaves e certificados GPG
+ Não é possível alterar a configuração do Argo CD
+ Não é possível gerenciar clusters ou repositórios diretamente
+ Não é possível ver ou gerenciar Applications sem perfis do projeto
**VIEWER**
Acesso somente de leitura a recursos do Argo CD:
+ Exiba a configuração do projeto
+ Liste todos os projetos (incluindo projetos aos quais o usuário não está atribuído)
+ Visualize chaves e certificados GPG
+ Sem permissão para o registro de clusters ou de repositórios
+ Sem permissão para a realização de quaisquer alterações
+ Não é possível ver ou gerenciar Applications sem perfis do projeto
**nota**
Para conceder aos usuários EDITOR ou VIEWER acesso a Applications, um ADMINISTRADOR ou EDITOR deve criar perfis do projeto que mapeiem os grupos do Centro de Identidade para permissões específicas em um projeto.
## Perfis do projeto e acesso ao escopo do projeto
Perfis globais (ADMIN, EDITOR e VIEWER) controlam o acesso ao Argo CD em si. Os perfis do projeto controlam o acesso a recursos e funcionalidades em um projeto específico, incluindo:
+ **Recursos**: Applications, ApplicationSets, credenciais do repositório, credenciais do cluster
+ **Funcionalidades**: acesso a registros, acesso executivo aos pods de aplicações
**Noções básicas sobre o modelo de permissão de dois níveis**:
+ **Escopo global**: perfis integrados determinam o que os usuários podem fazer com projetos, clusters, repositórios e configurações de CD do Argo
+ **Escopo do projeto**: os perfis do projeto determinam o que os usuários podem fazer com recursos e funcionalidades em um projeto específico
Isso significa que:
+ Os usuários ADMIN podem acessar todos os recursos e funcionalidades do projeto sem configuração adicional
+ Os usuários EDITOR e VIEWER devem receber perfis de projeto para acessar os recursos e funcionalidades do projeto
+ Os usuários EDITOR podem criar perfis do projeto para conceder a si mesmos e a outras pessoas acesso aos projetos que possam ser atualizados
**Exemplo de fluxo de trabalho**
1. Um ADMIN mapeia um grupo do Centro de Identidade para o perfil EDITOR globalmente
1. Um ADMINISTRADOR cria um projeto para uma equipe
1. O EDITOR configura os perfis do projeto dentro desse projeto para conceder aos membros da equipe acesso aos recursos do escopo do projeto
1. Os membros da equipe (que podem ter o perfil global VIEWER) agora podem ver e gerenciar aplicações nesse projeto com base nas permissões de perfil do projeto
Para obter detalhes sobre como configurar os perfis do projeto, consulte [Controle de acesso baseado em projetos](#_project_based_access_control).
## Configuração de mapeamentos de perfil
Mapeie usuários e grupos do Centro de Identidade da AWS para os perfis do Argo CD durante a criação ou a atualização da funcionalidade.
**Exemplo de mapeamento de perfil**:
```
{
"rbacRoleMapping": {
"ADMIN": ["AdminGroup", "alice@example.com"],
"EDITOR": ["DeveloperGroup", "DevOpsTeam"],
"VIEWER": ["ReadOnlyGroup", "bob@example.com"]
}
}
```
**nota**
Os nomes dos perfis diferenciam maiúsculas de minúsculas e devem estar em letras maiúsculas (ADMIN, EDITOR e VIEWER).
**Importante**
A integração das funcionalidades do EKS com o Centro de Identidade da AWS fornece suporte para até mil identidades por funcionalidade do Argo CD. Uma identidade pode ser um usuário ou um grupo.
**Atualize os mapeamentos de perfil**:
```
aws eks update-capability \
--region us-east-1 \
--cluster-name cluster \
--capability-name capname \
--endpoint "https://eks.ap-northeast-2.amazonaws.com" \
--role-arn "arn:aws:iam::[.replaceable]111122223333:role/[.replaceable]`EKSCapabilityRole`" \
--configuration '{
"argoCd": {
"rbacRoleMappings": {
"addOrUpdateRoleMappings": [
{
"role": "ADMIN",
"identities": [
{ "id": "686103e0-f051-7068-b225-e6392b959d9e", "type": "SSO_USER" }
]
}
]
}
}
}'
```
## Uso da conta de administrador
A conta de administrador é destinada à configuração inicial e às tarefas administrativas, como o registro de clusters e a configuração de repositórios.
**Situações apropriadas para o uso da conta de administrador**:
+ Configuração inicial da funcionalidade
+ Desenvolvimento individual ou demonstrações rápidas
+ Tarefas administrativas (como registro de cluster, configuração de repositórios e criação de projetos)
**Práticas recomendadas para a conta de administrador**:
+ Sem permissão para a confirmação de tokens da conta para o controle de versão
+ Rotação imediata de tokens em caso de exposição
+ Limitação do uso de tokens da conta para tarefas de configuração e de administração
+ Definição de prazos curtos de expiração (máximo de 12 horas)
+ Limite de criação de apenas cinco tokens simultâneos na conta
**Situações para uso do acesso baseado em projetos**:
+ Ambientes de desenvolvimento compartilhados com vários usuários
+ Qualquer ambiente com características do ambiente de produção
+ Quando há necessidade de trilhas de auditoria para identificação de ações por parte dos usuários
+ Quando há necessidade da aplicação de restrições de recursos ou limites de acesso
Para ambientes de produção e cenários com vários usuários, use o controle de acesso baseado em projetos com perfis de RBAC dedicados e mapeados para grupos do Centro de Identidade da AWS.
## Controle de acesso baseado em projetos
Use o Argo CD Projects (AppProject) para a disponibilização de controle de acesso detalhado e isolamento de recursos para as equipes.
**Importante**
Antes de atribuir usuários ou grupos aos perfis específicos do projeto, é necessário primeiro mapeá-los para um perfil global do Argo CD (ADMIN, EDITOR ou VIEWER) na configuração do recurso. Os usuários não podem acessar o Argo CD sem um mapeamento global de perfis, mesmo que estejam atribuídos aos perfis do projeto.
Considere mapear usuários para o perfil VIEWER globalmente e, em seguida, conceder permissões adicionais por meio de perfis específicos do projeto. Isso fornece acesso básico e, ao mesmo tempo, permite um controle refinado no nível do projeto.
Os projetos fornecem:
+ **Restrições de origem**: limitam quais repositórios do Git podem ser utilizados
+ **Restrições de destino**: limitam quais clusters e namespaces podem ser destinos de implantação
+ **Restrições de recursos**: limitam quais tipos de recursos do Kubernetes podem ser implantados
+ **Integração de RBAC**: mapeamento de projetos para grupos do Centro de Identidade da AWS ou perfis do Argo CD
**Exemplo de projeto para isolamento de equipes**:
```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: team-a
namespace: argocd
spec:
description: Team A applications
# Required: Specify which namespaces this project watches for Applications
sourceNamespaces:
- argocd
# Source restrictions
sourceRepos:
- https://github.com/myorg/team-a-apps
# Destination restrictions
destinations:
- namespace: team-a-*
server: arn:aws:eks:us-west-2:111122223333:cluster/production
# Resource restrictions
clusterResourceWhitelist:
- group: ''
kind: Namespace
namespaceResourceWhitelist:
- group: 'apps'
kind: Deployment
- group: ''
kind: Service
- group: ''
kind: ConfigMap
```
### Namespaces da origem
Ao usar a funcionalidade EKS do Argo CD, o campo `spec.sourceNamespaces` é obrigatório nas definições de AppProject. Esse campo especifica qual namespace pode conter Applications or ApplicationSets que façam referência a esse projeto.
**Importante**
A funcionalidade EKS do Argo CD oferece suporte a apenas um único namespace para Applications and ApplicationSets, o namespace que você especificou ao criar a funcionalidade (normalmente `argocd`). Isso difere do Argo CD de código aberto, que oferece suporte a vários namespaces.
**Configuração do AppProject**
Todos os AppProjects devem incluir o namespace configurado da funcionalidade em `sourceNamespaces`:
```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: team-a-project
namespace: argocd
spec:
description: Applications for Team A
# Required: Specify the capability's configured namespace (configuration.argoCd.namespace)
sourceNamespaces:
- argocd # Must match your capability's namespace configuration
# Source repositories this project can deploy from
sourceRepos:
- 'https://github.com/my-org/team-a-*'
# Destination restrictions
destinations:
- namespace: 'team-a-*'
server: arn:aws:eks:us-west-2:111122223333:cluster/my-cluster
```
**nota**
Se você omitir o namespace da funcionalidade de `sourceNamespaces`, Applications ou ApplicationSets nesse namespace não poderão referenciar esse projeto, resultando em falhas de implantação.
**Atribua usuários a projetos**:
Os perfis do projeto concedem aos usuários EDITOR e VIEWER acesso aos recursos do projeto (Applications, ApplicationSets, credenciais de repositório e cluster) e funcionalidades (logs, exec). Sem os perfis do projeto, esses usuários não podem acessar esses recursos, mesmo que tenham acesso global ao perfil.
Usuários com perfil de ADMIN têm acesso a todas as Applications sem precisar de perfis do projeto.
**Exemplo: concessão de acesso a Applications aos membros da equipe**
```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: team-a
namespace: argocd
spec:
# ... project configuration ...
sourceNamespaces:
- argocd
# Project roles grant Application-level access
roles:
- name: developer
description: Team A developers - can manage Applications
policies:
- p, proj:team-a:developer, applications, *, team-a/*, allow
- p, proj:team-a:developer, clusters, get, *, allow # See cluster names in UI
groups:
- 686103e0-f051-7068-b225-e6392b959d9e # Identity Center group ID
- name: viewer
description: Team A viewers - read-only Application access
policies:
- p, proj:team-a:viewer, applications, get, team-a/*, allow
- p, proj:team-a:viewer, clusters, get, *, allow # See cluster names in UI
groups:
- 786203e0-f051-7068-b225-e6392b959d9f # Identity Center group ID
```
**nota**
Inclua `clusters, get, *, allow` nos perfis do projeto para permitir que os usuários vejam os nomes dos clusters na interface do usuário. Sem essa permissão, o cluster de destino será exibido como “desconhecido”.
**Noções básicas das políticas de perfis do projeto**:
O formato da política é: `p, proj::, , ,