企业官网建设流程全解析

Karmada karmadactl create secret 命令完全指南：在联邦集群中创建 Opaque、Docker Registry 与 TLS 密钥

【免费下载链接】karmadaOpen, Multi-Cloud, Multi-Cluster Kubernetes Orchestration项目地址: https://gitcode.com/GitHub_Trending/ka/karmada

本文聚焦 Karmada 控制面命令行工具karmadactl的create secret命令族，系统讲解如何在联邦控制平面中创建docker-registry（镜像仓库认证）、generic（Opaque 通用密钥）与tls（证书密钥）三种类型的 Secret。读完本文，你将掌握三种子命令的完整参数语义、典型多集群使用场景（如为成员集群节点拉取私有镜像提供凭据、为联邦工作负载注入配置与证书），并能结合 Karmada 源码理解该命令与上游kubectl的继承关系，在实际集群中正确地创建、校验与使用 Secret。

命令总览：karmadactl create secret

karmadactl create secret是一个用于创建 Secret 的复合命令，通过指定的子命令来创建特定类型的 Secret。它位于karmadactl create命令族之下（create本身用于从文件或标准输入创建资源），完整用法为：

karmadactl create secret (docker-registry | generic | tls)

三种类型的语义如下：

从源码结构看，create secret命令族与karmadactl create一样，直接构建在 Kubernetes 官方kubectl的 create 命令基础之上。pkg/karmadactl/create/create.go 中的NewCmdCreate调用kubectlcreate.NewCmdCreate(f, ioStreams)完成命令装配，因此三个子命令的参数语义与 kubectl 保持一致，并额外挂载了 Karmada 所需的--kubeconfig、--karmada-context、-n/--namespace等父命令参数。

本命令自带选项

-h, --help help for secret

继承自父命令的全局参数

以下参数继承自karmadactl根命令，对所有create secret子命令均生效：

--add-dir-header If true, adds the file directory to the header of the log messages --alsologtostderr log to standard error as well as files (no effect when -logtostderr=true) --alsologtostderrthreshold severity logs at or above this threshold go to stderr when -alsologtostderr=true (no effect when -logtostderr=true) --karmada-context string The name of the kubeconfig context to use --kubeconfig string Path to the kubeconfig file to use for CLI requests. --legacy-stderr-threshold-behavior If true, stderrthreshold is ignored when logtostderr=true (legacy behavior). If false, stderrthreshold is honored even when logtostderr=true (default true) --log-backtrace-at traceLocation when logging hits line file:N, emit a stack trace (default :0) --log-dir string If non-empty, write log files in this directory (no effect when -logtostderr=true) --log-file string If non-empty, use this log file (no effect when -logtostderr=true) --log-file-max-size uint Defines the maximum size a log file can grow to (no effect when -logtostderr=true). Unit is megabytes. If the value is 0, the maximum file size is unlimited. (default 1800) --logtostderr log to standard error instead of files (default true) -n, --namespace string If present, the namespace scope for this CLI request. --one-output If true, only write logs to their native severity level (vs also writing to each lower severity level; no effect when -logtostderr=true) --skip-headers If true, avoid header prefixes in the log messages --skip-log-headers If true, avoid headers when opening log files (no effect when -logtostderr=true) --stderrthreshold severity logs at or above this threshold go to stderr when writing to files and stderr (no effect when -logtostderr=true or -alsologtostderr=true unless -legacy_stderr_threshold_behavior=false) (default 2) -v, --v Level number for the log level verbosity --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging

其中--karmada-context指定 kubeconfig 中要使用的 Karmada 控制面上下文，--kubeconfig指定 CLI 请求所使用的 kubeconfig 文件路径，-n/--namespace指定本次 CLI 请求的命名空间作用域——这三个参数是连接 Karmada 控制平面（而非本地集群）的关键。

子命令一：create secret docker-registry—— 创建 Docker 仓库认证凭据

docker-registry子命令用于创建供 Docker 镜像仓库认证使用的 Secret。dockercfg类型的 Secret 被用来向 Docker 仓库进行身份认证。

在 Karmada 多集群场景下，创建该 Secret 的典型动机是：当成员集群中的节点需要代表工作负载从私有仓库拉取镜像时，必须持有仓库凭据；通过创建dockerconfigjson类型的 Secret 并将其关联到 ServiceAccount，节点即可在拉取镜像时使用这些凭据。

使用 Docker 命令行推送镜像时，可以通过如下命令完成对指定仓库的认证：

$ docker login DOCKER_REGISTRY_SERVER --username=DOCKER_USER --password=DOCKER_PASSWORD --email=DOCKER_EMAIL

该命令会生成一个~/.dockercfg文件，供后续docker push与docker pull命令认证仓库使用。其中 email 地址是可选字段。

