KRO ResourceGraphDefinition with Pulumi TypeScript

Generate production-ready Kubernetes Resource Orchestrator (KRO) ResourceGraphDefinitions using Pulumi TypeScript for creating custom Kubernetes APIs and composing resources with AWS ACK integration.

When to Use This Skill

Use this skill when the user wants to:

• Create custom Kubernetes APIs using KRO ResourceGraphDefinitions
• Compose multiple K8s resources as a single declarative unit
• Integrate AWS resources via ACK (S3, RDS, DynamoDB, etc.) with KRO
• Build platform abstractions for developer self-service
• Generate Pulumi TypeScript code for KRO resources
• Define resource dependencies with automatic orchestration
• Create reusable application templates with CEL expressions (use CEL skill when necessary)

Overview

What is KRO?

KRO (Kube Resource Orchestrator) is an open-source Kubernetes-native project that allows you to:

• Define custom Kubernetes APIs without writing Go controllers
• Compose multiple resources as a directed acyclic graph (DAG)
• Automatically manage resource dependencies and ordering
• Use CEL expressions for dynamic configuration
• Provide lifecycle management with drift detection

What is ResourceGraphDefinition (RGD)?

An RGD is KRO's core custom resource that:

• Defines a schema for your custom API (apiVersion, kind, spec, status)
• Lists resources to create with CEL expression templating
• Automatically generates a CRD when applied
• Deploys a microcontroller to manage instances

Pulumi Integration

Using Pulumi TypeScript to deploy KRO resources provides:

• Type safety for resource definitions
• IDE support with autocomplete and error checking
• Programmatic logic for complex configurations
• GitOps-friendly workflow
• Multi-stack architecture for separation of concerns

Prerequisites

Required Components

# 1. Kubernetes cluster (1.25+ for CEL support)
kubectl version

# 2. KRO installed in cluster
helm install kro oci://ghcr.io/kubernetes-sigs/kro/charts/kro \
  --namespace kro-system \
  --create-namespace

# 3. ACK controllers (if using AWS resources)
helm install ack-s3-controller \
  oci://public.ecr.aws/aws-controllers-k8s/s3-chart \
  --namespace ack-system \
  --create-namespace

# 4. Pulumi CLI and Node.js
pulumi version
node --version

Pulumi Project Setup

# Create new Pulumi project
mkdir my-kro-project && cd my-kro-project
pulumi new kubernetes-typescript

# Install dependencies
npm install @pulumi/kubernetes @pulumi/pulumi

Instructions

Step 1: Understand the Requirements

Before generating code, gather:

1. Custom API design: What kind/apiVersion? What fields in spec?
2. Resources to compose: Deployments, Services, ConfigMaps, ACK resources?
3. Dependencies: Which resources depend on others?
4. Conditions: Any conditional resource creation (includeWhen)?
5. Status fields: What status to expose to users?

Step 2: Design the Schema

Define the user-facing API:

// Schema design principles:
// - Use descriptive field names
// - Provide sensible defaults
// - Group related fields in nested objects
// - Add validation rules for constraints

Step 3: Generate Pulumi TypeScript Code

Use this structure for KRO RGD:

import * as k8s from "@pulumi/kubernetes";
import * as pulumi from "@pulumi/pulumi";

// Create the ResourceGraphDefinition
const rgd = new k8s.apiextensions.CustomResource("my-app-rgd", {
    apiVersion: "kro.run/v1alpha1",
    kind: "ResourceGraphDefinition",
    metadata: {
        name: "my-application",
        namespace: "default",
    },
    spec: {
        schema: {
            apiVersion: "v1alpha1",
            kind: "Application",
            spec: {
                // Define user-configurable fields
                name: "string",
                image: "string | default=\"nginx:latest\"",
                replicas: "integer | default=3",
            },
            status: {
                // Auto-populated status fields
                ready: "${deployment.status.conditions.exists(c, c.type == 'Available' && c.status == 'True')}",
                availableReplicas: "${deployment.status.availableReplicas}",
            },
            validation: [
                {
                    expression: "self.replicas >= 1 && self.replicas <= 100",
                    message: "Replicas must be between 1 and 100",
                },
            ],
        },
        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}",
                                    },
                                ],
                            },
                        },
                    },
                },
                readyWhen: [
                    "${deployment.status.conditions.exists(c, c.type == 'Available' && c.status == 'True')}",
                ],
            },
            {
                id: "service",
                template: {
                    apiVersion: "v1",
                    kind: "Service",
                    metadata: {
                        name: "${schema.spec.name}-service",
                    },
                    spec: {
                        selector: {
                            app: "${schema.spec.name}",
                        },
                        ports: [
                            {
                                port: 80,
                                targetPort: 8080,
                            },
                        ],
                    },
                },
            },
        ],
    },
});

