Apply the Raw K8s Manifest YAML
The guides above provide examples on how to configure workloads and accessories with KCL, and generate the related Kubernetes resources with Kusion Module generators, which is the usage method we recommend, as it can achieve the separation of concerns between developers and platform engineers, reducing the cognitive burden on developers.
However, in some specific scenario, users may also have the need to directly use Kusion to apply and manage the raw Kubernetes manifest YAML files, such as taking over some existing resources and deploying CRD (CustomResourceDefinition), or other special resources.
To help users directly apply raw K8s manifests, the KusionStack community has provided the k8s_manifest Kusion Module.
The module definition and implementation, as well as the example can be found at here.
Prerequisites
Please refer to the prerequisites in the guide for deploying an application.
The example below also requires you to have initialized the project using the kusion workspace create, kusion project create, kusion stack create command, which will create a workspace and project, and also generate a kcl.mod file under the stack directory.
Managing Workspace Configuration
In the first guide in this series, we introduced a step to initialize a workspace with an empty configuration. The same empty configuration will still work in this guide, no changes are required there. Alternatively, if you have updated your workspace config in the previous guides, no changes need to be made either.
However, if you (or the platform team) would like to set some default paths for the raw K8s manifest YAML files 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 decalred by the platform engineers in the workspace configs will be merged with the ones declared by the developers in the AppConfiguration in main.k.
The workspace configuration needs to be updated with the command:
kusion workspace update dev -f dev.yaml
Example
To apply the specified raw K8s manifest YAML files 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 and Applying
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.
➜ dev git:(main) ✗ kusion generate
✔︎ Generating Spec in the Stack dev...
resources:
- id: v1:Namespace:test
type: Kubernetes
attributes:
apiVersion: v1
kind: Namespace
metadata:
creationTimestamp: null
name: test
spec: {}
status: {}
extensions:
GVK: /v1, Kind=Namespace
- id: apps/v1:Deployment:test:nginx-deployment
type: Kubernetes
attributes:
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: nginx
name: nginx-deployment
namespace: test
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- image: nginx:1.14.2
name: nginx
ports:
- containerPort: 80
dependsOn:
- v1:Namespace:test
secretStore: null
context: {}
Execute the kusion apply command, you may get the output like the following:
➜ dev git:(main) ✗ kusion apply
✔︎ Generating Spec in the Stack dev...
Stack: dev
ID Action
v1:Namespace:test Create
apps/v1:Deployment:test:nginx-deployment Create
Do you want to apply these diffs?:
> yes
Start applying diffs ...
✔︎ Succeeded v1:Namespace:test
✔︎ Succeeded apps/v1:Deployment:test:nginx-deployment
Apply complete! Resources: 2 created, 0 updated, 0 deleted.
[v1:Namespace:test]
Type Kind Name Detail
READY Namespace test Phase: Active
[apps/v1:Deployment:test:nginx-deployment]
Type Kind Name Detail
READY Deployment nginx-deployment Ready: 3/3, Up-to-date: 3, Available: 3
READY ReplicaSet nginx-deployment-7fb96c846b Desired: 3, Current: 3, Ready: 3
READY Pod nginx-deployment-7fb96c846b-d9pp4 Ready: 1/1, Status: Running, Restart: 0, Age: 2s
Validation
We can verify the Deployment and Pod we have just applied:
➜ dev git:(main) ✗ kubectl get deployment -n test
NAME READY UP-TO-DATE AVAILABLE AGE
nginx-deployment 3/3 3 3 70s
➜ dev git:(main) ✗ kubectl get pod -n test
NAME READY STATUS RESTARTS AGE
nginx-deployment-7fb96c846b-d9pp4 1/1 Running 0 87s
nginx-deployment-7fb96c846b-j45nt 1/1 Running 0 87s
nginx-deployment-7fb96c846b-tnz5f 1/1 Running 0 87s