CDK8S Patterns#

Understanding construct patterns and best practices in cdk8s-mailu.

Introduction#

CDK8S (Cloud Development Kit for Kubernetes) allows you to define Kubernetes applications using familiar programming languages. cdk8s-mailu leverages CDK8S patterns to provide a type-safe, testable, and maintainable way to deploy Mailu.

Core Concepts#

Constructs#

What is a Construct?

A construct is a composable building block that encapsulates one or more Kubernetes resources. In cdk8s-mailu, each Mailu component is implemented as a construct.

export class AdminConstruct extends Construct {
  constructor(scope: Construct, id: string, config: AdminConfig) {
    super(scope, id);

    // Create Deployment
    new Deployment(this, 'deployment', { ... });

    // Create Service
    new Service(this, 'service', { ... });
  }
}

Benefits:

Encapsulation - Hide complex resource definitions
Reusability - Use the same construct in multiple charts
Testability - Unit test each construct independently
Composability - Combine constructs to build applications

Charts#

What is a Chart?

A chart is a top-level construct that represents a complete Kubernetes application. It contains all the constructs and resources needed for deployment.

export class MailuChart extends Chart {
  constructor(scope: Construct, id: string, props: MailuChartProps) {
    super(scope, id, props);

    // Create namespace
    const ns = new Namespace(this, 'namespace', { ... });

    // Create constructs
    new FrontConstruct(this, 'front', config);
    new AdminConstruct(this, 'admin', config);
    // ...
  }
}

Characteristics:

Extends Chart from cdk8s
Entry point for synthesis
Manages shared resources (namespace, configmaps)
Coordinates multiple constructs

Apps#

What is an App?

An app is the root of your CDK8S application. It contains one or more charts and is responsible for synthesizing Kubernetes manifests.

const app = new App();
new MailuChart(app, 'mailu', { ... });
app.synth();  // Generate YAML files

Design Patterns#

1. Configuration Object Pattern#

Pattern: Pass a single configuration object instead of many parameters

// Good: Single configuration object
new AdminConstruct(this, 'admin', {
  namespace: 'mailu',
  resources: { requests: { cpu: '100m' } },
  image: { repository: 'mailu/admin', tag: '2.0' },
});

// Avoid: Many individual parameters
new AdminConstruct(this, 'admin',
  'mailu',
  { cpu: '100m' },
  'mailu/admin',
  '2.0'
);

Benefits:

Type-safe with TypeScript interfaces
Easy to add optional parameters
Clear parameter names
IDE autocomplete support

2. Shared Configuration Pattern#

Pattern: Extract common configuration to shared objects

// Shared environment ConfigMap
const sharedConfig = new ConfigMap(this, 'shared-config', {
  metadata: { namespace: config.namespace },
  data: {
    DOMAIN: config.domain,
    HOSTNAMES: config.hostnames.join(','),
  },
});

// Reference in multiple constructs
new AdminConstruct(this, 'admin', {
  ...config,
  sharedConfigMap: sharedConfig,
});

Benefits:

Avoid duplication
Single source of truth
Easier to maintain
Consistent across components

3. Conditional Resource Creation#

Pattern: Create resources based on configuration flags

export class MailuChart extends Chart {
  constructor(scope: Construct, id: string, config: MailuConfig) {
    super(scope, id);

    // Always create core components
    new FrontConstruct(this, 'front', config);
    new AdminConstruct(this, 'admin', config);

    // Conditionally create optional components
    if (config.components.clamav) {
      new ClamAVConstruct(this, 'clamav', config);
    }

    if (config.components.webdav) {
      new WebdavConstruct(this, 'webdav', config);
    }
  }
}

Benefits:

Flexible deployments
Only create what’s needed
Clear intent in code
Reduces resource usage

4. Resource Requirements Pattern#

Pattern: Provide sensible defaults with override capability

