Getting started with cdk8s for Python¶

In this guide, we’ll walk you through the most essential concepts you need to know in order to build a Kubernetes application using cdk8s for Python.

Prerequisites¶

To install the cdk8s CLI, you need the Node Package Manager (npm) installed on your local machine.
cdk8s for Python supports Python versions 3.7+. Check your Python version:
```
python3 --version
```

Set up an environment¶

Initial setup¶

To get setup, follow these general steps:

To begin, you’ll need pipenv 2018.11.26+ installed. If you’re not familiar with this setup, use these instructions to setup pipenv.

Install the CLI¶

To initialize a cdk8s project and auto-generate Kubernetes manifests based on our code, we need the cdk8s CLI:

Run the following command to install the CLI using npm. For more installation methods, see Install the cdk8s CLI.
```
npm install -g cdk8s-cli
```

Create a project¶

Next, we’ll initialize a project to create the directory structure and install the necessary dependencies using the init command.

In a terminal window, run the following command in an empty directory:
```
cdk8s init python-app
```

In your preferred code editor, open the main.py file.

#!/usr/bin/env python
from constructs import Construct
from cdk8s import App, Chart


class MyChart(Chart):
   def __init__(self, scope: Construct, id: str):
       super().__init__(scope, id)

       # define resources here


app = App()
MyChart(app, "python")

app.synth()

This sample shows the basic structure of a cdk8s application with the essential libraries: constructs and cdk8s. These libraries supply the foundational classes and methods required for working with cdk8s. It includes the following components:

A custom MyChart class inherits from the Chart base class provided by the cdk8s library, serving as a representation of the Kubernetes resources to be generated and managed.
The __init__ method within the MyChart class is responsible for initializing the base class (Chart) and specifying the Kubernetes resources. This method is invoked when creating an instance of the class.
An instance of the App class signifies the primary entry point of the cdk8s application and oversees the application’s lifecycle and resources.
An instance of the MyChart class is created by passing the app instance and a string identifier, “python”, as arguments. This action generates and registers the Kubernetes resources defined in the MyChart class within the application. Note that in this example, the “python” string identifier is autogenerated based on the current directory name.
The synth method is called on the app instance, which produces the required Kubernetes YAML manifest files based on the defined resources. Note that in this example, we haven’t defined any resources within the MyChart constructor, so running the “cdk8s synth” command in the CLI would generate a blank Kubernetes manifest.

Define Kubernetes resources¶

Now, we are ready to define Kubernetes resources for our application. In this sample, we define a basic Kubernetes Deployment for a sample application. We start by importing the imports directory and the k8s sub-directory, which contains an __init__.py file where all cdk8s Kubernetes classes and functions are defined.

Copy the code sample¶

Copy and paste the following code sample into the existing main.py file of your project.

#!/usr/bin/env python
from cdk8s import App, Chart
from constructs import Construct
from imports import k8s


class MyChart(Chart):
   def __init__(self, scope: Construct, ns: str, app_label: str):
       super().__init__(scope, ns)

       # Define a Kubernetes Deployment
       k8s.KubeDeployment(self, "my-deployment",
                       spec=k8s.DeploymentSpec(
                           replicas=3,
                           selector=k8s.LabelSelector(match_labels={"app": app_label}),
                           template=k8s.PodTemplateSpec(
                               metadata=k8s.ObjectMeta(labels={"app": app_label}),
                               spec=k8s.PodSpec(containers=[
                                   k8s.Container(
                                       name="app-container",
                                       image="nginx:1.19.10", # Using public nginx image
                                       ports=[k8s.ContainerPort(container_port=80)] # Nginx listens on port 80 by default
                                   )
                               ])
                           )
                       )
                   )

app = App()
MyChart(app, "getting-started", app_label="my-app")

app.synth()

A few things worth noting about this sample:

The __init__ method in the custom MyChart class uses idiomatic Python’s features to construct a Kubernetes Deployment. The Deployment is created with specific parameters including replica count, label selectors, and pod specifications. Just as in the custom MyChart class instantiation process, this approach utilizes Python’s flexible handling of dictionary data structures to dynamically assign the “app” key in label selectors and metadata labels for our Kubernetes resources, creating a clear and concise way to set key configuration details.

Generate Kubernetes manifests¶

After you have defined the Kubernetes resources for your application, you are ready to generate the Kubernetes manifest that will define your Deployment resource.

Run the synth command¶

Open a terminal and navigate to your project directory.
Run the synth command. This command generates a Kubernetes manifest file in the dist folder of your project directory. The manifest file contains all the resources you defined inside the MyChart class.
```
cdk8s synth
```

View the manifest¶

Open the dist/getting-started.k8s.yaml file. You should see a Kubernetes manifest similar to the following:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: getting-started-my-deployment-c85252a6
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - image: nginx:1.19.10
          name: app-container
          ports:
            - containerPort: 80

Conclusion¶

Throughout this guide, we introduced you to the cdk8s Python library and guided you through the process of creating a cdk8s Python application. We initiated a simple project and constructed a Kubernetes Deployment using cdk8s code. This included leveraging Python-specific programming language conventions to dynamically set the “app” key in “label” selectors and “metadata” labels for Kubernetes resources using Python’s versatile handling of dictionary data structures.

Next up¶

To run a complete code sample, we recommend diving into the Kubernetes Deployment and Service using the cdk8s-core sample application.