feat: update kusion docs of v0.11.1 (#475)

* feat: update quickstart and guide for cloud rds (#465) * docs: update concepts doc for project, stack, workspace (#468) * feat: update kusion quickstart doc and database user guide (#470) * docs: update project&stack file reference (#471) * docs: update cmd reference (#472) * docs: update kusion vs other software (#474) --------- Co-authored-by: Forest <forest10161016@gmail.com> Co-authored-by: TonyAdo <71679464+adohe@users.noreply.github.com>
KusionStack · Apr 30, 2024 · 0886e82 · 0886e82
1 parent 185537c
commit 0886e82
Show file tree

Hide file tree

Showing 77 changed files with 777 additions and 692 deletions.
diff --git a/docs/kusion/1-what-is-kusion/2-kusion-vs-x.md b/docs/kusion/1-what-is-kusion/2-kusion-vs-x.md
@@ -22,11 +22,9 @@ Kusion allows you to have platform-like features without the constraints of a tr
 
 **vs. KubeVela**
 
-KubeVela is a modern software delivery and management control plane. KubeVela makes it easier to deploy and operate applications on top of Kubernetes.
+KubeVela is a modern software delivery and management control plane which makes it easier to deploy and operate applications on top of Kubernetes.
 
-Kusion is not a control plane. Kusion is a client-side tool for describing application intent in  a declarative way and providing consistent workflow to apply that desired state.
-
-With proper Generator implementation, the target Spec of [AppConfiguration](../concepts/app-configuration) can be [KubeVela Application](https://kubevela.io/docs/getting-started/core-concept/) and Kusion can use KubeVela to satisfy the "apply" step.
+Although some might initially perceive an overlap between Kusion and KubeVela, they are in fact complementary and can be integrated to work together. As a lightweight, purely client-side tool, coupled with corresponding [Generator](https://github.com/KusionStack/kusion-module-framework) implementation, Kusion can render [AppConfiguration](../concepts/app-configuration) schema to generate CRD resources for KubeVela and leverage KubeVela's control plane to implement application delivery.
 
 **vs. Helm**
 

diff --git a/docs/kusion/2-getting-started/2-deliver-quickstart.md b/docs/kusion/2-getting-started/2-deliver-quickstart.md
@@ -10,8 +10,8 @@ In this tutorial, we will walk through how to deploy a quickstart application on
 
 Before we start to play with this example, we need to have the Kusion CLI installed and run an accessible Kubernetes cluster. Here are some helpful documents: 
 
-- Install [Kusion CLI](./1-install-kusion.md)
-- Install [kubectl CLI](https://kubernetes.io/docs/tasks/tools/#kubectl) and run a [Kubernetes](https://kubernetes.io) cluster. Some light and convenient options for Kubernetes local deployment include [k3s](https://docs.k3s.io/quick-start), [k3d](https://k3d.io/v5.4.4/#installation), and [MiniKube](https://minikube.sigs.k8s.io/docs/tutorials/multi_node)
+- Install [Kusion CLI](./1-install-kusion.md). 
+- Run a [Kubernetes](https://kubernetes.io) cluster. Some light and convenient options for Kubernetes local deployment include [k3s](https://docs.k3s.io/quick-start), [k3d](https://k3d.io/v5.4.4/#installation), and [MiniKube](https://minikube.sigs.k8s.io/docs/tutorials/multi_node). 
 
 ## Initialize Project
 
@@ -30,7 +30,7 @@ The created project structure looks like below:
 ```shell
 tree
 .
-├── dev
+├── default
 │   ├── kcl.mod
 │   ├── main.k
 │   └── stack.yaml
@@ -45,10 +45,10 @@ More details about the project and stack structure can be found in [Project](../
 
 ### Review Configuration Files
 
-Now let's have a glance at the configuration codes of `dev` stack: 
+Now let's have a glance at the configuration codes of `default` stack: 
 
 ```shell
-cat dev/main.k
+cat default/main.k
 ```
 
 ```python
@@ -57,7 +57,7 @@ import kam.v1.workload as wl
 import kam.v1.workload.container as c
 import network as n
 
-# main.k declares the customized configuration codes for dev stack.
+# main.k declares the customized configuration codes for default stack.
 quickstart: ac.AppConfiguration {
     workload: wl.Service {
         containers: {
@@ -78,33 +78,26 @@ quickstart: ac.AppConfiguration {
 }
 ```
 
-The configuration file `main.k`, usually written by the **App Developers**, declares the customized configuration codes for `dev` stack, including an `AppConfiguration` instance with the name of `quickstart`. The `quickstart` application consists of a `Workload` with the type of `kam.v1.workload.Service`, which runs a container named `quickstart` using the image of `kusionstack/kusion-quickstart:latest`. 
+The configuration file `main.k`, usually written by the **App Developers**, declares the customized configuration codes for `default` stack, including an `AppConfiguration` instance with the name of `quickstart`. The `quickstart` application consists of a `Workload` with the type of `kam.v1.workload.Service`, which runs a container named `quickstart` using the image of `kusionstack/kusion-quickstart:latest`. 
 
 Besides, it declares a **Kusion Module** with the type of `network.Network`, exposing `8080` port to be accessed for the long-running service. 
 
 The `AppConfiguration` model can hide the major complexity of Kubernetes resources such as `Namespace`, `Deployment`, and `Service` which will be created and managed by Kusion, providing the concepts that are **application-centric** and **infrastructure-agnostic** for a more developer-friendly experience. 
 
 :::info
-More details about the `AppConfiguration` model and internal Kusion Module can be found in [kam](https://github.com/KusionStack/kam) and [catalog](https://github.com/KusionStack/catalog). 
+More details about the `AppConfiguration` model and built-in Kusion Module can be found in [kam](https://github.com/KusionStack/kam) and [catalog](https://github.com/KusionStack/catalog). 
 :::
 
-The declaration of the dependency packages can be found in `dev/kcl.mod`: 
+The declaration of the dependency packages can be found in `default/kcl.mod`: 
 
 ```shell
-cat dev/kcl.mod
+cat default/kcl.mod
 ```
 
 ```shell
-[package]
-name = "kusion-quickstart"
-version = "0.1.0"
-
 [dependencies]
 kam = { git = "https://github.com/KusionStack/kam.git", tag = "0.1.0" }
 network = { oci = "oci://ghcr.io/kusionstack/network", tag = "0.1.0" }
-
-[profile]
-entries = ["main.k"]
 ```
 
 :::info
@@ -113,120 +106,40 @@ More details about the application model and module dependency declaration can b
 
 ## Application Delivery
 
-Use the following command to deliver the quickstart application in `dev` stack on your accessible Kubernetes cluster while watching the resource creation. 
+Use the following command to deliver the quickstart application in `default` stack on your accessible Kubernetes cluster, while watching the resource creation and automatically port-forwarding the specified port (8080) from local to the Kubernetes Service of the application. We can check the details of the resource preview results before we confirm to apply the diffs. 
 
 ```shell
-cd dev && kusion apply --watch
+cd default && kusion apply --watch --port-forward 8080
 ```
 
 ![](/img/docs/user_docs/getting-started/kusion_apply_quickstart.gif)
 
 :::info
-During the first apply, the models and modules that the application depends on will be downloaded, so it may take some time (usually within two minutes). You can take a break and have a cup of coffee. 
+During the first apply, the models and modules that the application depends on will be downloaded, so it may take some time (usually within one minute). You can take a break and have a cup of coffee. 
 :::
 
-Check the created `Deployment` status: 
-
-```shell
-kubectl -n quickstart get deployment
-```
-
-The expected output is shown as follows: 
-
-```shell
-➜  dev kubectl -n quickstart get deployment
-NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
-quickstart-dev-quickstart   1/1     1            1           1m1s
-```
-
 :::info
-Kusion by default will create the Kubernetes resources of the application in the namespace the same as the project name. 
+Kusion by default will create the Kubernetes resources of the application in the namespace the same as the project name. If you want to customize the namespace, please refer to **[T.B.D]**. 
 :::
 
-Check the created `Service` status: 
-
-```shell
-kubectl -n quickstart get service
-```
-
-The expected output is shown as follows: 
-
-```shell
-➜  dev kubectl -n quickstart get service
-NAME                                TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
-quickstart-dev-quickstart-private   ClusterIP   10.43.129.16   <none>        8080/TCP   1m1s
-```
-
-Port-forward our application with the created `Service`: 
-
-```shell
-kubectl port-forward -n quickstart service/quickstart-dev-quickstart-private 12345:8080
-```
-
-Now we can visit [http://localhost:12345](http://localhost:12345) in our browser and play with the demo application! 
+Now we can visit [http://localhost:8080](http://localhost:8080) in our browser and play with the demo application! 
 
 ![](/img/docs/user_docs/getting-started/quickstart_page.png)
 
 ## Add MySQL Accessory
 
 As you can see, the demo application page indicates that the MySQL database is not ready yet. Hence, we will now add a MySQL database as an accessory for the workload. 
 
-### Update Default Workspace
-
-Besides the configuration codes we have seen above, **Workspace** configurations, usually written by **Platform Engineers** are also part of the complete application configuration. Kusion provides cmd for workspace create, update, delete, and switch, and it defaults to using the auto-generated `default` workspace for the targeted stack. 
-
-For now, we can only see an empty `default` workspace: 
+We can add the Kusion-provided built-in dependency in the `default/kcl.mod`, so that we can use the `MySQL` module in the configuration codes. 
 
 ```shell
-➜  dev kusion workspace list
-- default
-```
-
-```shell
-➜  dev kusion workspace show
-show configuration of workspace default:
-{}
-```
-
-To declare a MySQL database with a specified name, we need to first update the `default` workspace for the `dev` stack. Please copy the following example YAML file to your local `workspace.yaml`. 
-
-`workspace.yaml`
-```yaml
-modules: 
-  kusionstack/mysql@0.1.0: 
-    default: 
-      databaseName: test-database
-```
-
-Then update the default workspace with cmd below: 
-
-```shell
-kusion workspace update default -f workspace.yaml
-```
-
-:::info
-More details about the configuration of Workspace can be found in [Concepts of Workspace](../3-concepts/4-workspace.md)
-:::
-
-### Update Configuration Codes And Re-Apply
-
-We can add the Kusion-provided built-in dependency in the `dev/kcl.mod`, so that we can use the `MySQL` module in the configuration codes. 
-
-```shell
-[package]
-name = "kusion-quickstart"
-version = "0.1.0"
-
 [dependencies]
 kam = { git = "https://github.com/KusionStack/kam.git", tag = "0.1.0" }
 network = { oci = "oci://ghcr.io/kusionstack/network", tag = "0.1.0" }
 mysql = { oci = "oci://ghcr.io/kusionstack/mysql", tag = "0.1.0" }
-
-[profile]
-entries = ["main.k"]
 ```
 
-We can update the `dev/main.k` with the following configuration codes: 
+We can update the `default/main.k` with the following configuration codes: 
 
 ```python
 # The configuration codes in the perspective of developers. 
@@ -242,9 +155,9 @@ quickstart: ac.AppConfiguration {
             quickstart: c.Container {
                 image: "kusionstack/kusion-quickstart:latest"
                 env: {
-                    "DB_HOST": "$(KUSION_DB_HOST_TEST_DATABASE)"
-                    "DB_USERNAME": "$(KUSION_DB_USERNAME_TEST_DATABASE)"
-                    "DB_PASSWORD": "$(KUSION_DB_PASSWORD_TEST_DATABASE)"
+                    "DB_HOST": "$(KUSION_DB_HOST_QUICKSTART_DEFAULT_QUICKSTART_MYSQL)"
+                    "DB_USERNAME": "$(KUSION_DB_USERNAME_QUICKSTART_DEFAULT_QUICKSTART_MYSQL)"
+                    "DB_PASSWORD": "$(KUSION_DB_PASSWORD_QUICKSTART_DEFAULT_QUICKSTART_MYSQL)"
                 }
             }
         }
@@ -268,13 +181,13 @@ quickstart: ac.AppConfiguration {
 The configuration codes above declare a local `mysql.MySQL` with the engine version of `8.0` as an accessory for the application workload. The necessary Kubernetes resources for deploying and using the local MySQL database will be generated and users can get the `host`, `username` and `password` of the database through the [MySQL Credentials And Connectivity](../6-reference/2-modules/1-developer-schemas/database/mysql.md#credentials-and-connectivity) of Kusion in application containers. 
 
 :::info
-The collaboration paradigm between App Developers and Platform Engineers with Kusion can be found in [Collaboration Paradigm](https://github.com/KusionStack/kusion/blob/main/docs/design/collaboration/collaboration_paradigm.md). 
+For more information about the naming convention of Kusion built-in MySQL module, you can refer to [Module Naming Convention](../6-reference/2-modules/3-naming-conventions.md). 
 :::
 
 After that, we can re-apply the application: 
 
 ```shell
-kusion apply --watch
+kusion apply --watch --port-forward 8080
 ```
 
 ![](/img/docs/user_docs/getting-started/kusion_re_apply_quickstart.gif)
@@ -283,34 +196,7 @@ kusion apply --watch
 You may wait another minute to download the MySQL Module. 
 :::
 
-Re-check the `Deployment` and `Service` status: 
-
-```shell
-kubectl -n quickstart get deployment,service
-```
-
-The expected output is shown below: 
-
-```shell
-➜  dev kubectl -n quickstart get deployment,service
-NAME                                                READY   UP-TO-DATE   AVAILABLE   AGE
-deployment.apps/quickstart-dev-quickstart           1/1     1            1           1h1m
-deployment.apps/test-database-db-local-deployment   1/1     1            1           1m1s
-
-NAME                                        TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
-service/quickstart-dev-quickstart-private   ClusterIP   10.43.129.16   <none>        8080/TCP   1h1m
-service/test-database-db-local-service      ClusterIP   None           <none>        3306/TCP   1m1s
-```
-
-In the above Kubernetes resources, `deployment.apps/quickstart-dev-quickstart` and `service/quickstart-dev-quickstart-private` corresponds to the `Deployment` and `Resources` of the quickstart demo application, while `deployment.apps/test-database-db-local-deployment` and `service/test-database-db-local-service` corresponds to the local MySQL database. 
-
-We can port-forward the quickstart demo application again: 
-
-```shell
-kubectl port-forward -n quickstart service/quickstart-dev-quickstart-private 12345:8080
-```
-
-Let's visit [http://localhost:12345](http://localhost:12345) in our browser, and we can find that the application has successfully connected to the MySQL database. The connection information is also printed on the page. 
+Let's visit [http://localhost:8080](http://localhost:8080) in our browser, and we can find that the application has successfully connected to the MySQL database. The connection information is also printed on the page. 
 
 ![](/img/docs/user_docs/getting-started/quickstart_page_with_mysql.png)
 

diff --git a/docs/kusion/3-concepts/1-project/1-overview.md b/docs/kusion/3-concepts/1-project/1-overview.md
@@ -5,8 +5,8 @@ id: overview
 
 # Overview
 
-A project in Kusion is defined as any folder that contains a project.yaml file and is linked to a Git repository. Typically, the mapping between a project and a repository is 1:1, however, it is possible to have multiple projects connected to a single repository—for example, in the case of a monorepo. A project consists of one or more applications.
+A project in Kusion is defined as a folder that contains a `project.yaml` file and is generally recommended to be linked to a Git repository. Typically, the mapping between a project and a repository is 1:1, however, it is possible to have multiple projects connected to a single repository — for example, in the case of a monorepo. A project consists of one or more applications.
 
-The purpose of the project is to bundle application configurations and refer to a Git repository. Specifically, it organizes logical configurations for internal components to orchestrate the application and assembles these configurations to suit different roles, such as developers and SREs, thereby covering the entire life cycle of application development.
+The purpose of the project is to bundle application configurations there are relevant. Specifically, it organizes logical configurations for internal components to orchestrate the application and assembles these configurations to suit different roles, such as developers and SREs, thereby covering the entire lifecycle of application development.
 
-From the perspective of the application development life cycle, the configuration delineated by the project is decoupled from the application code. It takes an immutable image as input, allowing users to perform operations and maintain the application within an independent configuration codebase.
+From the perspective of the application development lifecycle, the configurations delineated by the project is decoupled from the application code. It takes an immutable image as input, allowing users to perform operations and maintain the application within an independent configuration codebase.
diff --git a/docs/kusion/3-concepts/1-project/2-configuration.md b/docs/kusion/3-concepts/1-project/2-configuration.md
@@ -1,29 +1,29 @@
 ---
 id: configuration
-sidebar_label: Project Configuration
+sidebar_label: Project file reference
 ---
 
-# Project Configuration
+# Kusion project file reference
 
-Users can add config items of the project in `project.yaml`, such as the project name, generator type, Prometheus monitoring, etc.
+Every Kusion project has a project file, `project.yaml`, which specifies metadata about your project, such as the project name and project description. The project file must begin with lowercase `project` and have an extension of either `.yaml` or `.yml`.
 
-Here is an example of `project.yaml`.
+## Attributes
 
-```yaml
-# The project basic info
-name: helloworld
-generator:
-  type: AppConfiguration
-prometheus:
-  operatorMode: True
-  monitorType: Service
-```
+| Name          | Required        | Description   | Options       |
+|:------------- |:--------------- |:------------- |:------------- |
+| `name`        | required        | Name of the project containing alphanumeric characters, hyphens, underscores. | None         |
+| `description` | optional        | A brief description of the project.  | None           |
+| `extensions`  | optional        | List of extensions on the project. | [See blow](#extensions)          |
 
-The config items in `project.yaml` are explained below.
+### Extensions
 
-- **name**: The name of the project
-- **generator**:
-    - `type`: The type of the module generator, supports `AppConfiguration` and `KCL`, default is `AppConfiguration`. If using the schema AppConfiguration, set type as AppConfiguration
-- **prometheus**:
-    - **operatorMode**: Decides whether Kusion runs Prometheus in `Operator` mode. Kusion will generate a `Custom Resource` if it is true, while generate some annotations if it is false
-    - **monitorType**: The type of the monitored resource, which can be one of `Service` or `Pod`
+Extensions allow you to customize how resources are generated or customized as part of release.
+
+#### kubernetesNamespace
+
+The Kubernetes namespace extension allows you to customize namespace within your application generate Kubernetes resources. 
+
+| Key  | Required | Description | Example |
+|:------|:--------:|:-------------|:---------|
+| kind | y | The kind of extension being used. Must be 'kubernetesNamespace' | `kubernetesNamespace` |
+| namespace | y | The namespace where all application-scoped resources generate Kubernetes objects. | `default` |