diff --git a/docs/kusion/2-getting-started/2-deliver-quickstart.md b/docs/kusion/2-getting-started/2-deliver-quickstart.md index 0ddbeb85..7b89b4fa 100644 --- a/docs/kusion/2-getting-started/2-deliver-quickstart.md +++ b/docs/kusion/2-getting-started/2-deliver-quickstart.md @@ -102,7 +102,7 @@ network = { oci = "oci://ghcr.io/kusionstack/network", tag = "0.2.0" } ``` :::info -More details about the application model and module dependency declaration can be found in [Kusion Module guide for app dev](../3-concepts/3-kusion-module/3-app-dev-guide.md). +More details about the application model and module dependency declaration can be found in [Kusion Module guide for app dev](../3-concepts/3-module/3-app-dev-guide.md). ::: :::tip diff --git a/docs/kusion/3-concepts/1-project/_category_.json b/docs/kusion/3-concepts/1-project/_category_.json index 3ca65e52..b62ac774 100644 --- a/docs/kusion/3-concepts/1-project/_category_.json +++ b/docs/kusion/3-concepts/1-project/_category_.json @@ -1,3 +1,3 @@ { - "label": "Project" + "label": "Projects" } diff --git a/docs/kusion/3-concepts/2-stack/_category_.json b/docs/kusion/3-concepts/2-stack/_category_.json index 6425c52e..914c863f 100644 --- a/docs/kusion/3-concepts/2-stack/_category_.json +++ b/docs/kusion/3-concepts/2-stack/_category_.json @@ -1,3 +1,3 @@ { - "label": "Stack" + "label": "Stacks" } diff --git a/docs/kusion/3-concepts/3-kusion-module/_category_.json b/docs/kusion/3-concepts/3-kusion-module/_category_.json deleted file mode 100644 index a346baad..00000000 --- a/docs/kusion/3-concepts/3-kusion-module/_category_.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "label": "Kusion Module" -} diff --git a/docs/kusion/3-concepts/3-kusion-module/1-overview.md b/docs/kusion/3-concepts/3-module/1-overview.md similarity index 100% rename from docs/kusion/3-concepts/3-kusion-module/1-overview.md rename to docs/kusion/3-concepts/3-module/1-overview.md diff --git a/docs/kusion/3-concepts/3-kusion-module/2-develop-guide.md b/docs/kusion/3-concepts/3-module/2-develop-guide.md similarity index 100% rename from docs/kusion/3-concepts/3-kusion-module/2-develop-guide.md rename to docs/kusion/3-concepts/3-module/2-develop-guide.md diff --git a/docs/kusion/3-concepts/3-kusion-module/3-app-dev-guide.md b/docs/kusion/3-concepts/3-module/3-app-dev-guide.md similarity index 100% rename from docs/kusion/3-concepts/3-kusion-module/3-app-dev-guide.md rename to docs/kusion/3-concepts/3-module/3-app-dev-guide.md diff --git a/docs/kusion/3-concepts/3-module/_category_.json b/docs/kusion/3-concepts/3-module/_category_.json new file mode 100644 index 00000000..5952a21e --- /dev/null +++ b/docs/kusion/3-concepts/3-module/_category_.json @@ -0,0 +1,3 @@ +{ + "label": "Modules" +} diff --git a/docs/kusion/3-concepts/4-workspace.md b/docs/kusion/3-concepts/4-workspace.md index 800a9825..8dee767c 100644 --- a/docs/kusion/3-concepts/4-workspace.md +++ b/docs/kusion/3-concepts/4-workspace.md @@ -1,6 +1,6 @@ --- id: workspace -sidebar_label: Workspace +sidebar_label: Workspaces --- # Workspace @@ -71,7 +71,7 @@ The values of the same fields in `patcher` will override the `default`, and one In the `patcher`, the applied Projects are assigned by the field `ProjectSelector`, which is an array of the Project names. The `ProjectSelector` is provided rather than something may like `StackSelector`, which specifies the applied Stacks. Here are the reasons. Explaining from the perspective of using Workspace, the mapping of Workspace and Stack is specified by the Kusion operation commands' users. While explaining from the perspective of the relationship among Project, Stack and Workspace, Workspace is designed for the reuse of platform-level configuration among multiple Projects. When a Project "encounters" a Workspace, it becomes a "Stack instance", which can be applied to a series of real resources. If using something like `StackSelector`, the reuse would not get realized, and Workspace would also lose its relevance. For more information of the relationship, please refer to [Project](project/overview) and [Stack](stack/overview). -Different Module and KAM has different name, fields, and corresponding format and restrictions. When writing the configuration, check the corresponding Module's or KAM's description, and make sure all the requisite Modules and KAMs have correctly configured. Please refer to [Kuiosn Module](kusion-module/overview) and find more information. The example above gives a sample of the Module `mysql`. +Different Module and KAM has different name, fields, and corresponding format and restrictions. When writing the configuration, check the corresponding Module's or KAM's description, and make sure all the requisite Modules and KAMs have correctly configured. Please refer to [Kuiosn Module](module/overview) and find more information. The example above gives a sample of the Module `mysql`. ## Managing Workspace diff --git a/docs/kusion/3-concepts/7-backend.md b/docs/kusion/3-concepts/7-backend.md index 336cb083..5262f7ac 100644 --- a/docs/kusion/3-concepts/7-backend.md +++ b/docs/kusion/3-concepts/7-backend.md @@ -1,6 +1,6 @@ --- id: backend -sidebar_label: Backend +sidebar_label: Backends --- # Backend diff --git a/docs/kusion/3-concepts/9-how-kusion-works.md b/docs/kusion/3-concepts/9-how-kusion-works.md deleted file mode 100644 index 6fe15005..00000000 --- a/docs/kusion/3-concepts/9-how-kusion-works.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -id: how-kusion-works -sidebar_label: How Kusion Works? ---- - -# How Kusion Works? - -Kusion is the platform engineering engine of [KusionStack](https://github.com/KusionStack). It delivers intentions described with Kusion Modules defined in [Catalog](https://github.com/KusionStack/catalog) to Kubernetes, Clouds and On-Prem infrastructures. - -![arch](https://raw.githubusercontent.com/KusionStack/kusion/main/docs/workflow.png) - -## Overview - -The workflow of KusionStack is illustrated in the diagram above, and it consists of three steps. The first step is `Write`, where platform engineers provide Kusion Modules and application developers write AppConfigurations based on the Kusion Modules to describe their operational intent. - -The second step is the `Build` process, which results in the creation of the SSoT (Single Source of Truth), also known as the [Intent](spec) of the current operational task. If you need version management of the SSoT, we recommend you manage the Intent with a VCS (Version Control System) tool like git. - -The third step is `Apply` which makes the Intent effective. Kusion parses the operational intent based on the Intent produced in the previous step. Before applying the intent, 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 expectations; the Apply command will then actualize the operational intent onto various infrastructure platforms. Currently, it supports three runtimes: Terraform, Kubernetes, and on-prem infrastructures. - -As a user of Kusion, if you prefer not to be conscious of so many steps, you can simply use `kusion apply`, and Kusion will automatically execute all the aforementioned steps for you. - -## Platform Developer’s Workflow - -### Design Kusion Modules - -[Kusion Module](kusion-module/overview) is a reusable building block designed by platform engineers and contains two components: an application developer-oriented schema and a Kusion module generator. When platform engineers have developed a Kusion module, they can push it to a [catalog](https://github.com/KusionStack/catalog) repository to make it into a KCL package. - -Given a database Kusion module as an example, the schema definition is shown below and the generator logic can be found [here](https://github.com/KusionStack/kusion/blob/main/pkg/modules/generators/accessories/database_generator.go). - -```python -schema MySQL: - """ MySQL describes the attributes to locally deploy or create a cloud provider - managed mysql database instance for the workload. - - Attributes - ---------- - type: "local" | "cloud", defaults to Undefined, required. - Type defines whether the mysql database is deployed locally or provided by - cloud vendor. - version: str, defaults to Undefined, required. - Version defines the mysql version to use. - - Examples - -------- - Instantiate a local mysql database with version of 5.7. - - import models.schema.v1.accessories.mysql - - mysql: mysql.MySQL { - type: "local" - version: "5.7" - } - """ - - # The deployment mode of the mysql database. - type: "local" | "cloud" - - # The mysql database version to use. - version: str -``` - -### Instantiate and Set Up Workspaces - -Each [workspace](workspace) includes a corresponding Platform config file maintained by platform engineers. -Platform engineers should instantiate all workspaces and fulfill all fields with platform default values. Kusion will merge the workspace configuration with AppConfiguration in the Stack of the same name. An example is as follows. - -```yaml -modules: - # platform configuration of AWS RDS MySQL - mysql: - path: oci://ghcr.io/kusionstack/mysql - version: 0.2.0 - configs: - default: - cloud: aws - size: 20 - instanceType: db.t3.micro - privateRouting: false - databaseName: "wordpress-mysql" -``` - -The `mysql` block represents a Kusion module. The fields inside are parts of the inputs for the Kusion module generator. For more details about the workspace, please refer to the [workspace](workspace) section. - -## Application Developer’s Workflow - -### Instantiate AppConfiguration and Apply - -Application developers choose Kusion modules they need and instantiate them in the AppConfiguration to describe their operation intentions. We have built some built-in Kusion modules in the repository [Catalog](https://github.com/KusionStack/catalog) and we warmly welcome you to join us in building this ecosystem together. - -`main.k` is the **only** configuration maintained by application developers and schemas in this file are defined from the application developer's perspective to reduce their cognitive load. An example is as follows. - -```pthyon -import kam.v1.app_configuration as ac -import service -import service.container as c -import network as n -import mysql - -# main.k declares customized configurations for dev stacks. -wordpress: ac.AppConfiguration { - workload: service.Service { - containers: { - wordpress: c.Container { - image: "wordpress:6.3" - env: { - "WORDPRESS_DB_HOST": "$(KUSION_DB_HOST_WORDPRESS_MYSQL)" - "WORDPRESS_DB_USER": "$(KUSION_DB_USERNAME_WORDPRESS_MYSQL)" - "WORDPRESS_DB_PASSWORD": "$(KUSION_DB_PASSWORD_WORDPRESS_MYSQL)" - "WORDPRESS_DB_NAME": "mysql" - } - ...... - } - } - ...... - } - accessories: { - "network": n.Network { - ...... - } - "mysql": mysql.MySQL { - type: "cloud" - version: "8.0" - } - } -} -``` - -`workload` and `database` are both Kusion modules provided by platform engineers and Kusion will convert them into actual infrastructure API calls eventually. - -Finally, application developers can deliver their operational intent to infrastructures with one command `kusion apply`. diff --git a/docs/kusion/4-configuration-walkthrough/1-overview.md b/docs/kusion/4-configuration-walkthrough/1-overview.md index 4b5f0a81..e7339ec9 100644 --- a/docs/kusion/4-configuration-walkthrough/1-overview.md +++ b/docs/kusion/4-configuration-walkthrough/1-overview.md @@ -66,7 +66,7 @@ As a general best practice, we recommend managing the common configurations in ` The schema for `AppConfiguration` is defined in the [KusionStack/kam](https://github.com/KusionStack/kam/blob/main/v1/app_configuration.k) repository. It is designed as a unified, application-centric model that encapsulates the comprehensive configuration details and in the meantime, hides the complexity of the infrastructure as much as possible. -`AppConfiguration` consists of multiple sub-components that each represent either the application workload itself, its dependencies (in the form of [Kusion Modules](../concepts/kusion-module/overview)), relevant workflows or operational expectations. We will deep dive into the details on how to author each of these elements in this upcoming documentation series. +`AppConfiguration` consists of multiple sub-components that each represent either the application workload itself, its dependencies (in the form of [Kusion Modules](../concepts/module/overview)), relevant workflows or operational expectations. We will deep dive into the details on how to author each of these elements in this upcoming documentation series. For more details on the `AppConfiguration`, please refer to the [design documentation](../concepts/app-configuration). @@ -86,7 +86,7 @@ In the context of Kusion, we abstracted a core set of KCL Schemas (such as the a ### Kusion Modules -To extend the capabilities beyond the core KAM model, we use a concept known as [Kusion Modules](../concepts/kusion-module/overview) to define components that could best abstract the capabilities during an application delivery. We provide a collection of official out-of-the-box Kusion Modules that represents the most common capabilities. They are maintained in [KusionStack's GitHub container registry](https://github.com/orgs/KusionStack/packages). When authoring an application configuration file, you can simply declare said Kusion Modules as dependencies and import them to declare ship-time capabilities that the application requires. +To extend the capabilities beyond the core KAM model, we use a concept known as [Kusion Modules](../concepts/module/overview) to define components that could best abstract the capabilities during an application delivery. We provide a collection of official out-of-the-box Kusion Modules that represents the most common capabilities. They are maintained in [KusionStack's GitHub container registry](https://github.com/orgs/KusionStack/packages). When authoring an application configuration file, you can simply declare said Kusion Modules as dependencies and import them to declare ship-time capabilities that the application requires. If the modules in the KusionStack container registry does not meet the needs of your applications, Kusion provides the necessary mechanisms to extend with custom-built Kusion Modules. You can always create and publish your own module, then import the new module in your application configuration written in KCL. diff --git a/docs/kusion/5-user-guides/5-production-practice-case/1-production-practice-case.md b/docs/kusion/5-user-guides/5-production-practice-case/1-production-practice-case.md index d29ea203..52d5f07e 100644 --- a/docs/kusion/5-user-guides/5-production-practice-case/1-production-practice-case.md +++ b/docs/kusion/5-user-guides/5-production-practice-case/1-production-practice-case.md @@ -6,7 +6,7 @@ id: collaborate-with-github-actions In this article, we will introduce how to use Kusion CLI in combination with GitHub Actions to achieve team collaboration in production practice. -Adopting the concept of separation of concerns, we divide the staff involved in application delivery and operation into two groups: **Platform Engineers (PEs)** and **Developers (Devs)**. As the builders of the Internal Developer Platform (IDP), platform engineers are primarily responsible for creating the [storage backend](../../3-concepts/7-backend.md) for the Kusion CLI in team collaborative scenarios (e.g. AWS S3 or Alicloud OSS), developing custom reusable [Kusion modules](../../3-concepts/3-kusion-module/1-overview.md), and creating and maintaining standardized platform configurations in [workspace](../../3-concepts/4-workspace.md). While application developers can focus on writing the application business logic and the configuration codes, self-serving the application delivery and operation by triggering the automated CI/CD pipelines. [GitHub Actions](https://github.com/features/actions) is such a CI/CD platform, and by customizing [GitHub Actions workflow](https://docs.github.com/en/actions/using-workflows), the pipeline such as building, testing, and deploying will be executed automatically. +Adopting the concept of separation of concerns, we divide the staff involved in application delivery and operation into two groups: **Platform Engineers (PEs)** and **Developers (Devs)**. As the builders of the Internal Developer Platform (IDP), platform engineers are primarily responsible for creating the [storage backend](../../3-concepts/7-backend.md) for the Kusion CLI in team collaborative scenarios (e.g. AWS S3 or Alicloud OSS), developing custom reusable [Kusion modules](../../3-concepts/3-module/1-overview.md), and creating and maintaining standardized platform configurations in [workspace](../../3-concepts/4-workspace.md). While application developers can focus on writing the application business logic and the configuration codes, self-serving the application delivery and operation by triggering the automated CI/CD pipelines. [GitHub Actions](https://github.com/features/actions) is such a CI/CD platform, and by customizing [GitHub Actions workflow](https://docs.github.com/en/actions/using-workflows), the pipeline such as building, testing, and deploying will be executed automatically. In the following sections, we will demonstrate the specific workflow from the perspectives of both PEs and Devs with the sample workflows from our [konfg](https://github.com/KusionStack/konfig) and [catalog](https://github.com/KusionStack/catalog) repository. diff --git a/docs_versioned_docs/version-v0.12/2-getting-started/2-deliver-quickstart.md b/docs_versioned_docs/version-v0.12/2-getting-started/2-deliver-quickstart.md index 0ddbeb85..7b89b4fa 100644 --- a/docs_versioned_docs/version-v0.12/2-getting-started/2-deliver-quickstart.md +++ b/docs_versioned_docs/version-v0.12/2-getting-started/2-deliver-quickstart.md @@ -102,7 +102,7 @@ network = { oci = "oci://ghcr.io/kusionstack/network", tag = "0.2.0" } ``` :::info -More details about the application model and module dependency declaration can be found in [Kusion Module guide for app dev](../3-concepts/3-kusion-module/3-app-dev-guide.md). +More details about the application model and module dependency declaration can be found in [Kusion Module guide for app dev](../3-concepts/3-module/3-app-dev-guide.md). ::: :::tip diff --git a/docs_versioned_docs/version-v0.12/3-concepts/1-project/_category_.json b/docs_versioned_docs/version-v0.12/3-concepts/1-project/_category_.json index 3ca65e52..b62ac774 100644 --- a/docs_versioned_docs/version-v0.12/3-concepts/1-project/_category_.json +++ b/docs_versioned_docs/version-v0.12/3-concepts/1-project/_category_.json @@ -1,3 +1,3 @@ { - "label": "Project" + "label": "Projects" } diff --git a/docs_versioned_docs/version-v0.12/3-concepts/2-stack/_category_.json b/docs_versioned_docs/version-v0.12/3-concepts/2-stack/_category_.json index 6425c52e..914c863f 100644 --- a/docs_versioned_docs/version-v0.12/3-concepts/2-stack/_category_.json +++ b/docs_versioned_docs/version-v0.12/3-concepts/2-stack/_category_.json @@ -1,3 +1,3 @@ { - "label": "Stack" + "label": "Stacks" } diff --git a/docs_versioned_docs/version-v0.12/3-concepts/3-kusion-module/_category_.json b/docs_versioned_docs/version-v0.12/3-concepts/3-kusion-module/_category_.json deleted file mode 100644 index a346baad..00000000 --- a/docs_versioned_docs/version-v0.12/3-concepts/3-kusion-module/_category_.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "label": "Kusion Module" -} diff --git a/docs_versioned_docs/version-v0.12/3-concepts/3-kusion-module/1-overview.md b/docs_versioned_docs/version-v0.12/3-concepts/3-module/1-overview.md similarity index 100% rename from docs_versioned_docs/version-v0.12/3-concepts/3-kusion-module/1-overview.md rename to docs_versioned_docs/version-v0.12/3-concepts/3-module/1-overview.md diff --git a/docs_versioned_docs/version-v0.12/3-concepts/3-kusion-module/2-develop-guide.md b/docs_versioned_docs/version-v0.12/3-concepts/3-module/2-develop-guide.md similarity index 100% rename from docs_versioned_docs/version-v0.12/3-concepts/3-kusion-module/2-develop-guide.md rename to docs_versioned_docs/version-v0.12/3-concepts/3-module/2-develop-guide.md diff --git a/docs_versioned_docs/version-v0.12/3-concepts/3-kusion-module/3-app-dev-guide.md b/docs_versioned_docs/version-v0.12/3-concepts/3-module/3-app-dev-guide.md similarity index 100% rename from docs_versioned_docs/version-v0.12/3-concepts/3-kusion-module/3-app-dev-guide.md rename to docs_versioned_docs/version-v0.12/3-concepts/3-module/3-app-dev-guide.md diff --git a/docs_versioned_docs/version-v0.12/3-concepts/3-module/_category_.json b/docs_versioned_docs/version-v0.12/3-concepts/3-module/_category_.json new file mode 100644 index 00000000..5952a21e --- /dev/null +++ b/docs_versioned_docs/version-v0.12/3-concepts/3-module/_category_.json @@ -0,0 +1,3 @@ +{ + "label": "Modules" +} diff --git a/docs_versioned_docs/version-v0.12/3-concepts/4-workspace.md b/docs_versioned_docs/version-v0.12/3-concepts/4-workspace.md index 800a9825..32fccfb0 100644 --- a/docs_versioned_docs/version-v0.12/3-concepts/4-workspace.md +++ b/docs_versioned_docs/version-v0.12/3-concepts/4-workspace.md @@ -71,7 +71,7 @@ The values of the same fields in `patcher` will override the `default`, and one In the `patcher`, the applied Projects are assigned by the field `ProjectSelector`, which is an array of the Project names. The `ProjectSelector` is provided rather than something may like `StackSelector`, which specifies the applied Stacks. Here are the reasons. Explaining from the perspective of using Workspace, the mapping of Workspace and Stack is specified by the Kusion operation commands' users. While explaining from the perspective of the relationship among Project, Stack and Workspace, Workspace is designed for the reuse of platform-level configuration among multiple Projects. When a Project "encounters" a Workspace, it becomes a "Stack instance", which can be applied to a series of real resources. If using something like `StackSelector`, the reuse would not get realized, and Workspace would also lose its relevance. For more information of the relationship, please refer to [Project](project/overview) and [Stack](stack/overview). -Different Module and KAM has different name, fields, and corresponding format and restrictions. When writing the configuration, check the corresponding Module's or KAM's description, and make sure all the requisite Modules and KAMs have correctly configured. Please refer to [Kuiosn Module](kusion-module/overview) and find more information. The example above gives a sample of the Module `mysql`. +Different Module and KAM has different name, fields, and corresponding format and restrictions. When writing the configuration, check the corresponding Module's or KAM's description, and make sure all the requisite Modules and KAMs have correctly configured. Please refer to [Kuiosn Module](module/overview) and find more information. The example above gives a sample of the Module `mysql`. ## Managing Workspace diff --git a/docs_versioned_docs/version-v0.12/3-concepts/7-backend.md b/docs_versioned_docs/version-v0.12/3-concepts/7-backend.md index 336cb083..5262f7ac 100644 --- a/docs_versioned_docs/version-v0.12/3-concepts/7-backend.md +++ b/docs_versioned_docs/version-v0.12/3-concepts/7-backend.md @@ -1,6 +1,6 @@ --- id: backend -sidebar_label: Backend +sidebar_label: Backends --- # Backend diff --git a/docs_versioned_docs/version-v0.12/3-concepts/9-how-kusion-works.md b/docs_versioned_docs/version-v0.12/3-concepts/9-how-kusion-works.md deleted file mode 100644 index 6fe15005..00000000 --- a/docs_versioned_docs/version-v0.12/3-concepts/9-how-kusion-works.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -id: how-kusion-works -sidebar_label: How Kusion Works? ---- - -# How Kusion Works? - -Kusion is the platform engineering engine of [KusionStack](https://github.com/KusionStack). It delivers intentions described with Kusion Modules defined in [Catalog](https://github.com/KusionStack/catalog) to Kubernetes, Clouds and On-Prem infrastructures. - -![arch](https://raw.githubusercontent.com/KusionStack/kusion/main/docs/workflow.png) - -## Overview - -The workflow of KusionStack is illustrated in the diagram above, and it consists of three steps. The first step is `Write`, where platform engineers provide Kusion Modules and application developers write AppConfigurations based on the Kusion Modules to describe their operational intent. - -The second step is the `Build` process, which results in the creation of the SSoT (Single Source of Truth), also known as the [Intent](spec) of the current operational task. If you need version management of the SSoT, we recommend you manage the Intent with a VCS (Version Control System) tool like git. - -The third step is `Apply` which makes the Intent effective. Kusion parses the operational intent based on the Intent produced in the previous step. Before applying the intent, 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 expectations; the Apply command will then actualize the operational intent onto various infrastructure platforms. Currently, it supports three runtimes: Terraform, Kubernetes, and on-prem infrastructures. - -As a user of Kusion, if you prefer not to be conscious of so many steps, you can simply use `kusion apply`, and Kusion will automatically execute all the aforementioned steps for you. - -## Platform Developer’s Workflow - -### Design Kusion Modules - -[Kusion Module](kusion-module/overview) is a reusable building block designed by platform engineers and contains two components: an application developer-oriented schema and a Kusion module generator. When platform engineers have developed a Kusion module, they can push it to a [catalog](https://github.com/KusionStack/catalog) repository to make it into a KCL package. - -Given a database Kusion module as an example, the schema definition is shown below and the generator logic can be found [here](https://github.com/KusionStack/kusion/blob/main/pkg/modules/generators/accessories/database_generator.go). - -```python -schema MySQL: - """ MySQL describes the attributes to locally deploy or create a cloud provider - managed mysql database instance for the workload. - - Attributes - ---------- - type: "local" | "cloud", defaults to Undefined, required. - Type defines whether the mysql database is deployed locally or provided by - cloud vendor. - version: str, defaults to Undefined, required. - Version defines the mysql version to use. - - Examples - -------- - Instantiate a local mysql database with version of 5.7. - - import models.schema.v1.accessories.mysql - - mysql: mysql.MySQL { - type: "local" - version: "5.7" - } - """ - - # The deployment mode of the mysql database. - type: "local" | "cloud" - - # The mysql database version to use. - version: str -``` - -### Instantiate and Set Up Workspaces - -Each [workspace](workspace) includes a corresponding Platform config file maintained by platform engineers. -Platform engineers should instantiate all workspaces and fulfill all fields with platform default values. Kusion will merge the workspace configuration with AppConfiguration in the Stack of the same name. An example is as follows. - -```yaml -modules: - # platform configuration of AWS RDS MySQL - mysql: - path: oci://ghcr.io/kusionstack/mysql - version: 0.2.0 - configs: - default: - cloud: aws - size: 20 - instanceType: db.t3.micro - privateRouting: false - databaseName: "wordpress-mysql" -``` - -The `mysql` block represents a Kusion module. The fields inside are parts of the inputs for the Kusion module generator. For more details about the workspace, please refer to the [workspace](workspace) section. - -## Application Developer’s Workflow - -### Instantiate AppConfiguration and Apply - -Application developers choose Kusion modules they need and instantiate them in the AppConfiguration to describe their operation intentions. We have built some built-in Kusion modules in the repository [Catalog](https://github.com/KusionStack/catalog) and we warmly welcome you to join us in building this ecosystem together. - -`main.k` is the **only** configuration maintained by application developers and schemas in this file are defined from the application developer's perspective to reduce their cognitive load. An example is as follows. - -```pthyon -import kam.v1.app_configuration as ac -import service -import service.container as c -import network as n -import mysql - -# main.k declares customized configurations for dev stacks. -wordpress: ac.AppConfiguration { - workload: service.Service { - containers: { - wordpress: c.Container { - image: "wordpress:6.3" - env: { - "WORDPRESS_DB_HOST": "$(KUSION_DB_HOST_WORDPRESS_MYSQL)" - "WORDPRESS_DB_USER": "$(KUSION_DB_USERNAME_WORDPRESS_MYSQL)" - "WORDPRESS_DB_PASSWORD": "$(KUSION_DB_PASSWORD_WORDPRESS_MYSQL)" - "WORDPRESS_DB_NAME": "mysql" - } - ...... - } - } - ...... - } - accessories: { - "network": n.Network { - ...... - } - "mysql": mysql.MySQL { - type: "cloud" - version: "8.0" - } - } -} -``` - -`workload` and `database` are both Kusion modules provided by platform engineers and Kusion will convert them into actual infrastructure API calls eventually. - -Finally, application developers can deliver their operational intent to infrastructures with one command `kusion apply`. diff --git a/docs_versioned_docs/version-v0.12/4-configuration-walkthrough/1-overview.md b/docs_versioned_docs/version-v0.12/4-configuration-walkthrough/1-overview.md index 4b5f0a81..e7339ec9 100644 --- a/docs_versioned_docs/version-v0.12/4-configuration-walkthrough/1-overview.md +++ b/docs_versioned_docs/version-v0.12/4-configuration-walkthrough/1-overview.md @@ -66,7 +66,7 @@ As a general best practice, we recommend managing the common configurations in ` The schema for `AppConfiguration` is defined in the [KusionStack/kam](https://github.com/KusionStack/kam/blob/main/v1/app_configuration.k) repository. It is designed as a unified, application-centric model that encapsulates the comprehensive configuration details and in the meantime, hides the complexity of the infrastructure as much as possible. -`AppConfiguration` consists of multiple sub-components that each represent either the application workload itself, its dependencies (in the form of [Kusion Modules](../concepts/kusion-module/overview)), relevant workflows or operational expectations. We will deep dive into the details on how to author each of these elements in this upcoming documentation series. +`AppConfiguration` consists of multiple sub-components that each represent either the application workload itself, its dependencies (in the form of [Kusion Modules](../concepts/module/overview)), relevant workflows or operational expectations. We will deep dive into the details on how to author each of these elements in this upcoming documentation series. For more details on the `AppConfiguration`, please refer to the [design documentation](../concepts/app-configuration). @@ -86,7 +86,7 @@ In the context of Kusion, we abstracted a core set of KCL Schemas (such as the a ### Kusion Modules -To extend the capabilities beyond the core KAM model, we use a concept known as [Kusion Modules](../concepts/kusion-module/overview) to define components that could best abstract the capabilities during an application delivery. We provide a collection of official out-of-the-box Kusion Modules that represents the most common capabilities. They are maintained in [KusionStack's GitHub container registry](https://github.com/orgs/KusionStack/packages). When authoring an application configuration file, you can simply declare said Kusion Modules as dependencies and import them to declare ship-time capabilities that the application requires. +To extend the capabilities beyond the core KAM model, we use a concept known as [Kusion Modules](../concepts/module/overview) to define components that could best abstract the capabilities during an application delivery. We provide a collection of official out-of-the-box Kusion Modules that represents the most common capabilities. They are maintained in [KusionStack's GitHub container registry](https://github.com/orgs/KusionStack/packages). When authoring an application configuration file, you can simply declare said Kusion Modules as dependencies and import them to declare ship-time capabilities that the application requires. If the modules in the KusionStack container registry does not meet the needs of your applications, Kusion provides the necessary mechanisms to extend with custom-built Kusion Modules. You can always create and publish your own module, then import the new module in your application configuration written in KCL. diff --git a/docs_versioned_docs/version-v0.12/5-user-guides/5-production-practice-case/1-production-practice-case.md b/docs_versioned_docs/version-v0.12/5-user-guides/5-production-practice-case/1-production-practice-case.md index d29ea203..52d5f07e 100644 --- a/docs_versioned_docs/version-v0.12/5-user-guides/5-production-practice-case/1-production-practice-case.md +++ b/docs_versioned_docs/version-v0.12/5-user-guides/5-production-practice-case/1-production-practice-case.md @@ -6,7 +6,7 @@ id: collaborate-with-github-actions In this article, we will introduce how to use Kusion CLI in combination with GitHub Actions to achieve team collaboration in production practice. -Adopting the concept of separation of concerns, we divide the staff involved in application delivery and operation into two groups: **Platform Engineers (PEs)** and **Developers (Devs)**. As the builders of the Internal Developer Platform (IDP), platform engineers are primarily responsible for creating the [storage backend](../../3-concepts/7-backend.md) for the Kusion CLI in team collaborative scenarios (e.g. AWS S3 or Alicloud OSS), developing custom reusable [Kusion modules](../../3-concepts/3-kusion-module/1-overview.md), and creating and maintaining standardized platform configurations in [workspace](../../3-concepts/4-workspace.md). While application developers can focus on writing the application business logic and the configuration codes, self-serving the application delivery and operation by triggering the automated CI/CD pipelines. [GitHub Actions](https://github.com/features/actions) is such a CI/CD platform, and by customizing [GitHub Actions workflow](https://docs.github.com/en/actions/using-workflows), the pipeline such as building, testing, and deploying will be executed automatically. +Adopting the concept of separation of concerns, we divide the staff involved in application delivery and operation into two groups: **Platform Engineers (PEs)** and **Developers (Devs)**. As the builders of the Internal Developer Platform (IDP), platform engineers are primarily responsible for creating the [storage backend](../../3-concepts/7-backend.md) for the Kusion CLI in team collaborative scenarios (e.g. AWS S3 or Alicloud OSS), developing custom reusable [Kusion modules](../../3-concepts/3-module/1-overview.md), and creating and maintaining standardized platform configurations in [workspace](../../3-concepts/4-workspace.md). While application developers can focus on writing the application business logic and the configuration codes, self-serving the application delivery and operation by triggering the automated CI/CD pipelines. [GitHub Actions](https://github.com/features/actions) is such a CI/CD platform, and by customizing [GitHub Actions workflow](https://docs.github.com/en/actions/using-workflows), the pipeline such as building, testing, and deploying will be executed automatically. In the following sections, we will demonstrate the specific workflow from the perspectives of both PEs and Devs with the sample workflows from our [konfg](https://github.com/KusionStack/konfig) and [catalog](https://github.com/KusionStack/catalog) repository.