From 00a4e4ca01ac27b59d6055ed656c2dd76667e396 Mon Sep 17 00:00:00 2001 From: "Lei Zhang (Harry)" Date: Wed, 21 Apr 2021 00:49:10 -0700 Subject: [PATCH] Align with doc site (#1545) --- README.md | 28 +++++++++++++--------------- docs/en/README.md | 2 +- docs/en/concepts.md | 28 +++++++++++++++++----------- 3 files changed, 31 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index e232993b7..64c76ede7 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ # KubeVela -KubeVela is a modern application engine that adapts to your application's needs, not the other way around. +KubeVela is a modern application platform that adapts to your application's needs, not the other way around. ## Community @@ -29,16 +29,7 @@ KubeVela is a modern application engine that adapts to your application's needs, Traditional Platform-as-a-Service (PaaS) systems enable easy application deployments, but this happiness disappears when your application outgrows the capabilities of your platform. This is inevitable regardless of your PaaS is built on Kubernetes or not - the root cause is its inflexibility. -KubeVela is a modern application deployment system that adapts to your needs. Essentially, KubeVela enables you to define platform capabilities (such as workloads, operational behaviors, and cloud services) as reusable [CUE](https://cuelang.org/) or [Helm](https://helm.sh) components, per needs of your application deployment. And when your needs grow, your platform capabilities expand naturally in a programmable approach. - -Perfect in flexibility though, X-as-Code tends to lead to configuration drift. That's why KubeVela is fully built as a [Kubernetes Controller](https://kubernetes.io/docs/concepts/architecture/controller/) instead of a client-side tool, i.e. all its capabilities are modeled as code but enforced with battle tested reconciling loops which will never leave inconsistency in your clusters. Think about *Platform-as-Code* enabled by Kubernetes, CUE and Helm. - -With developer experience in mind, KubeVela exposes those programmable platform capabilities as application-centric API shown as below: -- Components - deployable/provisionable entities that composed your application deployment - - e.g. a Kubernetes workload, a MySQL database, or a AWS S3 bucket -- Traits - attachable operational features per your needs - - e.g. autoscaling rules, rollout strategies, ingress rules, sidecars, security policies etc -- Application - full description of your application deployment assembled with components and traits. +KubeVela solves this problem with an easy-to-use yet highly extensible approach. ## Getting Started @@ -48,10 +39,17 @@ With developer experience in mind, KubeVela exposes those programmable platform ## Features -- **Zero-restriction application deployment system** - design and express platform capabilities with CUE and Helm per needs of your application, and let Kubernetes controller guarantee the determinism in the application deployment. GUI forms are automatically generated for capabilities so even your dashboard are fully extensible. -- **Generic progressive rollout framework** - built-in rollout framework and strategies to upgrade your microservice regardless of its workload type (e.g. stateless, stateful, or even custom operators etc). -- **Multi-cluster multi-revision application deployment** - built-in model to deploy or rollout your apps across hybrid infrastructures, with Service Mesh for traffic shifting. -- **Simple and native** - KubeVela is a just simple Kubernetes custom controller, all its capabilities are defined as [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) so they naturally work with any CI/CD or GitOps tools which work with Kubernetes. +**Developer Centric** + +KubeVela introduces the *Application* as the main API to capture a full deployment of microservices, and builds features around the application needs only. Progressive rollout and multi-cluster deployment are provided out-of-box. No infrastructure level concerns, simply deploy. + +**Platform-as-Code** + +KubeVela models platform features (such as workloads, operational behaviors, and cloud services) as reusable [CUE](https://github.com/cuelang/cue) and/or [Helm](https://helm.sh/) components, per needs of your application. And when your needs grow, these capabilities can expand naturally in a programmable approach. No restriction, fully extensible. + +**Simple yet Reliable** + +KubeVela enforces those programmable components with [Kubernetes Control Loop](https://kubernetes.io/docs/concepts/architecture/controller/) so they will never leave configuration drift in your clusters. Also, this makes KubeVela work with any CI/CD or GitOps tools via declarative API without any integration burden. ## Documentation diff --git a/docs/en/README.md b/docs/en/README.md index ae4e304e8..b33bb0f54 100644 --- a/docs/en/README.md +++ b/docs/en/README.md @@ -4,7 +4,7 @@ # KubeVela -KubeVela is a modern application engine that adapts to your application's needs, not the other way around. +KubeVela is a modern application platform that adapts to your application's needs, not the other way around. ## Community diff --git a/docs/en/concepts.md b/docs/en/concepts.md index 021f2f851..415df4807 100644 --- a/docs/en/concepts.md +++ b/docs/en/concepts.md @@ -2,27 +2,27 @@ title: How it Works --- -*"KubeVela is a scalable way to create PaaS-like experience on Kubernetes"* - In this documentation, we will explain the core idea of KubeVela and clarify some technical terms that are widely used in the project. ## Overview First of all, KubeVela introduces a workflow with separate of concerns as below: - **Platform Team** - - Defining templates for deployment environments and reusable capability modules to compose an application, and registering them into the cluster. + - Model deployment environments and platform capabilities as reusable templates, then register them into the platform. - **End Users** - - Choose a deployment environment, model and assemble the app with available modules, and deploy the app to target environment. + - Choose a deployment environment, assemble the app with available templates per needs, and then deploy the app to target environment. Below is how this workflow looks like: ![alt](resources/how-it-works.png) -This template based workflow make it possible for platform team enforce best practices and deployment confidence with a set of Kubernetes CRDs, and give end users a *PaaS-like* experience (*i.e. app-centric, higher level abstractions, self-service operations etc*) by natural. +This design make it possible for platform team to enforce best practices by *coding* platform capabilities into templates, and leverage them to expose end users with a *PaaS-like* experience (*i.e. app-centric abstractions, self-service workflow etc*). + +Also, as programmable components, these templates can be updated or extended easily per your needs at any time. ![alt](resources/what-is-kubevela.png) -Below are the core concepts in KubeVela that make this happen. +In the model layer, KubeVela leverages [Open Application Model (OAM)](https://oam.dev) to make above design happen. ## `Application` The *Application* is the core API of KubeVela. It allows developers to work with a single artifact to capture the complete application deployment with simplified primitives. @@ -62,13 +62,11 @@ spec: image: "fluentd" ``` -## Building the Abstraction - The `Application` resource in KubeVela is a LEGO-style object and does not even have fixed schema. Instead, it is composed by building blocks (app components and traits etc.) that allow you to on-board platform capabilities to this application definition via your own abstractions. -The building blocks to abstraction and model platform capabilities named `ComponentDefinition` and `TraitDefinition`. +The building blocks to model platform capabilities named `ComponentDefinition` and `TraitDefinition`. -### ComponentDefinition +### `ComponentDefinition` `ComponentDefinition` is a pre-defined *template* for the deployable workload. It contains template, parametering and workload characteristic information as a declarative API resource. @@ -76,7 +74,7 @@ Hence, the `Application` abstraction essentially declares how the user want to * Some typical component definitions are *Long Running Web Service*, *One-time Off Task* or *Redis Database*. All component definitions expected to be pre-installed in the platform, or provided by component providers such as 3rd-party software vendors. -### TraitDefinition +### `TraitDefinition` Optionally, each component has a `.traits` section that augments the component instance with operational behaviors such as load balancing policy, network ingress routing, auto-scaling policies, or upgrade strategies, etc. @@ -95,6 +93,14 @@ The main concepts of KubeVela could be shown as below: ![alt](resources/concepts.png) +Essentially: +- Components - deployable/provisionable entities that composed your application deployment + - e.g. a Kubernetes workload, a MySQL database, or a AWS S3 bucket +- Traits - attachable operational features per your needs + - e.g. autoscaling rules, rollout strategies, ingress rules, sidecars, security policies etc +- Application - full description of your application deployment assembled with components and traits. +- Environment - the target environments to deploy this application + ## Architecture The overall architecture of KubeVela is shown as below: