diff --git a/docs/kusion/1-what-is-kusion/2-kusion-vs-x.md b/docs/kusion/1-what-is-kusion/2-kusion-vs-x.md index a5ed333d..ca077620 100644 --- a/docs/kusion/1-what-is-kusion/2-kusion-vs-x.md +++ b/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** diff --git a/docs/kusion/3-concepts/0-overview.md b/docs/kusion/3-concepts/0-overview.md index 44aa634e..b0db99dc 100644 --- a/docs/kusion/3-concepts/0-overview.md +++ b/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. diff --git a/docs/kusion/3-concepts/1-project/1-overview.md b/docs/kusion/3-concepts/1-project/1-overview.md index edcc84d7..152d0ed1 100644 --- a/docs/kusion/3-concepts/1-project/1-overview.md +++ b/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. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/kusion/3-concepts/10-resources.md b/docs/kusion/3-concepts/10-resources.md new file mode 100644 index 00000000..582f17bf --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/kusion/3-concepts/8-configuration.md b/docs/kusion/3-concepts/11-cli-configuration.md similarity index 95% rename from docs/kusion/3-concepts/8-configuration.md rename to docs/kusion/3-concepts/11-cli-configuration.md index 2ad72e6b..fc681634 100644 --- a/docs/kusion/3-concepts/8-configuration.md +++ b/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. diff --git a/docs/kusion/3-concepts/2-stack/1-overview.md b/docs/kusion/3-concepts/2-stack/1-overview.md index c6dcd2b5..b896a736 100644 --- a/docs/kusion/3-concepts/2-stack/1-overview.md +++ b/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 diff --git a/docs/kusion/3-concepts/3-module/1-overview.md b/docs/kusion/3-concepts/3-module/1-overview.md index b6487117..fb9f1359 100644 --- a/docs/kusion/3-concepts/3-module/1-overview.md +++ b/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. diff --git a/docs/kusion/3-concepts/3-module/2-develop-guide.md b/docs/kusion/3-concepts/3-module/2-develop-guide.md index e4a076e9..9b60aaf4 100644 --- a/docs/kusion/3-concepts/3-module/2-develop-guide.md +++ b/docs/kusion/3-concepts/3-module/2-develop-guide.md @@ -12,7 +12,7 @@ To follow this guide, you will need: As a platform engineer, the workflow of developing a Kusion module looks like this: 1. Communicate with app developers and identify the fields that should exposed to them in the dev-orient schema -2. Identify module input parameters that should be configured by platform engineers in the [workspace](../workspace) +2. Identify module input parameters that should be configured by platform engineers in the [workspace](../4-workspace/1-overview.md) 3. Define the app dev-orient schema 4. Develop the module by implementing gRPC interfaces @@ -113,7 +113,7 @@ service: Service randomPassword: RandomPassword ``` -3. **Implement the [gRPC proto](https://github.com/KusionStack/kusion/blob/main/pkg/modules/proto/module.proto) generate interface.** The `generate` interface consumes the application developer's config described in the [`AppConfiguration`](../app-configuration) and the platform engineer's config described in the [`workspace`](../workspace) to generate all infrastructure resources represented by this module. +3. **Implement the [gRPC proto](https://github.com/KusionStack/kusion/blob/main/pkg/modules/proto/module.proto) generate interface.** The `generate` interface consumes the application developer's config described in the [`AppConfiguration`](../appconfigurations) and the platform engineer's config described in the [`workspace`](../4-workspace/1-overview.md) to generate all infrastructure resources represented by this module. ```go func (k *Kawesome) Generate(_ context.Context, request *module.GeneratorRequest) (*module.GeneratorResponse, error) { @@ -139,7 +139,7 @@ type Patcher struct { ``` The `GeneratorRequest` contains the application developer's config, platform engineer's config, workload config and related metadata a module could need to generate infrastructure resources. -In the `GeneratorResponse`, there are two fields, `Resources` and `Patchers`. The `Resource` represents resources that should operated by Kusion and they will be appended into the [Spec](../spec). The `Patchers` are used to patch the workload and other resources. +In the `GeneratorResponse`, there are two fields, `Resources` and `Patchers`. The `Resource` represents resources that should operated by Kusion and they will be appended into the [Spec](../specs). The `Patchers` are used to patch the workload and other resources. ### Workload diff --git a/docs/kusion/3-concepts/3-module/4-registration.md b/docs/kusion/3-concepts/3-module/4-registration.md new file mode 100644 index 00000000..e67f42a1 --- /dev/null +++ b/docs/kusion/3-concepts/3-module/4-registration.md @@ -0,0 +1,41 @@ +# Module Registration + +After a module is published, it needs to be registered before it can be used in **Kusion server**. This is to help the server to accurately generate a necessary `kcl.mod` file that describes the dependency of a configurations (i.e. what modules can I use as a developer). + +This step is not required when using Kusion CLI. + +## APIs + +The APIs to manage workspaces can be found in the swagger docs under `{server-endpoint}/docs/index.html#/module`. + +## Register a module via Developer Portal + +To register a new module via the developer portal, switch to the `Modules` tab and click on `New Module`. + +![module-create](/img/docs/concept/module-create.png) + +Fill out the module details. It's always recommended to provide a link to the module's documentation for developers to read. + +![module-details](/img/docs/concept/module-details.png) + +## Edit a registered module + +To edit a registered module, click the `edit` button. + +![module-edit](/img/docs/concept/module-edit.png) + +## Delete a registered module + +To delete a registered module, click the `delete` button. + +![module-delete](/img/docs/concept/module-delete.png) + +## Generate kcl.mod + +To generate the `kcl.mod` for a stack targeting a workspace, go the workspace page and select `Available Modules`, then click on `Generate kcl.mod`. + +![generate-kcl-mod](/img/docs/concept/generate-kcl-mod.png) + +A text box appears with the module dependency content generated. This should be copied and pasted into the `kcl.mod` file in the stack folder. + +![kcl-mod-generated](/img/docs/concept/kcl-mod-generated.png) diff --git a/docs/kusion/3-concepts/4-workspace.md b/docs/kusion/3-concepts/4-workspace/1-overview.md similarity index 57% rename from docs/kusion/3-concepts/4-workspace.md rename to docs/kusion/3-concepts/4-workspace/1-overview.md index f99977d0..f77158b6 100644 --- a/docs/kusion/3-concepts/4-workspace.md +++ b/docs/kusion/3-concepts/4-workspace/1-overview.md @@ -1,9 +1,4 @@ ---- -id: workspace -sidebar_label: Workspace ---- - -# Workspace +# Overview Workspace is a logical concept that maps to an actual target environment to deploy a stack to. In today's context, this _usually_ represents a Kubernetes cluster for the application workload and an optional cloud account to provision infrastructure resources that the workload depends on (A database, for example). Aside from the deployment destination, workspaces are also designed to be associated with a series of platform configurations that are used by all the stacks deployed to said workspace. @@ -23,6 +18,10 @@ The workspace configuration is in a deterministic format and currently written i The configuration of a Workspace is stored in a single YAML file, which consists of `modules`, `secretStore`, and `context`. An example of Workspace configuration is shown as below. +:::tip +The workspace configuration files are stored in [Backends](../7-backend/1-overview.md). +::: + ```yaml # The platform configuration for Modules or KAMs. # For each Module or KAM, the configuration format is as below. @@ -85,15 +84,15 @@ The `patcher` block is designed to increase the flexibility for platform enginee The values of the same fields in `patcher` will override the `default`, and one field in multiple patchers is forbidden to assign to the same Project. That is, if there are more than one `patcher` declaring the same field with different values, the applied Projects are prohibited to overlap. And, The name of `patcher` must not be `default`. -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). +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](../1-project/1-overview.md) and [Stack](../2-stack/1-overview.md). -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`. +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](../3-module/1-overview.md) and find more information. The example above gives a sample of the Module `mysql`. The `importedResources` block is designed to declare the import of existing cloud resources. The `importedResources` is a `map` where you can declare the mapping from `id` of the resource in Kusion `Spec` to the Terraform ID of the resource to be imported. Kusion will automatically synchronize the state of the existing cloud resource for the Kusion resource. ### secretStore -The `secretStore` field can be used to access the sensitive data stored in a cloud-based secrets manager. More details can be found in [here](../5-user-guides/1-using-kusion-cli/4-secrets-management/1-using-cloud-secrets.md). +The `secretStore` field can be used to access the sensitive data stored in a cloud-based secrets manager. More details can be found in [here](../../5-user-guides/1-using-kusion-cli/4-secrets-management/1-using-cloud-secrets.md). ### context @@ -104,119 +103,4 @@ The `context` field can be used to declare the information such as Kubernetes `k - `AWS_ACCESS_KEY_ID`: the access key ID of the AWS provider - `AWS_SECRET_ACCESS_KEY`: the secret key of the AWS provider - `ALICLOUD_ACCESS_KEY`: the access key ID of the Alicloud provider -- `ALICLOUD_SECRET_KEY`: the secret key of the Alicloud provider - -## Managing Workspace - -The subcommands of `kusion workspace` are used to manage Workspaces, including `create`, `show`, `list`, `switch`, `update` and `delete`. Cause the Workspace configurations are stored persistently, the current or a specified Backend will be used. For more information of Backend, please refer to [Backend](backend). - -Kusion will create a `default` Workspace with empty configuration in every Backend automatically, and set it as the current. When first using Kusion, or no configuration of Workspace, the `default` Workspace will be used. - -### Creating Workspace - -Use `kusion workspace create ${name} -f ${configuration_file_path}` to create a new Workspace with the configuration in a YAML file. The Workspace is identified by the `name`, and must be a new one, while the configuration must be written in a YAML file with correct format. - -The command above will create the Workspace in current Backend. If to create a Workspace in another backend, please use flag `--backend` to specify. The Workspace names in a Backend must be different, but allow the same in different Backends. - -In some scenarios, when a Workspace is created, it is expected to be the current. For simplification, the flag `--current` is provided to set the Workspace current alongside the creation. - -Be attention, creating `default` Workspace is not allowed, because it's created by Kusion automatically. - -The example is shown as below. - -```shell -# create a workspace in current backend -kusion workspace create dev -f dev.yaml - -# create a workspace in current backend ans set it as current -kusion workspace create dev -f dev.yaml --current - -# create a workspace in specified backend -kusion workspace create dev -f dev.yaml --backend oss-pre -``` - -The Workspaces to create are decided by the platform engineers. We recommend that they are organized by the following rules: - -- **SDLC phases**, such as `dev`, `pre`, `prod`; -- **cloud vendors**, such as `aws`, `alicloud`; -- combination of the two above, such as `dev-aws`, `prod-alicloud`. - -In design, Kusion does not support deploying Stack to multiple clouds or regions within a single Workspace. While users can technically define a Module that provisions resources across multiple clouds or regions, Kusion does not recommend this practice, and will not provide technical support for such configuration. If the platform engineers need to manage resources across multiple clouds or regions, they should create separate Workspaces. - -### Listing Workspace - -Use `kusion workspace list` to get all the workspace names. - -The example is shown as below. In order to simplify, The following examples will not give using specified backend, which is supported by `--backend` flag. - -```shell -# list all the workspace names -kusion workspace list -``` - -### Switching Workspace - -In order not to specify the Workspace name for each Kusion operation command, `kusion workspace switch ${name}` is provided to switch the current Workspace. Then when executing `kusion generate`, the current Workspace will be used. The to-switch Workspace must be created. - -The example is shown as below. - -```shell -# switch workspace -kusion workspace switch dev -``` - -### Showing Workspace - -Use `kusion workspace show ${name}` to get the Workspace configuration. If the `name` is not specified, the configuration of current Workspace will get returned. - -The example is shown as below. - -```shell -# show a specified workspace configuration -kusion workspace show dev - -# show the current workspace configuration -kusion workspace show -``` - -### Updating Workspace - -When the Workspace needs to update, use `kusion workspace update ${name} -f ${configuration_file_path}` to update with the new configuration file. The whole updated configuration is asked to provide, and the Workspace must be created. Get the Workspace configuration first, then refresh the configuration and execute the command, which are the recommended steps. If the `name` is not specified, the current Workspace will be used. - -Updating the `default` Workspace is allowed. And the flag `--current` is also supported to set it as the current. - -The example is shown as below. - -```shell -# update a specified workspace -kusion workspace update dev -f dev_new.yaml - -# update a specified workspace and set it as current -kusion workspace update dev -f dev_new.yaml --current - -# update the current workspace -kusion workspace update -f dev_new.yaml -``` - -### Deleting Workspace - -When a Workspace is not in use anymore, use `kusion workspace delete ${name}` to delete a Workspace. If the `name` is not specified, the current Workspace will get deleted, and the `default` Workspace will be set as the current Workspace. Therefore, deleting the `default` Workspace is not allowed. - -The example is shown as below. - -```shell -# delete a specified workspace -kusion workspace delete dev - -# delete the current workspace -kusion workspace delete -``` - -## Using Workspace - -Workspace is used in the command `kusion generate`, the following steps help smooth the operation process. - -1. Write the Workspace configuration file with the format shown above, and fulfill all the necessary fields; -2. Create the workspace with `kusion workspace create`, then Kusion perceives the Workspace. The flag `--current` can be used to set it as the current. -3. Execute `kusion generate` in a Stack to generate the whole Spec, the AppConfiguration and Workspace configuration get rendered automatically, and can be applied to the real infrastructure. If the appointed Workspace or Backend is asked, the flags `--workspace` and `--backend` will help achieve that. -4. If the Workspace needs to update, delete, switch, etc. Use the above commands to achieve that. +- `ALICLOUD_SECRET_KEY`: the secret key of the Alicloud provider \ No newline at end of file diff --git a/docs/kusion/3-concepts/4-workspace/2-manage-workspaces-with-server.md b/docs/kusion/3-concepts/4-workspace/2-manage-workspaces-with-server.md new file mode 100644 index 00000000..f478c7e7 --- /dev/null +++ b/docs/kusion/3-concepts/4-workspace/2-manage-workspaces-with-server.md @@ -0,0 +1,57 @@ +# Managing Workspace With Kusion Server + +When using Kusion server, workspaces are managed via the `/api/v1/workspaces` API. You can either access the APIs directly or if you have the Dev Portal enabled (`--dev-portal-enabled`, default to true), workspaces can be managed via the portal. The workspace configurations are also stored in the backends when using Kusion server. + +:::Tip +There are no "default" workspace when using the Kusion server. A workspace needs to be specified every time an operation (generate/preview/apply/destroy) is triggered. +::: + +## APIs + +The APIs to manage workspaces can be found in the swagger docs under `{server-endpoint}/docs/index.html#/workspace`. + +## Developer Portal + +### Creating Workspace + +Create a workspace by clicking on the `Create Workspace` button in the top right corner. + +![workspace-create-new](/img/docs/concept/workspace-create-new.png) + +Select the backend to store the workspace configurations. + +![workspace-select-backend](/img/docs/concept/workspace-select-backend.png) + +The Workspaces are generally managed by the platform engineers. We recommend that they are organized by the following rules: + +- **SDLC phases**, such as `dev`, `pre`, `prod`; +- **cloud vendors**, such as `aws`, `alicloud`; +- combination of the two above, such as `dev-aws`, `prod-alicloud`. + +In design, Kusion does not support deploying Stack to multiple clouds or regions within a single Workspace. While users can technically define a Module that provisions resources across multiple clouds or regions, Kusion does not recommend this practice, and will not provide technical support for such configuration. If the platform engineers need to manage resources across multiple clouds or regions, they should create separate Workspaces. + +### Listing Workspace + +List workspaces by clicking on the `Workspace` tab. + +## Showing Workspace + +Clicking on individual workspace to display the [workspace configurations](./1-overview.md#workspace-configuration). + +![workspace-configurations](/img/docs/concept/workspace-configurations.png) + +## Updating Workspace + +Update workspaces by clicking on the edit button on each workspace card. + +![workspace-edit](/img/docs/concept/workspace-edit.png) + +## Deleting Workspace + +![workspace-delete](/img/docs/concept/workspace-delete.png) + +## Using Workspace + +Workspace is used when creating [Runs](../9-runs.md). When creating each run, no matter what type, a workspace must be selected to represent the target environment. + +![workspace-select](/img/docs/concept/workspace-select.png) \ No newline at end of file diff --git a/docs/kusion/3-concepts/4-workspace/3-manage-workspaces-with-cli.md b/docs/kusion/3-concepts/4-workspace/3-manage-workspaces-with-cli.md new file mode 100644 index 00000000..703b95c7 --- /dev/null +++ b/docs/kusion/3-concepts/4-workspace/3-manage-workspaces-with-cli.md @@ -0,0 +1,114 @@ +# Managing Workspace With CLI + +The subcommands of `kusion workspace` are used to manage Workspaces, including `create`, `show`, `list`, `switch`, `update` and `delete`. Beause the Workspace configurations are stored persistently, the current or a specified Backend will be used. For more information of Backend, please refer to [Backend](../7-backend/1-overview.md). + +Kusion will create a `default` Workspace with empty configuration in every Backend automatically, and set it as the current. When first using Kusion, or no configuration of Workspace, the `default` Workspace will be used. + +## Creating Workspace + +Use `kusion workspace create ${name} -f ${configuration_file_path}` to create a new Workspace with the configuration in a YAML file. The Workspace is identified by the `name`, and must be a new one, while the configuration must be written in a YAML file with correct format. + +The command above will create the Workspace in current Backend. If to create a Workspace in another backend, please use flag `--backend` to specify. The Workspace names in a Backend must be different, but allow the same in different Backends. + +In some scenarios, when a Workspace is created, it is expected to be the current. For simplification, the flag `--current` is provided to set the Workspace current alongside the creation. + +Be attention, creating `default` Workspace is not allowed, because it's created by Kusion automatically. + +The example is shown as below. + +```shell +# create a workspace in current backend +kusion workspace create dev -f dev.yaml + +# create a workspace in current backend ans set it as current +kusion workspace create dev -f dev.yaml --current + +# create a workspace in specified backend +kusion workspace create dev -f dev.yaml --backend oss-pre +``` + +The Workspaces to create are decided by the platform engineers. We recommend that they are organized by the following rules: + +- **SDLC phases**, such as `dev`, `pre`, `prod`; +- **cloud vendors**, such as `aws`, `alicloud`; +- combination of the two above, such as `dev-aws`, `prod-alicloud`. + +In design, Kusion does not support deploying Stack to multiple clouds or regions within a single Workspace. While users can technically define a Module that provisions resources across multiple clouds or regions, Kusion does not recommend this practice, and will not provide technical support for such configuration. If the platform engineers need to manage resources across multiple clouds or regions, they should create separate Workspaces. + +## Listing Workspace + +Use `kusion workspace list` to get all the workspace names. + +The example is shown as below. In order to simplify, The following examples will not give using specified backend, which is supported by `--backend` flag. + +```shell +# list all the workspace names +kusion workspace list +``` + +## Switching Workspace + +In order not to specify the Workspace name for each Kusion operation command, `kusion workspace switch ${name}` is provided to switch the current Workspace. Then when executing `kusion generate`, the current Workspace will be used. The to-switch Workspace must be created. + +The example is shown as below. + +```shell +# switch workspace +kusion workspace switch dev +``` + +## Showing Workspace + +Use `kusion workspace show ${name}` to get the Workspace configuration. If the `name` is not specified, the configuration of current Workspace will get returned. + +The example is shown as below. + +```shell +# show a specified workspace configuration +kusion workspace show dev + +# show the current workspace configuration +kusion workspace show +``` + +## Updating Workspace + +When the Workspace needs to update, use `kusion workspace update ${name} -f ${configuration_file_path}` to update with the new configuration file. The whole updated configuration is asked to provide, and the Workspace must be created. Get the Workspace configuration first, then refresh the configuration and execute the command, which are the recommended steps. If the `name` is not specified, the current Workspace will be used. + +Updating the `default` Workspace is allowed. And the flag `--current` is also supported to set it as the current. + +The example is shown as below. + +```shell +# update a specified workspace +kusion workspace update dev -f dev_new.yaml + +# update a specified workspace and set it as current +kusion workspace update dev -f dev_new.yaml --current + +# update the current workspace +kusion workspace update -f dev_new.yaml +``` + +## Deleting Workspace + +When a Workspace is not in use anymore, use `kusion workspace delete ${name}` to delete a Workspace. If the `name` is not specified, the current Workspace will get deleted, and the `default` Workspace will be set as the current Workspace. Therefore, deleting the `default` Workspace is not allowed. + +The example is shown as below. + +```shell +# delete a specified workspace +kusion workspace delete dev + +# delete the current workspace +kusion workspace delete +``` + +## Using Workspace + +Workspace is used in the command `kusion generate`, the following steps help smooth the operation process. + +1. Write the Workspace configuration file with the format shown above, and fulfill all the necessary fields; +2. Create the workspace with `kusion workspace create`, then Kusion perceives the Workspace. The flag `--current` can be used to set it as the current. +3. Execute `kusion generate` in a Stack to generate the whole Spec, the AppConfiguration and Workspace configuration get rendered automatically, and can be applied to the real infrastructure. If the appointed Workspace or Backend is asked, the flags `--workspace` and `--backend` will help achieve that. +4. If the Workspace needs to update, delete, switch, etc. Use the above commands to achieve that. diff --git a/docs/kusion/3-concepts/4-workspace/_category_.json b/docs/kusion/3-concepts/4-workspace/_category_.json new file mode 100644 index 00000000..c79291d2 --- /dev/null +++ b/docs/kusion/3-concepts/4-workspace/_category_.json @@ -0,0 +1,3 @@ +{ + "label": "Workspaces" +} diff --git a/docs/kusion/3-concepts/5-appconfiguration.md b/docs/kusion/3-concepts/5-appconfigurations.md similarity index 97% rename from docs/kusion/3-concepts/5-appconfiguration.md rename to docs/kusion/3-concepts/5-appconfigurations.md index 570d1ac0..a24b1ed0 100644 --- a/docs/kusion/3-concepts/5-appconfiguration.md +++ b/docs/kusion/3-concepts/5-appconfigurations.md @@ -1,9 +1,4 @@ ---- -id: app-configuration -sidebar_label: AppConfiguration ---- - -# AppConfiguration +# AppConfigurations As a modern cloud-native application delivery toolchain, declarative intent-based actuation is the central idea of Kusion, and `AppConfiguration` model plays the role of describing the intent, which provides a simpler path for on-boarding developers to the platform without leaking low-level details in runtime infrastructure and allows developers to fully focus on the application logic itself. diff --git a/docs/kusion/3-concepts/6-spec.md b/docs/kusion/3-concepts/6-specs.md similarity index 73% rename from docs/kusion/3-concepts/6-spec.md rename to docs/kusion/3-concepts/6-specs.md index 2d39d47f..79f61fd9 100644 --- a/docs/kusion/3-concepts/6-spec.md +++ b/docs/kusion/3-concepts/6-specs.md @@ -1,13 +1,20 @@ ---- -id: spec -sidebar_label: Spec ---- +# Specs -# Spec +The spec is a system-generated, immutable, declarative representation of the resources involved in a particular deployment. As opposed to the static configurations that are stored in a stack folder in a git repository, which may or may not be scoped to a given deploy target, a spec is dynamically rendered from the aggregated intents from multiple sources, including those that are target-specific, and those aren't (e.g. global configs, constraints posed by security, compliance and so on, for example what kind of application may have Internet access). Specs are resource-facing desired states and are always rendered on the spot based on all the relevant inputs. -The Spec represents the operational intentions that you aim to deliver using Kusion. These intentions are expected to contain all components throughout the DevOps lifecycle, including resources (workload, database, load balancer, etc.), dependencies, and policies. The Kusion module generators are responsible for converting all AppConfigurations and environment configurations into the Spec. Once the Spec is generated, the Kusion Engine takes charge of updating the actual infrastructures to match the Spec. +The Specs are designed to be **THE** intermediate data layer between configuration code and actual resources. It is designed to be a structured data format that is both machine-friendly (so that we can use the proper libraries to process and actualize them) and human-friendly (so that it provides a readable reference to the resource perspective of an application). -## Purpose +## Generators + +The rendering logic that transforms the static configuration to the **Spec** are produced by "Generators", which are pieces of code written and distributed in Go. Generators are in charge of converting configuration code written in KCL into resource specifications in the Spec. They are packaged and wrapped inside a GRPC server whose lifecycle are dynamically managed as individual go-plugins. + +## Runtimes + +In this workflow, the component that processes the resources in the Spec is called a Runtime. Runtimes are in charge of bridging the resource specification to the actual infrastructure API. For Kubernetes resources, its runtime uses client-go to connect to the clusters. For the cloud resources, we are using IAC tools like Terraform/Crossplane and their providers to connect to the cloud control APIs. Runtimes are also extensible. + +![intent-flow](/img/docs/concept/intent-flow.png) + +## Purpose of Spec ### Single Source of Truth @@ -116,8 +123,8 @@ A `resource` is a concept in `Kusion` that abstract infrastructure. It represent - `dependsOn` contains all the other resources the resource depends on. - `extensions` specifies the arbitrary metadata of the resource, where you can declare information such as Kubernetes GVK, Terraform provider, and imported resource id, etc. -Besides the `resources`, Spec also records the `secretStore` and `context` field in the corresponding workspace. The former can be used to access sensitive data stored in an external secrets manager, while the latter can be used to declare the workspace-level configurations such as Kubernetes `kubeconfig` file path or content, and Terraform providers' AK/SK. More information can be found [here](4-workspace.md#secretstore). +Besides the `resources`, Spec also records the `secretStore` and `context` field in the corresponding workspace. The former can be used to access sensitive data stored in an external secrets manager, while the latter can be used to declare the workspace-level configurations such as Kubernetes `kubeconfig` file path or content, and Terraform providers' AK/SK. More information can be found [here](./4-workspace/1-overview.md#secretstore). ## Apply with Spec File -Kusion supports using the Spec file directly as input. Users can place the Spec file in the stack directory and execute `kusion preview --spec-file spec.yaml` and `kusion apply --spec-file spec.yaml` to preview and apply the resources. +When using the CLI, Kusion supports using the Spec file directly as input. Users can place the Spec file in the stack directory and execute `kusion preview --spec-file spec.yaml` and `kusion apply --spec-file spec.yaml` to preview and apply the resources. diff --git a/docs/kusion/3-concepts/7-backend/1-overview.md b/docs/kusion/3-concepts/7-backend/1-overview.md new file mode 100644 index 00000000..b51b78a1 --- /dev/null +++ b/docs/kusion/3-concepts/7-backend/1-overview.md @@ -0,0 +1,118 @@ +# Overview + +Backend is Kusion's storage, which defines the place to store Workspace and Release related files. By default, Kusion uses the `local` type of backend to store on the local disk. In the case of team collaboration, the Workspace and Release can be stored on a remote backend, such as an `AliCloud OSS Bucket` or an `AWS S3 bucket`, to enable simutaneous access from users. + +## Available Backend Types + +There are four available backend types: `local`, `oss`, `s3` and `google`. + +### local + +The `local` type backend uses local file system as storage, which is suitable for local operations, but not ideal for multi-user collaboration. The supported config items are as below. + +- **path**: `type string`, `optional`, specify the directory to store the Workspace and Release files. The subdirectories `workspaces` and `releases` are used to store the corresponding files separately. It's recommended to use an empty or a Kusion exclusive directory as the local backend path. If not set, the default path `${KUSION_HOME}` is in use. + +The whole local type backend configuration is as below. + +```yaml +{ + "type": "local", + "configs": { + "path": "${local_path}" # type string, optional, the directory to store files. + } +} +``` + +### oss + +The `oss` type backend uses the Alicloud Object Storage Service (OSS) as storage. The supported config items are as below. + +- **endpoint**: `type string`, `required`, specify the access endpoint for alicloud oss bucket. +- **accessKeyID**: `type string`, `required`, specify the alicloud account accessKeyID, support declaring by environment variable `OSS_ACCESS_KEY_ID`. +- **accessKeySecret**: `type string`, `required`, specify the alicloud account accessKeySecret, support declaring by environment variable `OSS_ACCESS_KEY_SECRET`. +- **bucket**: `type string`, `required`, specify the name of the alicloud oss bucket. +- **prefix**: `type string`, `optional`, constitute the prefix to store the Workspace and Release files, whose prefixes are `${prefix}/workspaces` and `${prefix}/releases` respectively. Using prefix can create a "dedicated space" for the Kusion data, which is beneficial for the management and reuse of the bucket. If not set, there is no prefix, the files are stored in the root path of the bucket if analogy to a file system. + +Noted that `accessKeyID` and `accessKeySecret` are required for the whole configuration combined by the configuration managed by the command `kusion config` and the environment variables. For the `kusion config` alone, they are not obligatory. And for the safety reason, using environment variables is the recommended way. + +The whole oss type backend configuration is as below. + +```yaml +{ + "type": "oss", + "configs": { + "endpoint": "${oss_endpoint}", # type string, required, the oss endpoint. + "accessKeyID": "${oss_access_key_id}", # type string, ooptional for the command "kusion config", the oss access key id. + "accessKeySecret": "${oss_access_key_secret}", # type string, optional for the command "kusion config", the oss access key secret. + "bucket": "${oss_bucket}", # type string, required, the oss bucket. + "prefix": "${oss_prefix}" # type string, optional, the prefix to store the files. + } +} +``` + +The supported environment variables are as below. + +```bash +export OSS_ACCESS_KEY_ID="${oss-access-key-id}" # configure accessKeyID +export OSS_ACCESS_KEY_SECRET="${oss-access-key-secret}" # configure accessKeySecret +``` + +### s3 + +The `s3` type backend uses the AWS Simple Storage Service (S3) as storage. The supported config items are as below. + +- **region**: `type string`, `required`, specify the region of aws s3 bucket, support declaring by environment variable `AWS_DEFAULT_REGION` or `AWS_REGION`, where the latter has higher priority. +- **endpoint**: `type string`, `optional`, specify the access endpoint for aws s3 bucket. +- **accessKeyID**: `type string`, `required`, specify the aws account accessKeyID, support declaring by environment variable `AWS_ACCESS_KEY_ID`. +- **accessKeySecret**: `type string`, `required`, specify the aws account.accessKeySecret, support declaring by environment variable `AWS_SECRET_ACCESS_KEY`. +- **bucket**: `type string`, `required`, specify the name of the aws s3 bucket. +- **prefix**: `type string`, `optional`, constitute the prefix to store the Workspace and Release files, whose prefixes are `${prefix}/workspaces` and `${prefix}/releases` respectively. + +Noted that `region`, `accessKeyID` and `accessKeySecret` are optional for the `kusion config` command. + +The whole s3 type backend configuration is as below. + +```yaml +{ + "type": "s3", + "configs": { + "region": "${s3_region}", # type string, optional for the command "kusion config", the aws region. + "endpoint": "${s3_endpoint}", # type string, optional, the aws endpoint. + "accessKeyID": "${s3_access_key_id}", # type string, optional for the command "kusion config", the aws access key id. + "accessKeySecret": "${s3_access_key_secret}", # type string, optional for the command "kusion config", the aws access key secret. + "bucket": "${s3_bucket}", # type string, required, the s3 bucket. + "prefix": "${s3_prefix}" # type string, optional, the prefix to store the files. + } +} +``` + +The supported environment variables are as below. + +```bash +export AWS_DEFAULT_REGION="${s3_region}" # configure region, lower priority than AWS_REGION +export AWS_REGION="${s3_region}" # configure region, higher priority than AWS_DEFAULT_REGION +export AWS_ACCESS_KEY_ID="${s3_access_key_id}" # configure accessKeyID +export AWS_SECRET_ACCESS_KEY="${s3_access_key_secret}" # configure accessKeySecret +``` + +### google cloud storage + +The `google` type backend uses the Google Cloud Storage as storage. The supported config items are as below. +- **bucket**: `type string`, `required`, specify the name of the google cloud storage bucket. +- **credentials**: `type string`, `required`, specify the content of the `credentials.json` file required to access the aforementioned bucket. + +```yaml +{ + "type":"google", + "configs":{ + "bucket":"kusion-kcp-gcp-backend", + "credentials":${content-from-credentials.json} + } +} +``` + +The supported environment variables are as below. + +```bash +export GOOGLE_CLOUD_CREDENTIALS="${content-from-credentials.json}" # configure credentials.json +``` \ No newline at end of file diff --git a/docs/kusion/3-concepts/7-backend/2-managing-backends-with-server.md b/docs/kusion/3-concepts/7-backend/2-managing-backends-with-server.md new file mode 100644 index 00000000..f7064e00 --- /dev/null +++ b/docs/kusion/3-concepts/7-backend/2-managing-backends-with-server.md @@ -0,0 +1,43 @@ +# Managing backends with Kusion Server + +When using Kusion server, backends are managed via the `/api/v1/backends` API. You can either access the APIs directly or if you have the Dev Portal enabled (`--dev-portal-enabled`, default to true), backends can be also managed via the portal. The backend configurations are also stored in the database when using Kusion server. + +## APIs + +The APIs to manage backends can be found in the swagger docs under `{server-endpoint}/docs/index.html#/backend`. + +## Developer Portal + +### Creating Backend + +Create a backend by clicking on the `Create Backend` button in the top right corner. + +![backend-create](/img/docs/concept/backend-create.png) + +The Backends are generally managed by the platform engineers. + +### Listing Backend + +List backends by clicking on the `Backend` tab. + +## Showing Backend + +Clicking on individual backend to display the backend configurations. + +![backend-details](/img/docs/concept/backend-details.png) + +## Updating Backend + +Update backends by clicking on the edit button on each backend. + +![backend-edit](/img/docs/concept/backend-edit.png) + +## Deleting Backend + +![backend-delete](/img/docs/concept/backend-delete.png) + +## Using Backend + +Backend is used when creating [Workspaces](../4-workspace/1-overview.md). When creating each workspace, a backend must be selected to represent the storage to keep the workspace related configurations. + +![workspace-select-backend](/img/docs/concept/workspace-select-backend.png) \ No newline at end of file diff --git a/docs/kusion/3-concepts/7-backend.md b/docs/kusion/3-concepts/7-backend/3-managing-backends-with-cli.md similarity index 50% rename from docs/kusion/3-concepts/7-backend.md rename to docs/kusion/3-concepts/7-backend/3-managing-backends-with-cli.md index 5262f7ac..36687c1e 100644 --- a/docs/kusion/3-concepts/7-backend.md +++ b/docs/kusion/3-concepts/7-backend/3-managing-backends-with-cli.md @@ -1,109 +1,8 @@ ---- -id: backend -sidebar_label: Backends ---- - -# Backend - -Backend is Kusion's storage, which defines the place to store Workspace and Release. By default, Kusion uses the `local` type of backend to store on the local disk. While in the scenario of team collaboration, the Workspace and Release can be stored on a remote backend, such as `oss` and `s3`, to allow multiple users' access. +# Managing backends with Kusion CLI The command `kusion config` is used to configure the backend configuration. Configuring a whole backend or an individual config item are both supported. For the sensitive data, the environment variables are supported, and with higher priority. -Furthermore, Kusion provides the operation of setting current backend. Thus, the trouble of specifying backend can be saved when executing operation commands and managing `workspace`. - -## Available Backend Types - -There are three available backend types: `local`, `oss`, `s3`. - -### local - -The `local` type backend uses local file system as storage, which is suitable for local operations, but not ideal for multi-user collaboration. The supported config items are as below. - -- **path**: `type string`, `optional`, specify the directory to store the Workspace and Release files. The subdirectories `workspaces` and `releases` are used to store the corresponding files separately. It's recommended to use an empty or a Kusion exclusive directory as the local backend path. If not set, the default path `${KUSION_HOME}` is in use. - -The whole local type backend configuration is as below. - -```yaml -{ - "type": "local", - "configs": { - "path": "${local_path}" # type string, optional, the directory to store files. - } -} -``` - -### oss - -The `oss` type backend uses the Alicloud Object Storage Service (OSS) as storage. The supported config items are as below. - -- **endpoint**: `type string`, `required`, specify the access endpoint for alicloud oss bucket. -- **accessKeyID**: `type string`, `required`, specify the alicloud account accessKeyID, support declaring by environment variable `OSS_ACCESS_KEY_ID`. -- **accessKeySecret**: `type string`, `required`, specify the alicloud account accessKeySecret, support declaring by environment variable `OSS_ACCESS_KEY_SECRET`. -- **bucket**: `type string`, `required`, specify the name of the alicloud oss bucket. -- **prefix**: `type string`, `optional`, constitute the prefix to store the Workspace and Release files, whose prefixes are `${prefix}/workspaces` and `${prefix}/releases` respectively. Using prefix can create a "dedicated space" for the Kusion data, which is beneficial for the management and reuse of the bucket. If not set, there is no prefix, the files are stored in the root path of the bucket if analogy to a file system. - -Noted that `accessKeyID` and `accessKeySecret` are required for the whole configuration combined by the configuration managed by the command `kusion config` and the environment variables. For the `kusion config` alone, they are not obligatory. And for the safety reason, using environment variables is the recommended way. - -The whole oss type backend configuration is as below. - -```yaml -{ - "type": "oss", - "configs": { - "endpoint": "${oss_endpoint}", # type string, required, the oss endpoint. - "accessKeyID": "${oss_access_key_id}", # type string, ooptional for the command "kusion config", the oss access key id. - "accessKeySecret": "${oss_access_key_secret}", # type string, optional for the command "kusion config", the oss access key secret. - "bucket": "${oss_bucket}", # type string, required, the oss bucket. - "prefix": "${oss_prefix}" # type string, optional, the prefix to store the files. - } -} -``` - -The supported environment variables are as below. - -```bash -export OSS_ACCESS_KEY_ID="${oss-access-key-id}" # configure accessKeyID -export OSS_ACCESS_KEY_SECRET="${oss-access-key-secret}" # configure accessKeySecret -``` - -### s3 - -The `s3` type backend uses the AWS Simple Storage Service (S3) as storage. The supported config items are as below. - -- **region**: `type string`, `required`, specify the region of aws s3 bucket, support declaring by environment variable `AWS_DEFAULT_REGION` or `AWS_REGION`, where the latter has higher priority. -- **endpoint**: `type string`, `optional`, specify the access endpoint for aws s3 bucket. -- **accessKeyID**: `type string`, `required`, specify the aws account accessKeyID, support declaring by environment variable `AWS_ACCESS_KEY_ID`. -- **accessKeySecret**: `type string`, `required`, specify the aws account.accessKeySecret, support declaring by environment variable `AWS_SECRET_ACCESS_KEY`. -- **bucket**: `type string`, `required`, specify the name of the aws s3 bucket. -- **prefix**: `type string`, `optional`, constitute the prefix to store the Workspace and Release files, whose prefixes are `${prefix}/workspaces` and `${prefix}/releases` respectively. - -Noted that `region`, `accessKeyID` and `accessKeySecret` are optional for the `kusion config` command. - -The whole s3 type backend configuration is as below. - -```yaml -{ - "type": "s3", - "configs": { - "region": "${s3_region}", # type string, optional for the command "kusion config", the aws region. - "endpoint": "${s3_endpoint}", # type string, optional, the aws endpoint. - "accessKeyID": "${s3_access_key_id}", # type string, optional for the command "kusion config", the aws access key id. - "accessKeySecret": "${s3_access_key_secret}", # type string, optional for the command "kusion config", the aws access key secret. - "bucket": "${s3_bucket}", # type string, required, the s3 bucket. - "prefix": "${s3_prefix}" # type string, optional, the prefix to store the files. - } -} -``` - -The supported environment variables are as below. - -```bash -export AWS_DEFAULT_REGION="${s3_region}" # configure region, lower priority than AWS_REGION -export AWS_REGION="${s3_region}" # configure region, higher priority than AWS_DEFAULT_REGION -export AWS_ACCESS_KEY_ID="${s3_access_key_id}" # configure accessKeyID -export AWS_SECRET_ACCESS_KEY="${s3_access_key_secret}" # configure accessKeySecret -``` - +Furthermore, Kusion CLI provides the operation of setting current backend. Thus, the trouble of specifying backend can be saved when executing operation commands and managing `workspace`. ## Setting a Backend @@ -188,7 +87,7 @@ Setting the current backend to `default` is legal. Actually, if there is no back ## Getting Backend Configuration -Use the command `kusion config get ${key}` to get a whole backend configuration or a specified backend config item. The `key` is same as setting and unsetting operation, the whole list can be found in the [Configuration](configuration). +Use the command `kusion config get ${key}` to get a whole backend configuration or a specified backend config item. The `key` is same as setting and unsetting operation, the whole list can be found in the [Configuration](../11-cli-configuration.md). ```shell # get a whole backend diff --git a/docs/kusion/3-concepts/7-backend/_category_.json b/docs/kusion/3-concepts/7-backend/_category_.json new file mode 100644 index 00000000..c24bf98e --- /dev/null +++ b/docs/kusion/3-concepts/7-backend/_category_.json @@ -0,0 +1,3 @@ +{ + "label": "Backends" +} diff --git a/docs/kusion/3-concepts/8-release.md b/docs/kusion/3-concepts/8-release.md new file mode 100644 index 00000000..6f1096b1 --- /dev/null +++ b/docs/kusion/3-concepts/8-release.md @@ -0,0 +1,28 @@ +--- +id: release +sidebar_label: Releases +--- + +# Release + +Release is used to indicate a single operation, triggered only by `apply` and `destroy`, providing users with a more coherent and consistent operation experience with Kusion. Release also provides audit and rollback capabilities, which is currently under development. + +Every time an `apply` or `destroy` operation is executed, it will trigger the generation of a `release` file. The combination of a `project` and `workspace` corresponds to a set of `release` files, which also relates to a set of the real application resources. The `release` file is stored in the same `backend` as the `workspace`, and the default path is `releases/$PROJECT_NAME/$WORKSPACE_NAME`, whose revision starts from 1 and increments. + +:::tip +For kusion server, the default release path is `releases/server/$SOURCE_NAME/$PROJECT_NAME/$WORKSPACE_NAME` +::: + +The release file contains the [Spec](./6-specs.md) and [State](./8-release.md#state) of an application, both of which are composed of `Resources`, representing the expected description from the configuration code and the actual state of the resources respectively. In addition, the release file also contains the information of creation and modification time, operation phase, and application metadata, etc. + +## State + +State is a record of an operation's result. It is a mapping between `resources` managed by `Kusion` and the actual infra resources. State is often used as a data source for three-way merge/diff in operations like `Apply` and `Preview`. + +A `resource` here represents an individual unit of infrastructure or application component, serving as a fundamental building block for defining and managing the actual state of your `project`. These `resources` are defined within the `State` and accurately reflect the actual states of the infrastructure. By providing a unified and consistent approach, `Kusion` enables seamless management of diverse resource types, encompassing Kubernetes objects and Terraform resources.Importantly, the structure of these resources in the `State` mirrors that of the `resources` in the `Spec`, ensuring coherence and facilitating efficient state management throughout the lifecycle of your `project`. + +State can be stored in many storage [backend](./7-backend/1-overview.md) mediums like filesystems, S3, and OSS, etc. + +## Concurrency Control + +Release supports collaboration among multiple users and implements the concurrency control through operation `phase`. When the field of `phase` in the release file is not `succeeded` or `failed`, kusion will not be able to execute `apply` or `destroy` operation to the corresponding stack. For example, if a user unexpectedly exits during the `apply` or `destroy` process, the `phase` of the release file may be kept as `applying` or `destroying`. In this case, the user can use the command of `kusion release unlock` to unlock the release file for a specified application and workspace, setting the `phase` to `failed`. diff --git a/docs/kusion/3-concepts/9-release.md b/docs/kusion/3-concepts/9-release.md deleted file mode 100644 index 05f27f71..00000000 --- a/docs/kusion/3-concepts/9-release.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -id: release -sidebar_label: Releases ---- - -# Release - -Release is used to indicate a single operation, triggered by `kusion apply` and `kusion destroy`, providing users with a more coherent and consistent operation experience with Kusion. Release also provides audit and rollback capabilities, which is currently under development. - -Every time `kusion apply` or `kusion destroy` is executed, it will trigger the generation of a `release` file. The combination of a `project` and `workspace` corresponds to a set of `release` files, which also relates to a set of the real application resources. The `release` file is stored in the same `backend` as the `workspace`, and the default path is `$HOME/.kusion/releases/$PROJECT_NAME/$WORKSPACE_NAME`, whose revision starts from 1 and increments. - -The release file contains the [Spec](./6-spec.md) and [State](./9-release.md#state) of an application, both of which are composed of `Resources`, representing the expected description from the configuration code and the actual state of the resources respectively. In addition, the release file also contains the information of creation and modification time, operation phase, and application metadata, etc. - -## State - -State is a record of an operation's result. It is a mapping between `resources` managed by `Kusion` and the actual infra resources. State is often used as a data source for three-way merge/diff in operations like `Apply` and `Preview`. - -A `resource` here represents an individual unit of infrastructure or application component, serving as a fundamental building block for defining and managing the actual state of your `project`. These `resources` are defined within the `State` and accurately reflect the actual states of the infrastructure. By providing a unified and consistent approach, `Kusion` enables seamless management of diverse resource types, encompassing Kubernetes objects and Terraform resources.Importantly, the structure of these resources in the `State` mirrors that of the `resources` in the `Spec`, ensuring coherence and facilitating efficient state management throughout the lifecycle of your `project`. - -State can be stored in many storage [backend](./7-backend.md) mediums like filesystems, S3, and OSS, etc. - -## Concurrency Control - -Release supports collaboration among multiple users and implements the concurrency control through operation `phase`. When the field of `phase` in the release file is not `succeeded` or `failed`, kusion will not be able to execute `kusion apply` or `kusion destroy` operation to the corresponding stack. For example, if a user unexpectedly exits during the `kusion apply` or `kusion destroy` process, the `phase` of the release file may be kept as `applying` or `destroying`. In this case, the user can use the command of `kusion release unlock` to unlock the release file for a specified application and workspace, setting the `phase` to `failed`. diff --git a/docs/kusion/3-concepts/9-runs.md b/docs/kusion/3-concepts/9-runs.md new file mode 100644 index 00000000..63194132 --- /dev/null +++ b/docs/kusion/3-concepts/9-runs.md @@ -0,0 +1,50 @@ +# Runs + +:::tip +Run is a concept only applicable in Kusion server. +::: + +A `Run` represents an operation performed on a given [Stack](./2-stack/1-overview.md) to a target [workspace](./4-workspace/1-overview.md). + +## APIs + +The APIs to manage runs can be found in the swagger docs under `{server-endpoint}/docs/index.html#/run`. + +:::tip +Please note that in the case of APIs the runs APIs are asynchronous. An external system interacting with runs API is expected to query the status of runs on a polling basis. +::: + +## Types of Runs + +There are 4 types of runs: + +- Generate: Generate the resource-facing desired state, or [Spec](./6-specs.md) for the given stack and workspace +- Preview: Preview the resource changes for the given stack and workspace based on the difference between desired state and current state +- Apply: Apply the desired state to the target workspace +- Destroy: Destroy the resources for the given stack in the target workspace + +## Run History + +- Run history are persisted in Kusion Server. To check all runs for a given stack, click on the `Project` tab, select a project, click on the stack tab, then select the Runs tab to locate all runs for this stack. + +![run-history](/img/docs/concept/run-history.png) + +## Run Results and Logs + +- Each run persisted also includes the run result and its corresponding logs. + +The run result may differ based on the different types of runs: + +- `Generate` runs yield a `Spec` in the YAML format on success. +![generate-result](/img/docs/concept/generate-result.png) + +- `Preview` runs yield a structured json that represents the resource changes calculated based on desired state and current state. In the case of a developer portal, this is visualized with a left-right comparison. +![preview-result](/img/docs/concept/preview-result.png) + +- `Apply` and `Destroy` runs produces a message that says "apply/destroy completed". + +The run logs are used for troubleshooting in case of any errors during the run. + +## Exception Handling + +Kusion workflow includes the execution of out-of-tree go-plugins in the form of [Kusion Module](../3-concepts/3-module/1-overview.md) Generators. If any of the plugin code causes a panic, the stack trace is expected to be printed in the run log for closer examination. \ No newline at end of file diff --git a/docs/kusion/4-configuration-walkthrough/1-overview.md b/docs/kusion/4-configuration-walkthrough/1-overview.md index 7c19c7b3..3a4916a8 100644 --- a/docs/kusion/4-configuration-walkthrough/1-overview.md +++ b/docs/kusion/4-configuration-walkthrough/1-overview.md @@ -68,7 +68,7 @@ The schema for `AppConfiguration` is defined in the [KusionStack/kam](https://gi `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). +For more details on the `AppConfiguration`, please refer to the [design documentation](../concepts/appconfigurations). ## Authoring Configuration Files diff --git a/docs/kusion/4-configuration-walkthrough/8-monitoring.md b/docs/kusion/4-configuration-walkthrough/8-monitoring.md index 9141a8af..c3dbf04c 100644 --- a/docs/kusion/4-configuration-walkthrough/8-monitoring.md +++ b/docs/kusion/4-configuration-walkthrough/8-monitoring.md @@ -30,7 +30,7 @@ In the event that they do not exist for you or your organization, e.g. if you ar :::info -For more details on how workspaces work, please refer to the [workspace concept](../3-concepts/4-workspace.md) +For more details on how workspaces work, please refer to the [workspace concept](../3-concepts/4-workspace/1-overview.md) ::: By separating configurations that the developers are interested in and those that platform owners are interested in, we can reduce the cognitive complexity of the application configuration and achieve separation of concern. diff --git a/docs/kusion/5-user-guides/1-using-kusion-cli/1-cloud-resources/1-database.md b/docs/kusion/5-user-guides/1-using-kusion-cli/1-cloud-resources/1-database.md index 5ca028a3..613b01bf 100644 --- a/docs/kusion/5-user-guides/1-using-kusion-cli/1-cloud-resources/1-database.md +++ b/docs/kusion/5-user-guides/1-using-kusion-cli/1-cloud-resources/1-database.md @@ -125,7 +125,7 @@ kusion workspace show The `workspace.yaml` is a sample configuration file for workspace management, including `MySQL` module configs. Workspace configurations are usually declared by **Platform Engineers** and will take effect through the corresponding stack. :::info -More details about the configuration of Workspace can be found in [Concepts of Workspace](../../../3-concepts/4-workspace.md). +More details about the configuration of Workspace can be found in [Concepts of Workspace](../../../3-concepts/4-workspace/1-overview.md). ::: ## Create Project And Stack diff --git a/docs/kusion/5-user-guides/1-using-kusion-cli/2-working-with-k8s/1-deploy-application.md b/docs/kusion/5-user-guides/1-using-kusion-cli/2-working-with-k8s/1-deploy-application.md index 92504641..df283a11 100644 --- a/docs/kusion/5-user-guides/1-using-kusion-cli/2-working-with-k8s/1-deploy-application.md +++ b/docs/kusion/5-user-guides/1-using-kusion-cli/2-working-with-k8s/1-deploy-application.md @@ -44,7 +44,7 @@ This guide is to deploy an app using Kusion, relying on the Kusion CLI and an ex ### Initializing workspace configuration -In version 0.10.0, we have introduced the new concept of [workspaces](../../../3-concepts/4-workspace.md), which is a logical layer whose configurations represent an opinionated set of defaults, often appointed by the platform team. In most cases workspaces are represented with an "environment" in traditional SDLC terms. These workspaces provide a means to separate the concerns between the **application developers** who wish to focus on business logic, and a group of **platform engineers** who wish to standardize the applications on the platform. +In version 0.10.0, we have introduced the new concept of [workspaces](../../../3-concepts/4-workspace/1-overview.md), which is a logical layer whose configurations represent an opinionated set of defaults, often appointed by the platform team. In most cases workspaces are represented with an "environment" in traditional SDLC terms. These workspaces provide a means to separate the concerns between the **application developers** who wish to focus on business logic, and a group of **platform engineers** who wish to standardize the applications on the platform. Driven by the discipline of Platform Engineering, management of the workspaces, including create/updating/deleting workspaces and their configurations should be done by dedicated platform engineers in a large software organizations to facilitate a more mature and scalable collaboration pattern. diff --git a/docs/kusion/5-user-guides/1-using-kusion-cli/3-observability/1-prometheus.md b/docs/kusion/5-user-guides/1-using-kusion-cli/3-observability/1-prometheus.md index 3d9d2f9c..d1dddc13 100644 --- a/docs/kusion/5-user-guides/1-using-kusion-cli/3-observability/1-prometheus.md +++ b/docs/kusion/5-user-guides/1-using-kusion-cli/3-observability/1-prometheus.md @@ -137,7 +137,7 @@ If you are running a non-local cluster, you can try to expose it via another way ## Setting up workspace configs -Since v0.10.0, we have introduced the concept of [workspaces](../../../3-concepts/4-workspace.md), whose configurations represent the part of the application behaviors that platform teams are interested in standardizing, or the ones to eliminate from developer's mind to make their lives easier. +Since v0.10.0, we have introduced the concept of [workspaces](../../../3-concepts/4-workspace/1-overview.md), whose configurations represent the part of the application behaviors that platform teams are interested in standardizing, or the ones to eliminate from developer's mind to make their lives easier. In the case of setting up Prometheus, there are a few things to set up on the workspace level: diff --git a/docs/kusion/5-user-guides/1-using-kusion-cli/4-secrets-management/1-using-cloud-secrets.md b/docs/kusion/5-user-guides/1-using-kusion-cli/4-secrets-management/1-using-cloud-secrets.md index 02681041..6d0afce4 100644 --- a/docs/kusion/5-user-guides/1-using-kusion-cli/4-secrets-management/1-using-cloud-secrets.md +++ b/docs/kusion/5-user-guides/1-using-kusion-cli/4-secrets-management/1-using-cloud-secrets.md @@ -25,7 +25,7 @@ export AWS_SECRET_ACCESS_KEY="oE/xxxx" # replace it with your SecretKey ## Setting up workspace -Since v0.10.0, we have introduced the concept of [workspaces](../../../3-concepts/4-workspace.md), whose configurations represent the part of the application behaviors that platform teams are interested in standardizing, or the ones to eliminate from developer's mind to make their lives easier. +Since v0.10.0, we have introduced the concept of [workspaces](../../../3-concepts/4-workspace/1-overview.md), whose configurations represent the part of the application behaviors that platform teams are interested in standardizing, or the ones to eliminate from developer's mind to make their lives easier. In the case of setting up cloud secrets manager, platform teams need to specify which secrets management solution to use and necessary information to access on the workspace level. diff --git a/docs/kusion/5-user-guides/1-using-kusion-cli/5-production-practice-case/1-production-practice-case.md b/docs/kusion/5-user-guides/1-using-kusion-cli/5-production-practice-case/1-production-practice-case.md index 6433d11c..9672cd55 100644 --- a/docs/kusion/5-user-guides/1-using-kusion-cli/5-production-practice-case/1-production-practice-case.md +++ b/docs/kusion/5-user-guides/1-using-kusion-cli/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-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/1-overview.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/1-overview.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. @@ -70,7 +70,7 @@ So far, PE has almost completed the fundamental work for setting up the IDP. ### Setup Kusion Storage Backend -In order to get the available modules of the workspace and validate the generated [spec](../../../3-concepts/6-spec.md), developers need to communicate with PEs to obtain the AK/SK (usually with **Read-Only** permission), bucket name, and the endpoint to access the remote storage backend. And similar to the PEs, developers can set up the backend configs with the following commands. +In order to get the available modules of the workspace and validate the generated [spec](../../../3-concepts/6-specs.md), developers need to communicate with PEs to obtain the AK/SK (usually with **Read-Only** permission), bucket name, and the endpoint to access the remote storage backend. And similar to the PEs, developers can set up the backend configs with the following commands. ```shell # please replace the env with actual AK/SK diff --git a/static/img/docs/concept/app-resource-graph-detail.png b/static/img/docs/concept/app-resource-graph-detail.png new file mode 100644 index 00000000..79ef92a0 Binary files /dev/null and b/static/img/docs/concept/app-resource-graph-detail.png differ diff --git a/static/img/docs/concept/app-resource-graph.png b/static/img/docs/concept/app-resource-graph.png new file mode 100644 index 00000000..9a3bc82d Binary files /dev/null and b/static/img/docs/concept/app-resource-graph.png differ diff --git a/static/img/docs/concept/backend-create.png b/static/img/docs/concept/backend-create.png new file mode 100644 index 00000000..429ca464 Binary files /dev/null and b/static/img/docs/concept/backend-create.png differ diff --git a/static/img/docs/concept/backend-delete.png b/static/img/docs/concept/backend-delete.png new file mode 100644 index 00000000..9c90e80e Binary files /dev/null and b/static/img/docs/concept/backend-delete.png differ diff --git a/static/img/docs/concept/backend-details.png b/static/img/docs/concept/backend-details.png new file mode 100644 index 00000000..a99326ec Binary files /dev/null and b/static/img/docs/concept/backend-details.png differ diff --git a/static/img/docs/concept/backend-edit.png b/static/img/docs/concept/backend-edit.png new file mode 100644 index 00000000..2275e09a Binary files /dev/null and b/static/img/docs/concept/backend-edit.png differ diff --git a/static/img/docs/concept/backend-type.png b/static/img/docs/concept/backend-type.png new file mode 100644 index 00000000..ee8521f0 Binary files /dev/null and b/static/img/docs/concept/backend-type.png differ diff --git a/static/img/docs/concept/generate-kcl-mod.png b/static/img/docs/concept/generate-kcl-mod.png new file mode 100644 index 00000000..4cfbf635 Binary files /dev/null and b/static/img/docs/concept/generate-kcl-mod.png differ diff --git a/static/img/docs/concept/generate-result.png b/static/img/docs/concept/generate-result.png new file mode 100644 index 00000000..cc7fd909 Binary files /dev/null and b/static/img/docs/concept/generate-result.png differ diff --git a/static/img/docs/concept/intent-flow.png b/static/img/docs/concept/intent-flow.png new file mode 100644 index 00000000..37096ba3 Binary files /dev/null and b/static/img/docs/concept/intent-flow.png differ diff --git a/static/img/docs/concept/kcl-mod-generated.png b/static/img/docs/concept/kcl-mod-generated.png new file mode 100644 index 00000000..a7877fec Binary files /dev/null and b/static/img/docs/concept/kcl-mod-generated.png differ diff --git a/static/img/docs/concept/module-create.png b/static/img/docs/concept/module-create.png new file mode 100644 index 00000000..bff80ece Binary files /dev/null and b/static/img/docs/concept/module-create.png differ diff --git a/static/img/docs/concept/module-delete.png b/static/img/docs/concept/module-delete.png new file mode 100644 index 00000000..1cb681b8 Binary files /dev/null and b/static/img/docs/concept/module-delete.png differ diff --git a/static/img/docs/concept/module-details.png b/static/img/docs/concept/module-details.png new file mode 100644 index 00000000..402797ac Binary files /dev/null and b/static/img/docs/concept/module-details.png differ diff --git a/static/img/docs/concept/module-edit.png b/static/img/docs/concept/module-edit.png new file mode 100644 index 00000000..097f004d Binary files /dev/null and b/static/img/docs/concept/module-edit.png differ diff --git a/static/img/docs/concept/platform-orchestrator.png b/static/img/docs/concept/platform-orchestrator.png new file mode 100644 index 00000000..11838a7a Binary files /dev/null and b/static/img/docs/concept/platform-orchestrator.png differ diff --git a/static/img/docs/concept/preview-result.png b/static/img/docs/concept/preview-result.png new file mode 100644 index 00000000..fe2f1714 Binary files /dev/null and b/static/img/docs/concept/preview-result.png differ diff --git a/static/img/docs/concept/run-history.png b/static/img/docs/concept/run-history.png new file mode 100644 index 00000000..c0790b92 Binary files /dev/null and b/static/img/docs/concept/run-history.png differ diff --git a/static/img/docs/concept/workspace-configurations.png b/static/img/docs/concept/workspace-configurations.png new file mode 100644 index 00000000..ba53ea13 Binary files /dev/null and b/static/img/docs/concept/workspace-configurations.png differ diff --git a/static/img/docs/concept/workspace-create-new.png b/static/img/docs/concept/workspace-create-new.png new file mode 100644 index 00000000..bc0f6789 Binary files /dev/null and b/static/img/docs/concept/workspace-create-new.png differ diff --git a/static/img/docs/concept/workspace-delete.png b/static/img/docs/concept/workspace-delete.png new file mode 100644 index 00000000..b5b42909 Binary files /dev/null and b/static/img/docs/concept/workspace-delete.png differ diff --git a/static/img/docs/concept/workspace-edit.png b/static/img/docs/concept/workspace-edit.png new file mode 100644 index 00000000..e6f37730 Binary files /dev/null and b/static/img/docs/concept/workspace-edit.png differ diff --git a/static/img/docs/concept/workspace-select-backend.png b/static/img/docs/concept/workspace-select-backend.png new file mode 100644 index 00000000..beeccb48 Binary files /dev/null and b/static/img/docs/concept/workspace-select-backend.png differ diff --git a/static/img/docs/concept/workspace-select.png b/static/img/docs/concept/workspace-select.png new file mode 100644 index 00000000..bdc17627 Binary files /dev/null and b/static/img/docs/concept/workspace-select.png differ