Revise en sidebar and doc (#143)
This commit is contained in:
Lei Zhang (Harry)
GitHub
parent
84a73d4cc7
commit
3fbe396fcb
|
|
@ -225,7 +225,7 @@ spec:
|
|||
|
||||
### [Optional] Configure another workload type
|
||||
|
||||
By now we have deployed a *[Web Service](../end-user/components/webservice)*, which is the default workload type in KubeVela. We can also add another service of *[Task](../end-user/components/task)* type in the same app:
|
||||
By now we have deployed a *[Web Service](../end-user/components/cue/webservice)*, which is the default workload type in KubeVela. We can also add another service of *[Task](../end-user/components/cue/task)* type in the same app:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: Alibaba-ROS
|
||||
title: Alibaba ROS
|
||||
---
|
||||
|
||||
TBD
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: Helm Components
|
||||
title: Helm
|
||||
---
|
||||
|
||||
TBD
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: Helm Components
|
||||
title: Kustomize
|
||||
---
|
||||
|
||||
TBD
|
||||
|
|
|
|||
|
|
@ -1,3 +1,3 @@
|
|||
---
|
||||
title: 本地试运行
|
||||
title: Dry Run
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: Live-Diff
|
||||
title: Live Diff
|
||||
---
|
||||
|
||||
KubeVela allows you to dry-run and live-diff your application.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: First Application
|
||||
title: Deploy First Application
|
||||
---
|
||||
|
||||
TBD
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: Other Install Topics
|
||||
title: Custom Installation
|
||||
---
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: How-to
|
||||
title: CUE Component
|
||||
---
|
||||
|
||||
In this section, it will introduce how to use [CUE](https://cuelang.org/) to declare app components via `ComponentDefinition`.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
---
|
||||
title: Component Defualt
|
||||
title: Built-in Component
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: Component Terraform
|
||||
title: Terraform Component
|
||||
---
|
||||
|
||||
In this documentation, we will use Alibaba Cloud's RDS (Relational Database Service), and Alibaba Cloud's OSS (Object Storage System) as examples to show how to enable cloud services as part of the application deployment.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: 开发与调试
|
||||
title: CUE Advanced
|
||||
---
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: Learning CUE
|
||||
title: CUE Basic
|
||||
---
|
||||
|
||||
This document will explain more about how to use CUE to encapsulate and abstract a given capability in Kubernetes in detail.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: 自定义交付环境
|
||||
title: Custom Initializer
|
||||
---
|
||||
|
||||
TBD
|
||||
|
|
@ -1,207 +1,5 @@
|
|||
---
|
||||
title: 交付环境原理
|
||||
title: Introduction
|
||||
---
|
||||
|
||||
This documentation will explain the core resource model of KubeVela which is fully powered by Open Application Model (OAM).
|
||||
|
||||
## Application
|
||||
|
||||
The *Application* is the core API of KubeVela. It allows End User to work with a single artifact to capture the complete application deployment with simplified primitives.
|
||||
|
||||
This provides a simpler path for on-boarding End User to the platform without leaking low level details in runtime infrastructure. For example, they will be able to declare a "web service" without defining a detailed Kubernetes Deployment + Service combo each time, or claim the auto-scaling requirements without referring to the underlying KEDA ScaleObject. They can also declare a cloud database with same API if they want.
|
||||
|
||||
Every application is composed by multiple components with attachable operational behaviors (traits). For example:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: application-sample
|
||||
spec:
|
||||
components:
|
||||
- name: foo
|
||||
type: webservice
|
||||
properties:
|
||||
image: crccheck/hello-world
|
||||
port: 8000
|
||||
traits:
|
||||
- type: ingress
|
||||
properties:
|
||||
domain: testsvc.example.com
|
||||
http:
|
||||
"/": 8000
|
||||
- type: sidecar
|
||||
properties:
|
||||
name: "logging"
|
||||
image: "fluentd"
|
||||
- name: bar
|
||||
type: aliyun-oss # cloud service
|
||||
bucket: "my-bucket"
|
||||
```
|
||||
|
||||
The `Application` resource in KubeVela is a LEGO-style entity and does not even have fixed schema. Instead, it is assembled by below building block entities that are maintained by the platform-engineers.
|
||||
Though the application object doesn't have fixed schema, it is a composition object assembled by several *programmable building blocks* as shown below.
|
||||
|
||||
## Component
|
||||
|
||||
The component model (`ComponentDefinition` API) is designed to allow *component providers* to encapsulate deployable/provisionable entities with a wide range of tools, and hence give a easier path to End User to deploy complicated microservices across hybrid environments at ease. A component normally carries its workload type description (i.e. `WorkloadDefinition`), a encapsulation module with a parameter list.
|
||||
|
||||
> Hence, a components provider could be anyone who packages software components in form of Helm chart of CUE modules. Think about 3rd-party software distributor, DevOps team, or even your CI pipeline.
|
||||
|
||||
Components are shareable and reusable. For example, by referencing the same *Alibaba Cloud RDS* component and setting different parameter values, End User could easily provision Alibaba Cloud RDS instances of different sizes in different availability zones.
|
||||
|
||||
End User will use the `Application` entity to declare how they want to instantiate and deploy a group of certain components. In above example, it describes an application composed with Kubernetes stateless workload (component `foo`) and a Alibaba Cloud OSS bucket (component `bar`) alongside.
|
||||
|
||||
### How it Works?
|
||||
|
||||
In above example, `type: worker` means the specification of this component (claimed in following `properties` section) will be enforced by a `ComponentDefinition` object named `worker` as below:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: ComponentDefinition
|
||||
metadata:
|
||||
name: worker
|
||||
annotations:
|
||||
definition.oam.dev/description: "Describes long-running, scalable, containerized services that running at backend. They do NOT have network endpoint to receive external network traffic."
|
||||
spec:
|
||||
workload:
|
||||
definition:
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
schematic:
|
||||
cue:
|
||||
template: |
|
||||
output: {
|
||||
apiVersion: "apps/v1"
|
||||
kind: "Deployment"
|
||||
spec: {
|
||||
selector: matchLabels: {
|
||||
"app.oam.dev/component": context.name
|
||||
}
|
||||
template: {
|
||||
metadata: labels: {
|
||||
"app.oam.dev/component": context.name
|
||||
}
|
||||
spec: {
|
||||
containers: [{
|
||||
name: context.name
|
||||
image: parameter.image
|
||||
|
||||
if parameter["cmd"] != _|_ {
|
||||
command: parameter.cmd
|
||||
}
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
parameter: {
|
||||
image: string
|
||||
cmd?: [...string]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Hence, the `properties` section of `backend` only exposes two parameters to fill: `image` and `cmd`, this is enforced by the `parameter` list of the `.spec.template` field of the definition.
|
||||
|
||||
## Traits
|
||||
|
||||
Traits (`TraitDefinition` API) are operational features provided by the platform. A trait augments the component instance with operational behaviors such as load balancing policy, network ingress routing, auto-scaling policies, or upgrade strategies, etc.
|
||||
|
||||
To attach a trait to component instance, the user will declare `.type` field to reference the specific `TraitDefinition`, and `.properties` field to set property values of the given trait. Similarly, `TraitDefinition` also allows you to define *template* for operational features.
|
||||
|
||||
In the above example, `type: autoscaler` in `frontend` means the specification (i.e. `properties` section) of this trait will be enforced by a `TraitDefinition` object named `autoscaler` as below:
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: TraitDefinition
|
||||
metadata:
|
||||
annotations:
|
||||
definition.oam.dev/description: "configure k8s HPA for Deployment"
|
||||
name: hpa
|
||||
spec:
|
||||
appliesToWorkloads:
|
||||
- deployments.apps
|
||||
schematic:
|
||||
cue:
|
||||
template: |
|
||||
outputs: hpa: {
|
||||
apiVersion: "autoscaling/v2beta2"
|
||||
kind: "HorizontalPodAutoscaler"
|
||||
metadata: name: context.name
|
||||
spec: {
|
||||
scaleTargetRef: {
|
||||
apiVersion: "apps/v1"
|
||||
kind: "Deployment"
|
||||
name: context.name
|
||||
}
|
||||
minReplicas: parameter.min
|
||||
maxReplicas: parameter.max
|
||||
metrics: [{
|
||||
type: "Resource"
|
||||
resource: {
|
||||
name: "cpu"
|
||||
target: {
|
||||
type: "Utilization"
|
||||
averageUtilization: parameter.cpuUtil
|
||||
}
|
||||
}
|
||||
}]
|
||||
}
|
||||
}
|
||||
parameter: {
|
||||
min: *1 | int
|
||||
max: *10 | int
|
||||
cpuUtil: *50 | int
|
||||
}
|
||||
```
|
||||
|
||||
The application also have a `sidecar` trait.
|
||||
|
||||
```yaml
|
||||
apiVersion: core.oam.dev/v1beta1
|
||||
kind: TraitDefinition
|
||||
metadata:
|
||||
annotations:
|
||||
definition.oam.dev/description: "add sidecar to the app"
|
||||
name: sidecar
|
||||
spec:
|
||||
appliesToWorkloads:
|
||||
- deployments.apps
|
||||
schematic:
|
||||
cue:
|
||||
template: |-
|
||||
patch: {
|
||||
// +patchKey=name
|
||||
spec: template: spec: containers: [parameter]
|
||||
}
|
||||
parameter: {
|
||||
name: string
|
||||
image: string
|
||||
command?: [...string]
|
||||
}
|
||||
```
|
||||
|
||||
Please note that the End User do NOT need to know about definition objects, they learn how to use a given capability with visualized forms (or the JSON schema of parameters if they prefer). Please check the [Generate Forms from Definitions](../openapi-v3-json-schema) section about how this is achieved.
|
||||
|
||||
## Standard Contract Behind The Abstractions
|
||||
|
||||
Once the application is deployed, KubeVela will index and manage the underlying instances with name, revisions, labels and selector etc in automatic approach. These metadata are shown as below.
|
||||
|
||||
| Label | Description |
|
||||
| :--: | :---------: |
|
||||
|`workload.oam.dev/type=<component definition name>` | The name of its corresponding `ComponentDefinition` |
|
||||
|`trait.oam.dev/type=<trait definition name>` | The name of its corresponding `TraitDefinition` |
|
||||
|`app.oam.dev/name=<app name>` | The name of the application it belongs to |
|
||||
|`app.oam.dev/component=<component name>` | The name of the component it belongs to |
|
||||
|`trait.oam.dev/resource=<name of trait resource instance>` | The name of trait resource instance |
|
||||
|`app.oam.dev/appRevision=<name of app revision>` | The name of the application revision it belongs to |
|
||||
|
||||
|
||||
Consider these metadata as a standard contract for any "day 2" operation controller such as rollout controller to work on KubeVela deployed applications. This is the key to ensure the interoperability for KubeVela based platform as well.
|
||||
|
||||
## No Configuration Drift
|
||||
|
||||
Despite the efficiency and extensibility in abstracting application deployment, IaC (Infrastructure-as-Code) tools may lead to an issue called *Infrastructure/Configuration Drift*, i.e. the generated component instances are not in line with the expected configuration. This could be caused by incomplete coverage, less-than-perfect processes or emergency changes. This makes them can be barely used as a platform level building block.
|
||||
|
||||
Hence, KubeVela is designed to maintain all these programmable capabilities with [Kubernetes Control Loop](https://kubernetes.io/docs/concepts/architecture/controller/) and leverage Kubernetes control plane to eliminate the issue of configuration drifting, while still keeps the flexibly and velocity enabled by IaC.
|
||||
TBD
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: OAM Model
|
||||
title: Introduction
|
||||
---
|
||||
|
||||
This documentation will explain the core resource model of KubeVela which is fully powered by Open Application Model (OAM).
|
||||
|
|
|
|||
|
|
@ -1,2 +1,2 @@
|
|||
---
|
||||
title: 自定义工作流
|
||||
title: Custom Workflow
|
||||
|
|
@ -1,3 +1,3 @@
|
|||
---
|
||||
title: 工作流原理
|
||||
title: Introduction
|
||||
---
|
||||
|
|
@ -81,7 +81,7 @@ module.exports = {
|
|||
to: '/docs/install',
|
||||
},
|
||||
{
|
||||
label: 'platform-engineers Guide',
|
||||
label: 'Platform Admin Guide',
|
||||
to: '/docs/platform-engineers/overview',
|
||||
},
|
||||
{
|
||||
|
|
|
|||
|
|
@ -131,9 +131,9 @@
|
|||
"message": "调试指南",
|
||||
"description": "The label for category Debugging in sidebar docs"
|
||||
},
|
||||
"sidebar.docs.category.platform-engineers Guide": {
|
||||
"sidebar.docs.category.Platform Admin Guide": {
|
||||
"message": "管理员手册",
|
||||
"description": "The label for category platform-engineers Guide in sidebar docs"
|
||||
"description": "The label for category Platform Admin Guide in sidebar docs"
|
||||
},
|
||||
"sidebar.docs.category.Simple Template": {
|
||||
"message": "Simple Template",
|
||||
|
|
|
|||
|
|
@ -219,7 +219,7 @@ spec:
|
|||
|
||||
### [可选] 配置其他类型的 workload
|
||||
|
||||
至此，我们成功地部署一个默认类型的 workload 的 *[web 服务](../end-user/components/webservice)*。我们也可以添加 *[Task](../end-user/components/task)* 类型的服务到同一个 app 中。
|
||||
至此，我们成功地部署一个默认类型的 workload 的 *[web 服务](../end-user/components/cue/webservice)*。我们也可以添加 *[Task](../end-user/components/cue/task)* 类型的服务到同一个 app 中。
|
||||
|
||||
```yaml
|
||||
services:
|
||||
|
|
|
|||
|
|
@ -15,9 +15,9 @@
|
|||
"message": "快速开始",
|
||||
"description": "The label of footer link with label=Getting Started linking to /docs/install"
|
||||
},
|
||||
"link.item.label.platform-engineers Guide": {
|
||||
"message": "platform-engineers Guide",
|
||||
"description": "The label of footer link with label=platform-engineers Guide linking to /docs/platform-engineers/overview"
|
||||
"link.item.label.Platform Admin Guide": {
|
||||
"message": "Platform Admin Guide",
|
||||
"description": "The label of footer link with label=Platform Admin Guide linking to /docs/platform-engineers/overview"
|
||||
},
|
||||
"link.item.label.End User Guide": {
|
||||
"message": "End User Guide",
|
||||
|
|
|
|||
55
sidebars.js
55
sidebars.js
|
|
@ -22,30 +22,36 @@ module.exports = {
|
|||
},
|
||||
{
|
||||
type: 'category',
|
||||
label: 'End User Guide',
|
||||
label: 'User Guide',
|
||||
collapsed: false,
|
||||
items: [
|
||||
'end-user/initializer-end-user',
|
||||
{
|
||||
'Components': [
|
||||
'end-user/components/default',
|
||||
'end-user/components/helm',
|
||||
'end-user/components/kustomize',
|
||||
{
|
||||
'CUE': [
|
||||
'end-user/components/cue/webservice',
|
||||
'end-user/components/cue/task',
|
||||
'end-user/components/cue/worker',
|
||||
]
|
||||
},
|
||||
{
|
||||
'Cloud Services': [
|
||||
{
|
||||
'Terraform': [
|
||||
'end-user/components/cloud-services/terraform/sls',
|
||||
'end-user/components/cloud-services/terraform/rds',
|
||||
]
|
||||
},
|
||||
'end-user/components/cloud-services/alibaba-ros',
|
||||
'Terraform': [
|
||||
'end-user/components/cloud-services/terraform/sls',
|
||||
'end-user/components/cloud-services/terraform/rds',
|
||||
]
|
||||
},
|
||||
'end-user/components/cloud-services/alibaba-ros',
|
||||
]
|
||||
},
|
||||
]
|
||||
},
|
||||
{
|
||||
'Workflow End User': [
|
||||
'Workflow': [
|
||||
'end-user/workflow/multi-env',
|
||||
]
|
||||
},
|
||||
|
|
@ -53,7 +59,7 @@ module.exports = {
|
|||
'Traits': [
|
||||
'end-user/traits/ingress',
|
||||
{
|
||||
'Scaler': [
|
||||
'Scaling': [
|
||||
'end-user/traits/manual-scaler',
|
||||
'end-user/traits/autoscaler',
|
||||
]
|
||||
|
|
@ -77,24 +83,23 @@ module.exports = {
|
|||
},
|
||||
{
|
||||
type: 'category',
|
||||
label: 'platform-engineers Guide',
|
||||
label: 'Platform Admin Guide',
|
||||
collapsed: false,
|
||||
items: [
|
||||
'platform-engineers/advanced-install',
|
||||
{
|
||||
'OAM': [
|
||||
'Learning OAM': [
|
||||
'platform-engineers/oam/oam-model',
|
||||
'platform-engineers/oam/x-definition',
|
||||
]
|
||||
},
|
||||
{
|
||||
'CUE': [
|
||||
'Learning CUE': [
|
||||
'platform-engineers/cue/basic',
|
||||
'platform-engineers/cue/advanced',
|
||||
]
|
||||
},
|
||||
{
|
||||
'Initializer Platform Eng': [
|
||||
'Environment System': [
|
||||
'platform-engineers/initializer/basic-initializer',
|
||||
'platform-engineers/initializer/advanced-initializer',
|
||||
]
|
||||
|
|
@ -102,7 +107,7 @@ module.exports = {
|
|||
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Defining Components',
|
||||
label: 'Component System',
|
||||
items: [
|
||||
'platform-engineers/components/component-default',
|
||||
'platform-engineers/components/component-cue',
|
||||
|
|
@ -110,27 +115,23 @@ module.exports = {
|
|||
]
|
||||
},
|
||||
{
|
||||
'Workflow Platform Engineers': [
|
||||
'Worfklow System': [
|
||||
'platform-engineers/workflow/basic-workflow',
|
||||
'platform-engineers/workflow/advanced-workflow',
|
||||
]
|
||||
},
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Defining Traits',
|
||||
label: 'Traits System',
|
||||
items: [
|
||||
'platform-engineers/traits/trait',
|
||||
{
|
||||
'Customize Traits': [
|
||||
'platform-engineers/traits/patch-trait',
|
||||
'platform-engineers/traits/status',
|
||||
'platform-engineers/traits/advanced',
|
||||
]
|
||||
}
|
||||
|
||||
'platform-engineers/traits/patch-trait',
|
||||
'platform-engineers/traits/status',
|
||||
'platform-engineers/traits/advanced',
|
||||
]
|
||||
},
|
||||
],
|
||||
'platform-engineers/advanced-install',
|
||||
]
|
||||
},
|
||||
{
|
||||
type: 'category',
|
||||
|
|
|
|||
|
|
@ -132,7 +132,7 @@
|
|||
{
|
||||
"collapsed": false,
|
||||
"type": "category",
|
||||
"label": "platform-engineers Guide",
|
||||
"label": "Platform Admin Guide",
|
||||
"items": [
|
||||
{
|
||||
"type": "doc",
|
||||
|
|
|
|||
|
|
@ -136,7 +136,7 @@
|
|||
{
|
||||
"collapsed": false,
|
||||
"type": "category",
|
||||
"label": "platform-engineers Guide",
|
||||
"label": "Platform Admin Guide",
|
||||
"items": [
|
||||
{
|
||||
"type": "doc",
|
||||
|
|
|
|||
Loading…
Reference in New Issue