命令格式

karmadactl create secret docker-registry NAME --docker-username=user --docker-password=password --docker-email=email [--docker-server=string] [--from-file=[key=]source] [--dry-run=server|client|none]

使用示例

# 若本地没有 .dockercfg 文件，直接创建 dockercfg Secret karmadactl create secret docker-registry my-secret --docker-server=DOCKER_REGISTRY_SERVER --docker-username=DOCKER_USER --docker-password=DOCKER_PASSWORD --docker-email=DOCKER_EMAIL # 基于 ~/.docker/config.json 创建名为 my-secret 的新 Secret karmadactl create secret docker-registry my-secret --from-file=path/to/.docker/config.json

子命令专属选项

--docker-email string Email for Docker registry --docker-password string Password for Docker registry authentication --docker-server string Server location for Docker registry (default "https://index.docker.io/v1/") --docker-username string Username for Docker registry authentication

需要特别说明--docker-server：默认值为https://index.docker.io/v1/，即 Docker Hub；当目标是私有仓库（如 Harbor、自建 registry）时，必须显式传入该仓库的服务器地址。--from-file选项在此处的语义与 generic 不同——当仅传文件路径时，Secret 内的键名默认为.dockerconfigjson，因此“对于本命令，键名应始终为.dockerconfigjson”。

通用选项（与 generic、tls 共享）

以下选项同时适用于docker-registry、generic、tls三个子命令：

