Skip to content

Commit

Permalink
docs: update readme.md (#80)
Browse files Browse the repository at this point in the history
<!-- Thank you for contributing to Catalog!

Note: 

1. With pull requests:

    - Open your pull request against "main"
- Your pull request should have no more than three commits, if not you
should squash them.
- It should pass all tests in the available continuous integration
systems such as GitHub Actions.
    - You should add/modify tests to cover your proposed code changes.
- If your pull request contains a new feature, please document it on the
README.

2. Please create an issue first to describe the problem.

We recommend that link the issue with the PR in the following question.
For more info, check https://kusionstack.io/docs/governance/contribute/
-->

## What type of PR is this?

<!--
Add one of the following kinds:
/kind bug
/kind cleanup
/kind documentation
/kind feature
/kind chore
-->

## What this PR does / why we need it:

## Which issue(s) this PR fixes:

<!--
*Automatically closes linked issue when PR is merged.
Usage: `Fixes #<issue number>`, or `Fixes (paste link of issue)`.
_If PR is about `failing-tests or flakes`, please post the related
issues/tests in a comment and do not use `Fixes`_*
-->

Fixes #

## Special notes for your reviewer:

### Does this PR introduce a user-facing change?

<!--
If no, just write "NONE" in the release-note block below.
If yes, a release note is required:
Enter your extended release note in the block below. If the PR requires
additional action from users switching to the new release, include the
string "action required".

-->

```release-note

```

### Additional documentation e.g., design docs, usage docs, etc.:

<!--
Please use the following format for linking documentation:
- [Design]: <link>
- [Usage]: <link>
- [Other doc]: <link>
-->

```docs

```
  • Loading branch information
SparkYuan authored Jun 28, 2024
1 parent c4aa5b4 commit 29f00bd
Showing 1 changed file with 30 additions and 29 deletions.
59 changes: 30 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,56 +1,57 @@
# 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

The `modules` directory contains all the out-of-the-box Kusion Module definitions, with the following directory structure.

```
├── 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
│   └── ...
```

## Using the Catalog Modules

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.
Please visit the [application developer user guide](https://www.kusionstack.io/docs/concepts/kusion-module/app-dev-guide) for more details.

0 comments on commit 29f00bd

Please sign in to comment.