# Secret
LLMS index: [llms.txt](/llms.txt)
---
Secret 是一种包含少量敏感信息例如密码、令牌或密钥的对象。
这样的信息可能会被放在 Pod
规约中或者镜像中。使用 Secret 意味着你不需要在应用程序代码中包含机密数据。
由于创建 Secret 可以独立于使用它们的 Pod，
因此在创建、查看和编辑 Pod 的工作流程中暴露 Secret（及其数据）的风险较小。
Kubernetes 和在集群中运行的应用程序也可以对 Secret 采取额外的预防措施，
例如避免将敏感数据写入非易失性存储。
Secret 类似于 ConfigMap
但专门用于保存机密数据。
注意：
默认情况下，Kubernetes Secret 未加密地存储在 API 服务器的底层数据存储（etcd）中。
任何拥有 API 访问权限的人都可以检索或修改 Secret，任何有权访问 etcd 的人也可以。
此外，任何有权限在命名空间中创建 Pod 的人都可以使用该访问权限读取该命名空间中的任何 Secret；
这包括间接访问，例如创建 Deployment 的能力。
为了安全地使用 Secret，请至少执行以下步骤：
- 为 Secret 启用静态加密。
- 以最小特权访问 Secret 并启用或配置 RBAC 规则。
- 限制 Secret 对特定容器的访问。
- 考虑使用外部 Secret 存储驱动。
有关管理和提升 Secret 安全性的指南，请参阅
Kubernetes Secret 良好实践。
说明：
以句点开头的文件会在 ls -l 的输出中被隐藏起来；
列举目录内容时你必须使用 ls -la 才能看到它们。
apiVersion: v1
kind: Secret
metadata:
name: dotfile-secret
data:
.secret-file: dmFsdWUtMg0KDQo=
---
apiVersion: v1
kind: Pod
metadata:
name: secret-dotfiles-pod
spec:
volumes:
- name: secret-volume
secret:
secretName: dotfile-secret
containers:
- name: dotfile-test-container
image: registry.k8s.io/busybox
command:
- ls
- "-l"
- "/etc/secret-volume"
volumeMounts:
- name: secret-volume
readOnly: true
mountPath: "/etc/secret-volume"
### 使用场景：仅对 Pod 中一个容器可见的 Secret {#use-case-secret-visible-to-one-container-in-a-pod}
考虑一个需要处理 HTTP 请求，执行某些复杂的业务逻辑，之后使用 HMAC
来对某些消息进行签名的程序。因为这一程序的应用逻辑很复杂，
其中可能包含未被注意到的远程服务器文件读取漏洞，
这种漏洞可能会把私钥暴露给攻击者。
这一程序可以分隔成两个容器中的两个进程：前端容器要处理用户交互和业务逻辑，
但无法看到私钥；签名容器可以看到私钥，并对来自前端的简单签名请求作出响应
（例如，通过本地主机网络）。
采用这种划分的方法，攻击者现在必须欺骗应用服务器来做一些其他操作，
而这些操作可能要比读取一个文件要复杂很多。
### Secret 的替代方案 {#alternatives-to-secrets}
除了使用 Secret 来保护机密数据，你也可以选择一些替代方案。
下面是一些选项：
- 如果你的云原生组件需要执行身份认证来访问你所知道的、在同一 Kubernetes 集群中运行的另一个应用，
你可以使用 [ServiceAccount](/zh-cn/docs/reference/access-authn-authz/authentication/#service-account-tokens)
及其令牌来标识你的客户端身份。
- 你可以运行的第三方工具也有很多，这些工具可以运行在集群内或集群外，提供机密数据管理。
例如，这一工具可能是 Pod 通过 HTTPS 访问的一个服务，该服务在客户端能够正确地通过身份认证
（例如，通过 ServiceAccount 令牌）时，提供机密数据内容。
- 就身份认证而言，你可以为 X.509 证书实现一个定制的签名者，并使用
[CertificateSigningRequest](/zh-cn/docs/reference/access-authn-authz/certificate-signing-requests/)
来让该签名者为需要证书的 Pod 发放证书。
- 你可以使用一个[设备插件](/zh-cn/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/)
来将节点本地的加密硬件暴露给特定的 Pod。例如，你可以将可信任的 Pod
调度到提供可信平台模块（Trusted Platform Module，TPM）的节点上。
这类节点是另行配置的。
你还可以将如上选项的两种或多种进行组合，包括直接使用 Secret 对象本身也是一种选项。
例如：实现（或部署）一个 Operator，
从外部服务取回生命期很短的会话令牌，之后基于这些生命期很短的会话令牌来创建 Secret。
运行在集群中的 Pod 可以使用这些会话令牌，而 Operator 则确保这些令牌是合法的。
这种责权分离意味着你可以运行那些不了解会话令牌如何发放与刷新的确切机制的 Pod。
## Secret 的类型 {#secret-types}
创建 Secret 时，你可以使用
[Secret](/zh-cn/docs/reference/kubernetes-api/config-and-storage-resources/secret-v1/)
资源的 `type` 字段，或者与其等价的 `kubectl` 命令行参数（如果有的话）为其设置类型。
Secret 类型有助于对 Secret 数据进行编程处理。
Kubernetes 提供若干种内置的类型，用于一些常见的使用场景。
针对这些类型，Kubernetes 所执行的合法性检查操作以及对其所实施的限制各不相同。
| 内置类型 | 用法 |
|--------------|-------|
| `Opaque` | 用户定义的任意数据 |
| `kubernetes.io/service-account-token` | 服务账号令牌 |
| `kubernetes.io/dockercfg` | `~/.dockercfg` 文件的序列化形式 |
| `kubernetes.io/dockerconfigjson` | `~/.docker/config.json` 文件的序列化形式 |
| `kubernetes.io/basic-auth` | 用于基本身份认证的凭据 |
| `kubernetes.io/ssh-auth` | 用于 SSH 身份认证的凭据 |
| `kubernetes.io/tls` | 用于 TLS 客户端或者服务器端的数据 |
| `bootstrap.kubernetes.io/token` | 启动引导令牌数据 |
通过为 Secret 对象的 `type` 字段设置一个非空的字符串值，你也可以定义并使用自己
Secret 类型（如果 `type` 值为空字符串，则被视为 `Opaque` 类型）。
Kubernetes 并不对类型的名称作任何限制。不过，如果你要使用内置类型之一，
则你必须满足为该类型所定义的所有要求。
如果你要定义一种公开使用的 Secret 类型，请遵守 Secret 类型的约定和结构，
在类型名前面添加域名，并用 `/` 隔开。
例如：`cloud-hosting.example.net/cloud-api-credentials`。
### Opaque Secret
当你未在 Secret 清单中显式指定类型时，默认的 Secret 类型是 `Opaque`。
当你使用 `kubectl` 来创建一个 Secret 时，你必须使用 `generic`
子命令来标明要创建的是一个 `Opaque` 类型的 Secret。
例如，下面的命令会创建一个空的 `Opaque` 类型的 Secret：
```shell
kubectl create secret generic empty-secret
kubectl get secret empty-secret
```
输出类似于：
```
NAME TYPE DATA AGE
empty-secret Opaque 0 2m6s
```
`DATA` 列显示 Secret 中保存的数据条目个数。
在这个例子中，`0` 意味着你刚刚创建了一个空的 Secret。
### ServiceAccount 令牌 Secret {#service-account-token-secrets}
类型为 `kubernetes.io/service-account-token` 的 Secret 用来存放标识某
ServiceAccount
的令牌凭据。这是为 Pod 提供长期有效 ServiceAccount 凭据的传统机制。
在 Kubernetes v1.22 及更高版本中，推荐的方法是通过使用
[`TokenRequest`](/zh-cn/docs/reference/kubernetes-api/authentication-resources/token-request-v1/) API
来获取短期自动轮换的 ServiceAccount 令牌。你可以使用以下方法获取这些短期令牌：
- 直接调用 `TokenRequest` API，或者使用像 `kubectl` 这样的 API 客户端。
例如，你可以使用
[`kubectl create token`](/zh-cn/docs/reference/generated/kubectl/kubectl-commands#-em-token-em-) 命令。
- 在 Pod 清单中请求使用[投射卷](/zh-cn/docs/reference/access-authn-authz/service-accounts-admin/#bound-service-account-token-volume)挂载的令牌。
Kubernetes 会创建令牌并将其挂载到 Pod 中。
当挂载令牌的 Pod 被删除时，此令牌会自动失效。
更多细节参阅[启动使用服务账号令牌投射的 Pod](/zh-cn/docs/tasks/configure-pod-container/configure-service-account/#launch-a-pod-using-service-account-token-projection)。
使用这种 Secret 类型时，你需要确保对象的注解 `kubernetes.io/service-account-name`
被设置为某个已有的 ServiceAccount 名称。
如果你同时创建 ServiceAccount 和 Secret 对象，应该先创建 ServiceAccount 对象。
当 Secret 对象被创建之后，某个 Kubernetes
控制器会填写
Secret 的其它字段，例如 `kubernetes.io/service-account.uid` 注解和
`data` 字段中的 `token` 键值（该键包含一个身份认证令牌）。
下面的配置实例声明了一个 ServiceAccount 令牌 Secret：
apiVersion: v1
kind: Secret
metadata:
name: secret-sa-sample
annotations:
kubernetes.io/service-account.name: "sa-name"
type: kubernetes.io/service-account-token
data:
extra: YmFyCg==
创建了 Secret 之后，等待 Kubernetes 在 `data` 字段中填充 `token` 主键。
参考 [ServiceAccount](/zh-cn/docs/concepts/security/service-accounts/)
文档了解 ServiceAccount 的工作原理。你也可以查看
[`Pod`](/docs/reference/generated/kubernetes-api/v1.36/#pod-v1-core)
资源中的 `automountServiceAccountToken` 和 `serviceAccountName` 字段文档，
进一步了解从 Pod 中引用 ServiceAccount 凭据。
### Docker 配置 Secret {#docker-config-secrets}
如果你要创建 Secret 用来存放用于访问容器镜像仓库的凭据，则必须选用以下 `type`
值之一来创建 Secret：
- `kubernetes.io/dockercfg`：存放 `~/.dockercfg` 文件的序列化形式，它是配置 Docker
命令行的一种老旧形式。Secret 的 `data` 字段包含名为 `.dockercfg` 的主键，
其值是用 base64 编码的某 `~/.dockercfg` 文件的内容。
- `kubernetes.io/dockerconfigjson`：存放 JSON 数据的序列化形式，
该 JSON 也遵从 `~/.docker/config.json` 文件的格式规则，而后者是 `~/.dockercfg`
的新版本格式。使用此 Secret 类型时，Secret 对象的 `data` 字段必须包含
`.dockerconfigjson` 键，其键值为 base64 编码的字符串包含 `~/.docker/config.json`
文件的内容。
下面是一个 `kubernetes.io/dockercfg` 类型 Secret 的示例：
apiVersion: v1
kind: Secret
metadata:
name: secret-dockercfg
type: kubernetes.io/dockercfg
data:
.dockercfg: |
eyJhdXRocyI6eyJodHRwczovL2V4YW1wbGUvdjEvIjp7ImF1dGgiOiJvcGVuc2VzYW1lIn19fQo=
说明：
如果你不希望执行 base64 编码转换，可以使用 stringData 字段代替。
注意：
auths 值是 base64 编码的，其内容被屏蔽但未被加密。
任何能够读取该 Secret 的人都可以了解镜像库的访问令牌。
建议使用凭据提供程序来动态、
安全地按需提供拉取 Secret。
apiVersion: v1
kind: Secret
metadata:
name: secret-basic-auth
type: kubernetes.io/basic-auth
stringData:
username: admin # kubernetes.io/basic-auth 类型的必需字段
password: t0p-Secret # kubernetes.io/basic-auth 类型的必需字段
说明：
Secret 的 stringData 字段不能很好地与服务器端应用配合使用。
apiVersion: v1
kind: Secret
metadata:
name: secret-ssh-auth
type: kubernetes.io/ssh-auth
data:
# 此例中的实际数据被截断
ssh-privatekey: |
MIIEpQIBAAKCAQEAulqb/Y ...
提供 SSH 身份认证类型的 Secret 仅仅是出于方便性考虑。
你可以使用 `Opaque` 类型来保存用于 SSH 身份认证的凭据。
不过，使用预定义的、公开的 Secret 类型（`kubernetes.io/tls`）
有助于其他人理解你的 Secret 的用途，也可以就其中包含的主键名形成约定。
Kubernetes API 会验证这种类型的 Secret 中是否设定了所需的主键。
注意：
SSH 私钥自身无法建立 SSH 客户端与服务器端之间的可信连接。
需要其它方式来建立这种信任关系，以缓解“中间人（Man In The Middle）”
攻击，例如向 ConfigMap 中添加一个 known_hosts 文件。
apiVersion: v1
kind: Secret
metadata:
name: secret-tls
type: kubernetes.io/tls
data:
# 值为 base64 编码，这样会掩盖它们，但不会提供任何有用的机密性级别
# 注意：将以下值替换为你自己的base64编码的证书和密钥。
tls.crt: "REPLACE_WITH_BASE64_CERT"
tls.key: "REPLACE_WITH_BASE64_KEY"
提供 TLS 类型的 Secret 仅仅是出于方便性考虑。
你可以创建 `Opaque` 类型的 Secret 来保存用于 TLS 身份认证的凭据。
不过，使用已定义和公开的 Secret 类型（`kubernetes.io/tls`）有助于确保你自己项目中的 Secret 格式的一致性。
API 服务器会验证这种类型的 Secret 是否设定了所需的主键。
要使用 `kubectl` 创建 TLS Secret，你可以使用 `tls` 子命令：
```shell
kubectl create secret tls my-tls-secret \
--cert=path/to/cert/file \
--key=path/to/key/file
```
公钥/私钥对必须事先存在，`--cert` 的公钥证书必须采用 `.PEM` 编码，
并且必须与 `--key` 的给定私钥匹配。
### 启动引导令牌 Secret {#bootstrap-token-secrets}
`bootstrap.kubernetes.io/token` Secret 类型针对的是节点启动引导过程所用的令牌。
其中包含用来为周知的 ConfigMap 签名的令牌。
启动引导令牌 Secret 通常创建于 `kube-system` 名字空间内，并以
`bootstrap-token-<令牌 ID>` 的形式命名；
其中 `<令牌 ID>` 是一个由 6 个字符组成的字符串，用作令牌的标识。
以 Kubernetes 清单文件的形式，某启动引导令牌 Secret 可能看起来像下面这样：
apiVersion: v1
kind: Secret
metadata:
name: bootstrap-token-5emitj
namespace: kube-system
type: bootstrap.kubernetes.io/token
data:
auth-extra-groups: c3lzdGVtOmJvb3RzdHJhcHBlcnM6a3ViZWFkbTpkZWZhdWx0LW5vZGUtdG9rZW4=
expiration: MjAyMC0wOS0xM1QwNDozOToxMFo=
token-id: NWVtaXRq
token-secret: a3E0Z2lodnN6emduMXAwcg==
usage-bootstrap-authentication: dHJ1ZQ==
usage-bootstrap-signing: dHJ1ZQ==
启动引导令牌类型的 Secret 会在 `data` 字段中包含如下主键：
- `token-id`：由 6 个随机字符组成的字符串，作为令牌的标识符。必需。
- `token-secret`：由 16 个随机字符组成的字符串，包含实际的令牌机密。必需。
- `description`：供用户阅读的字符串，描述令牌的用途。可选。
- `expiration`：一个使用 [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339)
来编码的 UTC 绝对时间，给出令牌要过期的时间。可选。
- `usage-bootstrap-`：布尔类型的标志，用来标明启动引导令牌的其他用途。
- `auth-extra-groups`：用逗号分隔的组名列表，身份认证时除被认证为
`system:bootstrappers` 组之外，还会被添加到所列的用户组中。
你也可以在 Secret 的 `stringData` 字段中提供值，而无需对其进行 base64 编码：
apiVersion: v1
kind: Secret
metadata:
# 注意 Secret 的命名方式
name: bootstrap-token-5emitj
# 启动引导令牌 Secret 通常位于 kube-system 名字空间
namespace: kube-system
type: bootstrap.kubernetes.io/token
stringData:
auth-extra-groups: "system:bootstrappers:kubeadm:default-node-token"
expiration: "2020-09-13T04:39:10Z"
# 此令牌 ID 被用于生成 Secret 名称
token-id: "5emitj"
token-secret: "kq4gihvszzgn1p0r"
# 此令牌还可用于 authentication （身份认证）
usage-bootstrap-authentication: "true"
# 且可用于 signing （证书签名）
usage-bootstrap-signing: "true"
说明：
Secret 的 stringData 字段不能很好地与服务器端应用配合使用。
apiVersion: v1
kind: Pod
metadata:
name: mypod
spec:
containers:
- name: mypod
image: redis
volumeMounts:
- name: foo
mountPath: "/etc/foo"
readOnly: true
volumes:
- name: foo
secret:
secretName: mysecret
optional: true
默认情况下，Secret 是必需的。在所有非可选的 Secret 都可用之前，Pod
的所有容器都不会启动。
如果 Pod 引用了非可选 Secret 中的特定键，并且该 Secret 确实存在，但缺少所指定的键，
则 Pod 在启动期间会失败。
### 在 Pod 以文件形式使用 Secret {#using-secrets-as-files-from-a-pod}
如果你要在 Pod 中访问来自 Secret 的数据，一种方式是让 Kubernetes 将该 Secret
的值以文件的形式呈现，该文件存在于 Pod 中一个或多个容器内的文件系统内。
相关的指示说明，
可以参阅[创建一个可以通过卷访问 Secret 数据的 Pod](/zh-cn/docs/tasks/inject-data-application/distribute-credentials-secure/#create-a-pod-that-has-access-to-the-secret-data-through-a-volume)。
当卷中包含来自 Secret 的数据，而对应的 Secret 被更新，Kubernetes
会跟踪到这一操作并更新卷中的数据。更新的方式是保证最终一致性。
说明：
对于以 subPath
形式挂载 Secret 卷的容器而言，它们无法收到自动的 Secret 更新。
注意：
在提供你自己的 SSH 密钥之前要仔细思考：集群的其他用户可能有权访问该 Secret。
你也可以创建一个 SSH 私钥，代表一个你希望与你共享 Kubernetes 集群的其他用户分享的服务标识。
当凭据信息被泄露时，你可以收回该访问权限。
说明：
特殊字符（例如 $、\、*、= 和 !）会被你的
Shell 解释，因此需要转义。
在大多数 Shell 中，对密码进行转义的最简单方式是用单引号（'）将其括起来。
例如，如果你的实际密码是 S!B\*d$zDsb，则应通过以下方式执行命令：
kubectl create secret generic dev-db-secret --from-literal=username=devuser --from-literal=password='S!B\*d$zDsb='
你无需对文件中的密码（--from-file）中的特殊字符进行转义。
特性状态：
Kubernetes v1.21 [stable]
Kubernetes 允许你将特定的 Secret（和 ConfigMap）标记为 **不可更改（Immutable）**。
禁止更改现有 Secret 的数据有下列好处：
- 防止意外（或非预期的）更新导致应用程序中断
- （对于大量使用 Secret 的集群而言，至少数万个不同的 Secret 供 Pod 挂载），
通过将 Secret 标记为不可变，可以极大降低 kube-apiserver 的负载，提升集群性能。
kubelet 不需要监视那些被标记为不可更改的 Secret。
### 将 Secret 标记为不可更改 {#secret-immutable-create}
你可以通过将 Secret 的 `immutable` 字段设置为 `true` 创建不可更改的 Secret。
例如：
```yaml
apiVersion: v1
kind: Secret
metadata:
...
data:
...
immutable: true
```
你也可以更改现有的 Secret，令其不可更改。
说明：
一旦一个 Secret 或 ConfigMap 被标记为不可更改，撤销此操作或者更改 data
字段的内容都是不可能的。
只能删除并重新创建这个 Secret。现有的 Pod 将维持对已删除 Secret
的挂载点 —— 建议重新创建这些 Pod。
警告：
在一个节点上以 privileged: true 运行的所有容器可以访问该节点上使用的所有 Secret。
