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

ResourceGraphDefinition

Uma ResourceGraphDefinition (RGD) define uma API personalizada do Kubernetes ao especificar:

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

Próximas etapas