refactor: judge kubernetes user guide structure

versioned_docs/version-0.5.0/user_docs/guides/working-with-k8s/adopt_from_kubernetes.md → docs/user_docs/guides/working-with-k8s/1-adopt-from-kubernetes.md

@@ -1,40 +1,49 @@
-# Adopt From Kubernetes to KCL
+---
+title: "Adopt From Kubernetes"
+sidebar_position: 1
+---
 
-## 1. Kubernetes OpenAPI Spec
+## Introduction
+
+KCL provides many out of the box support for Kubernetes configuration. Through KCL tools, we can integrate Kubernetes Schema and configuration into KCL. This section will introduce how to use KCL to integrate Kubernetes.
+
+## Quick Start
+
+### 1. Kubernetes OpenAPI Spec
 
 Starting from Kubernetes 1.4, the alpha support for the OpenAPI specification (known as Swagger 2.0 before it was donated to the OpenAPI Initiative) was introduced, and the API descriptions follow the [OpenAPI Spec 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md). And since Kubernetes 1.5, Kubernetes supports [directly extracting models from source code and then generating the OpenAPI spec file](https://github.com/kubernetes/kube-openapi) to automatically keep the specifications and documents up to date with the operation and models.
 
 In addition, Kubernetes CRD uses [OpenAPI V3.0 validation](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation) to describe a custom schema (in addition to the built-in attributes apiVersion, Kind, and metadata), that APIServer uses to validate the CR during the resource creation and update phases.
 
-## 2. KCL OpenAPI Support
+### 2. KCL OpenAPI Support
 
 The `kcl-openapi` tool supports extracting and generating KCL schemas from Kubernetes OpenAPI/CRD. the [KCL OpenAPI Spec](/docs/tools/cli/openapi/spec) defines the mapping between the OpenAPI specification and the KCL language features. For a quick start with the tool, see [KCL OpenAPI tool](/docs/tools/cli/openapi/)
 
-## 3. Migrate From Kubernetes To KCL
+### 3. Migrate From Kubernetes To KCL
 
-### 3.1 Write configurations based on the Kusion_Models package
+#### 3.1 Write configurations based on the Kusion_Models package
 ``
 We provide an out-of-the-box `kusion_models` package for you to quickly start. It contains a well-designed frontend model called [`Server schema`](https://github.com/KusionStack/konfig/blob/main/base/pkg/kusion_models/kube/frontend/server.k). You can declare the configurations by initializing the `Server schema`. For the description and usage of the schema and its attributes, please refer to the [Server schema documentation](https://kusionstack.io/docs/reference/model/kusion_models/kube/frontend/doc_server).
 ``
-### 3.2 Build Your Custom Frontend Models
+#### 3.2 Build Your Custom Frontend Models
 
 The existing KCL Models may not meet your specific business requirements, then you can also design your custom frontend model package. You can design your custom models based on the pre-generated Kubernetes KCL models among all versions. And you can also develop your custom scripts to migrate your configuration data as what `kube2kcl` tool does. 
 
-#### 3.2.1 Get the k8s package
+##### 3.2.1 Get the k8s package
 
 The [Kubernetes KCL models](https://github.com/orgs/KusionStack/packages/container/package/k8s) among all versions are pre-generated, you get it by executing `kpm add k8s:<version>` under your project. For detailed information about kpm usage, please refer to [kpm quick start guide](https://github.com/kcl-lang/kpm#quick-start).
 
 Alternatively, if you may want to generate them yourself, please refer to [Generate KCL Packages from Kubernetes OpenAPI Specs](https://github.com/kcl-lang/kcl-openapi/blob/main/docs/generate_from_k8s_spec.md).
 
-#### 3.2.2 Design Custom Frontend Models
+##### 3.2.2 Design Custom Frontend Models
 
 Since the Kubernetes built-in models are atomistic and kind of complex to beginners, we recommend taking the native model of Kubernetes as the backend output model and designing a batch of frontend models which could become a more abstract, friendlier and simpler interface to the user. You can refer to the design pattern in the [`Server Schema in the Konfig repo`](https://github.com/KusionStack/konfig/blob/main/base/pkg/kusion_models/kube/frontend/server.k).
 
-#### 3.2.3 Migrate The Configuration Data
+##### 3.2.3 Migrate The Configuration Data
 
 You can develop your custom scripts to migrate your configuration data automatically. KCL will later provide writing scaffolding and writing guidelines for this script.
 
-## 4. Migrate From Kubernetes CRD
+### 4. Migrate From Kubernetes CRD
 
 If you developed CRDs, you can generate the KCL version of the CRD schemas and declare CRs based on that.
 
@@ -47,3 +56,7 @@ If you developed CRDs, you can generate the KCL version of the CRD schemas and d
 * Define CR based on CRDs in KCL
 
     You can initialize the CRD schema to define a CR, or further, you can use the generated schema as a backend model and design a frontend interface for users to initialize. The practice is similar to what `KCL Models` does on Kubernetes built-in models.
+
+## Summary
+
+This section provides a quick start guide for using KCL with OpenAPI and Custom Resource Definitions (CRD). KCL also supports OpenAPI through the `kcl-openapi tool`, which maps OpenAPI specifications to KCL language features.

versioned_docs/version-0.5.0/user_docs/guides/working-with-k8s/generate_k8s_manifests.md → docs/user_docs/guides/working-with-k8s/2-generate-k8s-manifests.md

@@ -1,5 +1,5 @@
 ---
-title: "Generate and Manage Kubernetes Resource"
+title: "Generate Kubernetes Manifests"
 sidebar_position: 2
 ---
 

docs/user_docs/guides/working-with-k8s/3-mutate-manifests/1-kubectl-kcl-plugin.md

@@ -0,0 +1,100 @@
+---
+title: "Kubectl KCL Plugin"
+sidebar_position: 1
+---
+
+## Introduction
+
+[Kubectl](https://kubernetes.io/docs/reference/kubectl/) is a command line tool for communicating with a Kubernetes cluster's control plane, using the Kubernetes API. You can use the `Kubectl-KCL-Plugin` to
+
++ Edit the YAML configuration in a hook way to separate data and logic for the Kubernetes manifests management.
++ For multi-environment and multi-tenant scenarios, you can maintain these configurations gracefully rather than simply copy and paste.
++ Validate all KRM resources using the KCL schema.
+
+## Prerequisites
+
++ Install [Kubectl](https://github.com/kubernetes/kubectl)
++ Install [Kubectl KCL Plugin](https://github.com/kcl-lang/kubectl-kcl)
+
+## Quick Start
+
+Let’s write a KCL function which add annotation `managed-by=krm-kcl` only to `Deployment` resources in the helm chart.
+
+### 1. Get the Example
+
+```bash
+git clone https://github.com/kcl-lang/kubectl-kcl.git/
+cd ./kubectl-kcl/examples/
+```
+
+### 2. Test and Run
+
+Run the KCL code via the `Kubectl KCL Plugin`.
+
+```bash
+kubectl kcl run -f ./kcl-run.yaml
+```
+
+The output yaml is
+
+```yaml
+apiVersion: config.kubernetes.io/v1
+kind: ResourceList
+items:
+- apiVersion: apps/v1
+  kind: Deployment
+  metadata:
+    annotations:
+      managed-by: krm-kcl
+    labels:
+      app: nginx
+    name: nginx-deployment
+  spec:
+    replicas: 3
+    selector:
+      matchLabels:
+        app: nginx
+    template:
+      metadata:
+        labels:
+          app: nginx
+      spec:
+        containers:
+        - image: "nginx:1.14.2"
+          name: nginx
+          ports:
+          - containerPort: 80
+- apiVersion: v1
+  kind: Service
+  metadata:
+    name: test
+  spec:
+    ports:
+    - port: 80
+      protocol: TCP
+      targetPort: 9376
+    selector:
+      app: MyApp
+functionConfig:
+  # kcl-fn-config.yaml
+  apiVersion: krm.kcl.dev/v1alpha1
+  kind: KCLRun
+  metadata:
+  # EDIT THE SOURCE!
+  # This should be your KCL code which preloads the `ResourceList` to `option("resource_list")
+  spec:
+    source: |
+      [resource | {if resource.kind == "Deployment": metadata.annotations: {"managed-by" = "krm-kcl"}} for resource in option("resource_list").items]
+```
+
+## Guides for Developing KCL
+
+Here's what you can do in the KCL code:
+
++ Read resources from `option("resource_list")`. The `option("resource_list")` complies with the [KRM Functions Specification](https://kpt.dev/book/05-developing-functions/01-functions-specification). You can read the input resources from `option("resource_list")["items"]` and the `functionConfig` from `option("resource_list")["functionConfig"]`.
++ Return a KPM list for output resources.
++ Return an error using `assert {condition}, {error_message}`.
+
+## More Documents and Examples
+
++ [Kubectl KCL Plugin](https://github.com/kcl-lang/kubectl-kcl)

versioned_docs/version-0.5.0/user_docs/guides/working-with-k8s/helm_kcl_plugin.md → docs/user_docs/guides/working-with-k8s/3-mutate-manifests/2-helm-kcl-plugin.md

@@ -1,6 +1,6 @@
 ---
 title: "Helm KCL Plugin"
-sidebar_position: 4
+sidebar_position: 2
 ---
 
 ## Introduction

docs/user_docs/guides/working-with-k8s/kpt_kcl_sdk.md → docs/user_docs/guides/working-with-k8s/3-mutate-manifests/4-kpt-kcl-sdk.md

@@ -1,6 +1,6 @@
 ---
 title: "KPT KCL SDK"
-sidebar_position: 5
+sidebar_position: 4
 ---
 
 ## Introduction

docs/user_docs/guides/working-with-k8s/3-mutate-manifests/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Mutate or Validate Kubernetes Manifests",
+  "position": 3
+}

docs/user_docs/guides/_working-with-kusion/_category_.json → docs/user_docs/guides/working-with-kusion/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "KusionStack",
-  "position": 11
+  "position": 13
 }

i18n/en/docusaurus-plugin-content-docs/current.json

@@ -722,5 +722,13 @@
   "sidebar.user_docs.category.CI Integration": {
     "message": "CI Integration",
     "description": "The label for category CI Integration in sidebar user_docs"
+  },
+  "sidebar.docs.category.Mutate or Validate Kubernetes Manifests": {
+    "message": "Mutate or Validate Kubernetes Manifests",
+    "description": "The label for category Mutate or Validate Kubernetes Manifests in sidebar docs"
+  },
+  "sidebar.user_docs.category.Mutate or Validate Kubernetes Manifests": {
+    "message": "Mutate or Validate Kubernetes Manifests",
+    "description": "The label for category Mutate or Validate Kubernetes Manifests in sidebar user_docs"
   }
 }

i18n/en/docusaurus-plugin-content-docs/version-0.5.0.json

@@ -214,5 +214,13 @@
   "sidebar.user_docs.category.CI Integration": {
     "message": "CI Integration",
     "description": "The label for category CI Integration in sidebar user_docs"
+  },
+  "sidebar.docs.category.Mutate or Validate Kubernetes Manifests": {
+    "message": "Mutate or Validate Kubernetes Manifests",
+    "description": "The label for category Mutate or Validate Kubernetes Manifests in sidebar docs"
+  },
+  "sidebar.user_docs.category.Mutate or Validate Kubernetes Manifests": {
+    "message": "Mutate or Validate Kubernetes Manifests",
+    "description": "The label for category Mutate or Validate Kubernetes Manifests in sidebar user_docs"
   }
 }