From 4da3c722a5d7d40f801dc9d12aecd07b032dcf51 Mon Sep 17 00:00:00 2001 From: Jianbo Sun Date: Wed, 18 May 2022 17:54:48 +0800 Subject: [PATCH] refine docs structure Signed-off-by: Jianbo Sun --- ...n-open-application-model-and-kubernetes.md | 2 +- blog/2021-09-02-kubevela-jenkins-cicd.md | 4 +- blog/2021-10-08-blog-1.1.md | 2 +- blog/2021-10-10-kubevela-gitops.md | 2 +- blog/2022-01-27-blog-1.2.md | 2 +- ...22-03-02-kubevela-with-machine-learning.md | 2 +- blog/2022-03-27-kubevela-with-nocalhost.md | 2 +- .../2022-04-01-offline-deployment-practice.md | 2 +- blog/2022-04-06-multi-cluster-management.md | 2 +- blog/2022-04-24-blog-1.3.md | 2 +- docs/getting-started/architecture.md | 10 +- docs/tutorials/webservice.md | 26 ++- .../platform-engineers/traits/patch-trait.md | 99 ++++++++++- sidebars.js | 54 +++--- .../getting-started/architecture.md | 10 +- .../platform-engineers/traits/patch-trait.md | 101 ++++++++++- .../version-v1.3/tutorials/webservice.md | 26 ++- versioned_sidebars/version-v1.3-sidebars.json | 162 +++++++++--------- 18 files changed, 332 insertions(+), 178 deletions(-) diff --git a/blog/2020-12-7-kubevela-the-extensible-app-platform-based-on-open-application-model-and-kubernetes.md b/blog/2020-12-7-kubevela-the-extensible-app-platform-based-on-open-application-model-and-kubernetes.md index 0ebf44f5..957929df 100644 --- a/blog/2020-12-7-kubevela-the-extensible-app-platform-based-on-open-application-model-and-kubernetes.md +++ b/blog/2020-12-7-kubevela-the-extensible-app-platform-based-on-open-application-model-and-kubernetes.md @@ -4,7 +4,7 @@ author: Lei Zhang and Fei Guo author_title: CNCF TOC Member/Kubernetes author_url: https://github.com/JoelMarcey author_image_url: https://avatars.githubusercontent.com/u/1701782?s=200&v=4 -tags: [ KubeVela ] +tags: [ KubeVela, release-note ] description: The Extensible App Platform Based on Open Application Model and Kubernetes image: https://tva1.sinaimg.cn/large/ad5fbf65gy1glgj5q8inej208g049aa6.jpg hide_table_of_contents: false diff --git a/blog/2021-09-02-kubevela-jenkins-cicd.md b/blog/2021-09-02-kubevela-jenkins-cicd.md index 24be8e8b..a9d1f399 100644 --- a/blog/2021-09-02-kubevela-jenkins-cicd.md +++ b/blog/2021-09-02-kubevela-jenkins-cicd.md @@ -1,10 +1,10 @@ --- -title: Using Jenkins + KubeVela for Application Continuous Delivery +title: "Using Jenkins + KubeVela for Application Continuous Delivery" author: Da Yin, Yang Song author_title: KubeVela Team author_url: https://github.com/kubevela/kubevela author_image_url: https://kubevela.io/img/logo.svg -tags: [ KubeVela ] +tags: [ KubeVela, "use-case" ] description: "" image: https://raw.githubusercontent.com/kubevela/kubevela.io/main/docs/resources/KubeVela-03.png hide_table_of_contents: false diff --git a/blog/2021-10-08-blog-1.1.md b/blog/2021-10-08-blog-1.1.md index 2416f02c..b9a9293a 100644 --- a/blog/2021-10-08-blog-1.1.md +++ b/blog/2021-10-08-blog-1.1.md @@ -4,7 +4,7 @@ author: KubeVela Maintainers author_title: KubeVela Team author_url: https://github.com/kubevela/kubevela author_image_url: https://kubevela.io/img/logo.svg -tags: [ DevOps ] +tags: [ DevOps, release-note ] description: "" hide_table_of_contents: false --- diff --git a/blog/2021-10-10-kubevela-gitops.md b/blog/2021-10-10-kubevela-gitops.md index 88999296..436e7904 100644 --- a/blog/2021-10-10-kubevela-gitops.md +++ b/blog/2021-10-10-kubevela-gitops.md @@ -4,7 +4,7 @@ author: Tianxin Dong author_title: KubeVela Team author_url: https://github.com/kubevela/kubevela author_image_url: https://kubevela.io/img/logo.svg -tags: [ KubeVela ] +tags: [ KubeVela, "use-case" ] description: "" image: https://raw.githubusercontent.com/kubevela/kubevela.io/main/docs/resources/KubeVela-03.png hide_table_of_contents: false diff --git a/blog/2022-01-27-blog-1.2.md b/blog/2022-01-27-blog-1.2.md index 88b5db4b..1ee083f5 100644 --- a/blog/2022-01-27-blog-1.2.md +++ b/blog/2022-01-27-blog-1.2.md @@ -4,7 +4,7 @@ author: KubeVela Maintainers author_title: KubeVela Team author_url: https://github.com/kubevela/kubevela author_image_url: https://kubevela.io/img/logo.svg -tags: [ DevOps ] +tags: [ DevOps, release-note ] description: "" hide_table_of_contents: false --- diff --git a/blog/2022-03-02-kubevela-with-machine-learning.md b/blog/2022-03-02-kubevela-with-machine-learning.md index feb7ab62..6a2bd917 100644 --- a/blog/2022-03-02-kubevela-with-machine-learning.md +++ b/blog/2022-03-02-kubevela-with-machine-learning.md @@ -4,7 +4,7 @@ author: Tianxin Dong author_title: KubeVela team author_url: https://github.com/kubevela/kubevela author_image_url: https://kubevela.io/img/logo.svg -tags: [ KubeVela ] +tags: [ KubeVela, "use-case" ] description: "" image: https://raw.githubusercontent.com/kubevela/kubevela.io/main/docs/resources/KubeVela-03.png hide_table_of_contents: false diff --git a/blog/2022-03-27-kubevela-with-nocalhost.md b/blog/2022-03-27-kubevela-with-nocalhost.md index f76ac379..25e24e5d 100644 --- a/blog/2022-03-27-kubevela-with-nocalhost.md +++ b/blog/2022-03-27-kubevela-with-nocalhost.md @@ -4,7 +4,7 @@ author: Tianxin Dong and Yicai Yu author_title: KubeVela and Nocalhost team author_url: https://github.com/kubevela/kubevela author_image_url: https://kubevela.io/img/logo.svg -tags: [ kubevela ] +tags: [ kubevela, "use-case" ] description: "" image: https://raw.githubusercontent.com/kubevela/kubevela.io/main/docs/resources/KubeVela-03.png hide_table_of_contents: false diff --git a/blog/2022-04-01-offline-deployment-practice.md b/blog/2022-04-01-offline-deployment-practice.md index 6ac7e04a..6fadb8f0 100644 --- a/blog/2022-04-01-offline-deployment-practice.md +++ b/blog/2022-04-01-offline-deployment-practice.md @@ -4,7 +4,7 @@ author: Xiangbo Ma author_title: (Cloud platform development team) author_url: http://www.cmbchina.com/ author_image_url: /img/china-merchants-bank.jpg -tags: [ KubeVela ] +tags: [ KubeVela , "use-case"] description: "" image: https://raw.githubusercontent.com/oam-dev/KubeVela.io/main/docs/resources/KubeVela-03.png hide_table_of_contents: false diff --git a/blog/2022-04-06-multi-cluster-management.md b/blog/2022-04-06-multi-cluster-management.md index fe136390..e4f70c54 100644 --- a/blog/2022-04-06-multi-cluster-management.md +++ b/blog/2022-04-06-multi-cluster-management.md @@ -4,7 +4,7 @@ author: Wei Duan author_title: KubeVela Team author_url: https://github.com/kubevela/kubevela author_image_url: https://KubeVela.io/img/logo.svg -tags: [ KubeVela ] +tags: [ KubeVela, "use-case" ] description: "" image: https://raw.githubusercontent.com/oam-dev/KubeVela.io/main/docs/resources/KubeVela-03.png hide_table_of_contents: false diff --git a/blog/2022-04-24-blog-1.3.md b/blog/2022-04-24-blog-1.3.md index 0af7aee7..1fb4605d 100644 --- a/blog/2022-04-24-blog-1.3.md +++ b/blog/2022-04-24-blog-1.3.md @@ -4,7 +4,7 @@ author: KubeVela Community author_title: KubeVela Team author_url: https://github.com/kubevela/KubeVela author_image_url: https://KubeVela.io/img/logo.svg -tags: [ KubeVela ] +tags: [ KubeVela, release-note ] description: "" image: https://raw.githubusercontent.com/oam-dev/KubeVela.io/main/docs/resources/KubeVela-03.png hide_table_of_contents: false diff --git a/docs/getting-started/architecture.md b/docs/getting-started/architecture.md index 3cb1792b..2dcc177f 100644 --- a/docs/getting-started/architecture.md +++ b/docs/getting-started/architecture.md @@ -8,7 +8,7 @@ The overall architecture of KubeVela is shown as below: ## KubeVela is a Control Plane System -KubeVela orchestrates application components, cloud resources and pipeline over multiple clusters and hybrid environments. It is designed to be an application delivery and management control plane instead of a runtime plugin. +KubeVela orchestrates application components, cloud resources and pipeline over multiple clusters and hybrid environments. It is designed to be an application delivery and operation control plane instead of a runtime plugin. For easy integration with upstream CI pipelines and GitOps tools, KubeVela API (i.e. Open Application Model) are designed as declarative and application-centric, including: @@ -21,7 +21,7 @@ For easy integration with upstream CI pipelines and GitOps tools, KubeVela API ( In implementation, KubeVela relies on a dedicated Kubernetes cluster to achieve above goals. We chose to rely on Kubernetes as the control plane implementation because this approach is battle tested and brings determinism, convergence and automation to application management at scale. In detail, KubeVela is composed by several parts: - _KubeVela Core Controller_ that provides the core control logic of the entire system. For example, handling KubeVela API resources, orchestrating workflow, storing revisions, parsing and executing CUE code, garbage collecting, etc. -- _Addon Controllers_ that register and manage built-in addons that KubeVela needed to work. For example, Flux and Terraform controller. +- _Addons_ that register and manage definitions along with extended CRD controllers that KubeVela needed to work. For example, Flux and Terraform addons. This control plane Kubernetes cluster will be referenced as the "control plane cluster" in the following documentation. @@ -32,11 +32,7 @@ KubeVela itself is fully runtime infrastructure agnostic and hence allows you to ## KubeVela is Programmable -In real world, application deployment tends to be complex and varies from teams, environments and scenarios. Hence, KubeVela introduced a fully programmable approach to implement its deployment model so it can adapt to every need of your application delivery use case in-place. - -![alt](../resources/kernel.png) - -For learning how to program KubeVela in detail, please check the `Administrator Manuals` in the documentation site. +In real world, application deployment tends to be complex and varies from teams, environments and scenarios. Hence, KubeVela introduced the [Definition Mechanism](./definition) which is a fully programmable approach to implement its deployment model so it can adapt to every need of your application delivery use case in-place. ## Who should use KubeVela? diff --git a/docs/tutorials/webservice.md b/docs/tutorials/webservice.md index 6c9988cd..86d2dad1 100644 --- a/docs/tutorials/webservice.md +++ b/docs/tutorials/webservice.md @@ -3,13 +3,13 @@ title: Container Image description: deploy the business application by kubevela --- -This article introduces how companies deliver business applications based on KubeVela. It does not require you to know much about Kubernetes. +In this section, we will introduce how to deploy a container based application with KubeVela. The main process will be shown with UI console, +if you're using CLI, jump to [Deploy via CLI](#deploy-via-cli) part. ## Before starting -- Containerize your business. No matter what language you're using, first to build an image via CI or locally. -- Place your business image at a hub that KubeVela can access to. -- Enable the VelaUX addon, If you are only CLI users, go to [Deploy via CLI](#deploy-via-cli) +- Containerize your business, you need a container image within your image registry that can be accessed by KubeVela. +- Enable the [VelaUX addon](../reference/addons/velaux) by running command `vela addon enable velaux`. ## Creating an application @@ -57,6 +57,8 @@ After all of the environments have been recycled, the application can be deleted At this point, you have basically mastered the deployment method of Docker image. +You can refer to [how to manage applications](../how-to/dashboard/application/create-application) to learn the details about the UI console operations. + ## Deploy via CLI You also can deploy the application via CLI. @@ -103,18 +105,7 @@ About: Created at: 2022-04-21 12:03:42 +0800 CST Status: running -Workflow: - - mode: DAG - finished: true - Suspend: false - Terminated: false - Steps - - id:y4n26n7uql - name:frontend - type:apply-component - phase:succeeded - message: +...snip... Services: @@ -126,6 +117,9 @@ Services: ✅ scaler ``` +* Refer to [webservice details](../end-user/components/references#webservice) to know usage of full fields. +* Refer to [trait reference](../end-user/traits/references) to know which traits can be used for webservice. + ## Next Step [Learn to deploy Helm Chart](./helm) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.3/platform-engineers/traits/patch-trait.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.3/platform-engineers/traits/patch-trait.md index 542fa111..206b490b 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-v1.3/platform-engineers/traits/patch-trait.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-v1.3/platform-engineers/traits/patch-trait.md @@ -8,9 +8,11 @@ title: 补丁型特征 当我们的组件是从第三方提供并自定义而来的时候，由于它们的模版往往是固定不可变的，所以能使用补丁型特征就显得尤为有用了。 -> 尽管运维特征是由 CUE 来定义，它能打补丁的组件类型并不限，不管是来自 CUE、Helm 还是其余支持的模版格式 +> 尽管运维特征是由 CUE 来定义，它能打补丁的组件类型并不限，不管是来自 CUE、Helm 还是其余支持的模版格式。 -下面，我们通过一个节点亲和性（node affinity）的例子，讲解如何使用补丁型特征： +## 为组件打补丁 + +下面，我们通过一个节点亲和性（node affinity）的例子，讲解如何使用补丁型特征为组件打补丁： ```yaml apiVersion: core.oam.dev/v1beta1 @@ -84,7 +86,85 @@ spec: server-owner: "old-owner" ``` -### 待解决的短板 +## 为其他运维特征打补丁 + +> 注意：该功能在 KubeVela 1.4 版本之后生效。 + +你还可以通过在 Definition 中使用 `patchOutputs`，来为其他运维特征打补丁。如： + +```yaml +apiVersion: core.oam.dev/v1beta1 +kind: TraitDefinition +metadata: + name: patch-annotation +spec: + appliesToWorkloads: + - deployments.apps + podDisruptive: true + schematic: + cue: + template: | + patchOutputs: { + ingress: { + metadata: annotations: { + "kubernetes.io/ingress.class": "istio" + } + } + } +``` + +上面的这个补丁型特征，假定了它绑定的组件还有别的运维特征，并且别的运维特征拥有 `ingress` 资源。该补丁型特征则会为这个 `ingress` 资源打上一个 istio 的 annotation。 + +我们可以部署如下应用来查看： + +```yaml +apiVersion: core.oam.dev/v1alpha2 +kind: Application +metadata: + name: testapp +spec: + components: + - name: express-server + type: webservice + properties: + image: oamdev/testapp:v1 + traits: + - type: "gateway" + properties: + domain: testsvc.example.com + http: + "/": 8000 + - type: "patch-annotation" + properties: + name: "patch-annotation-trait" +``` + +应用成功运行后，`ingress` 资源如下： + +```yaml +apiVersion: networking.k8s.io/v1beta1 +kind: Ingress +metadata: + annotations: + kubernetes.io/ingress.class: istio + name: ingress +spec: + rules: + spec: + rules: + - host: testsvc.example.com + http: + paths: + - backend: + service: + name: express-server + port: + number: 8000 + path: / + pathType: ImplementationSpecific +``` + +## 待解决的短板和解决方案 默认来说，补丁型特征是通过 CUE 的 `merge` 操作来实现的。它有以下限制： @@ -104,7 +184,7 @@ spec: - 如果发现重复的键名，补丁数据会直接替换掉它的值 - 如果没有重复键名，补丁则会自动附加这些数据 -下面来看看，一个使用 'patchKey' 的策略补丁： +下面来看看，一个使用 `patchKey` 的策略补丁： ```yaml apiVersion: core.oam.dev/v1beta1 @@ -132,6 +212,8 @@ spec: ``` 在上述的这个例子中，我们定义了要 `patchKey` 的字段 `name`，是来自容器的参数键名。如果工作负载中并没有同名的容器，那么一个 sidecar 容器就会被加到 `spec.template.spec.containers` 数组列表中。如果工作负载中有重名的 `sidecar` 运维特征，则会执行 merge 操作而不是附加。 +> 在 KubeVela 1.4 版本之后，你可以使用 `,` 分割多个 patchKey，如 `patchKey=name,image`。 + 如果 `patch` 和 `outputs` 同时存在于一个运维特征定义中，`patch` 会率先被执行然后再渲染 `outputs`。 ```yaml @@ -169,11 +251,11 @@ spec: ``` 在上面这个运维特征定义中，我们将会把一个 `Service` 添加到给定的组件实例上。同时会先去给工作负载类型打上补丁数据，然后基于模版里的 `outputs` 渲染余下的资源。 -#### 2. 使用 `+patchStrategy=retainkeys` 注解 +#### 2. 使用 `+patchStrategy=retainKeys` 注解 -这个注解的策略，与 Kubernetes 官方的 [retainkeys](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/#use-strategic-merge-patch-to-update-a-deployment-using-the-retainkeys-strategy) 策略类似。 +这个注解的策略，与 Kubernetes 官方的 [retainKeys](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/#use-strategic-merge-patch-to-update-a-deployment-using-the-retainkeys-strategy) 策略类似。 -在一些场景下，整个对象需要被一起替换掉，使用 `retainkeys` 就是最适合的办法。 +在一些场景下，整个对象需要被一起替换掉，使用 `retainKeys` 就是最适合的办法。 假定一个 `Deployment` 对象是这样编写的： ```yaml @@ -241,6 +323,7 @@ spec: - name: retainkeys-demo-ctr image: nginx ``` + ## 更多补丁型特征的使用场景 补丁型特征，针对组件层面做些整体操作时，非常有用。我们看看还可以满足哪些需求： @@ -354,7 +437,7 @@ spec: // +patchKey=name containers: [{ name: context.name - // +patchKey=name + // +patchStrategy=retainKeys env: [ for k, v in parameter.env { name: k diff --git a/sidebars.js b/sidebars.js index 09f7114e..d3c9328f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -54,22 +54,6 @@ module.exports = { 'end-user/components/cloud-services/provision-an-RDS-instance-with-more-than-one-database', ], }, - { - 'How-to manage the applications': [ - 'how-to/dashboard/application/create-application', - 'how-to/dashboard/application/bind-new-environment', - 'tutorials/workflows', - 'how-to/dashboard/application/deploy-application', - 'how-to/dashboard/application/get-application-instance', - 'tutorials/scaler', - 'how-to/dashboard/application/get-application-log', - 'how-to/dashboard/application/get-application-endpoint', - 'how-to/dashboard/application/view-application-resource', - 'how-to/dashboard/application/get-application-revision', - 'how-to/dashboard/application/recycle-environment', - 'how-to/dashboard/application/delete-application', - ], - }, { 'Day-2 Operations': [ 'end-user/traits/rollout', @@ -82,12 +66,6 @@ module.exports = { 'end-user/traits/more', ], }, - { - 'Manage integration configs': [ - 'how-to/dashboard/config/dex-connectors', - 'how-to/dashboard/config/helm-repo', - ], - }, { 'Advanced Features': [ 'end-user/workflow/component-dependency-parameter', @@ -103,6 +81,13 @@ module.exports = { type: 'category', label: 'Operator Manual', items: [ + { + 'Advanced Installation': [ + 'platform-engineers/system-operation/bootstrap-parameters', + 'platform-engineers/advanced-install', + 'platform-engineers/system-operation/offline-installation', + ], + }, 'tutorials/sso', 'how-to/dashboard/user/user', 'how-to/dashboard/user/rbac', @@ -113,14 +98,13 @@ module.exports = { 'how-to/dashboard/target/overview', ], }, - 'how-to/cli/addon/addon', { - 'Install or upgrade': [ - 'platform-engineers/system-operation/bootstrap-parameters', - 'platform-engineers/advanced-install', - 'platform-engineers/system-operation/offline-installation', + 'Manage integration configs': [ + 'how-to/dashboard/config/dex-connectors', + 'how-to/dashboard/config/helm-repo', ], }, + 'how-to/cli/addon/addon', 'platform-engineers/system-operation/observability', 'platform-engineers/system-operation/performance-finetuning', { @@ -193,6 +177,22 @@ module.exports = { ], }, 'end-user/components/cloud-services/cloud-resources-list', + { + 'How-to manage the applications': [ + 'how-to/dashboard/application/create-application', + 'how-to/dashboard/application/bind-new-environment', + 'tutorials/workflows', + 'how-to/dashboard/application/deploy-application', + 'how-to/dashboard/application/get-application-instance', + 'tutorials/scaler', + 'how-to/dashboard/application/get-application-log', + 'how-to/dashboard/application/get-application-endpoint', + 'how-to/dashboard/application/view-application-resource', + 'how-to/dashboard/application/get-application-revision', + 'how-to/dashboard/application/recycle-environment', + 'how-to/dashboard/application/delete-application', + ], + }, 'reference/ui-schema', 'reference/user-improvement-plan', { diff --git a/versioned_docs/version-v1.3/getting-started/architecture.md b/versioned_docs/version-v1.3/getting-started/architecture.md index 3cb1792b..2dcc177f 100644 --- a/versioned_docs/version-v1.3/getting-started/architecture.md +++ b/versioned_docs/version-v1.3/getting-started/architecture.md @@ -8,7 +8,7 @@ The overall architecture of KubeVela is shown as below: ## KubeVela is a Control Plane System -KubeVela orchestrates application components, cloud resources and pipeline over multiple clusters and hybrid environments. It is designed to be an application delivery and management control plane instead of a runtime plugin. +KubeVela orchestrates application components, cloud resources and pipeline over multiple clusters and hybrid environments. It is designed to be an application delivery and operation control plane instead of a runtime plugin. For easy integration with upstream CI pipelines and GitOps tools, KubeVela API (i.e. Open Application Model) are designed as declarative and application-centric, including: @@ -21,7 +21,7 @@ For easy integration with upstream CI pipelines and GitOps tools, KubeVela API ( In implementation, KubeVela relies on a dedicated Kubernetes cluster to achieve above goals. We chose to rely on Kubernetes as the control plane implementation because this approach is battle tested and brings determinism, convergence and automation to application management at scale. In detail, KubeVela is composed by several parts: - _KubeVela Core Controller_ that provides the core control logic of the entire system. For example, handling KubeVela API resources, orchestrating workflow, storing revisions, parsing and executing CUE code, garbage collecting, etc. -- _Addon Controllers_ that register and manage built-in addons that KubeVela needed to work. For example, Flux and Terraform controller. +- _Addons_ that register and manage definitions along with extended CRD controllers that KubeVela needed to work. For example, Flux and Terraform addons. This control plane Kubernetes cluster will be referenced as the "control plane cluster" in the following documentation. @@ -32,11 +32,7 @@ KubeVela itself is fully runtime infrastructure agnostic and hence allows you to ## KubeVela is Programmable -In real world, application deployment tends to be complex and varies from teams, environments and scenarios. Hence, KubeVela introduced a fully programmable approach to implement its deployment model so it can adapt to every need of your application delivery use case in-place. - -![alt](../resources/kernel.png) - -For learning how to program KubeVela in detail, please check the `Administrator Manuals` in the documentation site. +In real world, application deployment tends to be complex and varies from teams, environments and scenarios. Hence, KubeVela introduced the [Definition Mechanism](./definition) which is a fully programmable approach to implement its deployment model so it can adapt to every need of your application delivery use case in-place. ## Who should use KubeVela? diff --git a/versioned_docs/version-v1.3/platform-engineers/traits/patch-trait.md b/versioned_docs/version-v1.3/platform-engineers/traits/patch-trait.md index 69903f32..3ae98382 100644 --- a/versioned_docs/version-v1.3/platform-engineers/traits/patch-trait.md +++ b/versioned_docs/version-v1.3/platform-engineers/traits/patch-trait.md @@ -8,6 +8,8 @@ This pattern is extremely useful when the component definition is provided by th > Note that even patch trait itself is defined by CUE, it can patch any component regardless how its schematic is defined (i.e. CUE, Helm, and any other supported schematic approaches). +## Patch to components + Below is an example for `node-affinity` trait: ```yaml @@ -54,9 +56,13 @@ spec: } ``` +In `patch`, we declare the component object fields that this trait will patch to. If you want to modify other traits in this trait, you can use `patchOutputs`. + The patch trait above assumes the target component instance have `spec.template.spec.affinity` field. Hence, we need to use `appliesToWorkloads` to enforce the trait only applies to those workload types have this field. +At the same time, this patch also assumes that there is another trait bound to the component, and that there will be a `service` resource in this trait. + Another important field is `podDisruptive`, this patch trait will patch to the pod template field, so changes on any field of this trait will cause the pod to restart, We should add `podDisruptive` and make it to be true to tell users that applying this trait will cause the pod to restart. @@ -76,6 +82,11 @@ spec: properties: image: oamdev/testapp:v1 traits: + - type: "gateway" + properties: + domain: testsvc.example.com + http: + "/": 8000 - type: "node-affinity" properties: affinity: @@ -86,7 +97,85 @@ spec: server-owner: "old-owner" ``` -### Known Limitations +## Patch to traits + +> Note: it's available after KubeVela v1.4. + +You can also patch to other traits by using `patchOutputs` in the Definition. Such as: + +```yaml +apiVersion: core.oam.dev/v1beta1 +kind: TraitDefinition +metadata: + name: patch-annotation +spec: + appliesToWorkloads: + - deployments.apps + podDisruptive: true + schematic: + cue: + template: | + patchOutputs: { + ingress: { + metadata: annotations: { + "kubernetes.io/ingress.class": "istio" + } + } + } +``` + +The patch trait above assumes that the component it binds has other traits which have `ingress` resource. The patch trait will patch an `istio` annotation to the `ingress` resource. + +We can deploy the following application: + +```yaml +apiVersion: core.oam.dev/v1alpha2 +kind: Application +metadata: + name: testapp +spec: + components: + - name: express-server + type: webservice + properties: + image: oamdev/testapp:v1 + traits: + - type: "gateway" + properties: + domain: testsvc.example.com + http: + "/": 8000 + - type: "patch-annotation" + properties: + name: "patch-annotation-trait" +``` + +And the ingress resource is now like: + +```yaml +apiVersion: networking.k8s.io/v1beta1 +kind: Ingress +metadata: + annotations: + kubernetes.io/ingress.class: istio + name: ingress +spec: + rules: + spec: + rules: + - host: testsvc.example.com + http: + paths: + - backend: + service: + name: express-server + port: + number: 8000 + path: / + pathType: ImplementationSpecific +``` + +## Known Limitations and Workarounds By default, patch trait in KubeVela leverages the CUE `merge` operation. It has following known constraints though: @@ -135,6 +224,8 @@ spec: In above example we defined `patchKey` is `name` which is the parameter key of container name. In this case, if the workload don't have the container with same name, it will be a sidecar container append into the `spec.template.spec.containers` array list. If the workload already has a container with the same name of this `sidecar` trait, then merge operation will happen instead of append (which leads to duplicated containers). +> After KubeVela 1.4, you can use `,` to split multiple patchKeys, such as `patchKey=name,image`. + If `patch` and `outputs` both exist in one trait definition, the `patch` operation will be handled first and then render the `outputs`. ```yaml @@ -173,11 +264,11 @@ spec: So the above trait which attaches a Service to given component instance will patch an corresponding label to the workload first and then render the Service resource based on template in `outputs`. -#### 2. With `+patchStrategy=retainkeys` annotation +#### 2. With `+patchStrategy=retainKeys` annotation -Similar to strategy [retainkeys](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/#use-strategic-merge-patch-to-update-a-deployment-using-the-retainkeys-strategy) in K8s strategic merge patch +Similar to strategy [retainKeys](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/#use-strategic-merge-patch-to-update-a-deployment-using-the-retainkeys-strategy) in K8s strategic merge patch -In some scenarios that the entire object needs to be replaced, retainkeys strategy is the best choice. the example as follows: +In some scenarios that the entire object needs to be replaced, retainKeys strategy is the best choice. the example as follows: Assume the Deployment is the base resource ```yaml @@ -356,7 +447,7 @@ spec: // +patchKey=name containers: [{ name: context.name - // +patchKey=name + // +patchStrategy=retainKeys env: [ for k, v in parameter.env { name: k diff --git a/versioned_docs/version-v1.3/tutorials/webservice.md b/versioned_docs/version-v1.3/tutorials/webservice.md index 6c9988cd..86d2dad1 100644 --- a/versioned_docs/version-v1.3/tutorials/webservice.md +++ b/versioned_docs/version-v1.3/tutorials/webservice.md @@ -3,13 +3,13 @@ title: Container Image description: deploy the business application by kubevela --- -This article introduces how companies deliver business applications based on KubeVela. It does not require you to know much about Kubernetes. +In this section, we will introduce how to deploy a container based application with KubeVela. The main process will be shown with UI console, +if you're using CLI, jump to [Deploy via CLI](#deploy-via-cli) part. ## Before starting -- Containerize your business. No matter what language you're using, first to build an image via CI or locally. -- Place your business image at a hub that KubeVela can access to. -- Enable the VelaUX addon, If you are only CLI users, go to [Deploy via CLI](#deploy-via-cli) +- Containerize your business, you need a container image within your image registry that can be accessed by KubeVela. +- Enable the [VelaUX addon](../reference/addons/velaux) by running command `vela addon enable velaux`. ## Creating an application @@ -57,6 +57,8 @@ After all of the environments have been recycled, the application can be deleted At this point, you have basically mastered the deployment method of Docker image. +You can refer to [how to manage applications](../how-to/dashboard/application/create-application) to learn the details about the UI console operations. + ## Deploy via CLI You also can deploy the application via CLI. @@ -103,18 +105,7 @@ About: Created at: 2022-04-21 12:03:42 +0800 CST Status: running -Workflow: - - mode: DAG - finished: true - Suspend: false - Terminated: false - Steps - - id:y4n26n7uql - name:frontend - type:apply-component - phase:succeeded - message: +...snip... Services: @@ -126,6 +117,9 @@ Services: ✅ scaler ``` +* Refer to [webservice details](../end-user/components/references#webservice) to know usage of full fields. +* Refer to [trait reference](../end-user/traits/references) to know which traits can be used for webservice. + ## Next Step [Learn to deploy Helm Chart](./helm) diff --git a/versioned_sidebars/version-v1.3-sidebars.json b/versioned_sidebars/version-v1.3-sidebars.json index 00d41b74..c95bfe3d 100644 --- a/versioned_sidebars/version-v1.3-sidebars.json +++ b/versioned_sidebars/version-v1.3-sidebars.json @@ -116,61 +116,6 @@ } ] }, - { - "collapsed": true, - "type": "category", - "label": "How-to manage the applications", - "items": [ - { - "type": "doc", - "id": "version-v1.3/how-to/dashboard/application/create-application" - }, - { - "type": "doc", - "id": "version-v1.3/how-to/dashboard/application/bind-new-environment" - }, - { - "type": "doc", - "id": "version-v1.3/tutorials/workflows" - }, - { - "type": "doc", - "id": "version-v1.3/how-to/dashboard/application/deploy-application" - }, - { - "type": "doc", - "id": "version-v1.3/how-to/dashboard/application/get-application-instance" - }, - { - "type": "doc", - "id": "version-v1.3/tutorials/scaler" - }, - { - "type": "doc", - "id": "version-v1.3/how-to/dashboard/application/get-application-log" - }, - { - "type": "doc", - "id": "version-v1.3/how-to/dashboard/application/get-application-endpoint" - }, - { - "type": "doc", - "id": "version-v1.3/how-to/dashboard/application/view-application-resource" - }, - { - "type": "doc", - "id": "version-v1.3/how-to/dashboard/application/get-application-revision" - }, - { - "type": "doc", - "id": "version-v1.3/how-to/dashboard/application/recycle-environment" - }, - { - "type": "doc", - "id": "version-v1.3/how-to/dashboard/application/delete-application" - } - ] - }, { "collapsed": true, "type": "category", @@ -210,21 +155,6 @@ } ] }, - { - "collapsed": true, - "type": "category", - "label": "Manage integration configs", - "items": [ - { - "type": "doc", - "id": "version-v1.3/how-to/dashboard/config/dex-connectors" - }, - { - "type": "doc", - "id": "version-v1.3/how-to/dashboard/config/helm-repo" - } - ] - }, { "collapsed": true, "type": "category", @@ -259,6 +189,25 @@ "type": "category", "label": "Operator Manual", "items": [ + { + "collapsed": true, + "type": "category", + "label": "Advanced Installation", + "items": [ + { + "type": "doc", + "id": "version-v1.3/platform-engineers/system-operation/bootstrap-parameters" + }, + { + "type": "doc", + "id": "version-v1.3/platform-engineers/advanced-install" + }, + { + "type": "doc", + "id": "version-v1.3/platform-engineers/system-operation/offline-installation" + } + ] + }, { "type": "doc", "id": "version-v1.3/tutorials/sso" @@ -290,29 +239,25 @@ } ] }, - { - "type": "doc", - "id": "version-v1.3/how-to/cli/addon/addon" - }, { "collapsed": true, "type": "category", - "label": "Install or upgrade", + "label": "Manage integration configs", "items": [ { "type": "doc", - "id": "version-v1.3/platform-engineers/system-operation/bootstrap-parameters" + "id": "version-v1.3/how-to/dashboard/config/dex-connectors" }, { "type": "doc", - "id": "version-v1.3/platform-engineers/advanced-install" - }, - { - "type": "doc", - "id": "version-v1.3/platform-engineers/system-operation/offline-installation" + "id": "version-v1.3/how-to/dashboard/config/helm-repo" } ] }, + { + "type": "doc", + "id": "version-v1.3/how-to/cli/addon/addon" + }, { "type": "doc", "id": "version-v1.3/platform-engineers/system-operation/observability" @@ -501,6 +446,61 @@ "type": "doc", "id": "version-v1.3/end-user/components/cloud-services/cloud-resources-list" }, + { + "collapsed": true, + "type": "category", + "label": "How-to manage the applications", + "items": [ + { + "type": "doc", + "id": "version-v1.3/how-to/dashboard/application/create-application" + }, + { + "type": "doc", + "id": "version-v1.3/how-to/dashboard/application/bind-new-environment" + }, + { + "type": "doc", + "id": "version-v1.3/tutorials/workflows" + }, + { + "type": "doc", + "id": "version-v1.3/how-to/dashboard/application/deploy-application" + }, + { + "type": "doc", + "id": "version-v1.3/how-to/dashboard/application/get-application-instance" + }, + { + "type": "doc", + "id": "version-v1.3/tutorials/scaler" + }, + { + "type": "doc", + "id": "version-v1.3/how-to/dashboard/application/get-application-log" + }, + { + "type": "doc", + "id": "version-v1.3/how-to/dashboard/application/get-application-endpoint" + }, + { + "type": "doc", + "id": "version-v1.3/how-to/dashboard/application/view-application-resource" + }, + { + "type": "doc", + "id": "version-v1.3/how-to/dashboard/application/get-application-revision" + }, + { + "type": "doc", + "id": "version-v1.3/how-to/dashboard/application/recycle-environment" + }, + { + "type": "doc", + "id": "version-v1.3/how-to/dashboard/application/delete-application" + } + ] + }, { "type": "doc", "id": "version-v1.3/reference/ui-schema"