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