Generación Declarativa de Manifiestos con KCL

En la plataforma ANDES, KCL (Kusion Configuration Language) es utilizado como un motor de traducción interno de Platform Engineering. Si deseas aprender más sobre el lenguaje, puedes visitar la documentación oficial de KCL.

Esta página separa dos ideas: qué hace KCL como motor de generación y cómo se usa hoy dentro del flujo soportado de ANDES DX.

Los desarrolladores no interactúan con el repositorio core de KCL (kcl-base) ni necesitan compilar plantillas localmente; en el flujo actual, ANDES DX entrega la metadata aprobada de la aplicación y el pipeline la procesa de manera automatizada.

---

El Rol de KCL en el Ecosistema ANDES DX

KCL actúa como un compilador y validador de configuración type-safe. Por sí solo puede transformar un contrato de entrada en manifiestos Kubernetes, pero en ANDES ese contrato debe venir del flujo soportado por ANDES DX. Hoy no existe una API de metadata separada de DX para alimentar este proceso de forma general.

En el flujo soportado, el pipeline obtiene la metadata aprobada desde la API de ANDES DX, la entrega al motor KCL y genera manifiestos Kubernetes completos, aplicando políticas de seguridad, recursos y nomenclatura corporativa.

Este enfoque permite:

• Abstracción Total: Los desarrolladores declaran qué necesita su aplicación a nivel lógico en la plataforma, y el motor infiere y redacta la infraestructura técnica correcta.
• Garantía de Cumplimiento: Todo manifiesto generado cumple con los estándares de seguridad de LATAM Airlines por diseño.

---

Lógica de Procesamiento de Configuración

La conversión desde la metadata de la aplicación hasta los manifiestos de infraestructura fue diseñada junto al modelo de ANDES DX y sigue una lógica secuencial en 4 etapas principales ejecutadas internamente en el pipeline de integración continua:

1. Extracción de Identidad (schemas/identity.k)

El motor de la plataforma resuelve la identidad del workload (Identity), validando formatos de DNS estándar y normalizando campos como el nombre de la app, el ambiente, la imagen y el proyecto correspondiente.

2. Validación de Contratos (schemas/input.k)

Antes de generar recursos, se aplican validaciones estrictas sobre el contrato de entrada:

• Límites de Recursos: Validación de formato y coherencia (ej: cpu_limit >= cpu_request).
• Probes de Salud: Verificación de liveness/readiness paths correctos.
• Autoscaling: Validación lógica de replicas y políticas de balanceo.

3. Inyección Automática de Convenciones (conventions/)

La plataforma inyecta de forma silenciosa defaults corporativos y de seguridad:

• Variables de Entorno Base: Toda aplicación recibe automáticamente APP_NAME, APP_ENV y APP_PRODUCT.
• Etiquetado de Gobernabilidad: Etiquetas estándar del ciclo de vida de LATAM.
• Seguridad Restringida: Políticas restrictivas para contenedores (sin escalamiento de privilegios).

4. Mapeo y Ensamblado de Recursos (backends/)

Dependiendo de la plataforma configurada, el motor compone los manifiestos planos de la carpeta de recursos compartidos (backends/_k8s/resources/):

• GKE: Deployment, Service, HorizontalPodAutoscaler (HPA), ServiceAccount, PDB y NetworkPolicies.
• Cloud Run: Google Cloud Run Service y políticas de control de acceso correspondientes.

---

Cómo Funciona Hoy en ANDES DX

El camino soportado actualmente es:

1. El equipo configura la aplicación en ANDES DX.
2. ANDES DX mantiene la metadata aprobada para ese repositorio y ambiente.
3. El pipeline descarga esa metadata mediante dx-client.
4. KCL renderiza los manifiestos a partir de esa metadata.
5. El componente GitOps publica los YAML en el repositorio latam-applications/{dominio}.
6. ArgoCD sincroniza esos manifiestos contra GKE o Cloud Run.

Ejemplo Conceptual de Traducción

La plataforma obtiene la metadata en formato JSON desde la API de ANDES DX y la entrega al motor KCL:

Metadata Real de la Aplicación (Consumida automáticamente de la API)

{
  "name": "test-backend-app",
  "app_type": "backend",
  "product": {
    "productId": "000000000000000000000000",
    "name": "test-product"
  },
  "deployment": [
    {
      "environment": "intg",
      "infrastructure": {
        "cluster": {
          "gke_cluster_name": "gke-test-cluster-01",
          "project_id": "test-gcp-project-dev"
        },
        "app_config": {
          "replicas": {
            "max": "2",
            "min": "2"
          },
          "resources": {
            "cpu": {
              "limit": "500m",
              "request": "250m"
            },
            "memory": {
              "limit": "512Mi",
              "request": "256Mi"
            }
          },
          "autoscaling": {
            "enabled": true,
            "metrics": {
              "cpu_utilization_percent": 70
            }
          },
          "healthchecks": {
            "liveness_path": "/health/liveness",
            "readiness_path": "/health/readiness"
          }
        }
      }
    }
  ]
}

Manifiestos de Salida (Generados en el GitOps Repo del Dominio)

El motor compila esta estructura e inyecta los recursos y defaults corporativos correctos en Kubernetes:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test-product-test-backend-app
  namespace: test-namespace-app
  labels:
    app.kubernetes.io/name: test-backend-app
    app.kubernetes.io/managed-by: argocd
spec:
  replicas: 2  # Mapeado dinámicamente según la API
  template:
    spec:
      containers:
      - name: test-backend-app
        image: us-docker.pkg.dev/test-proj/reg/test-app:tag
        resources:
          limits:
            cpu: "500m"
            memory: "512Mi"
          requests:
            cpu: "250m"
            memory: "256Mi"
        securityContext:
          allowPrivilegeEscalation: false  # Estándar restrictivo
---
apiVersion: v1
kind: Service
metadata:
  name: test-product-test-backend-app
  namespace: test-namespace-app
spec:
  ports:
  - port: 80
    targetPort: 8080
  selector:
    app.kubernetes.io/name: test-backend-app

---

Siguiente Paso

Aprende cómo se automatiza esta sincronización en la sección de GitOps con GitLab.