export const rgdName = rgd.metadata.name;

Step 4: Add ACK Resources (AWS Integration)

For AWS resources via ACK:

const rgdWithAws = new k8s.apiextensions.CustomResource("app-with-aws-rgd", {
    apiVersion: "kro.run/v1alpha1",
    kind: "ResourceGraphDefinition",
    metadata: {
        name: "application-with-storage",
    },
    spec: {
        schema: {
            apiVersion: "v1alpha1",
            kind: "AppWithStorage",
            spec: {
                name: "string",
                image: "string",
                bucketName: "string",
            },
            status: {
                bucketArn: "${bucket.status.ackResourceMetadata.arn}",
                ready: "${deployment.status.conditions.exists(c, c.type == 'Available' && c.status == 'True')}",
            },
        },
        resources: [
            // ACK S3 Bucket
            {
                id: "bucket",
                template: {
                    apiVersion: "s3.services.k8s.aws/v1alpha1",
                    kind: "Bucket",
                    metadata: {
                        name: "${schema.spec.bucketName}",
                    },
                    spec: {
                        name: "${schema.spec.bucketName}",
                        tagging: {
                            tagSet: [
                                {
                                    key: "ManagedBy",
                                    value: "KRO",
                                },
                            ],
                        },
                    },
                },
                readyWhen: [
                    "${bucket.status.ackResourceMetadata.?arn != null}",
                ],
            },
            // Deployment referencing bucket
            {
                id: "deployment",
                template: {
                    apiVersion: "apps/v1",
                    kind: "Deployment",
                    metadata: {
                        name: "${schema.spec.name}",
                    },
                    spec: {
                        replicas: 3,
                        selector: {
                            matchLabels: {
                                app: "${schema.spec.name}",
                            },
                        },
                        template: {
                            metadata: {
                                labels: {
                                    app: "${schema.spec.name}",
                                },
                            },
                            spec: {
                                containers: [
                                    {
                                        name: "app",
                                        image: "${schema.spec.image}",
                                        env: [
                                            {
                                                name: "S3_BUCKET",
                                                value: "${schema.spec.bucketName}",
                                            },
                                            {
                                                name: "S3_BUCKET_ARN",
                                                value: "${bucket.status.ackResourceMetadata.arn}",
                                            },
                                        ],
                                    },
                                ],
                            },
                        },
                    },
                },
            },
        ],
    },
});

Step 5: Deploy and Test

# Deploy the RGD
pulumi up

# Verify RGD is active
kubectl get resourcegraphdefinition
kubectl describe resourcegraphdefinition my-application

# Check generated CRD
kubectl get crd | grep kro

# Create an instance of your custom API
kubectl apply -f - <<EOF
apiVersion: v1alpha1
kind: Application
metadata:
  name: my-test-app
spec:
  name: my-test-app
  image: nginx:1.21
  replicas: 5
EOF

# Monitor instance
kubectl get application
kubectl describe application my-test-app

CEL Expression Reference

Referencing Schema Fields

${schema.spec.name}              // User-provided spec field
${schema.metadata.name}          // Instance name
${schema.metadata.namespace}     // Instance namespace
${schema.metadata.uid}           // Unique ID

Referencing Other Resources

${deployment.metadata.name}      // Resource name
${deployment.spec.replicas}      // Spec field
${deployment.status.?endpoint}   // Optional status field (use ? for null safety)

Operators and Functions

// Ternary conditional
${schema.spec.env == 'prod' ? 10 : 3}

// String concatenation
${"prefix-" + schema.spec.name}

// Null coalescing
${deployment.status.?ready ?? false}

// List operations
${deployment.status.conditions.exists(c, c.type == 'Available' && c.status == 'True')}
${schema.spec.containers.map(c, c.name)}

// Type conversion
${string(schema.spec.replicas)}
${int(schema.spec.replicasString)}

