define cloud native app

SUMMARY.md

@@ -17,6 +17,12 @@
   * [云原生编程语言 Ballerina](cloud-native/cloud-native-programming-language-ballerina.md)
   * [云原生编程语言 Pulumi](cloud-native/cloud-native-programming-language-pulumi.md)
 * [云原生的未来](cloud-native/the-future-of-cloud-native.md)
+* [定义云原生应用](cloud-native/define-cloud-native-app.md)
+  * [Workload](cloud-native/workload.md)
+  * [Component](cloud-native/component.md)
+  * [Trait](cloud-native/trait.md)
+  * [Application Scope](cloud-native/application-scope.md)
+  * [Application Configuration](cloud-native/application-configuration.md)
 
 ## 概念与原理
 

cloud-native/application-configuration.md

@@ -0,0 +1,45 @@
+# Application Configuration
+
+本文基于 OAM v1alpha2 版本。
+
+`ApplicationConfiguration` 将 `Component` 与 `Trait` 组合，定义了一个应用程序的配置，`Component` 每部署一次就会产生一个实例（`Instance`），实例是可以被升级的（包括回滚和重新部署），而每次部署和升级就会产生一次新的发布（`Release`）。
+
+{{% alert title="关于 Release" color="primary" %}}
+[12 因素应用](https://12factor.net/zh_cn/)严格区分[构建、发布、运行](https://12factor.net/zh_cn/build-release-run)这三个步骤。每次构建和修改配置后都会产生一次新的发布（`Release`）。OAM 中将 `Component`、`Trait`、`ApplicaitonScope` 组合而成的 `ApplicationConfiguration` 即等同于 `Release`。每次对 `ApplciationConfiguration` 的更新都会创建一个新的 `Release`（跟 [Helm](https://helm.sh) 中的 `Release` 概念一致）。
+{{% /alert %}}
+
+下面是一个 `ApplicationConfiguration` 示例。
+
+```yaml
+apiVersion: core.oam.dev/v1alpha2
+kind: ApplicationConfiguration
+metadata:
+  name: my-app
+  annotations:
+    version: v1.0.0
+    description: "My first application deployment."
+spec:
+  components:
+    - componentName: my-component
+      parameterValues:
+        - name: PARAMETER_NAME
+          value: SUPPLIED_VALUE
+        - name: ANOTHER_PARAMETER
+          value: "AnotherValue"
+      traits:
+        - name: manualscaler.core.oam.dev
+          version: v1
+          spec:
+            replicaCount: 3
+      scopes:
+        - scopeRef:
+            apiVersion: core.oam.dev/v1alpha2
+            kind: NetworkScope
+            name: my-network
+```
+
+关于 `ApplicationConfiguration` 的详细信息参考 OAM 中的 [ApplicationConfiguration 规范](https://github.com/oam-dev/spec/blob/master/7.application_configuration.md)。
+
+## 参考
+
+- [The Open Application Model specification - github.com](https://github.com/oam-dev/spec)

cloud-native/application-scope.md

@@ -0,0 +1,39 @@
+本文基于 OAM v1alpha2 版本。
+
+`ApplicationScope` 根据 `Component` 中的应用逻辑或共同行为划定作用域，将其分组以便于管理。
+
+`ApplicationScope` 具有以下特征：
+
+- 一个 `Component` 可能属于一个或多个 `ApplicationScope`；
+- 有的 `ApplicationScope` 可以限定其中是否可以部署同一个 `Component` 的多个实例；
+- `ApplicationScope` 可以作为 `Component` 与基础设施的连接层，提供身份、网络或安全能力；
+- `Trait` 可以根据 `Component` 中定义的 `ApplicationScope` 来执行适当的运维特性；
+
+目前 OAM 中支持的核心应用范围类型有 [`NetworkScope`](https://github.com/oam-dev/spec/blob/master/standard/scopes/network_scope.md) 和 [`HealthScope`](https://github.com/oam-dev/spec/blob/master/standard/scopes/health_scope.md)。
+
+下面是使用 `NetworkScope` 来声明作用域的示例：
+
+```yaml
+apiVersion: core.oam.dev/v1alpha2
+kind: NetworkScope
+metadata:
+  name: my-network
+  labels:
+    region: my-region
+    environment: production
+spec:
+  networkId: my-network
+  subnetIds:
+  - my-subnetwork-01
+  - my-subnetwork-02
+  - my-subnetwork-03
+  internetGatewayType: nat
+```
+
+上面的示例的作用是将三个子网划定为一组网络边界，这通常是使用 VPC 实现。
+
+关于 `ApplicationScope` 的详细信息请参考 OAM 中的 [ApplicationScope 规范](https://github.com/oam-dev/spec/blob/master/5.application_scopes.md)。
+
+## 参考
+
+- [The Open Application Model specification - github.com](https://github.com/oam-dev/spec)

cloud-native/component.md

@@ -0,0 +1,43 @@
+# Component
+
+本文基于 OAM v1alpha2 版本。
+
+`Component` 用于定义应用程序的基本组件，其中包含了对 Workload 的引用，一个 Component 中只能定义一个 Workload，这个 Workload 是与平台无关的，可以直接引用 Kubernetes 中的 CRD。
+
+下面是根据 OAM 规范定义的一个 Component 示例。
+
+```yaml
+apiVersion: core.oam.dev/v1alpha2
+kind: Component
+metadata:
+  name: my-component
+spec:
+  workload:
+    apiVersion: core.oam.dev/v1alpha2
+    kind: ContainerizedWorkload
+    spec:
+      os: linux
+      containers:
+        - name: server
+          image: my-image:latest
+  parameters:
+  - name: myServerImage
+    required: true
+    fieldPaths:
+    - ".spec.containers[0].image"
+```
+
+`Component`  定义由以下几个部分组成：
+
+- `metadata`：关于 Component 的信息，主要是针对应用运维的信息。
+- `workload`：该 Component 的实际工作负载。具体有哪些负载类型可用可以咨询平台提供商，平台运维也可以根据 [Workload 规范](https://github.com/oam-dev/spec/blob/master/3.workload.md) 来扩展负载类型，比如 `Containers`、`Functions`、`VirtualMachine`、[`VirtualService `](https://istio.io/docs/reference/config/networking/virtual-service/) 等。OAM 目前定义的核心负载类型有 [ContainerizedWorkload](https://github.com/oam-dev/spec/blob/master/core/workloads/containerized_workload/containerized_workload.md)（与 Kubernetes 中的 [Pod 定义](https://kubernetes.io/zh/docs/concepts/workloads/pods/pod/)类似，同样支持定义多个容器，但是缺少了 Pod 中的一些属性 ）。
+- `parameters`：在应用程序运行时可以调整的参数，即应用开发者在 `Component` 中的原有定义可以在运行时被应用运维人员覆盖。`parameters` 使用 [JSONPath](https://kubernetes.io/zh/docs/reference/kubectl/jsonpath/) 的方式引用 `spec` 中的字段。
+
+> `Component` 的配置在应用后是**可更改的（Mutable）**， 有的 [`Trait`](trait.md) 可能会监听 `Component` 的变更并作出相应的操作，每次变更都会导致新的 `ApplicationConfiguration` 发布。
+>
+
+关于 Component 的详细信息请参考 OAM 中的 [Component 规范](https://github.com/oam-dev/spec/blob/master/4.component.md)。
+
+## 参考
+
+- [The Open Application Model specification - github.com](https://github.com/oam-dev/spec)

cloud-native/define-cloud-native-app.md

@@ -0,0 +1,40 @@
+# 定义云原生应用
+
+本文参考的是 [OAM 规范](https://github.com/oam-dev/spec)中对云原生应用的定义，并做出了引申。
+
+云原生应用是一个相互关联但又不独立的组件（service、task、worker）的集合，这些组件与配置结合在一起并在适当的运行时实例化后，共同完成统一的功能目的。
+
+## 云原生应用模型
+
+下图是 OAM 定义的云原生应用模型示意图，为了便于理解，图中相同颜色的部分为同一类别的对象定义。
+
+![云原生应用模型](../images/cloud-native-app-model.png)
+
+OAM 的规范中定义了以下对象，它们既是 OAM 规范中的基本术语也是云原生应用的基本组成。
+
+- **[Workload](../spec/workload)（工作负载）**：应用程序的工作负载类型，由平台提供。
+- **[Component](../spec/component)（组件）**：定义了一个 `Workload` 的实例，并以基础设施中立的术语声明其运维特性。
+- **[Trait](../spec/trait)（特征）**：用于将运维特性分配给组件实例。
+- **[ApplicationScope](../spec/application-scope)（应用作用域）**：用于将组件分组成具有共同特性的松散耦合的应用。
+- **[ApplicationConfiguration](../spec/application-configuration)（应用配置）**：描述 `Component` 的部署、`Trait` 和 `ApplicationScope`。
+
+OAM 规范中提供了一个使用以上对象定义云原生应用的[工作流示例](https://github.com/oam-dev/spec/blob/master/examples/workflow.md)。
+
+## 关注点分离
+
+下图是不同角色对于该模型的关注点示意图。
+
+![云原生应用模型中的目标角色](../images/roles.png)
+
+我们可以看到对于一个云原生应用来说，不同的对象是由不同的角色来负责的：
+
+- 基础设施运维：提供不同的 `Workload` 类型供开发者使用；
+- 应用运维：定义适用于不同 `Workload` 的运维属性 `Trait` 和管理 `Component` 的 `ApplicationScope` 即作用域；
+- 应用开发者：负责应用组件 `Component` 的定义；
+- 应用开发者和运维：共同将 `Component` 与运维属性 `Trait` 绑定在一起，维护应用程序的生命周期；
+
+基于 OAM 中的对象定义的云原生应用可以充分利用平台能力自由组合，开发者和运维人员的职责可以得到有效分离，组件的复用性得到大幅提高。
+
+## 参考
+
+- [The Open Application Model specification - github.com](https://github.com/oam-dev/spec)

cloud-native/play-with-kubernetes.md

@@ -17,19 +17,19 @@
 
 启动第一个实例作为Master节点，在web终端上执行：
 
-1. 初始化master节点：
+**1.** 初始化master节点：
 
 ```bash
 kubeadm init --apiserver-advertise-address $(hostname -i)
 ```
 
-2. 初始化集群网络：
+**2.** 初始化集群网络：
 
 ```bash
 kubectl apply -n kube-system -f  "https://cloud.weave.works/k8s/net?k8s-version=$(kubectl version | base64 | tr -d '\n')"
 ```
 
-3. 执行下列初始化命令：
+**3.** 执行下列初始化命令：
 
 ```bash
 mkdir -p $HOME/.kube
@@ -37,7 +37,7 @@ cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
 chown $(id -u):$(id -g) $HOME/.kube/config
 ```
 
-4. 启动新的实例作为node节点，根据master节点上的提示，在新的web终端上执行：
+**4.** 启动新的实例作为node节点，根据master节点上的提示，在新的web终端上执行：
 
 ```bash
 kubeadm join --token 513212.cfea0165b8988d18 192.168.0.13:6443 --discovery-token-ca-cert-hash sha256:b7b6dcc98f3ead3f9e363cb3928fbc04774ee0d63e8eb2897ae30e05aebf8070

cloud-native/trait.md

@@ -0,0 +1,43 @@
+# Trait
+
+本文基于 OAM v1alpha2 版本。
+
+`Trait` 用于定义 `Component` 的运维属性，是对 `Component` 运行时的叠加，需要通过 `ApplicationConfiguration` 的配置将其与 `Component` 绑定，用于动态修改 `Component` 中 `workload` 的行为。
+
+不同的 `Trait` 可能适用于不同的 `Component`（因为不同的 `Component` 中的  `workload` 可能不同，因此它们的运维特性也可能不同），如流量路由规则（如负载均衡策略、入口路由、出口路由、百分比路由、限流、熔断、超时限制、故障注入等）、自动缩放策略、升级策略、发布策略等。
+
+`Trait` 还具有以下几个特征：
+
+- `Trait` 是根据在 `Component` 中引用的顺序应用的，如果某些运维特征本身具有依赖性，可以通过显式排序来解决；
+- 对于某一类型的 `Trait` 在同一个 `Component` 实例只能应用一个；
+- 在应用 `Trait` 时，需要进行冲突检查，如果一组 `Trait` 的特性不能满足运维组合，则判定为不合法；
+
+将运维属性从应用组件本身的定义（ `Component`）中剥离有如下几个好处：
+
+- `Trait` 通常由应用运维人员定义和维护，而不需要应用开发人员参与，应用开发人员对 `Trait` 可能无感知，减轻了应用开发人员的负担；
+- `Trait` 将云原生应用程序的一些通用运维属性从应用配置中剥离出来，大大提高了运维逻辑的可复用性；
+- 应用 `Trait` 组合前进行运维特性检查，可以有效防止配置冲突和无法预期的情况发生；
+
+下面是根据 OAM 规范定义的一个 Trait 示例。
+
+```yaml
+apiVersion: core.oam.dev/v1alpha2
+kind: TraitDefinition
+metadata:
+  name: manualscalertrait.core.oam.dev
+spec:
+  appliesToWorkloads:
+    - core.oam.dev/v1alpha2.ContainerizedWorkload
+  definitionRef:
+    name: manualscalertrait.core.oam.dev
+```
+
+> CR  即 Custom Resource（自定义资源），指的是实例化后的 Kubernetes [CRD](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)。`definitionRef` 将 `Trait` shcema 在 OAM 解释器中注册，通过增加一个抽象层，使其与 Operator 框架解耦（毕竟不是说有 CRD 都是面向应用开发者的）。
+
+OAM 中将 `Trait` 分成了 `core.oam.dev`（核心）、`standard.oam.dev`（标准）及自定义扩展类别。一个 `Trait` 具体适用于哪些 `workload` 可以在 `Trait` 的 `TraitDefinition` 中定义。目前 OAM 中支持的核心 `Trait` 有 [`ManualScalerTrait`](https://github.com/oam-dev/spec/blob/master/core/traits/manual_scaler_trait.md)。
+
+关于 Trait 的详细请参考 OAM 中的 [Trait 规范](https://github.com/oam-dev/spec/blob/master/6.traits.md)。
+
+## 参考
+
+- [The Open Application Model specification - github.com](https://github.com/oam-dev/spec)

cloud-native/workload.md

@@ -0,0 +1,29 @@
+# Workload
+
+本文基于 OAM v1alpha2 版本。
+
+应用程序可用的 `Workload` 类型是由平台提供商和基础设施运维人员提供的。`Workload` 模型参照 [Kubernetes 规范](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields)定义，理论上，平台商可以定义如容器、Pod、Serverless 函数、虚拟机、数据库、消息队列等任何类型的 `Workload`。
+
+下面是一个 `Workload` 定义的是示例。
+
+```yaml
+apiVersion: core.oam.dev/v1alpha2
+kind: WorkloadDefinition
+metadata:
+  name: schema.example.jimmysong.io
+spec:
+  definitionRef:
+    name: schema.example.jimmysong.io
+```
+
+> CR 即 Custom Resource（自定义资源），指的是实例化后的 Kubernetes [CRD](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)。应用开发者可以在 `Component` 的 `Workload` 中直接定义 CR。`definitionRef` 将 `Workload` shcema 在 OAM 解释器中注册，通过增加一个抽象层，使其与 Operator 框架解耦（毕竟不是说有 CRD 都是面向应用开发者的），表示可作为负载类型使用。
+
+请保持 `spec.definitionRef.name` 的值与 `metadata.name` 的值相同，因为 `definitionRef` 是对相应的 `Workload` schema 的引用，对于 Kubernetes 平台来说，即对 [CRD](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) 的引用。应用开发者在定义 [`Component`](component.md) 引用该 `Workload` 的时候需要直接实例化一个 CRD 的配置（及创建一个 CR）。
+
+OAM 中将 `Workload` 分成了 `core.oam.dev`（核心）、`standard.oam.dev`（标准）及自定义扩展类别。目前 OAM 中支持的核心 `Workload` 有 [`ContainerizedWorkload`](https://github.com/oam-dev/spec/blob/master/core/workloads/containerized_workload/containerized_workload.md)。
+
+关于 Workload 的详细信息参考 OAM 中的 [Workload 规范](https://github.com/oam-dev/spec/blob/master/3.workload.md)。
+
+## 参考
+
+- [The Open Application Model specification - github.com](https://github.com/oam-dev/spec)