CDK8s Library Project¶

The CDK8s Library Project type provides an opinionated setup for creating AWS CDK construct libraries with CDK8s integration for Kubernetes deployment, combining best practices and common configurations.

Overview¶

This project type extends the standard AwsCdkConstructLibrary from projen with additional CDK8s features:

CDK8s integration for Kubernetes manifest generation
Multi-version Kubernetes support (v1.29 to v1.33)
Prettier configuration and VSCode settings - see Default Configurations
Common project structure and tooling setup
Configurable CDK8s options for custom workflows

Quick Start¶

To create a new CDK8s Library project, use the projen CLI:

npx projen new --from @jttc/projen-project-types cdk8s-library

This command will create a new project with the CDK8s Library template and prompt you for the required configuration options such as:

Project name
Author information
Repository URL
CDK version
Kubernetes version
Default branch

After the project is created, you can customize it further by editing the .projenrc.ts file:

.projenrc.ts
import { Cdk8sLibrary } from '@jttc/projen-project-types';
import { K8sVersion } from '@jttc/projen-project-types';

const project = new Cdk8sLibrary({
  name: 'my-awesome-cdk8s-library',
  author: 'Your Name',
  authorAddress: 'your.email@example.com',
  repositoryUrl: 'https://github.com/yourusername/my-awesome-cdk8s-library.git',
  cdkVersion: '2.1.0',
  defaultReleaseBranch: 'main',

  // CDK8s specific configuration
  k8sVersion: K8sVersion.V1_31,
  appPath: 'src/k8s',
  outputPath: 'manifests',
  imports: ['custom-k8s-constructs@1.0.0'],
});

project.synth();

Highlighted lines explanation:

Line 4: Choose a descriptive name for your CDK8s construct library
Line 8: Pin to a specific CDK version for consistency
Line 13: Set the Kubernetes version for CDK8s imports
Line 14: Configure custom path for Kubernetes source code
Line 15: Set output directory for generated manifests
Line 16: Add custom Kubernetes imports

Features¶

CDK8s Integration¶

The CDK8s Library project includes full CDK8s integration with:

Automatic CDK8s setup with configurable Kubernetes versions
Import generation from Kubernetes APIs and custom resources
TypeScript-first Kubernetes manifest authoring
CDK8s tasks for building and synthesizing manifests

Kubernetes Version Support¶

Choose from multiple supported Kubernetes versions:

Version	CDK8s Plus Package	Description
v1.29	`cdk8s-plus-29`	Kubernetes 1.29 API support
v1.30	`cdk8s-plus-30`	Kubernetes 1.30 API support (default)
v1.31	`cdk8s-plus-31`	Kubernetes 1.31 API support
v1.32	`cdk8s-plus-32`	Kubernetes 1.32 API support
v1.33	`cdk8s-plus-33`	Kubernetes 1.33 API support

Common Configurations¶

This project type includes the same common configurations as other project types:

Default Configurations

For complete details about Prettier and VSCode configurations, see Default Configurations. This includes:

Prettier Configuration - Code formatting rules and customization
VSCode Configuration - Editor settings and recommended extensions

Configuration Options¶

Basic Configuration¶

All standard AwsCdkConstructLibraryOptions are supported, plus CDK8s-specific options:

Basic CDK8s Library Configuration
const project = new Cdk8sLibrary({
  // Required CDK options
  name: 'my-cdk8s-library',
  author: 'Your Name',
  authorAddress: 'your.email@example.com', 
  repositoryUrl: 'https://github.com/yourusername/my-cdk8s-library.git',
  cdkVersion: '2.1.0',
  defaultReleaseBranch: 'main',

  // Optional CDK8s configurations (see sections below)
});

CDK8s-Specific Options¶

Kubernetes Version¶

Kubernetes Version Configuration
import { K8sVersion } from '@jttc/projen-project-types';

