Declarative Manifest Generation with KCL

Within the ANDES platform, KCL (Kusion Configuration Language) is used as an internal translation engine by the Platform Engineering team. If you want to learn more about the language, you can visit the official KCL documentation.

This page separates two ideas: what KCL does as a generation engine and how it is used today in the supported ANDES DX flow.

Developers do not interact with the core KCL repository (kcl-base) nor do they need to compile templates locally. In the current flow, ANDES DX provides the approved application metadata and the pipeline processes it automatically.

---

The Role of KCL in the ANDES DX Ecosystem

KCL acts as a type-safe configuration compiler and validator. By itself, it can transform an input contract into Kubernetes manifests, but in ANDES that contract must come from the supported ANDES DX flow. Today, there is no metadata API separate from DX that can generally feed this process.

In the supported flow, the pipeline fetches the approved metadata from the ANDES DX API, passes it to the KCL engine, and generates complete Kubernetes manifests with LATAM Airlines security, resource, and naming conventions applied.

This approach enables:

• Total Abstraction: Developers declare what their application needs at a logical level, and the engine infers and writes the correct technical infrastructure.
• Compliance Guarantee: Every generated manifest complies with LATAM Airlines' security standards by design.

---

Configuration Processing Logic

The translation from application metadata to infrastructure manifests was designed together with the ANDES DX model and follows a sequential four-stage logic executed internally in the continuous integration pipeline:

1. Identity Resolution (schemas/identity.k)

The platform engine resolves the workload's identity (Identity), validating standard DNS formats and normalizing fields such as the app name, the target environment, the image tag, and the corresponding project.

2. Contract Validation (schemas/input.k)

Before generating resources, strict validations are run on the input contract:

• Resource Limits: Validation of format and coherence in CPU and memory (e.g., cpu_limit >= cpu_request).
• Health Probes: Verification of correct liveness/readiness paths.
• Autoscaling: Logical validation of replicas and load balancing policies.

3. Automatic Conventions Injection (conventions/)

The platform silently injects corporate defaults and security conventions:

• Base Environment Variables: Every application automatically receives APP_NAME, APP_ENV, and APP_PRODUCT.
• Standard Labeling: Standard LATAM lifecycle labels.
• Restricted Security: Restrictive pod security policies (no privilege escalation).

4. Resource Mapping and Assembly (backends/)

Depending on the configured target platform, the engine composes the required flat manifests from the shared resources folder (backends/_k8s/resources/):

• GKE: Deployment, Service, HorizontalPodAutoscaler (HPA), ServiceAccount, PDB, and NetworkPolicies.
• Cloud Run: Google Cloud Run Service and corresponding access control policies.

---

How It Works Today in ANDES DX

The currently supported path is:

1. The team configures the application in ANDES DX.
2. ANDES DX keeps the approved metadata for that repository and environment.
3. The pipeline downloads that metadata through dx-client.
4. KCL renders the manifests from that metadata.
5. The GitOps component publishes the YAML files into the latam-applications/{domain} repository.
6. ArgoCD syncs those manifests against GKE or Cloud Run.

Conceptual Translation Example

The automation platform fetches application metadata in JSON format directly from the ANDES DX API and hands it over to the KCL engine:

Real Application Metadata (Consumed automatically from the 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"
          }
        }
      }
    }
  ]
}

Output Manifests (Generated in the Domain's GitOps Repo)

The engine compiles this structure and injects the proper corporate resources and defaults into 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  # Dynamically mapped from replicas.min of the 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  # Restrictive standard
---
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

---

Next Step

Learn how this generation and synchronization is automated within the central pipeline cycle in GitOps with GitLab.