「译文」K8S 及 OpenShift 上应用程序的 Labels 和 Annotations 最佳实践

本文最后更新于:2024年7月24日 晚上

📚️ Quote:

原文链接:Guidelines for Labels and Annotations for OpenShift applications

术语

System

将价值传递给用户的最高抽象级别,无论用户是否是人类。一个 「System 」由一个或多个「Application」组成。

Application

一种抽象,它封装了软件系统交付的价值。一个应用程序由一个或多个「Component」组成。

Component

组件是一组 kubernetes 资源,用于承载代码或数据,为了使整个软件系统正常工作,这些资源需要运行。每个组件都是可单独部署和运行的单元。

Labels

下表定义了在 OpenShift 上部署的应用程序应该使用的常用标签,建议使用标记为 REC 的标签。标记为 OPT 的是可选的。操作上不应依赖标签。

你可以在以 Kubernetes 文档 中找到 app.kubernetes 为前缀的 Kubernetes 标签的更多信息

🔥 Tip:

标签必须应用到所有资源,DeploymentConfigs, BuildConfigs, Services, Routes, ConfigMaps, persistenvolumeccles 等,包括任何自定义资源定义 (crd)。

表 1 Labels

名字 状态 描述 示例
app.kubernetes.io/part-of REC 该资源所属的顶级 system 的名称 ticketmonster
app.kubernetes.io/name REC 组件的名称 mysql
app.kubernetes.io/component REC 这是该组件的角色 / 类型 frontend
app.kubernetes.io/managed-by OPT 用来管理组件操作的工具 odo/helm
app.kubernetes.io/instance REC 用于标识应用程序的唯一名称, 通常用在和 app.kubernetes.io/name 不一样的时候 accounts
app.kubernetes.io/version OPT 组件的当前版本(例如,语义版本,修订哈希,等等) 1.0.0
app.openshift.io/runtime OPT 用于引导组件的运行时 spring-boot
app.openshift.io/runtime-version: OPT 运行时的版本 e.g. 1.5.17 for Spring Boot

表 2 app.kubernetes.io/component label 的值

说明
frontend 为应用程序提供 UI 或部分 UI
backend 通常是运行在运行时或框架上的应用程序代码。
database 数据持久化
integration 集成中间件,如 API 网关或单点登录
cache 缓存,如 redis
queue 消息队列,如 RabbitMQ 或 Kafka

Annotations

表 3 Annotations

名称 状态 描述 示例
app.openshift.io/vcs-uri REC 版本控制下源代码的 URI git://git.kernel.org/pub/scm/linux.git
app.openshift.io/vcs-ref REC 源代码版本的标识符。可以是应用程序的 branch、tag 或 commit SHA。如果省略,则假定 master 为默认分支 v1.0.0
app.openshift.io/connects-to OPT app.openshift.io/connects-to 包括要连接的组件的 label app.kubernetes.io/instance 的值。 e.g. ['inventory','cart'] , inventorymysql
console.alpha.openshift.io/overview-app-route OPT 在控制台 UI 上注释您希望成为主路由的路由 console.alpha.openshift.io/overview-app-route: ‘true’

示例

简单的微服务与数据库

基于 Node.js 的 rest 服务,和数据库 (mongodb)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
@startuml
rectangle cool-service {
database mongodb [
\t<b>mongodb for storing data
----
<b>app.kubernetes.io/part-of :</b>cool-service
<b>app.kubernetes.io/name :</b> mongodb
<b>app.kubernetes.io/component :</b> database
<b>app.kubernetes.io/managed-by :</b> odo
<b>app.kubernetes.io/version :</b> 3.6
]
rectangle nodejs [
\t\t<b>The node.js service with code</b>
----
<b>app.kubernetes.io/part-of :</b> cool-service
<b>app.kubernetes.io/name :</b> nodejs
<b>app.kubernetes.io/component :</b> frontend
<b>app.kubernetes.io/managed-by :</b> odo
<b>app.kubernetes.io/version</b> : 1.0.1
<b>app.openshift.io/runtime</b>: nodejs
<b>app.openshift.io/runtime-version</b>: 10.14.1
----
<b>app.openshift.io/vcs-uri :</b> git://git@github.com:gorkem/cool-service.git
<b>app.openshift.io/vcs-ref :</b> master
<b>app.openshift.io/connects-to :</b> mongodb

]
nodejs --> mongodb

}

