refine the definition section

Signed-off-by: Jianbo Sun <jianbo.sjb@alibaba-inc.com>
This commit is contained in:
Jianbo Sun 2022-05-18 15:10:31 +08:00
parent 0848903867
commit 4a483c022e
11 changed files with 178 additions and 74 deletions

View File

@ -14,7 +14,7 @@ For easy integration with upstream CI pipelines and GitOps tools, KubeVela API (
`Application` for designing application deployment plan.
`X-Definitions` for managing the abstraction and capabilities of KubeVela with CUE.
`Definitions` for managing the abstraction and capabilities of KubeVela with CUE.
- e.g. `ComponentDefinition`, `TraitDefinition`, etc.

View File

@ -23,14 +23,157 @@ A definition's lifecycle usually has 3 stages:
### Discovery
When definitions installed in the system, they can be discovered by end user immediately.
* Check the list:
```
$ vela def list
NAME TYPE NAMESPACE DESCRIPTION
task ComponentDefinition vela-system Describes jobs that run code or a script to completion.
webservice ComponentDefinition vela-system Describes long-running, scalable, containerized services
that have a stable network endpoint to receive external
network traffic from customers.
gateway TraitDefinition vela-system Enable public web traffic for the component, the ingress API
matches K8s v1.20+.
labels TraitDefinition vela-system Add labels on K8s pod for your workload which follows the
pod spec in path 'spec.template'.
health PolicyDefinition vela-system Apply periodical health checking to the application.
deploy WorkflowStepDefinition vela-system Deploy components with policies.
notification WorkflowStepDefinition vela-system Send message to webhook
...snip...
```
* Show the details:
```
$ vela show webservice
# Properties
+------------------+-------------------------------------------------------------------------------------------+-----------------------------------+----------+---------+
| NAME | DESCRIPTION | TYPE | REQUIRED | DEFAULT |
+------------------+-------------------------------------------------------------------------------------------+-----------------------------------+----------+---------+
| cmd | Commands to run in the container | []string | false | |
| env | Define arguments by using environment variables | [[]env](#env) | false | |
| labels | Specify the labels in the workload | map[string]string | false | |
| annotations | Specify the annotations in the workload | map[string]string | false | |
| image | Which image would you like to use for your service | string | true | |
| ports | Which ports do you want customer traffic sent to, defaults to 80 | [[]ports](#ports) | false | |
+------------------+-------------------------------------------------------------------------------------------+-----------------------------------+----------+---------+
...snip...
```
You can also view the details with a browser, the following command will launch a server and invoke your browser automatically:
```
vela show webservice --web
```
* Discover in UI console
![alt](../resources/definition-ui.png)
These definitions can also be discovered by the UI console, the more important thing is they can be displayed very well with [ui schema](../reference/ui-schema) defined.
### Use
If you're a fan of our UI console, the usage of definition is very straight forward, just click along with the creation of the deployment process.
![alt](../resources/usage-of-def.png)
Finally, the UI console will compose the whole deployment plan in the format of OAM like below, then KubeVela controller will take care of the rest things:
```
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: first-vela-app
spec:
components:
- name: express-server
type: webservice
properties:
image: oamdev/hello-world
ports:
- port: 8000
expose: true
traits:
- type: scaler
properties:
replicas: 1
policies:
- name: target-default
type: topology
properties:
clusters: ["local"]
namespace: "default"
- name: target-prod
type: topology
properties:
clusters: ["local"]
namespace: "prod"
- name: deploy-ha
type: override
properties:
components:
- type: webservice
traits:
- type: scaler
properties:
replicas: 2
workflow:
steps:
- name: deploy2default
type: deploy
properties:
policies: ["target-default"]
- name: manual-approval
type: suspend
- name: deploy2prod
type: deploy
properties:
policies: ["target-prod", "deploy-ha"]
```
Use the definition in command works the same, you can compose the application yaml manually and use `vela` command line tool to deploy.
```
vela up -f https://kubevela.net/example/applications/first-app.yaml
```
### Customize
> ⚠️ In most cases, you don't need to customize any definitions unless you're going to extend the capability of KubeVela. Before that, you should check the built-in definitions and addons to confirm if they can fit your needs.
> **⚠️ In most cases, you don't need to customize any definitions unless you're going to extend the capability of KubeVela. Before that, you should check the built-in definitions and addons to confirm if they can fit your needs.**
A new definition is built in a declarative template in [CUE configuration language](https://cuelang.org/). If you're not familiar with CUE, you can refer to [CUE Basic](../platform-engineers/cue/basic) for some knowledge.
A definition describes the module's inputs, outputs, operations, and the wiring between them. Here is an example of a simple component definition:
```
webserver: {
type: "component"
attributes: {}
}
template: {
parameter: {
name: string
image: string
}
output: {
apiVersion: "apps/v1"
kind: "Deployment"
spec: {
containers: [{
name: parameter.name
image: parameter.image
}]
}
}
}
```
The `type` defines what kind of definition it is, the `parameter` defines the inputs, while the `output` section defines the outputs.
You can refer to detail docs about [how to manage definition](../platform-engineers/cue/definition-edit) or learn the [definition protocol](../platform-engineers/oam/x-definition).
## Next Step
- View [Architecture](./architecture) to learn the overall architecture of KubeVela.

View File

@ -5,40 +5,31 @@ slug: /
## What is KubeVela?
KubeVela is a modern software delivery platform that makes it easier and faster to deliver and manage applications across hybrid, multi-cloud environments.
Applications created with KubeVela use the best practices of modern applications by default: they are able to scale with clouds, they use infrastructure as code, they are observable, and they are secure.
KubeVela is a modern software delivery control plane. The goal is to make deploying and operating applications across today's hybrid, multi-cloud environments easier, faster and more reliable.
![](../resources/what-is-kubevela.png)
## Key Features
* **Unified Application Delivery Experience**
* **Deployment as Code**
KubeVela introduces a [unified and extensible model (OAM)](https://oam.dev/) that can glue and orchestrate all of your IaC based infrastructure configuration. As a result, KubeVela provides simple user experience for modern application delivery.
Declare your deployment plan as workflow, run it automatically with any CI/CD or GitOps system, extend or re-program the workflow steps with CUE. No add-hoc scripts, no dirty glue code, just deploy. The deployment workflow in KubeVela is powered by [Open Application Model](https://oam.dev/).
* **Automated Deployment across Clusters**
* **Built-in security and compliance building blocks**
KubeVela natively supports multi-cluster/hybrid-cloud scenarios such as promotion across clusters, high availability between clusters, automated cloud infrastructure provision.
Choose from the wide range of LDAP integrations we provided out-of-box, enjoy multi-cluster authorization that is fully automated, pick and apply fine-grained RBAC modules and customize them per your own supply chain requirements.
* **Enterprise-Grade Security**
* **Multi-cloud/hybrid-environments app delivery as first-class citizen**
KubeVela provides enterprise-grade security with fine-grained and custom RBAC, multi-cluster authorization, and first-class LDAP integrations.
* **Centralized Management and Observability**
KubeVela provides a unified control plane for modeling, provisioning, and deploying applications. The centralized management reduces the burden of looking over each clusters and gives unified experience across platforms. It greatly improve efficiency around troubleshooting and debugging when things go wrong.
* **Declarative and Highly Extensible Workflow**
KubeVela drives the delivery process with a declarative workflow, it provides automated canary and blue-green deployments with verification and rollback. After the workflow finished, it keeps the reconciliation loops to prevent any unexpected configuration drifts.
Progressive rollout across test/staging/production environments, automatic canary, blue-green and continuous verification, rich placement strategy across clusters and clouds, fully managed cloud environments provision.
## KubeVela vs. Other Software
### KubeVela vs. CI/CD (GitHub Actions, GitLab, CircleCI, Jenkins, etc.)
KubeVela is a continuous delivery platform that works at downstream of your CI process. So you will reuse the CI process you already adopted, and KubeVela will take over CD process by empowering it with modern application delivery best practices, such as hybrid/multi-cloud promotion workflow, unified cloud resource provision/binding, and much more. KubeVela is fully declarative by design, it natively supports GitOps if you want.
KubeVela is a continuous delivery platform that works at downstream of your CI process. So you will reuse the CI process you already adopted, and KubeVela will take over CD process by empowering it with modern application delivery best practices, such as declarative deployment plan as workflow, hybrid/multi-cloud resource provision/binding, security and compliance, and much more. It natively supports GitOps if you want.
> Feel free to check the [Integrating with Jenkins](./tutorials/jenkins) or [GitOps](./case-studies/gitops) documentation for more details.
@ -46,9 +37,8 @@ KubeVela is a continuous delivery platform that works at downstream of your CI p
KubeVela adopts your GitOps process and improves it by adding multi-cluster/hybrid-cloud capabilities:
* KubeVela has a user-friendly and programable workflow that allows you to integrate any of your delivery steps, including approval and notification flows.
* With the help of the workflow, KubeVela can provide cross-environment promotion for your multi-cluster/hybrid-cloud applications.
* KubeVela has a user-friendly workflow that allows you to extend, re-program or share any of your delivery process, including security and compliance flows.
* KubeVela regards multi-cloud/hybrid-environments app delivery as first-class citizen, it provides rich deployment strategies across clusters and clouds with fully managed cloud environments provision.
### KubeVela vs. PaaS (Heroku, Cloud Foundry, etc.)
@ -65,7 +55,7 @@ Using KubeVela is a good way to get many of the benefits of a PaaS (developer pr
Helm is a package manager for Kubernetes that provides package, install, and upgrade a set of YAML files for Kubernetes as a unit.
KubeVela as a modern delivery system can naturally deploy Helm charts. For example, you could use KubeVela to define an application that is composed by a WordPress chart and a AWS RDS Terraform module, orchestrate the components' topology, and then deploy them to multiple environments following certain strategy.
KubeVela as a modern software delivery control plane can naturally deploy Helm charts. For example, you could use KubeVela to define an application that is composed by a WordPress chart and a AWS RDS Terraform module, orchestrate the components' topology, and then deploy them to multiple environments following certain strategy.
Of course, KubeVela also supports other encapsulation formats including Kustomize etc.
@ -81,3 +71,4 @@ Welcome onboard and sail Vela!
## What's Next
- Start to [install KubeVela](./install).
- Learn [Core Concepts](./core-concept) to know more about how it works.

View File

@ -1,8 +1,8 @@
---
title: Manage X-Definition
title: Manage Definition
---
In KubeVela CLI (>= v1.1.0), `vela def` command group provides a series of convenient definition writing tools. With these commands, users only need to write CUE files to generate and edit definitions, instead of composing Kubernetes YAML object with mixed CUE string.
In KubeVela CLI, `vela def` command group provides a series of convenient definition writing tools. With these commands, users only need to write CUE files to generate and edit definitions, instead of composing Kubernetes YAML object with mixed CUE string.
## init

View File

@ -2,9 +2,10 @@
title: Definition Protocol
---
KubeVela is fully programmable via [CUE](https://cuelang.org).
KubeVela is fully programmable via [CUE](https://cuelang.org), while it leverage Kubernetes as control plane and align with the API in yaml.
You can [manage the definition](../cue/definition-edit) in CUE and the `vela def` command will render it into Kubernetes API with the following protocol.
This is achieved by implementing its [application model][1] as programmable entities (named `Definition`) include `ComponentDefinition`, `TraitDefinition`, `PolicyDefinition` and `WorkflowStepDefinition` as shown below.
## ComponentDefinition
@ -329,29 +330,6 @@ spec:
```
## WorkloadDefinition
WorkloadDefinition is a system-level feature. It's not a field that users should care about but as metadata checked, verified, and used by the OAM system itself.
The format is as follows:
```yaml
apiVersion: core.oam.dev/v1beta1
kind: WorkloadDefinition
metadata:
name: <WorkloadDefinition name>
spec:
definitionRef:
name: <corresponding Kubernetes resource group>
version: <corresponding Kubernetes resource version>
podSpecPath: <path to the Pod field in the Workload>
childResourceKinds:
- apiVersion: <resource group>
kind: <resource type>
```
In addition, other Kubernetes resource type that need to be introduced into OAM model in the future will also be added as fields to the workload definition.
## The Standard Protocol Behind Abstraction
Once the application is created, KubeVela will tag the created resources with a series of tags, which include the version, name, type, etc. of the application. Through these standard protocols, application components, traits and policies can be coordinated. The specific metadata list is as follows:
@ -392,11 +370,3 @@ At the same time, in the Workflow system, because the `context` has to act on th
Please note that all the Definition concepts introduced in this section only need to be understood by the platform administrator when they want to expand the functions of KubeVela. The end users will learn the schema of above definitions with visualized forms (or the JSON schema of parameters if they prefer) and reference them in application deployment plan. Please check the [Generate Forms from Definitions](../openapi-v3-json-schema) section about how this is achieved.
[1]: ./oam-model
[2]: ../cue/basic
[3]: ../kube/component
[4]: ../traits/customize-trait
[5]: ../traits/advanced.md
[6]: https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/
[7]: ../cue/basic.md

Binary file not shown.

After

Width:  |  Height:  |  Size: 242 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 274 KiB

View File

@ -197,22 +197,22 @@
"What is KubeVela?": {
"message": "KubeVela 是什么?"
},
"Unified Application Delivery Experience": {
"Deployment as Code": {
"message": "统一的应用交付模型"
},
"KubeVela introduces a unified and cross-platform delivery model(OAM) that allows you to deploy any workload type, including containers, databases, or even VM instances to any cloud or Kubernetes clusters. It helps you to just write application once, and deliver it the same everywhere, no more re-writing everything from scratch for any new delivery target.": {
"Declare your deployment plan as workflow, run it automatically with any CI/CD or GitOps system, extend or re-program the workflow steps with CUE. No add-hoc scripts, no dirty glue code, just deploy. The deployment workflow in KubeVela is powered by Open Application Model.": {
"message": "KubeVela 创新性的提出了开放应用模型OAM来作为应用交付的顶层抽象该模型支持交付任意类型的工作负载包括容器、数据库甚至是虚拟机到不同的云和 Kubernetes 集群中。用户无需关心任何基础设施细节,只需要专注于定义和部署应用即可。应用只需要一次编排,就可以随处运行,免去了适配不同平台的痛苦。"
},
"Automated Deployment across Clusters": {
"Built-in security and compliance building blocks": {
"message": "自动化跨集群交付"
},
"The application delivery process is driven by declarative workflow. Executed by reconciliation loops with limited privileges, the workflow is both robust and secure enough to prevent any unexpected configuration drifts. Users can also make arbitrary reusable customizations to the workflow through writing CUE definitions. The extensibility will always satisfy your growing business demands while keeping your production safe with continuous enforcement.": {
"Choose from the wide range of LDAP integrations we provided out-of-box, enjoy multi-cluster authorization that is fully automated, pick and apply fine-grained RBAC modules and customize them per your own supply chain requirements.": {
"message": "KubeVela 的整个交付模型完全是由用户声明式驱动的,兼顾用户体验和健壮性,其控制循环能够有效避免配置漂移,且具备多租权限控制能力。用户可以通过 CUE 语言(一种源自 Google Borg 系统的数据配置语言)自由的根据需求场景来设计和选用交付工作流中的每一个步骤,满足业务快速增长的需求,同时持续保证生产环境面向终态的稳定性。"
},
"Declarative and Highly Extensible Workflow": {
"Multi-cloud/hybrid-environments app delivery as first-class citizen": {
"message": "声明式高可扩展工作流"
},
"KubeVela natively supports rich continuous delivery strategies in various multi-cluster/hybrid-cloud scenarios or mixed environments. These strategies provides efficiency and safety to the distributed delivery process. The centralized management reduces the burden of looking over each clusters and gives unified experience across platforms. With KubeVela, you don't need to have any Ph.D. degree in Kubernetes to run automatic deployments.": {
"Progressive rollout across test/staging/production environments, automatic canary, blue-green and continuous verification, rich placement strategy across clusters and clouds, fully managed cloud environments provision.": {
"message": "KubeVela 原生支持丰富的多集群/混合环境持续交付策略也支持跨环境交付。这些交付策略为你的分布式交付流程提供了充足的效率和安全的保证。KubeVela 提供的中心化管控能力也减轻了到每一个集群去排查问题的负担,针对不同的平台提供统一的体验,为了享受自动化交付的便利,你再也不需要成为 Kubernetes 专家。"
},
"KubeVela is a": {
@ -236,8 +236,8 @@
".": {
"message": "."
},
" It allows you to build powerful software, and run them anywhere!": {
"message": "它可以帮助你构建多样化的云原生应用,并随处运行"
" It allows you to build powerful software, and deliver them anywhere!": {
"message": "它可以帮助你构建多样化的云原生应用,并交付到任意的云和基础设施"
},
"theme.SearchPage.documentsFound.plurals": {
"message": "One document found|{count} documents found",

View File

@ -11,7 +11,7 @@ module.exports = {
{
type: 'category',
label: 'Core Concepts',
collapsed: true,
collapsed: false,
items: [
'getting-started/core-concept',
'getting-started/definition',

View File

@ -3,26 +3,26 @@ import Translate, { translate } from '@docusaurus/Translate';
const features = [
{
title: <><Translate>Unified Application Delivery Experience</Translate></>,
title: <><Translate>Deployment as Code</Translate></>,
imgUrl: 'img/application-centric.svg',
description: (
<>
<p>
<Translate>
KubeVela introduces a unified and cross-platform delivery model(OAM) that allows you to deploy any workload type, including containers, databases, or even VM instances to any cloud or Kubernetes clusters. It helps you to just write application once, and deliver it the same everywhere, no more re-writing everything from scratch for any new delivery target.
Declare your deployment plan as workflow, run it automatically with any CI/CD or GitOps system, extend or re-program the workflow steps with CUE. No add-hoc scripts, no dirty glue code, just deploy. The deployment workflow in KubeVela is powered by Open Application Model.
</Translate>
</p>
</>
),
},
{
title: <><Translate>Automated Deployment across Clusters</Translate></>,
title: <><Translate>Built-in security and compliance building blocks</Translate></>,
imgUrl: 'img/extending-natively.svg',
description: (
<>
<p>
<Translate>
KubeVela natively supports rich continuous delivery strategies in various multi-cluster/hybrid-cloud scenarios or mixed environments. These strategies provides efficiency and safety to the distributed delivery process. The centralized management reduces the burden of looking over each clusters and gives unified experience across platforms. With KubeVela, you don't need to have any Ph.D. degree in Kubernetes to run automatic deployments.
Choose from the wide range of LDAP integrations we provided out-of-box, enjoy multi-cluster authorization that is fully automated, pick and apply fine-grained RBAC modules and customize them per your own supply chain requirements.
</Translate>
</p>
</>
@ -30,13 +30,13 @@ const features = [
reverse: true,
},
{
title: <><Translate>Declarative and Highly Extensible Workflow</Translate></>,
title: <><Translate>Multi-cloud/hybrid-environments app delivery as first-class citizen</Translate></>,
imgUrl: 'img/simple-yet-extensible-abstraction-mechanism.svg',
description: (
<>
<p>
<Translate>
The application delivery process is driven by declarative workflow. Executed by reconciliation loops with limited privileges, the workflow is both robust and secure enough to prevent any unexpected configuration drifts. Users can also make arbitrary reusable customizations to the workflow through writing CUE definitions. The extensibility will always satisfy your growing business demands while keeping your production safe with continuous enforcement.
Progressive rollout across test/staging/production environments, automatic canary, blue-green and continuous verification, rich placement strategy across clusters and clouds, fully managed cloud environments provision.
</Translate>
</p>
</>

View File

@ -109,7 +109,7 @@ const WhatIs = () => (
<Translate>
KubeVela is infrastructure agnostic, programmable, yet most importantly,
</Translate><i><b> <Translate>application-centric.</Translate></b></i>
<Translate> It allows you to build powerful software, and run them anywhere!</Translate>
<Translate> It allows you to build powerful software, and deliver them anywhere!</Translate>
</small>
</p>
</div>