DOCSEARCHbyAlgolia
Submit Docs

cdk8s Documentation

repository·master·Indexed 26 days ago

https://github.com/cdk8s-team/cdk8s

An open-source software development framework for defining Kubernetes applications and reusable abstractions using familiar programming languages and rich object-oriented APIs. cdk8s synthesizes code into standard Kubernetes manifests through a construct tree consisting of App, Chart, and Resources. The ecosystem includes the core library, cdk8s-cli, and cdk8s-plus for high-level L2 constructs.

Tokens
123.9K
Snippets
312
Records
808
Agent score
88%

What's inside cdk8s

  1. Overview of cdk8s+

    master
    cdk8s+ is a high-level abstraction library for authoring Kubernetes applications. It is built on top of the auto-generated building blocks provided by cdk8s, providing hand-crafted constructs for each native Kubernetes object to offer richer APIs with reduced complexity.

  2. Understand construct-aware validation reports

    master

    When validation fails during cdk8s synth, the CLI uses annotations added to the generated manifests to provide a traceback to the original source code. This helps developers locate exactly which construct caused the violation. The following annotations are used:

    • cdk8s.io/construct.path: The path to the construct (e.g., Chart/Deployment).
    • cdk8s.io/construct.traceback: A list of file names and line numbers representing the code path to the construct.

  3. Use the cdk8s CLI

    master

    The cdk8s command-line interface is a utility shipped with the cdk8s toolchain to help work with cdk8s apps. While not strictly required to use the library, it provides useful utilities for managing your projects.

    Note: This documentation refers to version 2.x of the cdk8s toolchain. If you are using version 1.x, you should consult the Migrating from 1.x Guide.

  4. Understand the role of cdk8s in manifest validation

    master

    cdk8s facilitates a "left-shift" approach to Kubernetes manifest validation. Instead of relying solely on a deployment-time gate (like an Admission Controller), cdk8s allows organizations to integrate validation directly into the developer's local workflow (authoring time) and the CI/CD pipeline (build time).

    By coupling manifest authoring with validation, cdk8s helps ensure that every manifest generated via cdk8s synth is checked against:

    1. Kubernetes Schema: Ensuring resources comply with defined Kubernetes schemas.
    2. Out-of-schema Validations: Checking for logic that the schema doesn't catch (e.g., mutual exclusivity of properties or specific label constraints).
    3. Best Practices: Enforcing standards like memory limits or liveness/readiness probes.
    4. Security and Compliance: Validating against organizational-specific policies and security standards.

    To benefit from this, ensure that cdk8s synth is a standard part of your local development and build processes.

  5. Understand the cdk8s core concepts

    master

    cdk8s is a framework for defining Kubernetes applications using object-oriented APIs. Applications are structured as a tree of constructs:

    • App: The root of the construct tree.
    • Chart: A class that extends the Chart class. Each chart synthesizes into a separate Kubernetes manifest file.
    • Resources: The leaf nodes representing Kubernetes resources like Pod, Service, Deployment, or ReplicaSet.

    Synthesis Workflow:

    1. Write your application in a supported programming language.
    2. Execute the app to synthesize the charts.
    3. The synthesized manifests are output to the dist directory.
    4. Apply the manifests to a cluster using kubectl apply -f dist/chart.k8s.yaml or a GitOps tool like Flux.

  7. Understand ApiObject and Kubernetes resource imports

    master

    An ApiObject is the base class representing a Kubernetes manifest entry (level 0). While you rarely use ApiObject directly, most Kubernetes resources imported via cdk8s import extend this class.

    When importing API objects, cdk8s automatically prefixes class names with Kube to distinguish them from high-level cdk8s+ APIs. You can modify this behavior using the CLI:

    • Use --class-prefix <string> to set a custom prefix.
    • Use --no-class-prefix to remove the prefix entirely (use caution to avoid naming conflicts).

  9. Understand the cdk8s workflow

    master

    cdk8s is a framework for defining Kubernetes applications using object-oriented programming. The workflow follows these steps:

    1. Define: Write programs using supported languages, structuring them as a tree of constructs starting from an App.
    2. Compose: Create Chart classes (which extend the Chart class) to group resources like Pod, Service, or Deployment.
    3. Synthesize: Execute the app to generate pure Kubernetes YAML manifests into a dist directory.
    4. Deploy: Apply the generated manifests to a cluster using standard tools like kubectl apply -f dist/chart.k8s.yaml or GitOps tools like Flux.

    Note: cdk8s only defines and synthesizes manifests; it does not interact with the Kubernetes cluster directly.

  10. Use StatefulSet for stateful applications

    master
    The StatefulSet class implements IScalable and is used to manage stateful applications. Unlike a Deployment, a StatefulSet maintains a sticky identity for each Pod, providing guarantees about ordering and uniqueness. This is useful when using storage volumes to provide persistence, as the persistent Pod identifiers make it easier to match existing volumes to replacement Pods.

  11. Understand L2 (Layer 2) constructs in cdk8s

    master

    In cdk8s, high-level abstractions are referred to as L2 (Layer 2) constructs. These are designed to sit on top of basic Kubernetes building blocks to simplify resource interaction and better represent a developer's mental model.

    Key capabilities of L2 constructs include:

    • Providing sane defaults.
    • Automatically creating and wiring dependent resources.
    • Exposing type-safe semantic APIs that convey intent rather than raw data.

  12. Understand cdk8s Constructs

    master

    Constructs are the fundamental building blocks of cdk8s. They allow you to create higher-level abstractions for Kubernetes resources using standard object-oriented programming.

    Think of constructs as programmatically defined Helm Charts that leverage the full power of your programming language. By using constructs, you can:

    • Express abstraction APIs using strongly-typed data types.
    • Implement rich interactions via methods and properties.
    • Create polymorphic programming models using interfaces and base classes.
    • Distribute abstractions through standard package managers.
    • Test and version your Kubernetes abstractions using standard software engineering practices.