From 29f00bd4938a5b625569fb57898cfd541e8c8a46 Mon Sep 17 00:00:00 2001 From: Dayuan Date: Fri, 28 Jun 2024 11:59:53 +0800 Subject: [PATCH] docs: update readme.md (#80) ## What type of PR is this? ## What this PR does / why we need it: ## Which issue(s) this PR fixes: Fixes # ## Special notes for your reviewer: ### Does this PR introduce a user-facing change? ```release-note ``` ### Additional documentation e.g., design docs, usage docs, etc.: ```docs ``` --- README.md | 59 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 30 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 1f4b7aa..be9835d 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,17 @@ # Kusion Catalog -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. +Kusion is an Intent-Driven Platform Orchestrator that enables developers to specify their desired intent in a declarative way and then use a consistent workflow to drive continuous delivery through the entire application lifecycle. -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. +To achieve that, we've introduced the concept of [Kusion Modules](https://www.kusionstack.io/docs/concepts/kusion-module/overview) 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. -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. +One of the core goals of Kusion is to build an open, inclusive and prosperous 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 Kusion Modules that can be used publicly. If your module is open to the public, we **welcome and highly encourage** you to contribute it to this repository, so that more people can benefit from the module. Submit a pull request to this repository, once it is merged, it will be published to the [KusionStack GitHub container registry](https://github.com/orgs/KusionStack/packages). + +We also provide a module [developer guide](https://www.kusionstack.io/docs/concepts/kusion-module/develop-guide) on our website, if you have any questions, please don't hesitate to contact us directly. + +Some of the modules in this repository are maintained by the KusionStack team, representing our understanding of a "golden path" and are designed to be used out-of-the-box. All examples can be found in the [User Guide](https://www.kusionstack.io/docs/user-guides/working-with-k8s/deploy-application) on our website. -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 @@ -14,18 +19,18 @@ The `modules` directory contains all the out-of-the-box Kusion Module definition ``` ├── modules -│   ├── monitoring 👈 Module definition for Promethues +│   ├── monitoring 👈 Module 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 +│   │   └── src 👈 gRPC interfaces implementation for Promethues module in Go +│   ├── mysql 👈 Module for Mysql database │   │   ├── ... -│   ├── network 👈 Module definition for Network +│   ├── network 👈 Module for Network │   │   └── ... -│   ├── opsrule 👈 Module definition for Operational Rule +│   ├── opsrule 👈 Module for Operational Rule │   │   └── ... -│   └── postgres 👈 Module definition for Postgres database +│   └── postgres 👈 Module for Postgres database │   └── ... ``` @@ -33,24 +38,20 @@ The `modules` directory contains all the out-of-the-box Kusion Module definition The modules defined in the `catalog` repository are published to the [KusionStack GitHub container registry](https://github.com/orgs/KusionStack/packages). -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): +### Platform Engineers -``` -[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"] -``` +1. Please visit [module references](https://www.kusionstack.io/docs/reference/modules/) on the website or example/readme.md in each module directory to understand the capabilities and usage of each module. +2. Register this module in your workspace and set default values to standardize the module's behavior + +Please visit the [platform engineer development guide](https://www.kusionstack.io/docs/concepts/kusion-module/develop-guide) for more details. + +### App Developers + +As an application developer, the workflow of using a Kusion module looks like this: + +1. Browse available modules registered by platform engineers in the workspace +2. Add modules you need to your Stack +3. Initialize modules +4. Apply the AppConfiguration -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. \ No newline at end of file +Please visit the [application developer user guide](https://www.kusionstack.io/docs/concepts/kusion-module/app-dev-guide) for more details. \ No newline at end of file