@enduml

简单的微服务与数据库

具有多个服务的复杂系统

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
@startuml
left to right direction

rectangle coolstore {
together {
rectangle inventory {
database postgresql [
<b>postgresql database
----
<b>app.kubernetes.io/part-of :</b> coolstore
<b>app.kubernetes.io/instance :</b> inventoryDB
<b>app.kubernetes.io/name :</b> postgresql
<b>app.kubernetes.io/component :</b> database
<b>app.kubernetes.io/managed-by :</b> odo
<b>app.kubernetes.io/version :</b> 11
]
rectangle nodeservice [
<b>The node.js service with code</b>
----
<b>app.kubernetes.io/part-of :</b> coolstore
<b>app.kubernetes.io/instance :</b> inventory
<b>app.kubernetes.io/name :</b> nodejs
<b>app.kubernetes.io/component :</b> backend
<b>app.kubernetes.io/managed-by :</b> odo
<b>app.kubernetes.io/version</b> : 10
<b>app.openshift.io/runtime</b>: nodejs
<b>app.openshift.io/runtime-version</b>: 10.14.1
----
<b>app.openshift.io/vcs-uri :</b> git://git@github.com:gorkem/inventory-service.git
<b>app.openshift.io/vcs-ref :</b> master

]
}
}

together {
rectangle cart{
node cart [
<b>The node.js service with code</b>
----
<b>app.kubernetes.io/part-of :</b> coolstore
<b>app.kubernetes.io/instance :</b> cart
<b>app.kubernetes.io/name :</b> nodejs
<b>app.kubernetes.io/component :</b> backend
<b>app.kubernetes.io/managed-by :</b> odo
<b>app.kubernetes.io/version</b> : 10
<b>app.openshift.io/runtime</b>: nodejs
<b> app.openshift.io/runtime-version</b>: 10.14.1
----
<b>app.openshift.io/vcs-uri :</b> git://git@github.com:gorkem/cart-service.git
<b>app.openshift.io/vcs-ref :</b> master
<b>app.openshift.io/connects-to :</b> '["inventory"]'
]
cart --> inventory
}
}
together {
rectangle catalog {
database catalogdb [
<b>mongodb for storing data
----
<b>app.kubernetes.io/part-of :</b> coolstore
<b>app.kubernetes.io/instance :</b> catalogDB
<b>app.kubernetes.io/name :</b> mongodb
<b>app.kubernetes.io/component :</b> database
<b>app.kubernetes.io/managed-by :</b> odo
<b>app.kubernetes.io/version :</b> 3.6
]
rectangle catalog [
<b>The node.js service with code</b>
----
<b>app.kubernetes.io/part-of :</b> coolstore
<b>app.kubernetes.io/instance :</b> catalog
<b>app.kubernetes.io/name :</b> nodejs
<b>app.kubernetes.io/component :</b> frontend
<b>app.kubernetes.io/managed-by :</b> odo
<b>app.kubernetes.io/version</b> : 10
<b>app.openshift.io/runtime</b>: nodejs
<b> app.openshift.io/runtime-version</b>: 10.14.1
----
<b>app.openshift.io/vcs-uri :</b> git://git@github.com:gorkem/catalog-service.git
<b>app.openshift.io/vcs-ref :</b> master
<b>app.openshift.io/connects-to :</b> '["cart"]'
]
catalog --> cart
}
}

}

@enduml

具有多个服务的复杂系统

🔥 Tip:

Label app.kubernetes.io/instance 应该指向一个有意义的标识符。Label app.kubernetes.io/part-of 用于标识应用程序分组,app.kubernetes.io/instance 用于标识应用程序分组中的组件名称。


「译文」K8S 及 OpenShift 上应用程序的 Labels 和 Annotations 最佳实践
https://ewhisper.cn/posts/11838/
作者
东风微鸣
发布于
2022年2月16日
许可协议