interface ComponentConfig {
  resources?: {
    requests?: { cpu: string; memory: string };
    limits?: { cpu: string; memory: string };
  };
}

// In construct
const resources = config.resources ?? {
  requests: { cpu: '100m', memory: '256Mi' },
  limits: { cpu: '300m', memory: '512Mi' },
};

Benefits:

Works out of the box
Production-ready defaults
Easy to customize
Explicit resource management

5. Secret Reference Pattern#

Pattern: Reference existing secrets instead of inline values

interface SecretReference {
  name: string;  // Secret name
  key: string;   // Key within secret
}

// Usage
database: {
  password: {
    name: 'postgres-credentials',
    key: 'password',
  },
}

// In construct
const passwordEnv = EnvValue.fromSecretValue({
  secret: Secret.fromSecretName(this, 'db-secret', config.password.name),
  key: config.password.key,
});

Benefits:

Never expose secrets in code
Integrate with secret management tools
Type-safe secret references
Clear intent

Testing Patterns#

1. Snapshot Testing#

Pattern: Verify generated manifests haven’t changed unexpectedly

test('generates expected manifests', () => {
  const app = Testing.app();
  const chart = new MailuChart(app, 'test', { ... });
  const results = Testing.synth(chart);
  expect(results).toMatchSnapshot();
});

Benefits:

Catch unintended changes
Document expected output
Fast regression testing

2. Resource Count Testing#

Pattern: Verify expected number of resources

test('creates correct number of resources', () => {
  const app = Testing.app();
  const chart = new MailuChart(app, 'test', { ... });
  const results = Testing.synth(chart);

  expect(results.filter(r => r.kind === 'Deployment')).toHaveLength(5);
  expect(results.filter(r => r.kind === 'Service')).toHaveLength(5);
});

Benefits:

Verify resource creation
Catch missing/extra resources
Quick validation

3. Configuration Validation Testing#

Pattern: Test that invalid configurations are rejected

test('rejects invalid domain', () => {
  const app = Testing.app();
  expect(() => {
    new MailuChart(app, 'test', {
      domain: 'invalid domain with spaces',
    });
  }).toThrow('Invalid domain format');
});

Benefits:

Fail fast on bad config
Clear error messages
Prevent invalid deployments

Best Practices#

1. Type Everything#

Use TypeScript interfaces for all configuration:

interface MailuConfig {
  domain: string;
  namespace: string;
  components: ComponentToggles;
  // ... all fields typed
}

2. Validate Early#

Validate configuration in construct constructors:

if (!isValidDomain(config.domain)) {
  throw new Error(`Invalid domain: ${config.domain}`);
}

3. Provide Defaults#

Make common configurations work with minimal input:

const resources = config.resources ?? DEFAULT_RESOURCES;
const image = config.image ?? DEFAULT_IMAGE;

4. Document Decisions#

Use JSDoc comments to explain choices:

/**
 * Creates Front component with Nginx reverse proxy.
 *
 * Note: When using Traefik TLS termination, the nginx-patch-configmap
 * is automatically applied to wrap backend connections properly.
 */
export class FrontConstruct extends Construct { ... }

5. Keep Constructs Focused#

Each construct should have a single responsibility:

// Good: Single component
class AdminConstruct { ... }
class FrontConstruct { ... }

// Avoid: Multiple components in one construct
class AllMailuComponents { ... }

CDK8S Patterns#

Introduction#

Core Concepts#

Constructs#

Charts#

Apps#

Design Patterns#

1. Configuration Object Pattern#

2. Shared Configuration Pattern#

3. Conditional Resource Creation#

4. Resource Requirements Pattern#

5. Secret Reference Pattern#

Testing Patterns#

1. Snapshot Testing#

2. Resource Count Testing#

3. Configuration Validation Testing#

Best Practices#

1. Type Everything#

2. Validate Early#

3. Provide Defaults#

4. Document Decisions#

5. Keep Constructs Focused#

See Also#