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.

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), 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.

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:

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:

Para saber mais sobre como o ACK funciona, consulte ACK 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.

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.

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.

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:

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:

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.

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. Para obter detalhes sobre a configuração entre contas, consulte Configuração das permissões do ACK.

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:

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.

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.

Próximas etapas