KusionStack使用文档

下载安装

1. 安装 Kusionup

如果想自定义默认安装版本，可以运行下述命令（将最后的 open@latest 替换为你想要默认安装的版本号就就行）：

curl -s "http://kusion-public.oss-cn-hzfinance.aliyuncs.com/cli/kusionup/scripts/install_kusionup.sh" | bash -s -- --skip-install && source $HOME/.kusionup/env && kusionup reinstall open@latest

该脚本执行后会创建 $HOME/.kusionup 目录，该目录下会包含：

• $HOME/.kusionup/bin 目录用于放置 kusionup 二进制工具
• $HOME/.kusionup/env 文件用于声明 kusionup 和 kusion 技术栈所需要的环境变量
• $HOME/.kusionup/current 软链接用于标识当前激活的 kusion 版本
• $HOME/.kusionup/$VERSION 目录代表不同的 kusion 版本目录，比如默认安装的内部最新版本 $HOME/.kusionup/alipay@latest

2. 管理 Kusion 版本

执行完安装脚本后，默认已经安装好了 kusionup 和一个默认的 kusion 版本，你可以通过执行 kusionup 查看已安装的所有版本：

$ kusionup
Use the arrow keys to navigate: ↓ ↑ → ←
? Select a version:▸ alipay@latest

执行 kusionup ls-ver 列出来自内置安装源中的所有可安装的 **kusion** 版本：

$ kusionup ls-ver
alipay@latest
alipay@v0.3.16
alipay@v0.3.15
alipay@v0.3.14
open@latest

执行 kusionup install $VERSION 安装指定版本：

# 这里假设安装开源 kusion 的最新版本 ↓
$ kusionup install open@latest
Downloaded   0.0% (     2426 / 139988826 bytes) ...
Downloaded  11.4% ( 16003466 / 139988826 bytes) ...
Downloaded  21.0% ( 29433014 / 139988826 bytes) ...
Downloaded  32.2% ( 45077686 / 139988826 bytes) ...
Downloaded  41.9% ( 58642898 / 139988826 bytes) ...
Downloaded  51.2% ( 71647010 / 139988826 bytes) ...
Downloaded  61.6% ( 86258486 / 139988826 bytes) ...
Downloaded  71.2% ( 99667706 / 139988826 bytes) ...
Downloaded  81.5% (114078806 / 139988826 bytes) ...
Downloaded  91.5% (128134166 / 139988826 bytes) ...
Downloaded 100.0% (139988826 / 139988826 bytes)
INFO[0055] Unpacking /root/.kusionup/kusion-open@latest/kusion-linux.tgz ...
INFO[0061] Success: latest downloaded in /root/.kusionup/kusion-open@latest
INFO[0061] Default Kusion is set to 'open@latest'$ kusion version
releaseVersion: v0.3.16-9f700718 (open)  # ReleaseVersion 带 (open) 后缀的即为开源版本
......

执行 kusionup show 查看目前正在使用的 kusion 版本：

$ kusionup show
|    VERSION    | ACTIVE |
|---------------|--------|
| alipay@latest |        |
|  open@latest  |   *    |

执行 kusionup remove $VERSION 删除指定版本：

# 这里假设删除内部 kusion 的最新版本 ↓
$ kusionup remove alipay@latest
INFO[0000] Removing alipay@latest$ kusionup
Use the arrow keys to navigate: ↓ ↑ → ←
? Select a version:▸ open@latest  # 已经没有 alipay@latest 的选项了

Kubernetes应用部署

1. 初始化

以 KCL 和 Kusion 的方式部署应用服务，依赖 kusion 工具、Konfig 大库和 Kubernetes 集群。

打开 Konfig 大库项目，进入 appops 目录，初始化 KCL 项目：

#先克隆 Kusion 模型库：
git clone [e-mail]:OpenKus/Konfig.gitcd appops && kusion init

kusion init 命令会提示你输入可能需要的参数，例如项目名称、项目描述，镜像地址等；也可以一路点击 回车 使用默认值。输出类似于：