Conditional Resource Inclusion

resources:
  - id: ingress
    includeWhen:
      - ${schema.spec.ingress.enabled}
    template:
      apiVersion: networking.k8s.io/v1
      kind: Ingress
      # ...

Common Patterns

Pattern 1: Web Application Stack

// Creates: Deployment + Service + optional Ingress + optional HPA
const webAppRgd = createWebAppRgd({
    name: "webapp",
    supportsIngress: true,
    supportsAutoscaling: true,
});

Pattern 2: Database Application

// Creates: ACK RDS Instance + Secret + ConfigMap + Deployment
const dbAppRgd = createDatabaseAppRgd({
    name: "dbapp",
    dbEngine: "postgres",
    withBackup: true,
});

Pattern 3: Microservices Bundle

// Creates: Multiple Deployments + Services + NetworkPolicies
const microservicesRgd = createMicroservicesRgd({
    name: "platform",
    services: ["api", "worker", "scheduler"],
});

Pattern 4: Multi-Environment App

// Creates environment-specific resources with quotas
const envAppRgd = createEnvironmentAppRgd({
    name: "envapp",
    environments: ["dev", "staging", "prod"],
});

ACK Resource Integration

Supported ACK Resources

Service	Resource Types	ACK Controller
S3	Bucket	s3-controller
RDS	DBInstance, DBCluster, DBSubnetGroup	rds-controller
DynamoDB	Table, GlobalTable	dynamodb-controller
SQS	Queue	sqs-controller
SNS	Topic, Subscription	sns-controller
Lambda	Function	lambda-controller
ElastiCache	CacheCluster, ReplicationGroup	elasticache-controller

ACK Status Fields

// Common ACK status patterns
${bucket.status.ackResourceMetadata.arn}           // AWS ARN
${bucket.status.ackResourceMetadata.ownerAccountID} // AWS Account
${dbinstance.status.endpoint.address}               // RDS endpoint
${dbinstance.status.endpoint.port}                  // RDS port
${queue.status.queueURL}                            // SQS URL

Best Practices

1. Schema Design

# Good: Clear, intuitive fields with defaults
spec:
  name: string
  image: string | default="nginx:latest"
  replicas: integer | default=3
  environment: string | default="dev"

# Bad: Cryptic field names, no defaults
spec:
  n: string
  i: string
  r: integer

2. Validation Rules

validation:
  - expression: "self.replicas >= 1 && self.replicas <= 100"
    message: "Replicas must be between 1 and 100"
  - expression: "self.environment in ['dev', 'staging', 'prod']"
    message: "Environment must be dev, staging, or prod"
  - expression: "self.environment == 'prod' ? self.replicas >= 3 : true"
    message: "Production requires at least 3 replicas"

3. Readiness Conditions

readyWhen:
  - ${deployment.status.conditions.exists(c, c.type == 'Available' && c.status == 'True')}
  - ${deployment.status.readyReplicas == deployment.spec.replicas}

4. Status Exposure

status:
  ready: ${deployment.status.conditions.exists(c, c.type == 'Available' && c.status == 'True')}
  availableReplicas: ${deployment.status.availableReplicas}
  endpoint: ${service.spec.clusterIP}
  bucketArn: ${bucket.status.ackResourceMetadata.?arn ?? 'pending'}

5. Naming Conventions

# Consistent naming pattern
metadata:
  name: ${schema.spec.name}
  labels:
    app.kubernetes.io/name: ${schema.spec.name}
    app.kubernetes.io/managed-by: kro

Reference Files

• KRO Schema Reference - Complete RGD schema documentation
• ACK Resources Reference - ACK resource definitions and status fields
• CEL Expressions Reference - CEL syntax and functions
• Templates - Production-ready Pulumi TypeScript templates

Current Status

KRO Status: v1alpha1 (Alpha)

• Not yet production-ready
• Breaking changes may occur
• Kubernetes 1.25+ required
• Latest release: v0.7.1 (December 2025)

Recommendation: Use in development/testing environments while awaiting v1beta1 for production readiness.

Output Format

When generating KRO RGD with Pulumi, always provide:

1. Complete Pulumi TypeScript code with proper types
2. RGD specification with schema, resources, and validations
3. Example instance YAML showing how to use the custom API
4. Deployment instructions for both Pulumi and kubectl
5. Testing commands to verify the deployment