**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.
# Composição de recursos com o kro (Kube Resource Orchestrator)
O **kro (Kube Resource Orchestrator**) é um projeto de código aberto nativo do Kubernetes que permite definir APIs personalizadas do Kubernetes usando uma configuração simples e direta. Com o kro, é fácil configurar novas APIs personalizadas para criar grupos de objetos do Kubernetes e definir operações lógicas entre esses recursos.
Com as funcionalidades do EKS, o kro torna-se uma funcionalidade totalmente gerenciada pela AWS, dispensando a instalação, a manutenção e a escalabilidade de controladores do kro nos clusters.
## Funcionamento do kro
O kro introduz uma definição de recurso personalizado (CRD, na sigla em inglês), chamada `ResourceGraphDefinition` (RGD), que viabiliza a criação simples e otimizada de APIs personalizadas do Kubernetes. Ao criar uma `ResourceGraphDefinition`, o kro usa extensões nativas do Kubernetes para a criação e o gerenciamento de novas APIs no cluster. A partir desta especificação exclusiva de recurso, o kro criará e registrará uma nova CRD para você com base na sua especificação e se adaptará para gerenciar os recursos personalizados definidos recentemente.
As RGDs podem conter vários recursos, cabendo ao kro determinar as interdependências e a sequência de criação de recursos, para que você não precise fazer isso. É possível usar uma sintaxe simples para injetar configurações de um recurso em outro, simplificando significativamente as composições e eliminando a necessidade de operadores de integração no cluster. Com o kro, os recursos personalizados podem incluir tanto recursos nativos do Kubernetes quanto quaisquer definições de recursos personalizados (CRDs) instaladas no cluster.
O kro oferece suporte a um tipo principal de recurso:
+ **ResourceGraphDefinition (RGD)**: define um recurso personalizado do Kubernetes, encapsulando um ou mais recursos nativos ou personalizados subjacentes
Além deste recurso, o kro criará e gerenciará o ciclo de vida dos recursos personalizados criados com ele, bem como de todos os recursos constituintes.
O kro se integra perfeitamente ao AWS Controllers for Kubernetes (ACK), permitindo que você componha recursos de workloads com recursos da AWS para criar abstrações de alto nível. Isso possibilita a criação de seus próprios blocos de criação na nuvem, simplificando o gerenciamento de recursos e permitindo padrões reutilizáveis com configurações padrão e imutáveis, baseadas nos padrões da organização.
## Benefícios do kro
Com o kro, as equipes responsáveis pela plataforma podem criar APIs personalizadas do Kubernetes que agrupam vários recursos em abstrações de alto nível. Isso simplifica o gerenciamento de recursos ao permitir que desenvolvedores implantem aplicações complexas por meio de recursos personalizados que são simples, padronizados e versionados. Você define padrões reutilizáveis para combinações comuns de recursos, permitindo a criação consistente de recursos em toda a organização.
O kro faz uso da [Common Expression Language (CEL) no Kubernetes](https://kubernetes.io/docs/reference/using-api/cel/) para a transferência de valores entre recursos e inclusão de lógica condicional, conferindo maior flexibilidade à composição de recursos. É possível compor tanto recursos do Kubernetes quanto recursos da AWS gerenciados pelo ACK em APIs personalizadas unificadas, permitindo definições completas de aplicação e de infraestrutura.
O kro oferece suporte à configuração declarativa por meio de 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. Como parte das funcionalidades do EKS, o kro é totalmente gerenciado pela AWS, dispensando a instalação, a configuração e a manutenção de controladores do kro nos clusters.
**Exemplo: criação de uma ResourceGraphDefinition**
O seguinte exemplo apresenta uma `ResourceGraphDefinition` simples para a criação de uma aplicação web contendo um Deployment e um Service:
```
apiVersion: kro.run/v1alpha1
kind: ResourceGraphDefinition
metadata:
name: web-application
spec:
schema:
apiVersion: v1alpha1
kind: WebApplication
spec:
name: string
replicas: integer | default=3
resources:
- id: deployment
template:
apiVersion: apps/v1
kind: Deployment
metadata:
name: ${schema.spec.name}
spec:
replicas: ${schema.spec.replicas}
- id: service
template:
apiVersion: v1
kind: Service
metadata:
name: ${schema.spec.name}
```
Quando os usuários criam instâncias do recurso personalizado `WebApplication`, o kro cria automaticamente os recursos correspondentes de Deployment e Service, gerenciando o ciclo de vida junto com o do recurso personalizado.
## Integração com outras funcionalidades gerenciadas do EKS
O kro pode ser integrado a outras funcionalidades gerenciadas do EKS.
+ **AWS Controllers for Kubernetes (ACK)**: use o kro para compor recursos do ACK em abstrações de alto nível, simplificando o gerenciamento de recursos da AWS.
+ **Argo CD**: use o Argo CD para gerenciar a implantação de recursos personalizados do kro em diversos clusters, possibilitando fluxos de trabalho GitOps para os blocos de criação de plataforma e de pilhas de aplicações.
## Conceitos básicos do kro
Para começar a usar a funcionalidade do EKS para o kro:
1. [Crie um recurso da funcionalidade do kro](create-kro-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. Crie ResourceGraphDefinitions (RGDs) que definam APIs personalizadas e composições de recursos.
1. Aplique instâncias dos recursos personalizados para realizar o provisionamento e o gerenciamento dos recursos subjacentes do Kubernetes e da AWS.
# Criação de uma funcionalidade do kro
Este tópico explica como criar uma funcionalidade do kro no cluster do Amazon EKS.
## Pré-requisitos
Antes de criar uma funcionalidade do kro, 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)
+ Permissões do IAM suficientes para criar recursos de funcionalidades em clusters de EKS
+ (Para a CLI ou o eksctl) A ferramenta de CLI apropriada instalada e configurada
**nota**
Ao contrário do ACK e do Argo CD, o kro não requer permissões do IAM adicionais além da política de confiança. O kro opera inteiramente no cluster e não faz chamadas de API da AWS. Contudo, ainda é necessário fornecer um perfil do IAM para a funcionalidade com a política de confiança apropriada. Para obter informações sobre como configurar as permissões de RBAC do Kubernetes para o kro, consulte [Configuração de permissões do kro](kro-permissions.md).
## Escolha da ferramenta
É possível criar uma funcionalidade do kro por meio do Console de gerenciamento da AWS, da AWS CLI ou do eksctl:
+ [Criação de uma funcionalidade do kro por meio do Console](kro-create-console.md): use o Console para obter uma experiência guiada
+ [Criação de uma funcionalidade do kro por meio da AWS CLI](kro-create-cli.md): use a AWS CLI para obter scripts e automação
+ [Criação de uma funcionalidade do kro por meio do eksctl](kro-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 kro
Ao criar uma funcionalidade do kro:
1. O EKS cria o serviço da funcionalidade do kro 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 a `AmazonEKSKROPolicy`, que concede permissões para gerenciar ResourceGraphDefinitions e suas instâncias (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ê (e é usado somente para a relação de confiança)
1. O kro começa a monitorar recursos da `ResourceGraphDefinition` e as respectivas instâncias
1. O status da funcionalidade é alterado de `CREATING` para `ACTIVE`
Uma vez ativa, é possível criar ResourceGraphDefinitions para definir APIs personalizadas e criar instâncias dessas APIs.
**nota**
A entrada de acesso criada automaticamente inclui a `AmazonEKSKROPolicy`, que concede permissões do kro para gerenciar ResourceGraphDefinitions e suas instâncias. Para permitir que o kro crie os recursos subjacentes do Kubernetes definidos em suas ResourceGraphDefinitions (como Deployments, Services ou recursos do ACK), é necessário configurar políticas de entrada de acesso adicionais. Para saber mais sobre entradas de acesso e como configurar permissões adicionais, consulte [Configuração de permissões do kro](kro-permissions.md) e [Considerações sobre segurança para funcionalidades do EKS](capabilities-security.md).
## Próximas etapas
Após criar a funcionalidade do kro:
+ [Conceitos do kro](kro-concepts.md): compreenda os conceitos do kro e a composição de recursos
+ [Conceitos do kro](kro-concepts.md): saiba mais sobre o SimpleSchema, expressões CEL e padrões de composição de recursos
# Criação de uma funcionalidade do kro por meio do Console
Este tópico descreve como criar uma funcionalidade do kro (Kube Resource Orchestrator) usando o Console de gerenciamento da AWS.
## Criação da funcionalidade do kro
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 **kro (Kube Resource Orchestrator)**.
1. Selecione **Criar funcionalidade do kro**.
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 kro**
Isso abre o console do IAM em uma nova guia com a política de confiança preenchida previamente. O perfil não requer permissões do IAM adicionais, uma vez que o kro opera inteiramente no cluster.
Após criar o perfil, retorne ao console do EKS e o perfil será selecionado automaticamente.
**nota**
Ao contrário do ACK e do Argo CD, o kro não requer permissões do IAM adicionais além da política de confiança. O kro opera inteiramente no cluster e não faz chamadas de API da AWS.
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 kro.
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).
## Concessão de permissões para o gerenciamento de recursos do Kubernetes
Quando você cria um recurso kro, uma entrada de acesso do EKS é criada automaticamente com a `AmazonEKSKROPolicy`, o que permite que o kro gerencie ResourceGraphDefinitions e suas instâncias. Contudo, nenhuma permissão é concedida por padrão para criar os recursos subjacentes do Kubernetes (como implantações, serviços, ConfigMaps etc.) definidos em suas ResourceGraphDefinitions.
Esse design intencional segue o princípio de privilégio mínimo, em que definições de gráficos de recursos diferentes exigem permissões diferentes. É necessário configurar explicitamente as permissões de que o kro precisa com base nos recursos que suas ResourceGraphDefinitions gerenciarão.
Para começar rapidamente, testar ou desenvolver ambientes, use a `AmazonEKSClusterAdminPolicy`:
1. No console do EKS, acesse a guia **Acesso** do cluster.
1. Em **Entradas de acesso**, localize a entrada referente ao perfil da funcionalidade para o kro (ela terá o ARN do perfil que você criou anteriormente).
1. Selecione a entrada de acesso para visualizar os detalhes.
1. Na seção **Políticas de acesso**, escolha **Associar política de acesso**.
1. Selecione `AmazonEKSClusterAdminPolicy` na lista de políticas.
1. Em **Escopo de acesso**, selecione **Cluster**.
1. Selecione **Associar**.
**Importante**
A `AmazonEKSClusterAdminPolicy` concede permissões abrangentes para criar e gerenciar todos os recursos do Kubernetes, incluindo a capacidade de criar qualquer tipo de recurso em todos os namespaces. Isso é conveniente para desenvolvimento e POCs, mas não deve ser usado em ambientes de produção. Para ambientes de produção, crie políticas de RBAC personalizadas que concedam somente as permissões necessárias para os recursos específicos que as ResourceGraphDefinitions gerenciarão. Para obter orientações sobre como configurar permissões de privilégio mínimo, consulte [Configuração de permissões do kro](kro-permissions.md) e [Considerações sobre segurança para funcionalidades do EKS](capabilities-security.md).
## Verificação da disponibilidade de recursos personalizados
Após a funcionalidade estar ativa, verifique se os recursos personalizados do kro 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**
O tipo de recurso `ResourceGraphDefinition` deve aparecer na lista apresentada.
**Uso do kubectl**
```
kubectl api-resources | grep kro.run
```
O tipo de recurso `ResourceGraphDefinition` deve aparecer na lista apresentada.
## Próximas etapas
+ [Conceitos do kro](kro-concepts.md): compreenda os conceitos do kro e a composição de recursos
+ [Conceitos do kro](kro-concepts.md): saiba mais sobre o SimpleSchema, expressões CEL e padrões de composição
+ [Como trabalhar com recursos de funcionalidade](working-with-capabilities.md): gerencie os recursos da funcionalidade do kro
# Criação de uma funcionalidade do kro por meio da AWS CLI
Este tópico descreve como criar uma funcionalidade do kro (Kube Resource Orchestrator) 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 > kro-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 KROCapabilityRole \
--assume-role-policy-document file://kro-trust-policy.json
```
**nota**
Ao contrário do ACK e do Argo CD, o kro não requer permissões do IAM adicionais. O kro opera inteiramente no cluster e não faz chamadas de API da AWS. O perfil é exigido exclusivamente para configurar a relação de confiança com o serviço de funcionalidades do EKS.
## Etapa 2: criação da funcionalidade do kro
Crie o recurso da funcionalidade do kro no cluster. Substitua *region-cod*e pela região da AWS em que seu cluster está localizado (por exemplo, `us-west-2`) e *my-cluster* pelo nome do seu cluster.
```
aws eks create-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-kro \
--type KRO \
--role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/KROCapabilityRole \
--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-kro \
--query 'capability.status' \
--output text
```
A funcionalidade estará pronta assim que o status mostrar `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-kro
```
## Etapa 4: concessão de permissões para o gerenciamento de recursos do Kubernetes
Quando você cria um recurso kro, uma entrada de acesso do EKS é criada automaticamente com a `AmazonEKSKROPolicy`, o que permite que o kro gerencie ResourceGraphDefinitions e suas instâncias. Contudo, nenhuma permissão é concedida por padrão para criar os recursos subjacentes do Kubernetes (como implantações, serviços, ConfigMaps etc.) definidos em suas ResourceGraphDefinitions.
Esse design intencional segue o princípio de privilégio mínimo, em que definições de gráficos de recursos diferentes exigem permissões diferentes. Por exemplo: \$1 Uma ResourceGraphDefinition que crie somente ConfigMaps e Segredos precisa de permissões diferentes daquela que cria Implantações e Serviços \$1 Uma ResourceGraphDefinition que cria recursos de ACK precisa de permissões para esses recursos personalizados específicos \$1 Algumas ResourceGraphDefinitions só podem ler recursos existentes sem criar novos
É necessário configurar explicitamente as permissões de que o kro precisa com base nos recursos que suas ResourceGraphDefinitions gerenciarão.
### Configuração rápida
Para começar rapidamente, testar ou desenvolver ambientes, use a `AmazonEKSClusterAdminPolicy`:
Obtenha o ARN do perfil da funcionalidade:
```
CAPABILITY_ROLE_ARN=$(aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-kro \
--query 'capability.roleArn' \
--output text)
```
Associe a política de administrador do cluster:
```
aws eks associate-access-policy \
--region region-code \
--cluster-name my-cluster \
--principal-arn $CAPABILITY_ROLE_ARN \
--policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \
--access-scope type=cluster
```
**Importante**
A `AmazonEKSClusterAdminPolicy` concede permissões abrangentes para criar e gerenciar todos os recursos do Kubernetes, incluindo a capacidade de criar qualquer tipo de recurso em todos os namespaces. Isso é conveniente para desenvolvimento e POCs, mas não deve ser usado em ambientes de produção. Para ambientes de produção, crie políticas de RBAC personalizadas que concedam somente as permissões necessárias para os recursos específicos que as ResourceGraphDefinitions gerenciarão. Para obter orientações sobre como configurar permissões de privilégio mínimo, consulte [Configuração de permissões do kro](kro-permissions.md) e [Considerações sobre segurança para funcionalidades do EKS](capabilities-security.md).
## Etapa 5: verificação da disponibilidade de recursos personalizados
Após a funcionalidade estar ativa, verifique se os recursos personalizados do kro estão disponíveis no cluster:
```
kubectl api-resources | grep kro.run
```
O tipo de recurso `ResourceGraphDefinition` deve aparecer na lista apresentada.
## Próximas etapas
+ [Conceitos do kro](kro-concepts.md): compreenda os conceitos do kro e a composição de recursos
+ [Conceitos do kro](kro-concepts.md): saiba mais sobre o SimpleSchema, expressões CEL e padrões de composição
+ [Como trabalhar com recursos de funcionalidade](working-with-capabilities.md): gerencie os recursos da funcionalidade do kro
# Criação de uma funcionalidade do kro por meio do eksctl
Este tópico descreve como criar uma funcionalidade do kro (Kube Resource Orchestrator) 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 > kro-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 KROCapabilityRole \
--assume-role-policy-document file://kro-trust-policy.json
```
**nota**
Ao contrário do ACK e do Argo CD, o kro não requer permissões do IAM adicionais além da política de confiança. O kro opera inteiramente no cluster e não faz chamadas de API da AWS.
## Etapa 2: criação da funcionalidade do kro
Crie a funcionalidade do kro 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 \
--region region-code \
--cluster my-cluster \
--name my-kro \
--type KRO \
--role-arn arn:aws:iam::[.replaceable]111122223333:role/KROCapabilityRole
```
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. 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-kro
```
A funcionalidade estará pronta assim que o status mostrar `ACTIVE`.
## Etapa 4: concessão de permissões para o gerenciamento de recursos do Kubernetes
Por padrão, o kro pode apenas criar e gerenciar ResourceGraphDefinitions e suas respectivas instâncias. Para permitir que o kro crie e gerencie os recursos subjacentes do Kubernetes definidos em suas ResourceGraphDefinitions, associe a política de acesso `AmazonEKSClusterAdminPolicy` à entrada de acesso da funcionalidade.
Obtenha o ARN do perfil da funcionalidade:
```
CAPABILITY_ROLE_ARN=$(aws eks describe-capability \
--region region-code \
--cluster my-cluster \
--name my-kro \
--query 'capability.roleArn' \
--output text)
```
Associe a política de administrador do cluster:
```
aws eks associate-access-policy \
--region region-code \
--cluster my-cluster \
--principal-arn $CAPABILITY_ROLE_ARN \
--policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \
--access-scope type=cluster
```
**Importante**
A política `AmazonEKSClusterAdminPolicy` concede permissões abrangentes para criar e gerenciar todos os recursos do Kubernetes e tem como objetivo agilizar os primeiros passos. Para uso em ambientes de produção, crie políticas de RBAC mais restritivas que concedam somente as permissões necessárias para os recursos específicos que as ResourceGraphDefinitions gerenciarão. Para obter orientações sobre como configurar permissões de privilégio mínimo, consulte [Configuração de permissões do kro](kro-permissions.md) e [Considerações sobre segurança para funcionalidades do EKS](capabilities-security.md).
## Etapa 5: verificação da disponibilidade de recursos personalizados
Após a funcionalidade estar ativa, verifique se os recursos personalizados do kro estão disponíveis no cluster:
```
kubectl api-resources | grep kro.run
```
O tipo de recurso `ResourceGraphDefinition` deve aparecer na lista apresentada.
## Próximas etapas
+ [Conceitos do kro](kro-concepts.md): compreenda os conceitos do kro e a composição de recursos
+ [Conceitos do kro](kro-concepts.md): saiba mais sobre o SimpleSchema, expressões CEL e padrões de composição
+ [Como trabalhar com recursos de funcionalidade](working-with-capabilities.md): gerencie os recursos da funcionalidade do kro
# Conceitos do kro
Com o kro, as equipes responsáveis pela plataforma podem criar APIs personalizadas do Kubernetes que agrupam vários recursos em abstrações de alto nível. 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 kro.
## Conceitos básicos do kro
Após criar a funcionalidade kro (consulte [Criação de uma funcionalidade do kro](create-kro-capability.md)), você poderá iniciar a criação de APIs personalizadas usando ResourceGraphDefinitions no cluster.
A seguir, apresentamos um exemplo completo que cria uma abstração simples de uma aplicação web:
```
apiVersion: kro.run/v1alpha1
kind: ResourceGraphDefinition
metadata:
name: webapplication
spec:
schema:
apiVersion: v1alpha1
kind: WebApplication
group: kro.run
spec:
name: string | required=true
image: string | default="nginx:latest"
replicas: integer | default=3
resources:
- id: deployment
template:
apiVersion: apps/v1
kind: Deployment
metadata:
name: ${schema.spec.name}
spec:
replicas: ${schema.spec.replicas}
selector:
matchLabels:
app: ${schema.spec.name}
template:
metadata:
labels:
app: ${schema.spec.name}
spec:
containers:
- name: app
image: ${schema.spec.image}
ports:
- containerPort: 80
- id: service
template:
apiVersion: v1
kind: Service
metadata:
name: ${schema.spec.name}
spec:
selector:
app: ${schema.spec.name}
ports:
- protocol: TCP
port: 80
targetPort: 80
```
Após aplicar esta ResourceGraphDefinition, as equipes responsáveis pela aplicação poderão criar aplicações web empregando a API simplificada:
```
apiVersion: kro.run/v1alpha1
kind: WebApplication
metadata:
name: my-app
spec:
name: my-app
replicas: 5
```
O kro cria automaticamente “Deployment” e “Service” com a configuração apropriada. Como `image` não foi especificado, o valor padrão `nginx:latest`, definido no esquema, é usado.
## Conceitos principais
**Importante**
O kro valida as ResourceGraphDefinitions no momento da criação, e não no runtime. Quando você cria uma RGD, o kro valida a sintaxe CEL, realiza a checagem de tipos das expressões em relação aos esquemas reais do Kubernetes, verifica a existência dos campos e detecta dependências circulares. Isso significa que os erros são capturados imediatamente ao criar a RGD, antes mesmo que qualquer instância seja implantada.
### ResourceGraphDefinition
Uma ResourceGraphDefinition (RGD) define uma API personalizada do Kubernetes ao especificar:
+ **Esquema**: a estrutura da API usando o formato SimpleSchema (que engloba nomes de campo, tipos, valores padrão e validação)
+ **Recursos**: modelos para os recursos subjacentes do Kubernetes ou da AWS que serão criados
+ **Dependências**: maneira como os recursos se relacionam entre si (detectadas automaticamente com base nas referências de campos)
Quando você aplica uma RGD, o kro registra uma nova definição de recurso personalizado (CRD, na sigla em inglês) no cluster. Em seguida, as equipes responsáveis pela aplicação podem criar instâncias da API personalizada, e o kro assume a criação e o gerenciamento de todos os recursos subjacentes.
Para obter mais informações, consulte [ResourceGraphDefinition Overview](https://kro.run/docs/concepts/rgd/overview/) na documentação do kro.
### Formato SimpleSchema
O SimpleSchema oferece uma maneira simplificada de definir esquemas de API sem a necessidade da OpenAPI completa:
```
schema:
apiVersion: v1alpha1
kind: Database
spec:
name: string | required=true description="Database name"
size: string | default="small" enum=small,medium,large
replicas: integer | default=1 minimum=1 maximum=5
```
O SimpleSchema fornece suporte para os tipos `string`, `integer`, `boolean` e `number`, com restrições como `required`, `default`, `minimum`/`maximum`, `enum` e `pattern`.
Para obter mais informações, consulte a seção [SimpleSchema](https://kro.run/docs/concepts/rgd/schema/) na documentação do kro.
### Expressões CEL
O kro utiliza a Common Expression Language (CEL) para referenciar valores dinamicamente e adicionar lógica condicional. As expressões CEL são envolvidas por `${` e `}`, e podem ser usadas de duas formas:
**Expressões autônomas**: o valor total do campo é composto por uma única expressão:
```
spec:
replicas: ${schema.spec.replicaCount} # Expression returns integer
labels: ${schema.spec.labelMap} # Expression returns object
```
O resultado da expressão substitui o valor total do campo e deve corresponder ao tipo esperado para o campo.
**Modelos de string**: uma ou mais expressões incorporadas em uma string:
```
metadata:
name: "${schema.spec.prefix}-${schema.spec.name}" # Multiple expressions
annotation: "Created by ${schema.spec.owner}" # Single expression in string
```
Todas as expressões nos modelos de string devem retornar strings. Use `string()` para converter outros tipos: `"replicas-${string(schema.spec.count)}"`.
**Referências de campos**: acesse os valores de especificação da instância usando `schema.spec`:
```
template:
metadata:
name: ${schema.spec.name}-deployment
namespace: ${schema.metadata.namespace} # Can also reference metadata
spec:
replicas: ${schema.spec.replicas}
```
**Acesso opcional ao campo**: use o operador `?` para campos que podem não existir:
```
# For ConfigMaps or Secrets with unknown structure
value: ${configmap.data.?DATABASE_URL}
# For optional status fields
ready: ${deployment.status.?readyReplicas > 0}
```
Se o campo não existir, a expressão retornará `null` em vez de gerar uma falha.
**Recursos condicionais**: inclua recursos somente quando condições específicas forem atendidas:
```
resources:
- id: ingress
includeWhen:
- ${schema.spec.enableIngress == true}
template:
# ... ingress configuration
```
O `includeWhen` campo aceita uma lista de expressões booleanas. Todas as condições devem ser verdadeiras para que o recurso seja criado. No momento, `includeWhen` permite referenciar apenas os campos contidos na `schema.spec`.
**Transformações**: altere valores usando funções e operadores ternários:
```
template:
spec:
resources:
requests:
memory: ${schema.spec.size == "small" ? "512Mi" : "2Gi"}
# String concatenation
image: ${schema.spec.registry + "/" + schema.spec.imageName}
# Type conversion
port: ${string(schema.spec.portNumber)}
```
**Referências entre recursos**: referencie valores provenientes de outros recursos:
```
resources:
- id: bucket
template:
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
spec:
name: ${schema.spec.name}-data
- id: configmap
template:
apiVersion: v1
kind: ConfigMap
data:
BUCKET_NAME: ${bucket.spec.name}
BUCKET_ARN: ${bucket.status.ackResourceMetadata.arn}
```
Quando você referencia outro recurso em uma expressão CEL, isso cria automaticamente uma dependência. O kro assegura que o recurso de referência seja estabelecido antes dos demais recursos.
Para obter mais informações, consulte [CEL Expressions](https://kro.run/docs/concepts/rgd/cel-expressions/) na documentação do kro.
### Dependências entre recursos
O kro infere automaticamente as dependências a partir das expressões CEL. Em vez de ditar a ordem, você apenas descreve como os recursos se relacionam. Se um recurso faz referência a outro usando uma expressão CEL, o kro cria uma dependência e determina a ordem de criação correta.
```
resources:
- id: bucket
template:
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
spec:
name: ${schema.spec.name}-data
- id: notification
template:
apiVersion: s3.services.k8s.aws/v1alpha1
kind: BucketNotification
spec:
bucket: ${bucket.spec.name} # Creates dependency: notification depends on bucket
```
A expressão `${bucket.spec.name}` cria uma dependência. O kro desenvolve um grafo acíclico direcionado (DAG, na sigla em inglês) e as dependências e, em seguida, calcula uma ordem topológica para a criação.
**Ordem de criação**: os recursos são criados em ordem topológica (ou seja, primeiro há a criação das dependências).
**Criação paralela**: recursos sem dependências são criados simultaneamente.
**Ordem de exclusão**: os recursos são excluídos em ordem topológica inversa (ou seja, primeiro os recursos dependentes).
**Dependências circulares**: não são permitidas. O kro rejeita as ResourceGraphDefinitions com dependências circulares durante a validação.
Para conferir a ordem de criação definida pelo sistema, use:
```
kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.topologicalOrder}'
```
Para obter mais informações, consulte [Graph inference](https://kro.run/docs/concepts/rgd/dependencies-ordering/) na documentação do kro.
## Composição com o ACK
O kro funciona perfeitamente com a funcionalidade do EKS para o ACK para compor recursos da AWS com recursos do Kubernetes:
```
resources:
# Create {aws} S3 bucket with ACK
- id: bucket
template:
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
spec:
name: ${schema.spec.name}-files
# Inject bucket details into Kubernetes ConfigMap
- id: config
template:
apiVersion: v1
kind: ConfigMap
data:
BUCKET_NAME: ${bucket.spec.name}
BUCKET_ARN: ${bucket.status.ackResourceMetadata.arn}
# Use ConfigMap in application deployment
- id: deployment
template:
apiVersion: apps/v1
kind: Deployment
spec:
template:
spec:
containers:
- name: app
envFrom:
- configMapRef:
name: ${config.metadata.name}
```
Com esse padrão, você consegue criar recursos na AWS, obter detalhes importantes (como ARNs, URLs e endpoints) e inseri-los diretamente na configuração da aplicação, tratando tudo como um único conjunto.
Para obter mais padrões de composição e exemplos avançados, consulte [Considerações sobre o kro para o EKS](kro-considerations.md).
## Próximas etapas
+ [Considerações sobre o kro para o EKS](kro-considerations.md): aprenda sobre padrões específicos do EKS, do RBAC e da integração com o ACK e com o Argo CD
+ [Documentação do kro](https://kro.run/docs/overview): acesse a documentação abrangente do kro, incluindo expressões CEL avançadas, padrões de validação e solução de problemas
# Configuração de permissões do kro
Ao contrário do ACK e do Argo CD, o kro não requer permissões do IAM. O kro opera inteiramente no cluster do Kubernetes e não faz chamadas de API da AWS. Controle o acesso aos recursos do kro usando o RBAC padrão do Kubernetes.
## Funcionamento de permissões com o kro
O kro usa dois tipos de recursos do Kubernetes com escopos diferentes:
**ResourceGraphDefinitions**: recursos com escopo de cluster para a definição de APIs personalizadas. Geralmente, esses recursos são gerenciados por equipes responsáveis pela plataforma que projetam e mantêm os padrões organizacionais.
**Instâncias**: recursos personalizados com escopo de namespace criados com base em ResourceGraphDefinitions. Podem ser criados por equipes responsáveis pela aplicação com as permissões de RBAC apropriadas.
Por padrão, a funcionalidade do kro tem permissões para gerenciar ResourceGraphDefinitions e as respectivas instâncias por meio da política de entrada de acesso `AmazonEKSKROPolicy`. No entanto, o kro requer permissões adicionais para criar e gerenciar os recursos subjacentes do Kubernetes definidos em suas ResourceGraphDefinitions (como Deployments, Services ou recursos do ACK). Você deve conceder essas permissões por meio de políticas de entrada de acesso ou de RBAC do Kubernetes. Para detalhes sobre a concessão dessas permissões, consulte a seção [Permissões de recursos arbitrários do kro](capabilities-security.md#kro-resource-permissions).
## Permissões da equipe responsável pela plataforma
As equipes responsáveis pela plataforma precisam de permissões para criar e gerenciar ResourceGraphDefinitions.
**Exemplo de ClusterRole para as equipes responsáveis pela plataforma**:
```
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: kro-platform-admin
rules:
- apiGroups: ["kro.run"]
resources: ["resourcegraphdefinitions"]
verbs: ["*"]
```
**Vincule aos membros da equipe responsável pela plataforma**:
```
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: platform-team-kro-admin
subjects:
- kind: Group
name: platform-team
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: ClusterRole
name: kro-platform-admin
apiGroup: rbac.authorization.k8s.io
```
## Permissões da equipe responsável pela aplicação
As equipes responsáveis pela aplicação precisam de permissões para criar instâncias de recursos personalizados em seus namespaces.
**Exemplo de perfil para as equipes responsáveis pela aplicação**:
```
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: kro-app-developer
namespace: my-app
rules:
- apiGroups: ["kro.run"]
resources: ["webapps", "databases"]
verbs: ["create", "get", "list", "update", "delete", "patch"]
```
**Vincule aos membros da equipe responsável pela aplicação**:
```
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: app-team-kro-developer
namespace: my-app
subjects:
- kind: Group
name: app-team
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: Role
name: kro-app-developer
apiGroup: rbac.authorization.k8s.io
```
**nota**
O grupo de API no perfil (`kro.run` neste exemplo) deve corresponder à `apiVersion` definida no esquema da ResourceGraphDefinition.
## Acesso somente leitura.
Conceda acesso somente de leitura para a visualização de ResourceGraphDefinitions e de instâncias, sem permissões de modificação.
**ClusterRole somente de leitura**:
```
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: kro-viewer
rules:
- apiGroups: ["kro.run"]
resources: ["resourcegraphdefinitions"]
verbs: ["get", "list", "watch"]
```
**Perfil somente de leitura para as instâncias**:
```
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: kro-instance-viewer
namespace: my-app
rules:
- apiGroups: ["kro.run"]
resources: ["webapps", "databases"]
verbs: ["get", "list", "watch"]
```
## Acesso a vários namespaces
Conceda às equipes responsáveis pela aplicação acesso a vários namespaces usando ClusterRoles com RoleBindings.
**ClusterRole para acesso a vários namespaces**:
```
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: kro-multi-namespace-developer
rules:
- apiGroups: ["kro.run"]
resources: ["webapps"]
verbs: ["create", "get", "list", "update", "delete"]
```
**Vincule a namespaces específicos**:
```
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: app-team-dev-access
namespace: development
subjects:
- kind: Group
name: app-team
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: ClusterRole
name: kro-multi-namespace-developer
apiGroup: rbac.authorization.k8s.io
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: app-team-staging-access
namespace: staging
subjects:
- kind: Group
name: app-team
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: ClusterRole
name: kro-multi-namespace-developer
apiGroup: rbac.authorization.k8s.io
```
## Práticas recomendadas
**Princípio do privilégio mínimo**: conceda somente as permissões mínimas necessárias para que cada equipe execute suas responsabilidades.
**Use grupos em vez de usuários individuais**: vincule perfis a grupos, em vez de usuários individuais, para facilitar o gerenciamento.
**Separação de responsabilidades entre equipes de plataforma e aplicação**: equipes responsáveis pela plataforma gerenciam ResourceGraphDefinitions, enquanto equipes responsáveis pela aplicação gerenciam instâncias.
**Isolamento de namespace**: use namespaces para isolar diferentes equipes ou ambientes, com o RBAC controlando o acesso a cada namespace.
**Acesso somente de leitura para auditoria**: forneça acesso somente de leitura para equipes responsáveis pela segurança e pela conformidade para fins de auditoria.
## Próximas etapas
+ [Conceitos do kro](kro-concepts.md): compreenda os conceitos do kro e a composição de recursos
+ [Conceitos do kro](kro-concepts.md): compreenda sobre o SimpleSchema, expressões CEL e padrões de composição
+ [Considerações sobre segurança para funcionalidades do EKS](capabilities-security.md): analise as práticas recomendadas de segurança para as funcionalidades
# Considerações sobre o kro para o EKS
Este tópico aborda considerações importantes para o uso da funcionalidade do EKS para o kro, incluindo quando utilizar a composição de recursos, os padrões de RBAC e a integração com outras funcionalidades do EKS.
## Situações para o uso do kro
O kro foi projetado para criar padrões de infraestrutura reutilizáveis e APIs personalizadas que simplificam o gerenciamento de recursos complexos.
**Use o kro quando for necessário**:
+ Criar plataformas de autoatendimento com APIs simplificadas para as equipes destinadas ao trabalho com APIs aplicação
+ Padronizar padrões de infraestrutura entre diferentes equipes (banco de dados \$1 backup \$1 monitoramento)
+ Gerenciar dependências de recursos e realizar a transferência de valores entre recursos
+ Desenvolver abstrações personalizadas que ocultam a complexidade da implementação
+ Compor diversos recursos do ACK em blocos de criação de nível superior
+ Habilitar fluxos de trabalho de GitOps para pilhas de infraestrutura complexas
**Não use kro ao**:
+ Gerenciar recursos simples e isolados (empregue recursos do Kubernetes ou do ACK diretamente)
+ Necessitar de lógica dinâmica de runtime (visto que o kro é declarativo, e não imperativo)
+ Lidar com recursos que não têm dependências nem configurações compartilhadas
O kro se destaca na criação de “caminhos pavimentados”, que são padrões opinativos e reutilizáveis que facilitam a implantação correta de infraestruturas complexas pelas equipes.
## Padrões de RBAC
O kro permite a separação de responsabilidades entre as equipes responsáveis pela plataforma, que criam as ResourceGraphDefinitions, e as equipes responsáveis pela aplicação, que criam as instâncias.
### Responsabilidades da equipe responsável pela plataforma
As equipes responsáveis pela plataforma criam e mantêm as ResourceGraphDefinitions (RGDs) que definem as APIs personalizadas.
**Permissões necessárias**:
+ Criar, atualizar e excluir ResourceGraphDefinitions
+ Gerenciar tipos de recursos subjacentes (como Deployments, Services e recursos do ACK)
+ Acessar a todos os namespaces nos quais as RGDs serão aplicadas
**Exemplo de ClusterRole para a equipe responsável pela plataforma**:
```
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: platform-kro-admin
rules:
- apiGroups: ["kro.run"]
resources: ["resourcegraphdefinitions"]
verbs: ["*"]
- apiGroups: ["*"]
resources: ["*"]
verbs: ["get", "list", "watch"]
```
Para obter a configuração detalhada de RBAC, consulte [Configuração de permissões do kro](kro-permissions.md).
### Responsabilidades da equipe responsável pela aplicação
As equipes responsáveis pela aplicação criam instâncias de recursos personalizados definidos por RGDs, sem a necessidade de compreender a complexidade subjacente.
**Permissões necessárias**:
+ Criar, atualizar e excluir instâncias de recursos personalizados
+ Ter um acesso de leitura ao próprio namespace
+ Não conseguir acessar os recursos subjacentes ou as RGDs
**Benefícios**:
+ As equipes usam APIs simplificadas de alto nível
+ As equipes responsáveis pela plataforma detêm o controle dos detalhes de implementação
+ Risco reduzido de erros de configuração
+ Integração mais rápida para os novos membros da equipe
## Integração com outras funcionalidades do EKS
### Composição de recursos do ACK
O kro torna-se especialmente eficiente ao ser integrado ao ACK para o desenvolvimento de padrões de infraestrutura.
**Padrões comuns**:
+ **Aplicação com armazenamento**: bucket do S3 \$1 fila do SQS \$1 configuração de notificação
+ **Pilha de banco de dados**: instância do RDS \$1 grupo de parâmetros \$1 grupo de segurança \$1 segredo do Secrets Manager
+ **Rede**: VPC \$1 sub-redes \$1 tabelas de rotas \$1 grupos de segurança \$1 gateways NAT
+ **Computação com armazenamento**: instância do EC2 \$1 volumes do EBS \$1 perfil de instância do IAM
O kro gerencia a ordenação de dependências, transfere valores entre recursos (como ARNs e strings de conexão) e gerencia o ciclo de vida completo como uma unidade única.
Para obter exemplos da composição de recursos do ACK, consulte [Conceitos do ACK](ack-concepts.md).
### GitOps com Argo CD
Use a funcionalidade do EKS para o Argo CD com a finalidade de implantar tanto RGDs quanto instâncias usando repositórios do Git.
**Organização de repositórios**:
+ **Repositório de plataforma**: contém as ResourceGraphDefinitions gerenciadas pela equipe responsável pela plataforma
+ **Repositórios de aplicação**: contêm instâncias de recursos personalizados gerenciadas pelas equipes responsáveis pela aplicação
+ **Repositório compartilhado**: contém tanto RGDs quanto instâncias para organizações de menor porte
**Considerações**:
+ Implante as RGDs antes das instâncias (os ciclos de sincronização do Argo CD podem ser úteis)
+ Use Projects distintos do CD Argo para as equipes responsáveis pela plataforma e pela aplicação
+ A equipe responsável pela plataforma controla o acesso ao repositório de RGDs
+ As equipes responsáveis pela aplicação têm acesso somente de leitura às definições de RGDs
Para saber mais sobre o Argo CD, consulte [Como trabalhar com o Argo CD](working-with-argocd.md).
## Organização de ResourceGraphDefinitions
Organize as RGDs por finalidade, complexidade e propriedade.
**Por finalidade**:
+ **Infraestrutura**: pilhas de banco de dados, rede e armazenamento
+ **Aplicação**: aplicativos web, APIs e trabalhos em lote
+ **Plataforma**: serviços compartilhados, monitoramento e registro em log
**Por complexidade**:
+ **Simples**: dois a três recursos com o mínimo de dependências
+ **Intermediária**: cinco a dez recursos com algumas dependências
+ **Complexa**: mais de dez recursos com dependências complexas
**Convenções de nomenclatura**:
+ Use nomes descritivos: `webapp-with-database` e `s3-notification-queue`
+ Inclua a versão no nome para alterações incompatíveis: `webapp-v2`
+ Use prefixos consistentes para RGDs relacionadas: `platform- ` e `app-`
**Estratégia de namespace**:
+ As RGDs têm escopo de cluster (não pertencem a um namespace)
+ As instâncias pertencem a um namespace
+ Use seletores de namespace nas RGDs para controlar em qual local as instâncias podem ser criadas
## Versionamento e atualizações
Planeje a evolução das RGDs e a migração de instâncias.
**Atualizações de RGD**:
+ **Alterações compatíveis**: atualize a RGD diretamente (adicione campos opcionais e novos recursos com includeWhen)
+ **Alterações incompatíveis**: crie uma nova RGD com um nome diferente (como webapp-v2)
+ **Descontinuação**: sinalize as RGDs antigas com anotações e comunique o cronograma de migração
**Migração de instâncias**:
+ Crie novas instâncias com a RGD atualizada
+ Valide se as novas instâncias funcionam corretamente
+ Exclua as instâncias antigas
+ O kro gerencia as atualizações dos recursos subjacentes automaticamente
**Práticas recomendadas**:
+ Teste as alterações de RGD primeiro em ambientes que não são de produção
+ Use o versionamento semântico nos nomes das RGDs para alterações significativas
+ Documente as alterações incompatíveis e os caminhos de migração
+ Forneça exemplos de migração para as equipes responsáveis pela aplicação
## Validação e testes
Valide as RGDs antes de implantá-las em ambientes de produção.
**Estratégias de validação**:
+ **Validação de esquema**: o kro valida a estrutura da RGD automaticamente
+ **Instâncias de simulação**: crie instâncias de teste em namespaces de desenvolvimento
+ **Testes de integração**: verifique se os recursos compostos funcionam em conjunto
+ **Aplicação de políticas**: use controladores de admissão para aplicar padrões organizacionais
**Problemas comuns em testes**:
+ Dependências e ordenação de recursos
+ Transferência de valores entre recursos (expressões CEL)
+ Inclusão condicional de recursos (includeWhen)
+ Propagação de status provenientes de recursos subjacentes
+ Permissões de RBAC para criação de instâncias
## Documentação original
Para obter informações detalhadas sobre o uso do kro:
+ [Getting Started with kro](https://kro.run/docs/guides/getting-started): criação de ResourceGraphDefinitions
+ [CEL Expressions](https://kro.run/docs/concepts/cel): gravação de expressões CEL
+ [kro Guides](https://kro.run/docs/guides/): padrões avançados de composição
+ [Troubleshooting](https://kro.run/docs/troubleshooting): solução de problemas e depuração
## Próximas etapas
+ [Configuração de permissões do kro](kro-permissions.md): configure o RBAC para as equipes responsáveis pela plataforma e pela aplicação
+ [Conceitos do kro](kro-concepts.md): compreenda os conceitos do kro e o ciclo de vida dos recursos
+ [Solução de problemas em funcionalidades do kro](kro-troubleshooting.md): solucione problemas do kro
+ [Conceitos do ACK](ack-concepts.md): saiba mais sobre os recursos do ACK para a composição
+ [Como trabalhar com o Argo CD](working-with-argocd.md): implante RGDs e instâncias utilizando GitOps
# Solução de problemas em funcionalidades do kro
Este tópico fornece orientações para a solução de problemas à funcionalidade do EKS para o kro, incluindo verificações de integridade da funcionalidade, permissões de RBAC, erros relacionados à expressão CEL e problemas de composição de recursos.
**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 ao namespace `kro-system`. A solução de problemas se concentra na integridade da funcionalidade, na configuração de RBAC e no status dos recursos.
## A funcionalidade está com o status ACTIVE, mas as ResourceGraphDefinitions não estão funcionando
Se a funcionalidade do kro apresentar o status `ACTIVE`, mas as ResourceGraphDefinitions não estiverem criando recursos subjacentes, verifique a integridade da funcionalidade, as permissões de RBAC e o status do recurso.
**Verifique a integridade da funcionalidade**:
Você pode 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-kro
# Look for issues in the health section
```
**Causas comuns**:
+ **Permissões de RBAC ausentes**: o kro não tem permissões para criar recursos subjacentes do Kubernetes
+ **Expressões CEL inválidas**: erros de sintaxe na ResourceGraphDefinition
+ **Dependências de recursos**: recursos dependentes não estão prontos
+ **Validação do esquema**: a instância não corresponde ao esquema da RGD
**Verifique as permissões do RBAC**:
```
# Check if capability has cluster admin policy
kubectl get accessentry -A | grep kro
```
Se a funcionalidade não tiver as permissões necessárias, associe a política `AmazonEKSClusterAdminPolicy` à entrada de acesso da funcionalidade do kro ou crie políticas de RBAC mais restritivas para uso em ambientes de produção. Para mais detalhes, consulte [Configuração de permissões do kro](kro-permissions.md).
**Verifique o status da ResourceGraphDefinition**:
```
# List all RGDs
kubectl get resourcegraphdefinition
# Describe specific RGD
kubectl describe resourcegraphdefinition my-rgd
# Check for validation errors
kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.conditions}'
```
As ResourceGraphDefinitions contam com três condições de status fundamentais:
+ `ResourceGraphAccepted`: se a RGD foi aprovada na validação (por exemplo, por sintaxe CEL, verificação de tipos e existência de campos)
+ `KindReady`: se a CRD para a API personalizada foi gerado e registrado
+ `ControllerReady`: se o kro está monitorando ativamente as instâncias da API personalizada
Se `ResourceGraphAccepted` for `False`, verifique a mensagem da condição para erros de validação, como campos desconhecidos, incompatibilidades de tipo ou dependências circulares.
## As instâncias foram criadas, porém os recursos subjacentes não estão sendo exibidos
Se existirem instâncias de recursos personalizados, mas os recursos subjacentes do Kubernetes (como Deployments, Services e ConfigMaps) não estiverem sendo criados, valide as permissões do kro e verifique se há erros na composição.
**Verifique o status da instância**:
```
# Describe the instance (replace with your custom resource kind and name)
kubectl describe custom-kind
my-instance
# View instance events
kubectl get events --field-selector involvedObject.name=my-instance
# Check instance status conditions
kubectl get custom-kind
my-instance -o jsonpath='{.status.conditions}'
# Check instance state
kubectl get custom-kind
my-instance -o jsonpath='{.status.state}'
```
As instâncias têm um campo `state` que indica o status geral:
+ `ACTIVE`: a instância está sendo executada com êxito
+ `IN_PROGRESS`: a instância está sendo processada ou reconciliada
+ `FAILED`: a instância apresentou falha na reconciliação
+ `DELETING`: a instância está sendo excluída
+ `ERROR`: ocorreu um erro durante o processamento
Além disso, as instâncias contam com quatro condições de status:
+ `InstanceManaged`: finalizadores e rótulos estão configurados corretamente
+ `GraphResolved`: gráfico de runtime criado e recursos resolvidos
+ `ResourcesReady`: todos os recursos foram criados e estão prontos
+ `Ready`: integridade geral da instância (torna-se `True` apenas quando todas as subcondições são `True`)
Monitore a condição `Ready` para determinar a integridade da instância. Se `Ready` for `False`, verifique as subcondições para identificar em qual fase ocorreu a falha.
**Verifique as permissões do RBAC**:
A funcionalidade do kro precisa de permissões para criar os recursos subjacentes do Kubernetes, definidos nas ResourceGraphDefinitions.
```
# Check if the capability has the AmazonEKSClusterAdminPolicy
kubectl get accessentry -A | grep kro
```
Se as permissões estiverem ausentes, associe a política `AmazonEKSClusterAdminPolicy` à entrada de acesso da funcionalidade do kro ou crie políticas de RBAC mais restritivas para uso em ambientes de produção. Para mais detalhes, consulte [Configuração de permissões do kro](kro-permissions.md).
## Erros em expressões CEL
Os erros em expressões CEL são detectados no momento da criação da ResourceGraphDefinition, e não quando as instâncias são criadas. O kro valida toda a sintaxe do CEL, verifica os tipos das expressões em relação aos esquemas do Kubernetes e verifica a existência de campos ao criar a RGD.
**Erros comuns de validação em expressões CEL**:
+ **Referência de campo indefinida**: referência a um campo que não existe no esquema ou no recurso
+ **Incompatibilidade de tipo**: a expressão retorna o tipo incorreto (por exemplo, string em que o número inteiro é esperado)
+ **Sintaxe inválida**: ausência de colchetes, aspas ou operadores na expressão CEL
+ **Tipo de recurso desconhecido**: referência a uma CRD que não está presente no cluster
**Verifique o status de validação da RGD**:
```
# Check if RGD was accepted
kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.conditions[?(@.type=="ResourceGraphAccepted")]}'
# View detailed validation errors
kubectl describe resourcegraphdefinition my-rgd
```
Se `ResourceGraphAccepted` for `False`, a mensagem da condição conterá o erro de validação.
**Exemplos de expressões CEL válidas**:
```
# Reference schema field
${schema.spec.appName}
# Conditional expression
${schema.spec.replicas > 1}
# String template (expressions must return strings)
name: "${schema.spec.appName}-service"
# Standalone expression (can be any type)
replicas: ${schema.spec.replicaCount}
# Resource reference
${deployment.status.availableReplicas}
# Optional field access (returns null if field doesn't exist)
${configmap.data.?DATABASE_URL}
```
## As dependências de recursos não estão sendo resolvidas
O kro identifica dependências automaticamente por meio das expressões CEL, garantindo a criação dos recursos na sequência correta. Se os recursos não estiverem sendo criados conforme o esperado, verifique a ordem de dependência e a prontidão dos recursos.
**Confira a ordem de criação definida pelo sistema**:
```
# See the order kro will create resources
kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.topologicalOrder}'
```
Isso mostra a ordem definida pelo sistema com base nas referências de expressões CEL entre os recursos.
**Verifique a prontidão dos recursos**:
```
# View instance status to see which resources are ready
kubectl get custom-kind
my-instance -o jsonpath='{.status}'
# Check specific resource status
kubectl get deployment my-deployment -o jsonpath='{.status.conditions}'
```
**Verifique as condições readyWhen (se houver)**:
O campo `readyWhen` é opcional. Se não for especificado, os recursos serão considerados prontos imediatamente após a criação. Se você definiu condições `readyWhen`, confirme se elas estão verificando o estado de prontidão do recurso de forma correta:
```
resources:
- id: deployment
readyWhen:
- ${deployment.status.availableReplicas == deployment.spec.replicas}
```
**Verifique os eventos do recurso**:
```
# View events for the underlying resources
kubectl get events -n namespace --sort-by='.lastTimestamp'
```
## Ocorrem falhas de validação do esquema
Se a criação de instâncias falhar devido a erros de validação do esquema, verifique se a instância corresponde aos requisitos de esquema da RGD.
**Verifique os erros de validação**:
```
# Attempt to create instance and view error
kubectl apply -f instance.yaml
# View existing instance validation status
kubectl describe custom-kind
my-instance | grep -A 5 "Validation"
```
**Problemas comuns de validação**:
+ **Campos obrigatórios ausentes**: a instância não fornece todos os campos obrigatórios do esquema
+ **Incompatibilidade de tipo**: fornecimento de string em um local em que um número inteiro é esperado
+ **Valor de enumeração inválido**: uso de um valor não constante na lista permitida
+ **Incompatibilidade de padrões**: a string não corresponde ao padrão regex
**Analise o esquema da RGD**:
```
# View the schema definition
kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.spec.schema}'
```
Certifique-se de que sua instância contenha todos os campos requeridos com os respectivos tipos configurados corretamente.
## Próximas etapas
+ [Considerações sobre o kro para o EKS](kro-considerations.md): obtenha considerações e práticas recomendadas para o kro
+ [Configuração de permissões do kro](kro-permissions.md): configure o RBAC para as equipes responsáveis pela plataforma e pela aplicação
+ [Conceitos do kro](kro-concepts.md): compreenda os conceitos do kro 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 kro em relação ao kro autogerenciado
A funcionalidade do EKS para o kro é equivalente à do kro autogerenciado, 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).
A funcionalidade do EKS para o kro usa os mesmos controladores da versão original do kro e é totalmente compatível com a versão original do projeto. As ResourceGraphDefinitions, as expressões CEL e a composição de recursos funcionam de maneira idêntica. Para obter a documentação completa do kro e exemplos, consulte a [documentação oficial do kro](https://kro.run/docs/overview).
## Caminho de migração
Você pode migrar de um kro autogerenciado para a funcionalidade gerenciada sem tempo de inatividade.
**Importante**
Antes de realizar a migração, certifique-se de que o controlador kro autogerenciado esteja executando a mesma versão da funcionalidade do EKS para o kro. Verifique a versão da funcionalidade no console do EKS ou usando o comando `aws eks describe-capability` e, em seguida, atualize a instalação do recurso autogerenciado para que seja compatível. Isso evita problemas de compatibilidade durante a migração.
1. Atualize o controlador do kro autogerenciado para usar `kube-system` para concessões de eleição de líder:
```
helm upgrade --install kro \
oci://ghcr.io/awslabs/kro/kro-chart \
--namespace kro \
--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 kro no cluster (consulte [Criação de uma funcionalidade do kro](create-kro-capability.md)).
1. A funcionalidade gerenciada reconhece as ResourceGraphDefinitions e as instâncias existentes, assumindo o processo de reconciliação.
1. Reduza gradualmente a escala verticalmente ou remova as implantações do kro autogerenciado:
```
helm uninstall kro --namespace kro
```
Com essa abordagem, ambos os controladores podem coexistir com segurança durante a migração. A funcionalidade gerenciada assume automaticamente as ResourceGraphDefinitions e as instâncias que antes eram gerenciadas pelo kro autogerenciado, assegurando reconciliação contínua sem gerar conflitos.
## Próximas etapas
+ [Criação de uma funcionalidade do kro](create-kro-capability.md): crie um recurso de funcionalidade do kro
+ [Conceitos do kro](kro-concepts.md): compreenda os conceitos do kro e a composição de recursos