kro-rgd-pulumi

What this skill does

# 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

```bash
# 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

```bash
# 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:

```typescript
// 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:

```typescript
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:

```typescript
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: [