编辑“︁Kubernetes注解（Annotations）”︁（章节）

= Kubernetes注解（Annotations） =

== 介绍 ==
'''Kubernetes注解（Annotations）'''是一种键值对（key-value pairs）形式的元数据，用于为Kubernetes对象（如Pod、Service、Deployment等）附加非标识性信息。与标签（Labels）不同，注解的主要目的是提供辅助数据，而不是用于筛选或组织对象。注解通常用于存储工具、库或用户自定义的元数据，例如构建信息、版本控制或配置说明。

注解的键值对格式如下：
<pre>
metadata:
  annotations:
    key1: "value1"
    key2: "value2"
</pre>

== 注解的特点 ==
* '''非标识性'''：注解不会用于对象的筛选或分组。
* '''任意数据'''：值可以是任意字符串（包括JSON或YAML格式的结构化数据）。
* '''工具和库使用'''：常用于存储由外部系统（如CI/CD工具、监控系统）使用的信息。

== 注解 vs 标签 ==
{| class="wikitable"
|-
! 特性 !! 注解（Annotations） !! 标签（Labels）
|-
| 用途 || 存储元数据 || 标识和筛选对象
|-
| 筛选支持 || 不支持 || 支持（通过<code>kubectl get -l</code>）
|-
| 结构化数据 || 支持（如JSON） || 通常为简单字符串
|}

== 代码示例 ==
以下是一个在Pod定义中使用注解的示例：

<syntaxhighlight lang="yaml">
apiVersion: v1
kind: Pod
metadata:
  name: nginx-pod
  annotations:
    build-version: "1.2.3"
    git-repo: "https://github.com/example/nginx-config"
    description: "This pod runs the latest stable NGINX image"
spec:
  containers:
  - name: nginx
    image: nginx:latest
</syntaxhighlight>

=== 查看注解 ===
使用<code>kubectl describe</code>查看注解：
<syntaxhighlight lang="bash">
kubectl describe pod nginx-pod
</syntaxhighlight>

输出示例：
<pre>
Name:         nginx-pod
Namespace:    default
Annotations:  build-version: 1.2.3
              git-repo: https://github.com/example/nginx-config
              description: This pod runs the latest stable NGINX image
...
</pre>

== 实际应用场景 ==
=== 场景1：CI/CD流水线集成 ===
在部署时，CI/CD工具（如Jenkins或GitLab CI）可以添加构建信息：
<syntaxhighlight lang="yaml">
annotations:
  jenkins-build-id: "12345"
  deploy-timestamp: "2024-03-01T12:00:00Z"
</syntaxhighlight>

=== 场景2：监控与日志 ===
监控系统（如Prometheus）可能使用注解配置抓取规则：
<syntaxhighlight lang="yaml">
annotations:
  prometheus.io/scrape: "true"
  prometheus.io/port: "8080"
</syntaxhighlight>

=== 场景3：自定义调度逻辑 ===
注解可以传递调度策略给自定义调度器：
<syntaxhighlight lang="yaml">
annotations:
  scheduler.alpha.kubernetes.io/custom-rules: '{"preferredNode":"gpu-node"}'
</syntaxhighlight>

== 高级用法 ==
=== 结构化数据 ===
注解支持JSON或YAML格式的结构化数据：
<syntaxhighlight lang="yaml">
annotations:
  config: |
    {
      "log-level": "debug",
      "retry-count": 3
    }
</syntaxhighlight>

=== 动态注解管理 ===
通过<code>kubectl annotate</code>动态添加或修改注解：
<syntaxhighlight lang="bash">
# 添加注解
kubectl annotate pod nginx-pod owner="team-dev"

# 更新注解
kubectl annotate pod nginx-pod owner="team-qa" --overwrite
</syntaxhighlight>

== 注意事项 ==
* 注解的键名应遵循DNS子域格式（如<code>example.com/key</code>）。
* 避免存储大量数据（Kubernetes对注解的总大小有限制，通常为256KB）。
* 注解不可用于资源筛选或自动化操作（需使用标签）。

== 总结 ==
Kubernetes注解是一种灵活的元数据机制，适用于存储与对象相关的辅助信息。通过合理使用注解，可以增强工具链集成、调试和运维能力，同时不影响Kubernetes的核心功能。

[[Category:集成部署]]
[[Category:Kubernetes]]
[[Category:Kubernetes核心概念]]