Merge pull request #500 from legal90/fix-konfig-guide

Peefy · web-flow · commit 1a8161b3f15a · 2025-01-20T23:54:01.000+08:00
Fix typos and outdated info in Konfig guide
diff --git a/docs/user_docs/guides/working-with-konfig/2-structure.md b/docs/user_docs/guides/working-with-konfig/2-structure.md
@@ -14,24 +14,31 @@ The core model library is generally named `models`, mainly including front-end m
 ```bash
 models
 ├── commons         # Common models
-├── kube            # Cloud-native resource core models
-│   ├── backend         # Back-end models
-│   ├── frontend        # Front-end models
-│   │   ├── common          # Common front-end models
-│   │   ├── configmap       # ConfigMap
-│   │   ├── container       # Container
-│   │   ├── ingress         # Ingress
-│   │   ├── resource        # Resource
-│   │   ├── secret          # Secret
-│   │   ├── service         # Service
-│   │   ├── sidecar         # Sidecar
-│   │   ├── strategy        # strategy
-│   │   ├── volume          # Volume
-│   │   └── server.k        # The `Server` model
-│   ├── metadata        # Kubernetes metadata
-│   ├── mixins          # Mixin
-│   ├── render          # Front-to-back-end renderers.
-│   ├── templates       # Data template
-│   └── utils
-└── metadata        # Common metadata
+└── kube            # Cloud-native resource core models
+    ├── backend         # Back-end models
+    ├── frontend        # Front-end models
+    │   ├── affinity        # Affinity
+    │   ├── deployment      # Deplyment
+    │   ├── common          # Common front-end models
+    │   ├── configmap       # ConfigMap
+    │   ├── container       # Container
+    │   ├── ingress         # Ingress
+    │   ├── rbac            # Role, RoleBinding, ClusterRole, ClusterRoleBinding
+    │   ├── resource        # Resource
+    │   ├── secret          # Secret
+    │   ├── service         # Service
+    │   ├── serviceaccount  # ServiceAccount
+    │   ├── sidecar         # Sidecar
+    │   ├── storage         # DataBase, ObjectStorage
+    │   ├── strategy        # SchedulingStrategy
+    │   ├── volume          # Volume
+    │   ├── job.k           # The `Job` model
+    │   └── server.k        # The `Server` model
+    ├── metadata        # Kubernetes metadata
+    ├── mixins          # Mixin
+    ├── protocol        # ServerProtocol
+    ├── render          # Front-to-back-end renderers.
+    ├── resource        # ResourceMapping
+    ├── templates       # Data template
+    └── utils           # Helper utils
 ```
diff --git a/docs/user_docs/guides/working-with-konfig/3-quick-start.md b/docs/user_docs/guides/working-with-konfig/3-quick-start.md
@@ -41,7 +41,7 @@ The programming language of the project is KCL, not JSON/YAML which Kubernetes r
 Enter stack dir `examples/appops/nginx-example/dev` and compile:
 
 ```bash
-cd examples/appops/nginx-example/dev && kcl run -D env=dev
+cd examples/appops/nginx-example/dev && kcl run -D appenv=dev
 ```
 
 The output YAML is:
@@ -50,71 +50,71 @@ The output YAML is:
 apiVersion: apps/v1
 kind: Deployment
 metadata:
-  name: sampleappdev
-  namespace: sampleapp
+  name: sampleapp-dev
+  namespace: sampleappns-dev
 spec:
   replicas: 1
   selector:
     matchLabels:
       app.kubernetes.io/name: sampleapp
       app.kubernetes.io/env: dev
       app.kubernetes.io/instance: sampleapp-dev
-      app.k8s.io/component: sampleappdev
+      app.k8s.io/component: sampleapp-dev
   template:
     metadata:
       labels:
         app.kubernetes.io/name: sampleapp
         app.kubernetes.io/env: dev
         app.kubernetes.io/instance: sampleapp-dev
-        app.k8s.io/component: sampleappdev
+        app.k8s.io/component: sampleapp-dev
     spec:
       containers:
-        - env:
-            - name: MY_ENV
-              value: MY_VALUE
-          image: nginx:1.7.8
-          name: main
-          ports:
-            - containerPort: 80
-              protocol: TCP
-          resources:
-            limits:
-              cpu: "100m"
-              memory: "100Mi"
-              ephemeral-storage: "1Gi"
-            requests:
-              cpu: "100m"
-              memory: "100Mi"
-              ephemeral-storage: "1Gi"
-          volumeMounts: []
+      - env:
+        - name: MY_ENV
+          value: MY_VALUE
+        image: nginx:1.7.8
+        name: main
+        ports:
+        - containerPort: 80
+          protocol: TCP
+        resources:
+          limits:
+            cpu: '100m'
+            memory: '100Mi'
+            ephemeral-storage: '1Gi'
+          requests:
+            cpu: '100m'
+            memory: '100Mi'
+            ephemeral-storage: '1Gi'
+        volumeMounts: []
 ---
 apiVersion: v1
 kind: Namespace
 metadata:
-  name: sampleapp
+  name: sampleappns-dev
 ---
 apiVersion: v1
 kind: Service
 metadata:
   name: nginx
-  namespace: sampleapp
+  namespace: sampleappns-dev
 spec:
   ports:
-    - nodePort: 30201
-      port: 80
-      targetPort: 80
+  - nodePort: 30201
+    port: 80
+    targetPort: 80
   selector:
     app.kubernetes.io/name: sampleapp
     app.kubernetes.io/env: dev
     app.kubernetes.io/instance: sampleapp-dev
