docs: update concepts (#591)

* docs: update concepts

* docs: add runs and resource concepts

* docs: update broken links

Author: ffforest

docs/kusion/1-what-is-kusion/2-kusion-vs-x.md

@@ -10,7 +10,7 @@ It can be difficult to understand how different software compare to each other.
 
 According to the [open GitOps principles](https://opengitops.dev/), GitOps systems typically have its desired state expressed declaratively, continuously observe actual system state and attempt to apply the desired state. In the design of Kusion toolchain, we refer to those principles but have no intention to reinvent any GitOps systems wheel. 
 
-Kusion adopts your GitOps process and improves it with richness of features. The declarative [AppConfiguration](../concepts/app-configuration) model can be used to express desired intent, once intent is declared [Kusion CLI](../reference/commands) takes the role to make production match intent as safely as possible. 
+Kusion adopts your GitOps process and improves it with richness of features. The declarative [AppConfiguration](../concepts/appconfigurations) model can be used to express desired intent, once intent is declared [Kusion CLI](../reference/commands) takes the role to make production match intent as safely as possible. 
 
 **vs. PaaS (Heroku, Vercel, etc.)**
 
@@ -24,7 +24,7 @@ Kusion allows you to have platform-like features without the constraints of a tr
 
 KubeVela is a modern software delivery and management control plane which makes it easier to deploy and operate applications on top of Kubernetes.
 
-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.
+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/appconfigurations) schema to generate CRD resources for KubeVela and leverage KubeVela's control plane to implement application delivery.
 
 **vs. Helm**
 

docs/kusion/3-concepts/0-overview.md

@@ -4,17 +4,25 @@ id: overview
 
 # Overview
 
-In this article, we will provide an overview of the core concepts of Kusion from the perspective of the Kusion workflow. 
+## Platform Orchestrator
+
+![platform orchestrator](/img/docs/concept/platform-orchestrator.png)
+
+A Platform Orchestrator is a system designed to capture and "orchestrate" intents from different configurations coming from different roles, and connecting them with different infrastructures. It serves as the glue for different intents throughout the software development lifecycle, from deployment to monitoring and operations, ensuring that users' intentions can seamlessly integrate and flow across different environments and infrastructures.
+
+## Kusion Workflow
+
+In this section, we will provide an overview of the core concepts of Kusion from the perspective of the Kusion workflow. 
 
 ![kusion workflow](/img/docs/concept/kusion_workflow.png)
 
 The workflow of Kusion is illustrated in the diagram above, which consists of three steps. 
 
-The first step is **Write**, where the platform engineers build the [Kusion Modules](./3-module/1-overview.md) and initialize a [Workspace](./4-workspace.md). And the application developers declare their operational intent in [AppConfiguration](./5-appconfiguration.md) under a specific [Project](./1-project/1-overview.md) and [Stack](./2-stack/1-overview.md) path. 
+The first step is **Write**, where the platform engineers build the [Kusion Modules](./3-module/1-overview.md) and initialize a [Workspace](./4-workspace/1-overview.md). And the application developers declare their operational intent in [AppConfiguration](./5-appconfigurations.md) under a specific [Project](./1-project/1-overview.md) and [Stack](./2-stack/1-overview.md) path. 
 
-The second step is the **Build** process, which results in the creation of the **SSoT** (Single Source of Truth), also known as the [Spec](./6-spec.md) of the current operational task. If you need version management of the SSoT, we recommend you manage the `Spec` with a VCS (Version Control System) tool like **Git**. 
+The second step is the **Generate** process, which results in the creation of the **SSoT** (Single Source of Truth), also known as the [Spec](./6-specs.md) of the current operation. Kusion stores and version controls the Spec as part of a [Release](./8-release.md).
 
-The third step is **Apply**, which makes the `Spec` effective. Kusion parses the operational intent based on the `Spec` produced in the previous step. Before applying the `Spec`, Kusion will execute the `Preview` command (you can also execute this command manually) which will use a three-way diff algorithm to preview changes and prompt users to make sure all changes meet their expectations. And the `Apply` command will then actualize the operation intent onto various infrastructure platforms, currently supporting **Kubernetes**, **Terraform**, and **On-Prem** infrastructures. A [Release](./9-release.md) file will be created in the [Storage Backend](./7-backend.md) to record an operation. The `Destroy` command will delete the resources recorded in the `Release` file of a project in a specific workspace. 
+The third step is **Apply**, which makes the `Spec` effective. Kusion parses the operational intent based on the `Spec` produced in the previous step. Before applying the `Spec`, Kusion will execute the `Preview` command (you can also execute this command manually) which will use a three-way diff algorithm to preview changes and prompt users to make sure all changes meet their expectations. And the `Apply` command will then actualize the operation intent onto various infrastructure platforms, currently supporting **Kubernetes**, **Terraform**, and **On-Prem** infrastructures. A [Release](./8-release.md) file will be created in the [Storage Backend](./7-backend/1-overview.md) to record an operation. The `Destroy` command will delete the resources recorded in the `Release` file of a project in a specific workspace. 
 
 A more detailed demonstration of the Kusion engine can be seen below. 
 

docs/kusion/3-concepts/1-project/1-overview.md

@@ -5,8 +5,10 @@ id: overview
 
 # Overview
 
-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.
+Projects, [Stacks](../2-stack/1-overview.md), [Modules](../3-module/1-overview.md) and [Workspaces](../4-workspace/1-overview.md) are the most pivotal concepts when using Kusion.
 
-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.
+A project in Kusion is defined as a folder that contains a `project.yaml` file and is generally recommended to be stored to a Git repository. There are generally no constraints on where this folder may reside. In some cases it can be stored in a large monorepo that manages configurations for multiple applications. It could also be stored either in a separate repo or alongside the application code. A project can logically consist of one or more applications.
 
-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.
+The purpose of the project is to bundle application configurations that are relevant. Specifically, it contains configurations for internal components that makes up the application and orchestrates these configurations to suit different roles, such as developers and SREs, thereby covering the entire lifecycle of application deployment.
+
+From the perspective of the application development lifecycle, the configurations delineated by the project is decoupled from the application code. It takes an immutable application image as input, allowing users to perform operations and maintain the application within an independent configuration codebase.

docs/kusion/3-concepts/10-resources.md

@@ -0,0 +1,43 @@
+# Resources
+
+Kusion uses [Spec](./6-specs.md) to manage resource specifications. A Kusion resource is a logical concept that encapsulates physical resources on different resource planes, including but not limited to Kubernetes, AWS, AliCloud, Azure and Google Cloud.
+
+Kusion Resources are produced by [Kusion Module Generators](./3-module/1-overview.md) and usually map to a physical resource that can be applied via a Kusion Runtime.
+
+## Runtimes
+
+Runtimes is the consumer of the resources in a Spec by turning them into actual physical resources in infrastructure providers.
+
+Currently there are two in-tree runtimes defined in the Kusion source code but we are planning to make them out-of-tree in the future:
+
+- Kubernetes, used to manage resources inside a Kubernetes cluster. This can be any native Kubernetes resources or CRDs (if you wish to manage infrastructures via [CrossPlane](https://www.crossplane.io/) or [Kubevela](https://kubevela.io/), for example, this is completely doable by creating a Kusion Module with a generator that produces the resource YAML for the relevant CRDs)
+- Terraform, used to manage infrastructure resources outside a Kubernetes cluster. Kusion uses Terraform as an executor that can manage basically any infrastructure given there is a [terraform provider](https://developer.hashicorp.com/terraform/language/providers) tailored for the infrastructure API. This is generally used to manage the lifecycle of infrastructure resources on clouds, no matter public or on-prem.
+
+## Resource Planes
+
+Resource Plane is a property of a Kusion resource. It represents the actual plane on which the resource exists. Current resource planes include `kubernetes`,`aws`,`azure`,`google`,`alicloud`,`ant` and `custom`.
+
+## Resource ID, Resource URN and Cloud Resource ID
+
+Kusion Resource ID is a unique identifier for a Kusion Resource within a Spec. It must be unique across a Spec. The resource ID is technically generated by module generators so there are no definite rules for producing a Kusion Resource ID. The best practice is to use the `KubernetesResourceID()` and `TerraformResourceID()` method from [kusion-module-framework](https://github.com/KusionStack/kusion-module-framework) to manage Kusion Resource IDs. You can use the [official module generators](https://github.com/KusionStack/catalog/blob/main/modules/mysql/src/alicloud_rds.go#L164) as a reference.
+
+'''tip
+Resource ID validations do exist. 
+For Kubernetes resources, the resource ID must include API version, kind, namespace (if applicable) and name.
+For Terraform resources, the resource ID must include provider namespace, provider name, resource type and resource name.
+It's always recommended to use the `KubernetesResourceID()` and `TerraformResourceID()` method from [kusion-module-framework](https://github.com/KusionStack/kusion-module-framework) to produce the Resource IDs.
+'''
+
+Kusion Resource URN is used to uniquely identify a Kusion Resource across a Kusion server instance. It consists of `${project-name}:${stack-name}:${workspace-name}:${kusion-resource-id}` to ensure global uniqueness.
+
+Cloud Resource ID is used to map to an actual resource on the cloud. For AWS and Alicloud, this is usually known as the resource `ARN` on the cloud. For Azure and Google Cloud, this is known as the Resource ID. It can be empty in some cases, for example, a Kubernetes resource does not have cloud resource ID.
+
+## Resource Graphs
+
+A Resource Graph visualizes the relationship between all resources for a given stack. In the Kusion developer portal, you can inspect the resource graph by clicking on the `Resource Graph` tab on the stack page:
+
+![app-resource-graph](/img/docs/concept/app-resource-graph.png)
+
+You can closely inspect the resource details by hovering over the resource node on the graph.
+
+![app-resource-detail](/img/docs/concept/app-resource-graph-detail.png)

docs/kusion/3-concepts/8-configuration.md …usion/3-concepts/11-cli-configuration.mddocs/kusion/3-concepts/8-configuration.md renamed to docs/kusion/3-concepts/11-cli-configuration.md docs/kusion/3-concepts/8-configuration.md renamed to docs/kusion/3-concepts/11-cli-configuration.md

@@ -1,11 +1,15 @@
 ---
 id: configuration
-sidebar_label: Configuration
+sidebar_label: CLI Configurations
 ---
 
-# Configuration
+# CLI Configurations
 
-Kusion can be configured with some global settings, which are separate from the AppConfiguration written by the application developers and the workspace configurations written by the platform engineers. 
+:::tip
+If you are using Kusion server, this article does NOT apply.
+:::
+
+Kusion CLI can be configured with some global settings, which are separate from the AppConfiguration written by the application developers and the workspace configurations written by the platform engineers. 
 
 The configurations are only relevant to the Kusion itself, and can be managed by command `kusion config`. The configuration items are specified, which are in the hierarchical format with full stop for segmentation, such as `backends.current`. For now, only the backend configurations are included.
 

docs/kusion/3-concepts/2-stack/1-overview.md

@@ -9,7 +9,7 @@ A stack in Kusion is defined as a folder within the project directory that conta
 
 The most common way to leverage stacks is to denote different phases of the software development lifecycle, such as `development`, `staging`, `production`, etc. For instance, in the case where the image and resource requirements for an application workload might be different across different phases in the SDLC, they can be represented by different stacks in the same project, namely `dev`, `stage` and `prod`.
 
-To distinguish this from the deploy-time concept of a "target environment" - which Kusion defines as `workspaces`, **stack** is a development-time concept for application developers to manage different configurations. One way to illustrate the difference is that you can easily be deploying the `prod` stack to multiple target environments, for example, `aws-prod-us-east`, `aws-prod-us-east-2` and `azure-prod-westus`.
+To distinguish this from the deploy-time concept of a "target environment" - which Kusion defines as [workspaces](../4-workspace/1-overview.md), **stack** is a development-time concept for application developers to manage different configurations. One way to illustrate the difference is that you can easily be deploying the `prod` stack to multiple target environments, for example, `aws-prod-us-east`, `aws-prod-us-east-2` and `azure-prod-westus`.
 
 ## High Level Schema
 

docs/kusion/3-concepts/3-module/1-overview.md

@@ -1,14 +1,14 @@
 # Overview
 
-A Kusion module is a reusable building block designed by platform engineers to standardize application deployments and enable app developers to self-service. It consists of two parts:
+A Kusion module is a reusable building block designed by platform engineers to standardize application deployments and enable application developers to self-service. It consists of two parts:
 
-- App developer-oriented schema: It is a [KCL schema](https://kcl-lang.io/docs/user_docs/guides/schema-definition/). Fields in this schema are recommended to be understandable to application developers and workspace-agnostic. For example, a database Kusion module schema only contains fields like database engine type and database version.
-- Kusion module generator: It is a piece of logic that generates the Intent with an instantiated schema mentioned above, along with platform configurations ([workspace](../workspace)). As a building block, Kusion module hides the complexity of infrastructures. A database Kusion module not only represents a cloud RDS, but it also contains logic to configure other resources such as security groups and IAM policies. Additionally, it seamlessly injects the database host address, username, and password into the workload's environment variables. The generator logic can be very complex in some situations so we recommend implementing it in a GPL like [go](https://go.dev/).
+- App developer-friendly schema: It is a [KCL schema](https://kcl-lang.io/docs/user_docs/guides/schema-definition/). Fields in this schema are recommended to be understandable to application developers and workspace-agnostic. For example, a database Kusion module schema only contains fields like database engine type and database version.
+- Kusion module generator: It is a piece of logic that generates the [Spec](../6-specs.md) with an instantiated schema mentioned above, along with platform configurations managed in [workspaces](../4-workspace/1-overview.md). As the most fundamental building block, Kusion module provides the necessary abstraction to the developers by hiding the complexity of infrastructures. A database Kusion module not only represents a cloud RDS, but it also contains logic to configure other resources such as security groups and IAM policies. Additionally, it seamlessly injects the database host address, username, and password into the workload's environment variables. The generator logic can be very complex in some situations so we recommend implementing it in a GPL like [go](https://go.dev/).
 
 Here are some explanations of the Kusion Module:
 
 1. It represents an independent unit that provides a specific capability to the application with clear business semantics.
-2. It consists of one or multiple infrastructure resources (K8s/Terraform resources), but it is not merely a collection of unrelated resources. For instance, a database, monitoring capabilities, and network access are typical Kusion Modules.
+2. It may consist of one or multiple infrastructure resources (K8s/Terraform resources), but it is not merely a collection of unrelated resources. For instance, a database, monitoring capabilities, and network access are typical Kusion Modules.
 3. Modules should not have dependencies or be nested within each other.
 4. AppConfig is not a Module.
 5. Kusion Module is a superset of [KPM](https://www.kcl-lang.io/docs/user_docs/guides/package-management/quick-start). It leverages the KPM to manage KCL schemas in the Kusion module.