From 104c33403e852ea4026359ae28c9efbaf195606e Mon Sep 17 00:00:00 2001 From: Harry Zhang Date: Fri, 30 Oct 2020 21:29:17 -0700 Subject: [PATCH] Follow up introduction doc --- README.md | 4 +- docs/introduction.md | 135 ++++++++----------------------------------- 2 files changed, 27 insertions(+), 112 deletions(-) diff --git a/README.md b/README.md index f6e61522b..5f0030d1e 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ # KubeVela -For developers, KubeVela is an easy-to-use tool that enables developers to describe and ship their applications with simple commands. +For developers, KubeVela is an easy-to-use tool that enables them to describe and ship their applications to Kubernetes with minimal effort. -For platform engineers, KubeVela is an extensible engine where platform builders can create something more complex on top of, in an easy and Kubernetes native approach. +For platform builders, KubeVela serves as a framework that empowers them to create developer facing yet highly extensible platforms at ease. - Slack: [Discuss](https://cloud-native.slack.com/archives/C01BLQ3HTJA) - Gitter: [Community](https://gitter.im/oam-dev/community) diff --git a/docs/introduction.md b/docs/introduction.md index 88ff63850..464a6634b 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -4,145 +4,60 @@ ## Motivation -The modern trends of cloud-native application management have moved towards -pursuing a simplified developer experience across clouds and infrastructures. -As the dominating cloud-native platform, Kubernetes, excellently -abstracts the infrastructure details and manages application lifecycle in -a consistent manner. However, many application developers -believe that Kubernete is not an easy platform to use. The primary reason -is that Kuberntes exposes full levels of API details in order to enable -flexible users control. Despite the flexibility, it leads to a few problems. +The modern trend of cloud-native technology is moving towards pursuing consistent application delivery across clouds and on-premises infrastructures using Kubernetes as the common abstraction layer. Kubernetes, although excellent in abstracting low-level infrastructure details, does introduce another layer of complexity to application developers, namely understanding the concepts of pods, port exposing, privilege escalation, resource claims, CRD, and so on. We’ve seen such a nontrivial learning curve and the lack of developer-facing abstraction have impacted user experience, slowed down productivity, led to unexpected errors or misconfigurations in production. People start questioning the value of this revolution: "why am I bothered with that many YAML files?". -Firstly, application developers have to understand quite a few new -concepts and resource specifications before deploying their applications. -Sometimes, this is not an easy task. For example, it may take a while -for developers to understand some runtime related configurations -such as `allowPrivilegeEscalation` which they rarely touch in daily work. -The pervasive use of CRDs makes the situation even worse since developers -have to learn all the CRD schemas as well. +On the other hand, abstracting Kubernetes to serve developers' needs is a highly opinionated process, and the resultant abstractions would only make sense had the decision makers been the platform builders. Unfortunately, the platform builders today face the following dilemma: -Moreover, since in Kubernetes developers have to know all of -the configuration details of involved objects, application management soon -becomes a headache of handling a large amount of resource YAML files. -We have seen that the lack of API abstraction had led to low productivity, -unexpected errors or misconfigurations in production. Application developers -start to question "why am I bothered with these many YAML files?" +*There is no tool or framework for them to easily extend the abstractions if any*. -On the other hand, Kubernetes is a platform for platforms. Literally, the extended -capabilities provided by the platform builders are the keys to support the -Kubenetes ecosystems. Nowadays, a typical production Kubernetes would install -dozens of customized operators and plugins. Since abstracting the Kubernetes -APIs is a highly opinionated process, the resultant simplified interfaces -would only make sense had the decision makers been the platform builders. -Unfortunately, the platform builders today face the following dilemmas when -dealing with the API abstraction: +Thus, many platforms today introduce restricted abstractions, implementations and add-on mechanisms despite the extensibility of Kubernetes. This makes extending such platforms per developers' requirements or to wider scenarios almost impossible, not to mention taking the full advantage of the extremely rich Kubernetes ecosystems. -- There is no tool or framework for them to easily extend the API abstraction - if any. They have to rely on existing interfaces or assumptions for new - capabilities which may be only suitable for specific user cases. - This makes extending such platform to leverage broader Kubernetes ecosystems - almost impossible. - -- It could be painful to develop new capability based on existing interfaces. - The operator design could easily becomes a marathon negotiation in order - to meet the abstraction requirement. - -In the end, application developers may complain that Kubernetes is hard to use -and the platform builders may want to help but they cannot do it easily. +In the end, developers complain those platforms are too rigid and slow in response to feature requests or improvements. The platform engineers do want to help but the engineering effort is daunting: any simple API change in the platform could easily become a marathon negotiation around the opinionated abstraction design. ## What is KubeVela? -KubeVela is a framework to help platform builders to easily expose and extend -Kubernetes capabilities for application management. It is built on top of -Kubernetes and relieves the pains of both the platform builders and the application -developers by doing the following: +For developers, KubeVela itself is an easy-to-use tool that enables them to describe and ship their applications to Kubernetes with minimal effort. Instead of managing a handful Kubernetes YAML files, a simple docker-compose style [Appfile](./docs/developers/devex/appfile.md) is all they need, following an application-centric workflow that can be easily integrated with any CI/CD pipeline. -- KubeVela enforces a single **application** concept and **ALL** the exposed - Kubernetes capabilities serve for the applications only. - It adopts the [Open Application Model](https://github.com/oam-dev/spec) (OAM) - for its application definition. The conventional Pod and container concepts - are completely eliminated. +The above experience cannot be achieved without KubeVela's innovative offerings to platform builders. + +For platform builders, KubeVela serves as a framework that empowers them to create developer facing yet highly extensible platforms at ease. In details, KubeVela relieves the pains of building such platforms by doing the following: + +- Application Centric. Behind the Appfile, KubeVela enforces the corresponding **application** concept as its main API and **ALL** KubeVela's capabilities serve for the applications' needs only. This is achieved by adopting the [Open Application Model](https://github.com/oam-dev/spec) as the core API for the platform. -- A KubeVela application is composed of various supported components or - [traits](https://github.com/oam-dev/spec/blob/master/introduction.md) and their - schemas are determined by the platform builders. New capabilities can be added - to KubeVela through a CRD registry mechanism. +- Extending Natively. An application in KubeVela is composed of various pluggable workload types and operation features (i.e. traits). Capabilities from Kubernetes ecosystem can be added to KubeVela as new workload types or traits through Kubernetes CRD registry mechanism at any time. -- KubeVela provides a rich set of tools to help platform builders to abstract - the Kubernetes resource and CRD APIs. - For example, a [CUELang](https://github.com/cuelang/cue) based templating tool - is used to easily build the contract between the user-facing schemas and the - underline Kubernetes Objects. KubeVela provides a set of built-in CUE templates - for platform builders to start with. - -- Schema changes take effect immediately. Neither recompiliation nor redeployment - of KubeVela is required. This makes the process of delivering new capabilities - using KubeVela extremely simple. +- Simple yet Extensible Abstraction Mechanism. KubeVela's main user interfaces （i.e. Appfile and CLI) are built with [CUELang](https://github.com/cuelang/cue) as the abstraction engine between the user-facing schemas and the underline Kubernetes resources. KubeVela provides a set of built-in abstractions to start with and platform administrators are free to modify them at any time. Abstraction changes take effect at runtime, neither recompilation nor redeployment of KubeVela is required. -With KubeVela, platform builders now have indefinite flexibilities in designing -and implementing new capabilities without worrying about what and how to expose -the new capabilities to the end users. However, the ultimate beneficiaries are -the application developers: -- Instead of managing a handful Kubernetes YAML files, only a simple - docker-compose style [appfile](./docs/developers/devex/appfile.md) is needed - to manage an application in KubeVela. -- Out of the box, KubeVela provides a CLI tool to simplify the application - management workflow which can be easily integrated with existing CI/CD pipelines. +With KubeVela, platform builders now finally have the tooling support to design and ship any new capabilities to their end-users with high confidence and low turn around time. ## Comparisons ### Platform-as-a-Service (PaaS) -The typical examples are Heroku and Cloud Foundry. They also provide full -application management capabilities and aim to improve developer experience -and efficiency. KubeVela shares the same goal but its built-in features are -much lighter and easier to maintain compared to most of the existing PaaS offerings. -KubeVela core components are nothing but a set of Kubernetes controllers/plugins. +The typical examples are Heroku and Cloud Foundry. They provides full application management capabilities and aim to improve developer experience and efficiency. KubeVela shares the same goal but its built-in features are much lighter and easier to maintain compared to most of the existing PaaS offerings. KubeVela core components are nothing but a set of Kubernetes controllers/plugins. -The biggest difference lies in the extensibility. Most PaaS systems enforce -constraints in the type of supported applications and the supported capabilities. -They are either inextensible or create their own addon systems maintained by the -user communities. In contrast, KubeVela is built on top of Kubernetes, -and all the supported capabilities are implemented by Kubernetes CRD controllers. -No additional addon system is introduced. A new capability can be installed in -KubeVela at any time by simply registering the CRD in KubeVela. +Though the biggest difference lies in the extensibility. +Most PaaS systems enforce constraints in the type of supported applications and the supported capabilities. They are either inextensible or create their own addon systems maintained by the their own communities. In contrast, KubeVela is designed to fully leverage the Kubernetes ecosystem as its capability pool. Hence, there's no additional addon system is introduced in this project. A new capability can be installed in KubeVela at any time by simply registering the CRD and providing a CUElang template. ### Serverless platforms -Serverless platform such as AWS Lambda provides extraordinary user experience -and agility to deploy serverless applications. However, those platforms impose -even more constraints in extensibility. They are argurably "hard-coded" PaaS. +Serverless platform such as AWS Lambda provides extraordinary user experience and agility to deploy serverless applications. However, those platforms impose even more constraints in extensibility. They are arguably "hard-coded" PaaS. -Kubernetes based serverless platforms such as Knative, OpenFaaS can be easily -integrated with KubeVela by registering themself as platform capabilities. -Even for AWS Lambda, there is an success story to integrate it with KubeVela -by the tools developed by Crossplane. +Kubernetes based serverless platforms such as Knative, OpenFaaS can be easily integrated with KubeVela by registering themselves as new workload types and traits. Even for AWS Lambda, there is an success story to integrate it with KubeVela by the tools developed by Crossplane. ### Platform agnostic developer tools -The typical example is [Waypoint](https://github.com/hashicorp/waypoint). It is -a user facing tool which introduces a consistent workflow (i.e., build, -deploy, release) for developers to ship applications on top of different platforms. -KubeVela can be integrated into Waypoint like any other supported platforms. -In this case, developers can use the Waypoint workflow instead of the KubeVela -CLI to manage applications. +The typical example is [Waypoint](https://github.com/hashicorp/waypoint). Waypoint is a developer facing tool which introduces a consistent workflow (i.e., build, deploy, release) to ship applications on top of different platforms. +KubeVela can be integrated into Waypoint like any other supported platforms. In this case, developers will use the Waypoint workflow instead of the KubeVela Appfile/CLI to manage applications, and all the capabilities of KubeVela including abstractions will still be available in this integration. -### Package management tools +### Helm, etc. -People may mistakenly think KubeVela is another package manager like Helm. -Although using Helm chart significantly reduces the burden of managing a -complicated Kubernetes application, whoever prepares the helm chart cannot avoid -the tedious and error-prone work of packaging those YAML files. +Helm is a package manager for Kubernetes that provides package, install, and upgrade a set of YAML files for Kubernetes as a unit. -KubeVela aims to fundamentally remove the need of managing conventional Kubernetes -YAML files. However, in the server side, KubeVela still relies on Helm to package -and manage the third-party plugins such as `Prometheus`, etc. +KubeVela is not a package manager. Developers are expected to use KubeVela's Appfile to describe how to build and deploy application and that Appfile is not Kubernetes YAML format. However, the server side API object behind Appfile (i.e. `Application Configuration`) is indeed a Kubernetes CRD, it could be packaged and distributed by Helm at ease. ### Kubernetes -KubeVela can be treated as a special Kubernetes "distribution" that focuses on -developers and application management only. -It leverages the native Kubernetes extensibility to resolve a hard problem - making -application management enjoyable in Kubernetes. +KubeVela is a Kubernetes plugin for building application-centric abstractions. It leverages the native Kubernetes extensibility and capabilities to resolve a hard problem - making application management enjoyable on Kubernetes.