docs: update readme

KusionStack · Mar 28, 2024 · 8422e34 · 8422e34
1 parent edcc408
commit 8422e34
Show file tree

Hide file tree

Showing 31 changed files with 43 additions and 395 deletions.
diff --git a/README.md b/README.md
@@ -1,33 +1,56 @@
 # Kusion Catalog
 
-Kusion is a modern application delivery and management toolchain that enables developers to specify desired intent in a declarative way and then using a consistent workflow to drive continuous deployment through application lifecycle.
+Kusion is an Intent-Driven Platform Orchestrator that enables developers to specify their desired intent in a declarative way and then using a consistent workflow to drive continuous delivery through the entire application lifecycle.
 
-One of the core goals of Kusion is to build an open, inclusive and vibrant OSS developer community focused on solving real-world application delivery and management problems, sharing the reusable building blocks and best practices.
+To achieve that, we've introduced the concept of [Kusion Modules](https://www.kusionstack.io/docs/kusion/concepts/kusion-module) for users to prescribe their intent in a structured way. Kusion Modules are modular building blocks that represent common and re-usable capabilities required during an application delivery.
 
-This repository contains a catalog of community maintained, shared `Kusion Module` resources, which are designed to be usable out of box.
+One of the core goals of Kusion is to build an open, inclusive and prosper open source community focused on solving real-world application delivery and management problems, in the meantime sharing the reusable building blocks and best practices.
+
+This repository contains the source code for all the official `Kusion Modules` maintained by the KusionStack team (all contributions welcome), representing our understanding of a "golden path" and is designed to be used out-of-the-box.
 
 ## Catalog Structure
 
-The `models/schema` directory contains all KCL schema definitions for application developers, and follows the following structure.
+The `modules` directory contains all the out-of-the-box Kusion Module definitions, with the following directory structure.
 
 ```
-    ./schema/v1                   
+├── modules
+│   ├── monitoring          👈 Module definition for Promethues
+│   │   ├── example         👈 Example for using the Promethues module
+│   │   ├── kcl.mod         👈 kcl.mod includes the KCL package metadata
+│   │   ├── prometheus.k    👈 Schema definition for Promethues configuration
+│   │   └── src             👈 Generator implementation for Promethues module in Go
+│   ├── mysql               👈 Module definition for Mysql database
+│   │   ├── ...
+│   ├── network             👈 Module definition for Network
+│   │   └── ...
+│   ├── opsrule             👈 Module definition for Operational Rule
+│   │   └── ...
+│   └── postgres            👈 Module definition for Postgres database
+│       └── ...
+```
 
-        /accessories            👈 schema definition for various accessory resources
+## Using the Catalog Modules
 
-        /monitoring             👈 schema definition for monitoring e.g. Promethues
-        
-        /trait                  👈 schema definition for various operation capabilities e.g. OpsRule
-        
-        /workload               👈 default workload schema definition
-        
-        app_configuration.k     👈 root AppConfiguration schema definition
-```
+The modules defined in the `catalog` repository are published to the [KusionStack GitHub container registry](https://github.com/orgs/KusionStack/packages).
 
-Based on the schema definitions, `models/samples` directory contains plenty of useful sample code. Here is a simple explanation of those samples.
+To reference and import the official Kusion Modules defined in this catalog repository, you can declare the dependencies in the corresponding `kcl.mod` file (Pick and choose the ones you need):
+
+```
+[package]
+name = "my-project"
+edition = "0.5.0"
+version = "0.1.0"
+
+[dependencies]
+kam = { git = "https://github.com/KusionStack/kam.git", tag = "0.1.0" }
+monitoring = { oci = "oci://ghcr.io/kusionstack/monitoring", tag = "0.1.0" }
+mysql = { oci = "oci://ghcr.io/kusionstack/mysql", tag = "0.1.0" }
+postgres = { oci = "oci://ghcr.io/kusionstack/postgres", tag = "0.1.0" }
+network = { oci = "oci://ghcr.io/kusionstack/network", tag = "0.1.0" }
+opsrule = { oci = "oci://ghcr.io/kusionstack/opsrule", tag = "0.1.0" }
+
+[profile]
+entries = ["../base/base.k", "main.k"]
+```
 
-* `hellocollaset` - demonstrates how to declare a long-running service, and the workload implementation of this service is `Collaset`, which is provided by [KusionStack Operating](https://github.com/KusionStack/operating).
-* `helloworld` - also declare a long-running service, with default Kubernetes Deployment workload.
-* `pgadmin` - declares a cloud provider managed Postgres resource, as well as a long-running service with `dpage/pgadmin4:latest` image.
-* `samplejob` - demonstrates how to declare a periodic job.
-* `wordpress` - declares a cloud provider managed MySQL resource, as well as a long-running service with `wordpress:6.3` image. 
+The `kam` repository referenced in the `kcl.mod` contains the definition for the `AppConfiguration` schema, which is a top layer concept for describing an application and may contains a collection of modules.
diff --git a/samples/hellocollaset/base/base.k b/samples/hellocollaset/base/base.k
diff --git a/samples/hellocollaset/prod/kcl.yaml b/samples/hellocollaset/prod/kcl.yaml
diff --git a/samples/hellocollaset/prod/main.k b/samples/hellocollaset/prod/main.k
diff --git a/samples/hellocollaset/prod/stack.yaml b/samples/hellocollaset/prod/stack.yaml
diff --git a/samples/hellocollaset/project.yaml b/samples/hellocollaset/project.yaml
diff --git a/samples/helloworld/base/base.k b/samples/helloworld/base/base.k
diff --git a/samples/helloworld/prod/kcl.yaml b/samples/helloworld/prod/kcl.yaml
diff --git a/samples/helloworld/prod/main.k b/samples/helloworld/prod/main.k
diff --git a/samples/helloworld/prod/stack.yaml b/samples/helloworld/prod/stack.yaml
diff --git a/samples/helloworld/project.yaml b/samples/helloworld/project.yaml
diff --git a/samples/pgadmin/base/base.k b/samples/pgadmin/base/base.k
diff --git a/samples/pgadmin/prod/kcl.yaml b/samples/pgadmin/prod/kcl.yaml
diff --git a/samples/pgadmin/prod/main.k b/samples/pgadmin/prod/main.k
diff --git a/samples/pgadmin/prod/stack.yaml b/samples/pgadmin/prod/stack.yaml
diff --git a/samples/pgadmin/project.yaml b/samples/pgadmin/project.yaml
diff --git a/samples/prometheus/base/base.k b/samples/prometheus/base/base.k
diff --git a/samples/prometheus/prod/kcl.yaml b/samples/prometheus/prod/kcl.yaml
diff --git a/samples/prometheus/prod/main.k b/samples/prometheus/prod/main.k
diff --git a/samples/prometheus/prod/stack.yaml b/samples/prometheus/prod/stack.yaml
diff --git a/samples/prometheus/project.yaml b/samples/prometheus/project.yaml
diff --git a/samples/samplejob/base/base.k b/samples/samplejob/base/base.k
diff --git a/samples/samplejob/prod/kcl.yaml b/samples/samplejob/prod/kcl.yaml
diff --git a/samples/samplejob/prod/main.k b/samples/samplejob/prod/main.k
diff --git a/samples/samplejob/prod/stack.yaml b/samples/samplejob/prod/stack.yaml