✔ deployment-single-stack    A minimal kusion project of single stack
This command will walk you through creating a new kusion project.Enter a value or leave blank to accept the (default), and press <ENTER>.
Press ^C at any time to quit.✔ project name: deployment-single-stack
✔ project description: A minimal kusion project of single stack
✔ Stack: dev
✔ ClusterName: kubernetes-dev
✔ Image: gcr.io/google-samples/gb-frontend:v4
Created project 'deployment-single-stack'

该项目的目录结构如下：

deployment-single-stack
├── README.md
├── base
│   └── base.k
├── dev
│   ├── ci-test
│   │   └── settings.yaml
│   ├── kcl.yaml
│   ├── main.k
│   └── stack.yaml
├── kusion.yaml
└── project.yaml3 directories, 8 files

2.添加/修改配置

一个应用的配置根据环境进行隔离，环境间的差异化配置存放到每个 Stack 目录中，环境间的通用配置存放在 base 目录中。

配置文件：

• dev/main.k：差异化配置
• base/base.k：通用配置

配置业务容器

appConfiguration: frontend.Server {# 业务容器配置mainContainer = container.Main {# 业务容器名称name = "main"# 环境变量env = [{name = "HOST_NAME"value = "example.com"}]# 端口号配置ports = [{ containerPort = 80 }]}
}

配置监控

通过将 enableMonitoring 设置为 True 使能配置，并添加业务容器端口号配置 8080

import base.pkg.kusion_models.kube.frontend
import base.pkg.kusion_models.kube.frontend.container
import base.pkg.kusion_models.kube.frontend.container.env as e
import base.pkg.kusion_models.kube.frontend.container.port as cp
import base.pkg.kusion_models.kube.frontend.container.probe as p# The application configuration in stack will overwrite 
# the configuration with the same attribute in base.
appConfiguration: frontend.Server {# Main container configurationmainContainer: container.Main {name = "prometheus-example-app"ports = [cp.ContainerPort {name = "web"containerPort = 8080}]}enableMonitoring = True
}

配置网络

在样例代码的 dev/main.k 或者 base/base.k 中添加 Service 配置：

import base.pkg.kusion_models.kube.frontend
import base.pkg.kusion_models.kube.frontend.serviceappConfiguration: frontend.Server {# 添加 Service 配置services = [service.Service {name = "app"type = "NodePort"ports = [{"port" = 80}]}]
}

镜像升级

编辑 dev/main.k 中的 image 的值:

