1. Secret到底是什么先厘清它的边界和底层逻辑1.1 为什么有了ConfigMap还需要Secret上一篇文章聊Kubernetes存储时我们把ConfigMap和Secret放在一起讲过。但实际用下来很多同学对Secret的认知停留在ConfigMap的加密版这个层面这个理解既不准确也容易在后续使用中踩坑。Secret和ConfigMap在API结构上的确非常像都是Key-Value形式的数据都可以通过环境变量或文件挂载的方式注入到Pod里。但它们的定位完全不同。ConfigMap管的是不敏感的配置比如应用启动参数、日志级别、功能开关Secret管的是敏感的数据比如数据库密码、API Token、TLS私钥、镜像仓库认证信息。Kubernetes把这两类数据分开不是为了在存储上做区分而是为了在权限控制、审计策略、生命周期管理上能分别对待。比如团队内部可以约定ConfigMap由所有人共享、随便改Secret只有特定角色能看、能改改动还要走审批。这个管理语义上的差异才是Secret存在的核心意义。1.2 base64只是编码不是加密很多第一次接触Secret的人看到kubectl get secret xxx -o yaml里那串data字段全是base64字符串就以为Kubernetes已经帮我们加密了。这里我必须说清楚base64编码不是加密它只是把二进制数据转成了可打印文本用echo xxx | base64 -d一秒就能还原。Kubernetes默认的Secret存储方式是Etcd里的明文base64编码后存储也就是说任何能直接访问Etcd的人或者有权限执行kubectl get secret -o yaml的人都能看到明文内容。Secret真正提供的保护是访问控制而不是数据加密。如果你的环境对安全性要求很高比如金融、医疗场景需要开启Etcd加密存储Kubernetes从1.13开始支持通过--encryption-provider-config配置KMS或AES加密或者使用外部Secret管理工具比如云厂商的KMS、HashiCorp Vault来做Secret的加密和轮换。这篇文章我们聚焦Kubernetes原生的Secret用法但心里要有这根弦原生Secret的保密能力有边界。1.3 Secret的类型不止Opaque一种很多人以为Secret只有一种通用字符串键值对的形态其实Kubernetes内置了好几种Secret类型每种类型对应的使用场景不同type字段决定了Kubernetes如何处理和校验这份数据Secret类型适用场景关键字段Opaque普通密码、Token等任意键值对data/stringDatakubernetes.io/dockerconfigjson私有镜像仓库认证.dockerconfigjsonkubernetes.io/tlsTLS证书与私钥tls.crt、tls.keykubernetes.io/service-account-tokenServiceAccount token由系统自动管理bootstrap.kubernetes.io/token节点引导Token由系统自动管理kubernetes.io/basic-authHTTP Basic Authusername、passwordkubernetes.io/ssh-authSSH密钥ssh-privatekey日常开发中用得最多的是Opaque和dockerconfigjson。这篇文章我们主要聊这两种TLS证书的Secret也比较常用但原理上跟Opaque的挂载方式完全一样只是数据内容换成了证书和私钥理解了Opaque基本就一通百通。2. 创建Secret的四种姿势命令式、文件式、声明式、从现有文件生成2.1 命令式创建kubectl create secret generic最快上手的方式就是直接用kubectl create secret generic。假设我们要给一个后端应用配置数据库连接信息用户名是dbuser密码是dbpass2024可以用下面的命令kubectl create secret generic db-secret \ --from-literalusernamedbuser \ --from-literalpassworddbpass2024这里有个细节值如果包含特殊字符比如$、!、最好用单引号包起来防止Shell展开。比如--from-literalpasswordPss$w0rd!如果不加单引号Shell会把$w0rd当成变量替换结果密码就变了。用--from-literal适合键值对不多、临时创建的场景。键值对多了之后命令会变得很长也不好维护。这时候可以把值写进文件用--from-file来创建。2.2 从文件创建--from-file和--from-env-file--from-file的语义是把文件内容作为一个键值对的valuekey默认是文件名。比如我们有一个config.yaml文件内容是数据库配置host: 127.0.0.1 port: 3306然后执行kubectl create secret generic app-config --from-fileconfig.yaml生成的Secret里会有一个key叫config.yamlvalue是文件里的完整内容。如果你想自定义key名可以这样kubectl create secret generic app-config --from-fileapp-config./config.yaml这样key就是app-config。还有一种场景你手上有一个.env格式的文件里面是KEYVALUE的若干行。用--from-env-file可以一次把这些键值对全部导入kubectl create secret generic env-secret --from-env-file.env需要注意--from-env-file要求文件格式严格是KEYVALUE不能有多余的空格除非值本身带引号注释行会被忽略。这个方式适合从本地环境变量文件迁移到K8s场景。2.3 声明式YAML创建最推荐的方式生产环境里我强烈建议用YAML文件声明Secret然后kubectl apply -f。这样做的好处是内容可以进代码仓库注意只建议把不敏感的骨架提交敏感值通过变量替换或外部Secret管理注入、变更可以走GitOps流程、团队评审能看清改动内容。一个典型的Opaque Secret YAML长这样apiVersion: v1 kind: Secret metadata: name: db-secret type: Opaque data: username: ZGJ1c2Vy password: ZGJwYXNzMjAyNA这里的username和password的值必须是自己先算好的base64编码。怎么算Linux下用base64命令echo -n dbuser | base64 echo -n dbpass2024 | base64注意echo要用-n不然换行符也会被编码进去导致最终挂载到Pod里的值多一个换行。很多同学在这里踩坑明明YAML里的base64是对的挂载出去的值末尾就是多了一个回车程序判断密码匹配总是失败。原因多半就是编码时没加-n。如果你觉得手动算base64太麻烦可以改用stringData字段。stringData里的值直接写明文Kubernetes会在创建时自动帮你编码成base64并合并到data里apiVersion: v1 kind: Secret metadata: name: db-secret type: Opaque stringData: username: dbuser password: dbpass2024这里有个值得注意的行为stringData不是最终的存储字段。你kubectl apply之后再get -o yaml会发现stringData消失了所有内容都变成了data下的base64字符串。所以stringData只是写入时的便捷方式读取时永远看到的是data。2.4 从现有文件/目录生成kubectl create secret的进阶玩法如果你的证书或配置文件分散在多个路径下可以一次给多个--from-filekubectl create secret generic tls-cert \ --from-filetls.crt./server.crt \ --from-filetls.key./server.key也可以指定目录把目录下所有文件都打包成Secretkubectl create secret generic app-secret --from-file./configs/此时每个文件名就是一个key。这种方式适合需要一次性把整个配置目录注入Pod的场景。注意目录下不能有子目录否则会报错。2.5 用kubectl create生成YAML再二次修改还有一个小技巧先用--dry-runclient -o yaml把命令式创建转换成YAML然后保存文件后续再手工补充字段kubectl create secret generic db-secret \ --from-literalusernamedbuser \ --from-literalpassworddbpass2024 \ --dry-runclient -o yaml db-secret.yaml生成的YAML里data已经是base64编码好的。之后你可以决定直接apply或者在这个基础上加namespace、labels、annotations。这个方式特别适合命令式快速起底 声明式长期维护的混合工作流。3. 把Secret挂载成文件volumeMounts、路径映射与默认权限3.1 基本挂载方式把Secret当成Volume创建好Secret之后最常见的需求是让Pod里的应用读取它比如从/etc/secrets下读密码文件。实现方式是在PodSpec里声明一个volume类型为secret然后挂载到容器指定路径。一个完整的Deployment示例apiVersion: apps/v1 kind: Deployment metadata: name: app spec: replicas: 1 selector: matchLabels: app: app template: metadata: labels: app: app spec: containers: - name: app image: myapp:latest volumeMounts: - name: db-secret-volume mountPath: /etc/secrets readOnly: true volumes: - name: db-secret-volume secret: secretName: db-secret这段配置执行后Secret里的每个key都会变成一个文件名value是文件内容。比如db-secret里有两个keyusername和password那么容器的/etc/secrets目录下就会出现username文件和password文件内容分别是明文dbuser和dbpass2024。这里的执行逻辑是什么Kubernetes的kubelet会在Pod启动前从API Server拉取Secret对象在节点本地生成一个临时目录把每个key写成文件然后以Volume挂载的方式绑定到容器里。应用进程看到的是一次普通的文件系统访问它根本不知道数据来自Secret。3.2 路径映射不想用key名当文件名怎么办有些应用会硬编码配置文件路径比如固定读取/app/config/db.properties。但Secret里的key可能叫db.properties也可能叫database-properties。如果不想为了一个key去改应用代码可以使用items字段做路径映射。items的作用是选哪些key以及把每个key映射成什么文件名。比如Secret里有三个keyusername、password、host但我们只想挂载username和password而且希望password在容器里显示成pass.txtvolumes: - name: db-secret-volume secret: secretName: db-secret items: - key: username path: user.txt - key: password path: pass.txt这样容器里/etc/secrets下就只有user.txt和pass.txt两个文件host不会出现。这个特性在做最小权限暴露时很有用——不需要把整个Secret的所有key全部给容器。需要注意一旦使用了items就必须为你想要的每个key都写出映射未列出的key都会忽略。如果你既想挂载大部分key又要个别改名可以把要改名的key单独写进items其他省略的key就都不能挂了。3.3 挂载目录与文件冲突一个经典的坑这里有个非常经典的坑几乎每个用过Secret挂载的人都遇到过如果你把mountPath指向一个已有内容的目录比如/app/config而这个目录在镜像里本来就有文件那么挂载之后Secret只会把它的key文件叠加到该目录原来的文件不可见实际是做了一个覆盖隐藏原目录内容仍然在但在容器内看不到。不止是SecretConfigMap的挂载也有同样行为。这是Kubernetes Volume挂载的固有语义挂载点会覆盖下层目录的可见性。解决办法主要有两种把Secret挂到镜像里不存在的空目录比如/etc/secrets然后在应用里配置读取这个目录。使用subPath只挂载单个文件而不是挂整个目录。subPath的用法如下volumeMounts: - name: db-secret-volume mountPath: /app/config/db.properties subPath: db.properties readOnly: true注意subPath引用的是文件在Volume中的路径也就是Secret的key名如果有items映射则是映射后的文件名。如果你没写items就直接写subPath: db.properties表示只把db.properties这个文件挂到/app/config/db.properties路径不会覆盖/app/config目录下的其他文件。不过subPath有一个代价它不支持Secret自动更新后面会细聊。所以能不用subPath就尽量不用挂到独立目录更省心。3.4 默认权限与defaultModeSecret文件挂载后的默认权限是0644owner可读写其他人可读。如果你的应用对权限敏感比如读取私钥文件要求0600可以通过defaultMode声明修改volumes: - name: db-secret-volume secret: secretName: db-secret defaultMode: 0600这样所有key文件的权限都变成0600。也可以针对单个key设置权限但defaultMode已经覆盖99%的场景。还有个容易忽略的点defaultMode在YAML里写的是八进制数字但要写成没有前导0的数字0600在Kubernetes API里会被解析成十进制384效果一样。如果用helm模板要注意别用strconv.Atoi强行转换直接整数就行。3.5 挂载之后如何更新是自动还是手动Secret作为Volume挂载到Pod后Kubelet会通过watch机制监听Secret变化。当Secret更新时kubelet会周期性地默认约1分钟把新内容同步到容器内的挂载文件。也就是说不用重启Pod文件内容也会变。但这里有两个坑Secret更新后已经存在的Pod里的文件不会即时更新有延迟官方文档说kubelet定期同步实测基本在1分钟内。更新同步的是整个挂载点里的文件。如果你用了subPath挂载那么子路径挂载的内容不会自动更新必须重启Pod才能生效。所以生产环境里如果应用支持动态读取配置文件用完整的Secret Volume挂载最合适如果应用只能在启动时加载一次配置改完Secret之后还是老老实实滚动重启一下Pod吧。4. 通过环境变量注入Secretenv、envFrom与依赖顺序4.1env方式把某个key转成环境变量很多应用不读文件而是从环境变量里取配置。Kubernetes也支持把Secret的值注入成环境变量。方法是在容器定义里写env用valueFrom.secretKeyRef来引用containers: - name: app image: myapp:latest env: - name: DB_USERNAME valueFrom: secretKeyRef: name: db-secret key: username - name: DB_PASSWORD valueFrom: secretKeyRef: name: db-secret key: password这样容器启动后环境变量DB_USERNAME的值就是Secret里username对应的明文值。这里我要强调一个细节环境变量的注入发生在容器进程启动前。也就是说如果Secret在Pod运行期间被更新环境变量不会跟着变。这个和Volume挂载的自动更新机制不同很多同学在排查为什么我改了Secret环境变量还是旧值时基本都会栽在这里。如果你确实需要动态更新配置优先用文件挂载如果你只能接受环境变量那么更新Secret后必须重启Pod。4.2envFrom方式批量导入当Secret里的key特别多比如有十来个配置项一个个写env会很啰嗦。envFrom可以把整个Secret的所有key全部变成环境变量containers: - name: app image: myapp:latest envFrom: - secretRef: name: db-secret这样db-secret里的username、password、host等key会直接变成username、password、host三个环境变量。注意key名本身就是环境变量名所以Secret的key必须符合环境变量命名规范比如不能有-不能用数字开头。否则Kubernetes在注入时会跳过不合法的key而且不会报错只是在Event里打一条警告。排查问题的时候如果发现某个环境变量一直不存在先看看key名合不合法。envFrom可以和env混用。当同一个环境变量名在envFrom和env里都有定义时env也就是显式声明的会覆盖envFrom导入的值。这个特性可以用来做默认值覆盖值的配置策略。4.3 环境变量引用的编译顺序Kubernetes在创建容器时环境变量之间可以有依赖关系。比如URL依赖HOST和PORTenv: - name: DB_HOST value: 127.0.0.1 - name: DB_PORT value: 3306 - name: DB_URL value: $(DB_HOST):$(DB_PORT)这种$(VAR)的展开方式同样适用于secretKeyRef的值。但有个注意点先声明DB_HOST和DB_PORT再声明DB_URL顺序不能反。Kubernetes是按照env列表顺序逐条处理的如果DB_URL出现在依赖项之前$(DB_HOST)不会被展开。4.4 Secret与ConfigMap混用时的优先级一个Pod里往往既有ConfigMap又有Secret。比如非敏感的配置放ConfigMap密码放Secret。你可以用envFrom混着引用envFrom: - configMapRef: name: app-config - secretRef: name: db-secret这里的优先级规则是列表后面的会覆盖前面的。上面的例子里如果app-config和db-secret里有同名的key最终值以db-secret为准。反过来写则ConfigMap优先。建议把需要被团队模板默认值覆盖的放前面把最终生效值的放后面这样语义清晰。4.5 要不要用immutable字段一个权衡Kubernetes从1.19开始支持Secret的immutable: true。设置之后这个Secret就不能被修改和删除只能整体删除再重建。这么做有两个好处性能不可变的Secret不需要被Kubelet监听更新减少API Server的负载。安全防止误操作导致线上配置被改。但代价也很明显你想改一个值只能重建Secret同时还得重启Pod让新值生效。我的建议是对于密钥类数据密码、Token用immutable是合理的因为密钥本来就该轮换轮换时重建Secret滚动更新Pod是标准操作。对于半配置类数据比如功能开关别用immutable你会想频繁调整的。5. 存储私有仓库认证信息从dockerconfigjson到imagePullSecrets5.1 为什么Kubernetes需要专门的Secret类型拉镜像Kubernetes节点的kubelet在从私有镜像仓库拉取镜像时需要提供仓库的用户名密码。这个认证信息不能写在Pod的YAML里也不能指望每个节点都手动配置docker login节点多了根本维护不过来。Kubernetes的做法是把私有仓库的认证信息保存成kubernetes.io/dockerconfigjson类型的Secret然后在PodSpec里通过imagePullSecrets引用。需要注意imagePullSecrets是Pod级别的字段意味着同一个namespace下的每个Pod都要声明一次。如果你有几十个Deployment都要用私有镜像逐个加imagePullSecrets会非常烦。解决办法有两个一是把imagePullSecrets写进Deployment模板这是最常见的做法二是给ServiceAccount配置imagePullSecrets这样所有使用该ServiceAccount的Pod自动继承。5.2 手动创建dockerconfigjson Secret假设你的私有仓库地址是registry.example.com用户名是ops密码是ops-pass-2024。在Kubernetes里这个Secret的内容本质上是一份docker CLI的config.json文件结构大致是这样{ auths: { registry.example.com: { username: ops, password: ops-pass-2024, auth: b3BzOm9wcy1wYXNzLTIwMjQ } } }其中auth是username:password的base64编码。你不需要手动去拼这个JSON直接用kubectl create secret docker-registry命令kubectl create secret docker-registry regcred \ --docker-serverregistry.example.com \ --docker-usernameops \ --docker-passwordops-pass-2024 \ --docker-emailopsexample.com--docker-email不是必填项但国内很多私有仓库或云厂商镜像仓库会校验邮箱建议填真实可用的邮箱。创建之后查看kubectl get secret regcred -o yaml会看到type: kubernetes.io/dockerconfigjsondata下有一个.dockerconfigjson字段里面就是上面那段JSON的base64编码。5.3 从已有docker CLI配置创建如果你本机已经通过docker login登录过某个私有仓库那么~/.docker/config.json里已经有认证信息。可以直接用它来创建Secretkubectl create secret docker-registry regcred \ --from-file.dockerconfigjson$HOME/.docker/config.json这条命令会读取config.json文件并转换为Secret。注意~/.docker/config.json里可能包含多个仓库的认证信息最好先确认只有你要用的那个仓库否则会把本机所有仓库凭据都带到集群里存在一定泄露风险。5.4 在Pod/Deployment中使用imagePullSecrets创建好regcred之后在Deployment里加上引用spec: template: spec: imagePullSecrets: - name: regcred containers: - name: app image: registry.example.com/team/app:v1.0.0这样kubelet拉取registry.example.com/team/app:v1.0.0时就会自动使用regcred里的认证信息。如果Pod一直处于ImagePullBackOff状态kubectl describe pod里通常会看到unauthorized: authentication required或pull access denied的错误这时先确认imagePullSecrets是否写对、Secret是否在同一个namespace下。还有一个隐藏细节imagePullSecrets只在Pod调度到的节点上生效API Server不参与镜像拉取。kubelet会把Secret内容下发到节点本地使用。所以不用担心Secret在节点间广播只要节点不被打到凭据不会出现在无关节点上。但如果集群节点的持久化出问题理论上凭据会落在节点磁盘的kubelet缓存里所以生产环境还是建议给节点开启加密磁盘或限制节点访问权限。5.5 给ServiceAccount统一配置免去逐个声明如果namespace里大部分Pod用的都是同一个私有仓库你可以给默认ServiceAccount绑定imagePullSecretskubectl patch serviceaccount default \ -p {imagePullSecrets: [{name: regcred}]}之后创建Pod时如果不显式声明imagePullSecretskubelet会从Pod绑定的ServiceAccount里获取imagePullSecrets并用于拉镜像。这个机制让新Pod自动获得拉取私有镜像的权限省去了每天重复写的麻烦。但要小心如果你在Pod里显式声明了imagePullSecrets它会完全覆盖ServiceAccount的配置而不是合并。所以如果你给Pod同时声明了另一个Secret那么ServiceAccount上的regcred就不会生效。5.6 私有仓库认证的其他变体ECR/ACR等云厂商仓库云厂商的镜像仓库多数是临时认证模式用户名密码经常轮换。比如某云厂商的容器镜像服务会提供专门的临时登录指令这时候你可以把临时凭据编排进CI流程每次发版前重新创建Secret再滚动更新Deployment。我在实际项目中是这样处理的在CI里拉取临时凭据生成dockerconfigjson Secret然后kubectl rollout restart deployment。注意Secret的name要保持不变否则需要同步修改Deployment里的imagePullSecrets。6. 实战排查路径与经验总结那些文档里不会写的事6.1 排查链路Pod拉不到私有镜像时的完整过程遇到ImagePullBackOff不要急着删Pod重建按下面这个顺序排查先看Pod的Eventskubectl describe pod pod-name重点看FATAAL/Errors行的内容。如果是unauthorized或denied大概率是凭据问题。先确认Secret是否存在kubectl get secret regcred注意namespace要对。确认Secret里的JSON是否正确kubectl get secret regcred -o jsonpath{.data.\.dockerconfigjson} | base64 -d输出看看auths里的仓库地址是不是你镜像的完整前缀包括/之后的路径不需要auths里只需要仓库域名/IP端口不要带镜像路径。确认Pod的imagePullSecrets有没有写对、有没有拼错Secret名字。如果是临时凭据过期docker login重新生成再更新Secret。排查时还有一个很好用的角度直接在集群节点上手动执行docker login如果有docker测试仓库凭据是否有效。如果节点上能登录K8s里拉不下来那就是Kubernetes侧的引用问题。6.2 挂载后的文件比想象中多了一个隐藏目录有些同学在容器里执行ls /etc/secrets会发现除了自己挂载的key文件之外还有一个..data目录。别慌这是Kubernetes Volume挂载Secret的机制产物kubelet在更新Secret时会先写到一个临时目录然后通过原子性的符号链接切换实现原位置更新。/etc/secrets其实是一个符号链接指向..data..data又指向一个带时间戳的目录。这个设计让应用读取文件时不会看到半写状态。如果你在容器里用cat /etc/secrets/password读文件完全没问题但如果你用ls -l查看符号链接路径可能会被搞晕。简单记看到..data是正常现象不要手工去动它。6.3 Secret大小限制1MB是硬约束Kubernetes对Secret对象有maxSecretSize限制默认是1MB1048576字节。这个限制不是指单个key而是所有key的value加起来不能超过1MB。如果你的配置里塞了一个Base64编码的证书链或者一份很大的私钥很容易触顶。解决办法是不要把大文件直接塞进Secret而是拆开比如证书用单独的TLS Secret管理大配置放到ConfigMap真正的敏感信息只是那一两个密码。如果非要把1MB以上的数据做成Secret需要修改API Server的--max-secret-size参数但不推荐因为这个限制是性能保护调大可能拖慢etcd。6.4 更新Secret后Pod里的环境变量没变怎么办前面提过环境变量只在容器创建时注入不会动态更新。所以改了Secret重启Pod环境变量才变是预期行为。但是很多同学发现kubectl rollout restart deployment之后环境变量还是旧值。原因通常是Secret确实更新了但是Deployment的Pod模板hash没变滚动重启没有真正触发新Pod创建。rollout restart会强制生成新的ReplicaSet理论上一定会创建新Pod。但如果你的Pod模板用的是latest镜像标签可能新Pod还是从节点镜像缓存里启动且镜像内容不变环境变量应该是新的。这时先确认Secret本身的值kubectl get secret db-secret -o jsonpath{.data.password} | base64 -d看是不是真的改成功了。如果Secret是新值Pod是新建的环境变量还是旧值那就是你应用读取环境变量的方式不对比如应用里配置了缓存。6.5 权限控制最小权限原则Secret的读取权限通过RBAC控制。默认的viewClusterRole不包含Secret的读取权限所以如果你用只读用户执行kubectl get secret会报Forbidden。这是故意的防止敏感信息被无关人员查看。如果需要给特定角色授予权限一般是自定义Role和RoleBinding只授权特定命名空间或特定Secret的get/list/watch。作为管理员建议你在日常操作中遵循这个原则能用kubectl create secret一次创建就绝不把明文密码写进YAML提交仓库。如果确实需要把Secret的YAML纳入版本管理请使用Sealed Secrets、External Secrets或Vault等相关工具做加密而不是直接提交明文stringData。6.6 我的一点实战体会文件挂载优先于环境变量最后分享一个个人习惯。对比两种注入方式我现在的选择是能挂文件就挂文件。原因有三第一文件挂载支持Secret更新后自动同步环境变量不行。第二文件挂载所见即所得ls和cat就能排查环境变量得进容器里env才能看排障成本高。第三文件挂载对包含换行/特殊字符的内容更友好比如私钥、证书环境变量在拼接和转义上容易出现意外。当然环境变量也有它的优势比如单进程应用只需要读几个简单值、不想折腾Volume挂载和subPath时用env最快。这个没有绝对标准关键是理解两者背后的更新和排查差异再根据应用形状做选择。Secret这块的知识点说多不多说少不少。核心就是搞清楚数据形态Opaque还是dockerconfigjson、知道怎么创建命令式/声明式、理解注入方式挂文件还是环境变量的更新语义。把这三件事想明白日常使用基本不会出大问题。真出了问题按我上面给的排查链路走一遍大多数都能快速定位。