**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.

# Solução de problemas em funcionalidades do kro
<a name="kro-troubleshooting"></a>

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
<a name="_capability_is_active_but_resourcegraphdefinitions_arent_working"></a>

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\#/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
<a name="_instances_created_but_underlying_resources_not_appearing"></a>

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
<a name="_cel_expression_errors"></a>

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
<a name="_resource_dependencies_not_resolving"></a>

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
<a name="_schema_validation_failures"></a>

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
<a name="_next_steps"></a>
+  [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