const project = new Cdk8sLibrary({
  // ... other options
  k8sVersion: K8sVersion.V1_31, // Default: V1_30
});

Custom Paths¶

Configure where CDK8s files are located:

Custom Path Configuration
const project = new Cdk8sLibrary({
  // ... other options
  appPath: 'src/k8s',        // Default: 'src'
  appFile: 'app.ts',         // Default: 'main.ts'
  outputPath: 'manifests',   // Default: 'kubernetes'
});

Custom Imports¶

Add additional Kubernetes resource imports:

Custom Imports Configuration
const project = new Cdk8sLibrary({
  // ... other options
  imports: [
    'cert-manager@v1.8.0',
    'prometheus-operator@v0.60.0',
    'custom-crds@latest',
  ],
});

Common Configuration Options¶

For Prettier and VSCode configuration options, refer to Default Configurations:

Prettier: Customization Guide
VSCode: Configuration Options

Examples¶

Basic CDK8s Library¶

Simple setup with default configurations:

.projenrc.ts - Basic Setup
import { Cdk8sLibrary } from '@jttc/projen-project-types';

const project = new Cdk8sLibrary({
  name: 'basic-cdk8s-library',
  author: 'Jane Smith',
  authorAddress: 'jane@company.com',
  repositoryUrl: 'https://github.com/company/basic-cdk8s-library.git',
  cdkVersion: '2.1.0',
  defaultReleaseBranch: 'main',
});

project.synth();

Advanced CDK8s Library¶

Customized setup with specific Kubernetes version and custom paths:

.projenrc.ts - Advanced Setup
import { Cdk8sLibrary, K8sVersion } from '@jttc/projen-project-types';

const project = new Cdk8sLibrary({
  name: 'advanced-cdk8s-library',
  author: 'John Developer',
  authorAddress: 'john@company.com',
  repositoryUrl: 'https://github.com/company/advanced-cdk8s-library.git',
  cdkVersion: '2.1.0',
  defaultReleaseBranch: 'main',

  // CDK8s customization
  k8sVersion: K8sVersion.V1_31,
  appPath: 'src/kubernetes',
  appFile: 'main.ts',
  outputPath: 'dist/manifests',
  imports: [
    'cert-manager@v1.13.0',
    'prometheus-operator@v0.70.0',
  ],

  // Standard configurations (see Default Configurations for options)
  prettier: true,
  vscode: true,
});

project.synth();

Highlighted lines explanation:

Line 12: Use Kubernetes v1.31 APIs
Line 13: Place CDK8s source files in src/kubernetes/
Line 14: Main entry file for CDK8s application
Line 15: Output generated manifests to dist/manifests/
Lines 16-19: Import cert-manager and Prometheus operator CRDs

Enterprise Setup¶

Example with minimal prettier configuration and disabled VSCode:

.projenrc.ts - Enterprise Setup
import { Cdk8sLibrary, K8sVersion } from '@jttc/projen-project-types';

const project = new Cdk8sLibrary({
  name: 'enterprise-cdk8s-library',
  author: 'Enterprise Team',
  authorAddress: 'team@enterprise.com',
  repositoryUrl: 'https://github.com/enterprise/cdk8s-library.git',
  cdkVersion: '2.1.0',
  defaultReleaseBranch: 'main',

  k8sVersion: K8sVersion.V1_32,

  // Custom configurations (see Default Configurations for more options)
  vscode: false,
  prettierOptions: {
    settings: {
      printWidth: 120,
      tabWidth: 4,
      singleQuote: false,
    },
  },
});

project.synth();

Highlighted lines explanation:

Line 11: Use latest supported Kubernetes version
Line 15: Disable VSCode configuration for enterprise environment
Lines 16-21: Custom prettier settings with longer lines and double quotes

Project Structure¶

After running projen synth, your CDK8s library project will have the following structure:

my-cdk8s-library/
├── src/
│   ├── main.ts              # Main CDK8s application entry point
│   └── index.ts             # Library exports
├── test/                    # Test files
├── kubernetes/              # Generated Kubernetes manifests (after synth)
├── cdk8s.yaml              # CDK8s configuration
├── package.json            # Dependencies including CDK8s packages
├── .prettierrc.json        # Code formatting configuration
├── .vscode/                # VSCode workspace settings
│   ├── settings.json
│   └── extensions.json
└── .projenrc.ts           # Projen configuration

Generated CDK8s Files¶

src/main.ts: Sample CDK8s application with basic Kubernetes resources
cdk8s.yaml: CDK8s configuration specifying app entry point and output location
kubernetes/: Directory where synthesized YAML manifests are generated

CDK8s Tasks¶

The project includes these npm scripts for CDK8s workflows:

Script	Command	Description
`cdk8s`	`cdk8s synth`	Generate Kubernetes manifests
`cdk8s:import`	`cdk8s import`	Import Kubernetes APIs and CRDs
`cdk8s:synth`	`cdk8s synth`	Alias for `cdk8s` command

Best Practices¶

Development Workflow¶

Define your constructs in TypeScript using CDK8s APIs
Import CRDs for custom resources: npm run cdk8s:import
Generate manifests regularly: npm run cdk8s
Test generated YAML with your Kubernetes cluster
Version your library using standard npm/projen publishing

Resource Organization¶

src/main.ts - Recommended Structure
import { App, Chart } from 'cdk8s';
import { Deployment, Service } from 'cdk8s-plus-31';

export class MyConstruct extends Chart {
  constructor(scope: App, id: string) {
    super(scope, id);

    // Define your Kubernetes resources here
    const deployment = new Deployment(this, 'app-deployment', {
      // ... configuration
    });

    const service = new Service(this, 'app-service', {
      // ... configuration
    });
  }
}

// For library usage
const app = new App();
new MyConstruct(app, 'my-construct');
app.synth();

Testing Strategy¶

Unit test your CDK8s constructs with Jest
Snapshot test generated manifests
Integration test with real Kubernetes clusters
Validate YAML output with kubeval or similar tools

Troubleshooting¶

Common Issues¶

Import Errors¶

If you encounter CDK8s import errors:

# Reimport Kubernetes APIs
npm run cdk8s:import

# Check your cdk8s.yaml configuration
cat cdk8s.yaml

Version Mismatches¶

Ensure your Kubernetes version matches your cluster:

// Update in .projenrc.ts
k8sVersion: K8sVersion.V1_31, // Match your cluster version

Path Issues¶

Verify your CDK8s paths are correctly configured:

cdk8s.yaml

language: typescript
app: npx ts-node src/main.ts
output: kubernetes

Getting Help¶

CDK8s Documentation: https://cdk8s.io/
Project Issues: GitHub Issues
AWS CDK: https://docs.aws.amazon.com/cdk/

Migration Guide¶

From Standard CDK Library¶

To migrate from a standard CDK library to CDK8s library:

Update your .projenrc.ts:

// Before
import { CdkLibrary } from '@jttc/projen-project-types';

// After  
import { Cdk8sLibrary } from '@jttc/projen-project-types';

Add CDK8s configuration:

const project = new Cdk8sLibrary({
  // ... existing options
  k8sVersion: K8sVersion.V1_31,
});

Run projen to regenerate:
```
npx projen
```

From Plain CDK8s¶

To adopt this project type from a plain CDK8s project:

Install the package:

npm install --save-dev @jttc/projen-project-types

Create .projenrc.ts with your current configuration
Run projen to apply the project template
Review and commit the generated configuration files

Contributing¶

Contributions to improve the CDK8s Library project type are welcome! Please check the repository for details on:

Reporting bugs
Suggesting enhancements
Submitting pull requests
Development workflow

Support¶

For support with the CDK8s Library project type:

Repository: GitHub Repository
Issues: GitHub Issues
Discussions: GitHub Discussions