-    app.k8s.io/component: sampleappdev
+    app.k8s.io/component: sampleapp-dev
   type: NodePort
 ```
 
 After compiling, we can see three resources:
 
-- A `Deployment` with the name `sampleappprod`
-- A `Namespace` with the name `sampleapp`
+- A `Deployment` with the name `sampleapp-dev`
+- A `Namespace` with the name `sampleappns-dev`
 - A `Service` with the name `nginx`
 
 ### 2. Modification
@@ -131,71 +131,72 @@ The `image` attribute in the `Server` model is used to declare the application's
 Recompile the configuration code to obtain the modified YAML output:
 
 ```shell
-kcl run
+kcl run -D appenv=dev
 ```
 
 ```yaml
 apiVersion: apps/v1
 kind: Deployment
 metadata:
-  name: sampleappdev
-  namespace: sampleapp
+  name: sampleapp-dev
+  namespace: sampleappns-dev
 spec:
   replicas: 1
   selector:
     matchLabels:
       app.kubernetes.io/name: sampleapp
       app.kubernetes.io/env: dev
       app.kubernetes.io/instance: sampleapp-dev
-      app.k8s.io/component: sampleappdev
+      app.k8s.io/component: sampleapp-dev
   template:
     metadata:
       labels:
         app.kubernetes.io/name: sampleapp
         app.kubernetes.io/env: dev
         app.kubernetes.io/instance: sampleapp-dev
-        app.k8s.io/component: sampleappdev
+        app.k8s.io/component: sampleapp-dev
     spec:
       containers:
-        - env:
-            - name: MY_ENV
-              value: MY_VALUE
-          image: nginx:latest
-          name: main
-          ports:
-            - containerPort: 80
-              protocol: TCP
-          resources:
-            limits:
-              cpu: "100m"
-              memory: "100Mi"
-              ephemeral-storage: "1Gi"
-            requests:
-              cpu: "100m"
-              memory: "100Mi"
-              ephemeral-storage: "1Gi"
-          volumeMounts: []
+      - env:
+        - name: MY_ENV
+          value: MY_VALUE
+        image: nginx:1.7.8
+        name: main
+        ports:
+        - containerPort: 80
+          protocol: TCP
+        resources:
+          limits:
+            cpu: '100m'
+            memory: '100Mi'
+            ephemeral-storage: '1Gi'
+          requests:
+            cpu: '100m'
+            memory: '100Mi'
+            ephemeral-storage: '1Gi'
+        volumeMounts: []
 ---
 apiVersion: v1
 kind: Namespace
 metadata:
-  name: sampleapp
+  name: sampleappns-dev
 ---
 apiVersion: v1
 kind: Service
 metadata:
   name: nginx
-  namespace: sampleapp
+  namespace: sampleappns-dev
 spec:
   ports:
-    - nodePort: 30201
-      port: 80
-      targetPort: 80
+  - nodePort: 30201
+    port: 80
+    targetPort: 80
   selector:
     app.kubernetes.io/name: sampleapp
     app.kubernetes.io/env: dev
     app.kubernetes.io/instance: sampleapp-dev
-    app.k8s.io/component: sampleappdev
+    app.k8s.io/component: sampleapp-dev
+  type: NodePort
 ```
 
 ## Resources
diff --git a/docs/user_docs/guides/working-with-konfig/4-best-practice.md b/docs/user_docs/guides/working-with-konfig/4-best-practice.md
@@ -87,7 +87,7 @@ schema SLI:
 
 The type of template is a combination of two string types, indicating that the template can only be `"success_ratio"` or `"service_cost"`. When the user fills in the values of other strings, the KCL compiler will report an error.
 
-In addition to using union types for literal types, KCL also supports union for complex types such as schema types. For the support of this backend **oneof** configuration, KCL has built-in composite structure union types for support. For example, we can define our own SLI front-end types for various scenarios: `CustomSliDataSource`, `PQLSLIDataSource`, and `StackSLIDataSource`.
+In addition to using union types for literal types, KCL also supports union for complex types such as schema types. For the support of this backend **oneof** configuration, KCL has built-in composite structure union types for support. For example, we can define our own SLI front-end types for various scenarios: `CustomSLIDataSource`, `PQLSLIDataSource`, and `StackSLIDataSource`.
 
 ```python
 schema CustomSLIDataSource:
@@ -175,7 +175,7 @@ house = House {
 }
 ```
 
-For example, in the above example, if you want to query the age of the person named `"Alice"` from the list of persons in the house, you need to loop through the list to find Alice's age. However, if you define persons as a dictionary like the following code, it not only looks more concise in code, but you can also directly retrieve Alice's age by using house.persons.Alice.age. In addition, the information of the entire configuration is complete and has no redundant information.
+For example, in the above example, if you want to query the age of the person named `"Alice"` from the list of persons in the house, you need to loop through the list to find Alice's age. However, if you define persons as a dictionary like the following code, it not only looks more concise in code, but you can also directly retrieve Alice's age by using `house.persons.Alice.age`. In addition, the information of the entire configuration is complete and has no redundant information.
 
 ```python
 schema Person:
@@ -346,11 +346,10 @@ The output is
 
 ```yaml
 cpuMap:
-  "1": 256
-  "2": 512
-  "3": 1024
-cpu256: 256
-cpu2048: 2048
+  '1': 256
+  '2': 512
+  '3': 1024
+cpu: 256
 ```
 
 ### Separate Logic and Data
