「译文」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'] , inventory，mysql
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 用于标识应用程序分组中的组件名称。

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