Applying Raw Kubernetes Manifest with Kusion

We have introduced many cases of how to use Kusion CLI to complete the deployment of an application running on Kubernetes. And these examples all involve using the corresponding Kusion Module Generator to generate Spec from the Workload and Accessories declared in the abstracted application model AppConfiguration with KCL. It is the usage we recommend, as it can achieve the separation of concerns between Developers and Platform Engineers, and thus reducing the cognitive burden on the developers.

However, in some specific scenario, users may also have the need to directly use Kusion CLI to apply the raw Kubernetes manifests, such as taking over some existing resources and deploying some special resources like CRDs (CustomResourceDefinition), benefitting from Kusion’s previewing resource diffs and managing the application Releases .

Hence, we are exciting to announce that, to help users directly apply raw K8s manifests, the KusionStack community has provided a k8s_manifest module.

The module definition and implementation, as well as the example we are about to show can be found here.

Pre-requisites

Please refer to the pre-requisites in the guide for deploying an application with Kusion.

The example below also requires users to have initialized the project with the command of kusion workspace create , kusion project create , and kusion stack create , which will create a workspace and a project, and also generate a kcl.mod file under the stack directory.

Managing Workspace Configuration

Steps to initialize a workspace with an empty configuration can be found at this document. And the same empty configuration will still work in this guide, no changes are required here.

However, if you (or the platform team) would like to set some default paths for the raw K8s manifests to standardize the behavior of applications in the dev workspace, you can do so by updating the dev.yaml with the following config block:

modules: 
    k8s_manifest: 
        path: oci://ghcr.io/kusionstack/k8s_manifest
        version: 0.1.0
        configs: 
            default: 
                # The default paths to apply for the raw K8s manifest YAML files. 
                paths: 
                    - /path/to/k8s_manifest.yaml
                    - /dir/to/k8s_manifest/

Please note that the paths declared by the platform engineers in the workspace configs will be merged with the ones declared in the AppConfiguration in main.k .

The workspace configs need to be updated with the command:

kusion workspace update dev -f dev.yaml

Example

To apply the specified raw K8s manifests with k8s_manifest module, please use the v0.2.1 version of kam , whose workload is no longer a required field in the AppConfiguration model.

An example is shown below:

kcl.mod :

[dependencies]
kam = { git = "https://github.com/KusionStack/kam.git", tag = "v0.2.1" }
k8s_manifest = { oci = "oci://ghcr.io/kusionstack/k8s_manifest", tag = "0.1.0" }

stack.yaml :

# Generate a specified namespace 
name: dev
extensions: 
  - kind: kubernetesNamespace
    kubernetesNamespace: 
      namespace: test

main.k :

import kam.v1.app_configuration as ac
import k8s_manifest
test: ac.AppConfiguration {
    accessories: {
        "k8s_manifests": k8s_manifest.K8sManifest {
            paths: [
                # The `test.yaml` should be placed under the stack directory, 
                # as it is declared using a relative path. 
                "./test.yaml"
            ]
        }
    }
}

test.yaml :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  namespace: test
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

Generate Spec

Execute the kusion generate command, the Deployment in the test.yaml will be generated into a Kusion Resource with a Kusion ID in the Spec .

Preview and Apply

Execute the kusion preview command, we can review the resource three-way diffs for a more secure deployment.

Execute the kusion apply command to deploy the K8s resources.