import base.pkg.kusion_models.kube.frontendappConfiguration: frontend.Server {# 修改 image 的值为要升级的版本# 修改前：image = "gcr.io/google-samples/gb-frontend:v4"# 修改后：image = "gcr.io/google-samples/gb-frontend:v5"

应用扩缩容

通过编辑 schedulingStrategy.resource 的值来设置业务容器的资源规格。

有两个方法修改资源规格，一种是修改 resource 表达式中 cpu、memory 的值：

import base.pkg.kusion_models.kube.frontend
import base.pkg.kusion_models.kube.frontend.resource as resappConfiguration: frontend.Server {# 修改 resource 表达式中 cpu、memory 的值# 原值：schedulingStrategy.resource = "cpu=100m,memory=100Mi,disk=1Gi"# 新的值（应用扩容）：schedulingStrategy.resource = res.Resource {cpu = 500mmemory = 500Midisk = 1Gi}
}

另一种是使用预置的 resource 值替代原值来进行应用扩容：

import base.pkg.kusion_models.kube.frontend
import base.pkg.kusion_models.kube.templates.resource as res_tplappConfiguration: frontend.Server {# 使用预置的 resource 值替代原值来进行应用扩容：# 原值：schedulingStrategy.resource = "cpu=100m,memory=100Mi,disk=1Gi"# 新的值（应用扩容）：schedulingStrategy.resource = res_tpl.large
}

上述代码是样例配置，可以根据 SchedulingStrategy 模型定义和实际情况添加自定义配置：

import base.pkg.kusion_models.kube.frontend.resource as resschema SchedulingStrategy:""" SchedulingStrategy represents scheduling strategy.Attributes----------resource: str | res.Resource, default is "1<cpu<2,1Gi<memory<2Gi,disk=20Gi", required.A Pod-level attribute.Main container resource."""resource: str | res.Resource = "1<cpu<2,1Gi<memory<2Gi,disk=20Gi"

差异化配置

base/bask.k 中 Pod Label 的配置：

appConfiguration: frontend.Server {podMetadata.labels = {if __META_CLUSTER_NAME in ["minikube", "kind"]:cluster = __META_CLUSTER_NAMEelse:cluster = "other"}
}

通过以上 KCL 代码，根据Konfig中的魔术变量判断实际部署时的集群名称来选择性的为应用容器中注入标签，来做到被第三方服务识别或者其他目的。

容器启动参数

3. 配置编译

首先进入到项目的 Stack 目录（deployment-single-stack/dev）并执行编译：

cd deployment-single-stack/dev && kusion compile

输出默认保存在 deployment-single-stack/dev/ci-test/stdout.golden.yaml 文件中。

4. 配置生效

完成编译，现在开始下发配置。通过查看 stdout.golden.yaml 文件，可以看到 3 个资源：

• 一个 name 为 deployment-single-stackdev 的 Deployment
• 一个 name 为 deployment-single-stack 的 Namespace
• 一个 name 为 frontend-service 的 Service

可以使用 kubectl apply -f stdout.golden.yaml 直接下发配置， 也可以使用 kusion apply 完成配置编译并下发。

执行命令：

kusion apply

输出类似于：

SUCCESS  Compiling in stack dev...Stack: dev    Provider                Type                           Name    Plan* ├─  kubernetes        v1:Namespace     deployment-single-stack[0]  Create* ├─  kubernetes  apps/v1:Deployment  deployment-single-stackdev[0]  Create* └─  kubernetes          v1:Service            frontend-service[0]  Create✔ yes
Start applying diffs......SUCCESS  Creating Namespace/deployment-single-stack     SUCCESS  Creating Deployment/deployment-single-stackdevSUCCESS  Creating Service/frontend-service
Creating Service/frontend-service [3/3] ███████████████████████████████████████████ 100% | 0sApply complete! Resources: 3 created, 0 updated, 0 deleted.

以上就完成了配置生效，可以使用 kubectl 工具检查资源的实际状态。

1、 检查 Namespace

kubectl get ns

输出类似于：

NAME                      STATUS        AGE
argocd                    Active        59d
default                   Active        72d
deployment-single-stack   Active        10m

2、检查 Deployment

kubectl get deploy -n deployment-single-stack

输出类似于：

NAME                         READY   UP-TO-DATE   AVAILABLE   AGE
deployment-single-stackdev   1/1     1            1           11m

3、检查 Service

kubectl get svc -n deployment-single-stack

输出类似于：

NAME               TYPE       CLUSTER-IP     EXTERNAL-IP   PORT(S)        AGE
frontend-service   NodePort   10.111.95.95   <none>        80:30226/TCP   11m

4、检查应用

使用 kubecl 工具，将本机端口 30000 映射到 Service 端口 80

kubectl port-forward svc/frontend-service -n deployment-single-stack-xx 30000:80

打开浏览器访问 http://127.0.0.1:30000

应用场景

1. 单租户场景：应用和环境

在某些通用场景，我们可以对集群的概念进一步进行抽象为环境，一个应用通常需要部署到多个环境，比如测试、预发、生产。在单租户场景中，一个推荐的做法是将 Project 映射为应用，Stack 映射为环境。

概念	映射为
Project	应用
Stack	环境

2.多租户场景：应用和环境

在多租户场景中且以应用为核心的运维体系中，一种推荐做法是在应用名中添加租户信息，应用名在不同租户间是唯一的，即 Project 映射为多租户间唯一应用，Project 的 Name 是多租户间唯一应用名，Stack 映射为该应用下的环境配置。

概念	映射为
Project	多租户间唯一的应用名称
Stack	环境