--allow-missing-template-keys If true, ignore any errors in templates when a field or map key is missing in the template. Only applies to golang and jsonpath output formats. (default true) --append-hash Append a hash of the secret to its name. --dry-run string[="unchanged"] Must be "none", "server", or "client". If client strategy, only print the object that would be sent, without sending it. If server strategy, submit server-side request without persisting the resource. (default "none") --field-manager string Name of the manager used to track field ownership. (default "kubectl-create") --from-file strings Key files can be specified using their file path, in which case a default name of .dockerconfigjson will be given to them, or optionally with a name and file path, in which case the given name will be used. Specifying a directory will iterate each named file in the directory that is a valid secret key. For this command, the key should always be .dockerconfigjson. -h, --help help for docker-registry -o, --output string Output format. One of: (json, yaml, kyaml, name, go-template, go-template-file, template, templatefile, jsonpath, jsonpath-as-json, jsonpath-file). --save-config If true, the configuration of current object will be saved in its annotation. Otherwise, the annotation will be unchanged. This flag is useful when you want to perform kubectl apply on this object in the future. --show-managed-fields If true, keep the managedFields when printing objects in JSON or YAML format. --template string Template string or path to template file to use when -o=go-template, -o=go-template-file. The template format is golang templates [http://golang.org/pkg/text/template/#pkg-overview]. --validate string[="strict"] Must be one of: strict (or true), warn, ignore (or false). "true" or "strict" will use a schema to validate the input and fail the request if invalid. It will perform server side validation if ServerSideFieldValidation is enabled on the api-server, but will fall back to less reliable client-side validation if not. "warn" will warn about unknown or duplicate fields without blocking the request if server-side field validation is enabled on the API server, and behave as "ignore" otherwise. "false" or "ignore" will not perform any schema validation, silently dropping any unknown or duplicate fields. (default "strict")

子命令二：create secret generic—— 从文件、目录或字面量创建通用密钥

generic子命令基于本地文件、目录或指定的字面量值创建 Secret，其类型为 Kubernetes 的Opaque类型。一个 Secret 可以打包一个或多个 key/value 对，非常适合在联邦环境中存放应用配置、环境变量、访问令牌等敏感信息。

数据来源规则

• 基于文件：以文件创建时，键名默认为文件的 basename，值为文件内容。若 basename 不是合法的键名，或希望自定义键名，可通过key=source形式显式指定键名。
• 基于目录：以目录创建时，目录中每个 basename 为合法键名的文件都会被打包进 Secret；目录中除常规文件以外的条目（如子目录、符号链接、设备、管道等）均会被忽略。
• 基于字面量：通过--from-literal=key1=value1直接以键=值形式插入内容。
• 基于 env 文件：通过--from-env-file读取形如key=val行的文件批量构建。

命令格式

karmadactl create secret generic NAME [--type=string] [--from-file=[key=]source] [--from-literal=key1=value1] [--dry-run=server|client|none]

使用示例

# 以文件夹 bar 中每个文件为键，创建名为 my-secret 的 Secret karmadactl create secret generic my-secret --from-file=path/to/bar # 指定自定义键名（而非磁盘上的文件名） karmadactl create secret generic my-secret --from-file=ssh-privatekey=path/to/id_rsa --from-file=ssh-publickey=path/to/id_rsa.pub # 以 key1=supersecret、key2=topsecret 创建 Secret karmadactl create secret generic my-secret --from-literal=key1=supersecret --from-literal=key2=topsecret # 混合使用文件与字面量 karmadactl create secret generic my-secret --from-file=ssh-privatekey=path/to/id_rsa --from-literal=passphrase=topsecret # 从 env 文件创建 karmadactl create secret generic my-secret --from-env-file=path/to/foo.env --from-env-file=path/to/bar.env

子命令专属选项

--from-env-file strings Specify the path to a file to read lines of key=val pairs to create a secret. --from-file strings Key files can be specified using their file path, in which case a default name will be given to them, or optionally with a name and file path, in which case the given name will be used. Specifying a directory will iterate each named file in the directory that is a valid secret key. --from-literal stringArray Specify a key and literal value to insert in secret (i.e. mykey=somevalue) --type string The type of secret to create

--type用于覆盖默认的Opaque类型，例如可显式指定--type=kubernetes.io/basic-auth等自定义类型。其余通用选项（--append-hash、--dry-run、--output、--validate等）与上文 docker-registry 共享同一套定义。

子命令三：create secret tls—— 创建 TLS 证书密钥

tls子命令根据给定的公钥/私钥对创建 TLS Secret。创建前公钥/私钥对必须已存在，且公钥证书必须为.PEM编码并与给定的私钥匹配。该类型 Secret 常用于为联邦工作负载（如 Ingress、Webhook 服务）注入证书。

命令格式

karmadactl create secret tls NAME --cert=path/to/cert/file --key=path/to/key/file [--dry-run=server|client|none]

使用示例

# 使用给定的密钥对创建名为 tls-secret 的 TLS Secret karmadactl create secret tls tls-secret --cert=path/to/tls.crt --key=path/to/tls.key

子命令专属选项

--cert string Path to PEM encoded public key certificate. --key string Path to private key associated with given certificate.

源码视角：命令如何从 kubectl 继承而来

create secret命令族并非 Karmada 重新实现，而是直接复用了 Kubernetes 官方kubectl的 create 实现：

• pkg/karmadactl/create/create.go 中NewCmdCreate通过kubectlcreate.NewCmdCreate(f, ioStreams)创建命令，随后追加 Karmada 的--kubeconfig、--namespace等全局参数，并注册--karmada-context与 namespace 的补全函数；
• pkg/karmadactl/create/create.go 中的replaceCreateSubcommandExamples会递归遍历所有子命令（包括create secret下的docker-registry、generic、tls），将示例文本中的kubectl create统一替换为karmadactl create，保证帮助信息与实际命令一致；
• 该命令在 pkg/karmadactl/karmadactl.go 中通过create.NewCmdCreate(f, parentCommand, ioStreams)注册到 karmadactl 根命令下。

因此，所有kubectl create secret的能力（如--append-hash名称哈希追加、--dry-run预演、-o输出格式等）在 Karmada 控制面中均可直接使用，区别在于这些 Secret 会被创建到Karmada 控制平面的 API Server中，随后由联邦控制面按需分发到成员集群。

实战要点与多集群使用建议

1. 先 dry-run 校验，再正式创建：使用--dry-run=client -o yaml可以先在本地生成 Secret 的 YAML 定义并检查，确认键名、类型与内容无误后再去掉 dry-run 正式提交，避免误写凭据。
2. 私有仓库务必显式指定--docker-server：默认值指向 Docker Hub，若目标为私有镜像仓库（Harbor、自建 registry 等），漏传该参数会导致成员集群节点拉取镜像时认证失败。
3. --append-hash提升可追踪性：该选项会在 Secret 名称后追加内容哈希，便于在 Secret 内容变更时生成新的资源名称，配合--save-config可在后续使用kubectl apply时保持配置可管理。
4. 结合命名空间作用域使用：通过-n/--namespace与--karmada-context指定目标命名空间与 Karmada 控制面上下文，确保 Secret 创建在正确的联邦命名空间下，再配合 PropagationPolicy 等机制分发到成员集群。
5. TLS 密钥对必须自洽：tls子命令要求证书为 PEM 编码且与私钥匹配，创建前可用openssl等工具核对密钥对的对应关系，避免创建出无法被 Ingress/Webhook 使用的证书 Secret。

关联命令

• karmadactl create - 从文件或标准输入创建资源
• karmadactl create secret docker-registry - 创建供 Docker 仓库使用的 Secret
• karmadactl create secret generic - 从本地文件、目录或字面量创建 Secret
• karmadactl create secret tls - 创建 TLS Secret

更多命令说明可返回 Karmadactl Commands 首页查看。

【免费下载链接】karmadaOpen, Multi-Cloud, Multi-Cluster Kubernetes Orchestration项目地址: https://gitcode.com/GitHub_Trending/ka/karmada