Conceptos de kro

kro permite a los equipos de plataformas crear API de Kubernetes personalizadas que componen varios recursos en abstracciones de nivel superior. En este tema, se muestra un ejemplo práctico y, a continuación, se explican los conceptos básicos que debe comprender al trabajar con la capacidad de EKS para kro.

Introducción a kro

Después de crear la capacidad de kro (consulte Creación de una capacidad de kro), puede comenzar a crear API personalizadas con ResourceGraphDefinitions en el clúster.

A continuación se muestra un ejemplo completo que crea una abstracción simple de una aplicación 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

Después de aplicar esta ResourceGraphDefinition, los equipos de aplicaciones pueden crear aplicaciones web mediante su API simplificada:

apiVersion: kro.run/v1alpha1
kind: WebApplication
metadata:
  name: my-app
spec:
  name: my-app
  replicas: 5

kro crea automáticamente la implementación y el servicio con la configuración adecuada. Como no se ha especificado image, utiliza el valor predeterminado nginx:latest del esquema.

Conceptos clave

importante

kro valida ResourceGraphDefinitions en el momento de la creación, no en tiempo de ejecución. Al crear una RGD, kro valida la sintaxis de CEL, compara las expresiones con los esquemas reales de Kubernetes, verifica la existencia de los campos y detecta las dependencias circulares. Esto significa que los errores se detectan inmediatamente al crear la RGD, antes de implementar cualquier instancia.

ResourceGraphDefinition

Una ResourceGraphDefinition (RGD) define una API de Kubernetes personalizada mediante la especificación de lo siguiente:

• Esquema: la estructura de la API con el formato SimpleSchema (nombres de campo, tipos, valores predeterminados, validación)

• Recursos: plantillas para la creación para recursos de AWS o Kubernetes subyacentes

• Dependencias: cómo se relacionan los recursos entre sí (se detectan automáticamente a partir de referencias de campo)

Al aplicar una RGD, kro registra una nueva definición de recursos personalizados (CRD) en el clúster. A continuación, los equipos de aplicaciones pueden crear instancias de la API personalizada y kro se encarga de crear y administrar todos los recursos subyacentes.

Para obtener más información, consulte la sección ResourceGraphDefinition Overview en la documentación de kro.

Formato SimpleSchema

SimpleSchema proporciona una forma simplificada de definir esquemas de API sin necesidad de conocimientos de OpenAPI:

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

SimpleSchema admite los tipos string, integer, boolean y number con restricciones como required, default, minimum/maximum, enum y pattern.

Para obtener más información, consulte SimpleSchema en la documentación de kro.

Expresiones de CEL

kro utiliza el lenguaje de expresión común (CEL) para hacer referencia a valores de forma dinámica y agregar lógica condicional. Las expresiones de CEL se encapsulan en ${ y } y se pueden usar de dos maneras:

Expresiones independientes. Todo el valor del campo es una sola expresión:

spec:
  replicas: ${schema.spec.replicaCount}  # Expression returns integer
  labels: ${schema.spec.labelMap}        # Expression returns object

El resultado de la expresión reemplaza todo el valor del campo y debe coincidir con el tipo esperado del campo.

Plantillas de cadenas. Una o más expresiones incrustadas en una cadena:

metadata:
  name: "${schema.spec.prefix}-${schema.spec.name}"  # Multiple expressions
  annotation: "Created by ${schema.spec.owner}"      # Single expression in string

Todas las expresiones de las plantillas de cadenas deben devolver cadenas. Utilice string() para convertir otros tipos: "replicas-${string(schema.spec.count)}".

Referencias de campos. Acceda a los valores de las especificaciones de la instancia mediante schema.spec:

template:
  metadata:
    name: ${schema.spec.name}-deployment
    namespace: ${schema.metadata.namespace}  # Can also reference metadata
  spec:
    replicas: ${schema.spec.replicas}

Acceso a campos opcionales. Utilice ? para campos que podrían no existir:

# For ConfigMaps or Secrets with unknown structure
value: ${configmap.data.?DATABASE_URL}

# For optional status fields
ready: ${deployment.status.?readyReplicas > 0}

Si el campo no existe, la expresión devuelve null en lugar de producir un error.

Recursos condicionales. Incluya los recursos solo cuando se cumplan las condiciones:

resources:
- id: ingress
  includeWhen:
    - ${schema.spec.enableIngress == true}
  template:
    # ... ingress configuration

El campo includeWhen acepta una lista de expresiones booleanas. Todas las condiciones deben ser verdaderas para que el recurso se cree. Actualmente, includeWhen solo puede hacer referencia a campos schema.spec.

Transformaciones. Transforme valores mediante funciones y operadores ternarios:

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

Referencias cruzadas entre recursos. Valores de referencia de otros 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}

Al hacer referencia a otro recurso en una expresión de CEL, se crea automáticamente una dependencia. kro garantiza que el recurso al que se hace referencia se cree primero.

Para obtener más información, consulte CEL Expressions en la documentación de kro.

Dependencias de recursos

kro infiere automáticamente las dependencias de las expresiones de CEL: no se especifica el orden, se describen las relaciones. Cuando un recurso hace referencia a otro mediante una expresión de CEL, kro crea una dependencia y determina el orden de creación correcto.

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

La expresión ${bucket.spec.name} crea una dependencia. kro crea un gráfico acíclico dirigido (DAG) de todos los recursos y sus dependencias y, a continuación, calcula un orden topológico para la creación.

Orden de creación: los recursos se crean por orden topológico (primero las dependencias).

Creación paralela: los recursos sin dependencias se crean simultáneamente.

Orden de eliminación: los recursos se eliminan por orden topológico inverso (primero los dependientes).

Dependencias circulares: no se permiten. kro rechaza las ResourceGraphDefinitions con dependencias circulares durante la validación.

Puede ver el orden de creación de computación:

kubectl get resourcegraphdefinition my-rgd -o jsonpath='{.status.topologicalOrder}'

Para obtener más información, consulte Graph inference en la documentación de kro.

Composición con ACK

kro funciona sin problemas con la capacidad de EKS para ACK para componer recursos de AWS con recursos de 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}

Este patrón le permite crear recursos de AWS, extraer sus detalles (ARN, URL, puntos de conexión) e inyectarlos en la configuración de la aplicación, todo ello administrado como una sola unidad.

Para obtener más patrones de composición y ejemplos avanzados, consulte Consideraciones sobre kro para EKS.

Siguientes pasos

• Consideraciones sobre kro para EKS: más información sobre los patrones específicos de EKS, el RBAC y la integración con ACK y Argo CD

• Documentación de kro: documentación exhaustiva de kro que incluye solución de problemas, patrones de validación y expresiones de CEL avanzadas