云原生开发工具微服务网络【免费下载链接】telepresenceLocal development against a remote Kubernetes or OpenShift cluster项目地址https://gitcode.com/gh_mirrors/te/telepresence点击查看免费下载本篇指南系统讲解 Telepresence 客户端命令telepresence genyaml config它用于为手工注入的 traffic-agent sidecar 生成telepresence-agentsConfigMap 中的条目 YAML是完全脱离 webhook 注入器、手动把 agent 写进现有 Kubernetes manifest这一高级场景的第一步。读完本文你将掌握该子命令的全部参数与默认值、输入输出的两种数据来源本地文件 / 集群中的 workload、生成结果Sidecar配置的字段含义以及它与genyaml annotations / container / initcontainer / volume其他四个子命令如何组成一套完整的手工注入流水线。一、背景为什么需要手动生成 agent 配置Telepresence 拦截intercept的工作原理是在目标 workload 的 Pod 中注入一个名为traffic-agent的 sidecar 容器见 pkg/agentconfig/sidecar.go 中的ContainerName traffic-agent由它接管指向应用容器的流量。绝大多数情况下这个注入由集群内的 webhook 注入器按需自动完成用户无需关心任何细节。但 Telepresence 也提供了一条完全手动的路径直接修改现有 Kubernetes manifest把 annotations、sidecar 容器、init 容器和 volume 手工写进 workload 定义。命令telepresence genyaml正是为这种场景设计的——其 Long 描述明确说明Generate traffic-agent yaml for use in kubernetes manifests. This allows the traffic agent to be injected by hand into existing kubernetes manifests.同时它也给出了强烈建议NOTE: It is recommended that you not do this unless strictly necessary. Instead, we suggest letting telepresences webhook injector configure the traffic agents on demand.也就是说手工注入只应在确有必要的场景例如无法使用 webhook 的受限集群、需要把 manifest 固化到 GitOps 仓库等下使用日常开发优先依赖 webhook 注入器。telepresence genyaml一共提供五个子命令它们各司其职、按序使用即可完成一次手工注入详见 docs/reference/cli/telepresence_genyaml.md子命令作用genyaml config生成 agent 在telepresence-agentsConfigMap 中的条目 YAML本文主题genyaml container生成 traffic-agent 容器 YAMLgenyaml initcontainer生成 traffic-agent init 容器 YAML仅在需要时genyaml annotations生成 Pod template 的 metadata annotations YAMLgenyaml volume生成 traffic-agent 所需的 volume YAML典型用法是先运行genyaml config得到配置条目再把该条目作为输入喂给其余子命令最终把四类 YAML 分别合并进 workload 的对应位置。二、命令用法与完整参数参考2.1 基本用法telepresence genyaml config [flags]该命令从 workload 定义Deployment / ReplicaSet / StatefulSet推导出 traffic-agent 的完整配置并输出为 YAML。workload 的定义可以来自本地文件--input或直接取自集群--workload。2.2 专属于 config 子命令的 Flags以下参数与默认值取自命令帮助文本docs/reference/cli/telepresence_genyaml_config.md并与源码实现pkg/client/cli/cmd/genyaml.go一一对应--agent-image string The qualified name of the agent image (default ghcr.io/telepresenceio/tel2:current version) --agent-port uint16 The port number you wish the agent to listen on. (default 9900) -h, --help help for config -i, --input string Path to the yaml containing the workload definition (i.e. Deployment, StatefulSet, etc). Pass - for stdin.. Mutually exclusive to --workload --loglevel The loglevel for the generated traffic-agent sidecar (default INFO) --manager-namespace string The traffic-manager namespace (default ambassador) --manager-port uint16 The traffic-manager API port (default 8081) -n, --namespace string If present, the namespace scope for this CLI request -o, --output string Path to the file to place the output in. Defaults to - which means stdout. (default -) -w, --workload string Name of the workload. If given, the workload will be retrieved from the cluster, mutually exclusive to --input对每个参数逐一说明--agent-imagetraffic-agent 镜像的完整限定名。默认值是占位符ghcr.io/telepresenceio/tel2:current version命令运行时会把current version替换为客户端实际版本——源码中通过strings.ReplaceAll(g.QualifiedAgentImage, current version, client.Semver().FinalizeVersion())实现genyaml.go。私有镜像仓库场景可在此指定自己的镜像地址。--agent-port默认 9900traffic-agent 希望监听的端口号。生成器会基于该起始端口为每个被拦截的容器端口分配递增的 agent 端口p : cfg.AgentPort uint16(len(pns))见 pkg/agentmap/generator.go 的agentPortNumberFunc。同时如果 workload 中某个应用容器已经暴露了与--agent-port相同的端口生成会直接失败提示与 traffic-agent sidecar 端口冲突generator.go。--manager-namespace默认ambassadortraffic-manager 所在的命名空间。生成结果中的managerHost由ManagerHost(cfg.ManagerNamespace, cfg.ClusterDomain)计算得出形如traffic-manager.ns.svc.clusterDomaingenerator.go。--manager-port默认 8081traffic-manager 的 API 端口写入配置后 agent 将使用该端口连接 manager。--loglevel默认 INFO生成的 traffic-agent sidecar 的日志级别对应slog.LevelInfogenyaml.go。-i, --input指向包含 workload 定义的本地 YAML 文件路径支持 Deployment、StatefulSet 等传-表示从标准输入读取。与--workload互斥。-w, --workload集群中 workload 的名称。指定后命令会通过 Kubernetes API 从集群拉取该 workload 的实时定义与--input互斥。-n, --namespace请求的命名空间作用域。未显式给出时会依次回退到 kubeconfig 中当前 context 的命名空间、再到defaultgenyaml.go。-o, --output默认-输出文件路径-表示写到标准输出。可把生成的条目直接落盘便于后续作为-a/--agent参数传给genyaml container等子命令。2.3 输入来源校验与解析逻辑从源码看loadWorkloadgenyaml.go对两种输入做了明确校验如果--input和--workload都为空报错either --input or --workload must be provided本地文件输入通过 Kubernetes 通用反序列化器解码支持apps/v1下的Deployment、StatefulSet、ReplicaSet三种类型其他类型会报错please pass in a Deployment, ReplicaSet, or StatefulSet若本地文件中的 workload 未声明 namespace会用--namespace填充genyaml.go。--input还支持从标准输入读取-对应源码中的getInputgenyaml.go方便与管道配合。2.4 Kubernetes Flags 与 Global Flags与 kubectl 一致的集群连接参数同样可用覆盖认证、上下文、代理等场景--as string Username to impersonate for the operation. --as-group stringArray Group to impersonate for the operation. --as-uid string UID to impersonate for the operation. --as-user-extra stringArray User extras to impersonate for the operation. --cache-dir string Default cache directory (default $HOME/.kube/cache) --certificate-authority string Path to a cert file for the certificate authority --client-certificate string Path to a client certificate file for TLS --client-key string Path to a client key file for TLS --cluster string The name of the kubeconfig cluster to use --context string The name of the kubeconfig context to use --disable-compression If true, opt-out of response compression --insecure-skip-tls-verify If true, the servers certificate will not be checked for validity --kubeconfig string Path to the kubeconfig file to use for CLI requests. --proxy-url string Proxy URL to use for requests to the API server --request-timeout string The length of time to wait before giving up on a single server request (default 0) -s, --server string The address and port of the Kubernetes API server --tls-server-name string Server name to use for server certificate validation --token string Bearer token for authentication to the API server --user string The name of the kubeconfig user to use此外还有 Telepresence 客户端通用的 Global Flags--config string Path to the Telepresence configuration file --format string Set the output format, supported values are json, yaml, json-stream, and default (default default) --progress string Set type of progress output (auto, tty, plain, json, quiet) (default auto) --use string Match expression that uniquely identifies the daemon container值得注意kubeconfig 中的 context 是命令解析集群连接的核心——源码中若当前 kubeconfig 没有任何 context 定义会直接报错kubeconfig has no context definition指定的 context 不存在也会报错genyaml.go。三、实际用法示例3.1 从本地文件生成输出到标准输出telepresence genyaml config -i ./deployment.yaml3.2 从本地文件生成写入指定文件telepresence genyaml config -i ./deployment.yaml -o ./agent-config.yaml3.3 从标准输入读取 workload 定义kubectl get deployment my-app -n my-ns -o yaml | telepresence genyaml config -i - -n my-ns3.4 直接从集群拉取 workloadtelepresence genyaml config -w my-app -n my-ns3.5 指定 manager 与 agent 的端口/命名空间telepresence genyaml config -w my-app -n my-ns \ --manager-namespace telepresence \ --manager-port 8081 \ --agent-port 9900 \ --agent-image ghcr.io/telepresenceio/tel2:2.20.0 \ --loglevel DEBUG3.6 与其余 genyaml 子命令衔接的手工注入流水线# 1) 生成 agent 配置条目 telepresence genyaml config -w my-app -n my-ns -o agent-config.yaml # 2) 基于该条目生成 annotations、container、initcontainer、volume telepresence genyaml annotations -a agent-config.yaml -o annotations.yaml telepresence genyaml container -a agent-config.yaml -i ./deployment.yaml -o container.yaml telepresence genyaml initcontainer -a agent-config.yaml -o initcontainer.yaml telepresence genyaml volume -a agent-config.yaml -o volume.yaml # 3) 把上述 YAML 分别合并进 workload 的 metadata.annotations、containers、initContainers、volumes其中genyaml container需要同时提供-a生成的 agent 配置和 workload-i或从集群加载并且会对 workload 名称、kind 与配置条目做一致性校验name %q of loaded workload is different from %q loaded configmap entrygenyaml.go。genyaml initcontainer仅当 workload 存在 headless 服务或数字 targetPort 的拦截时才需要输出 init 容器否则会提示 deployment does not need an init containergenyaml.go——因为只有这类拦截才需要在 init 容器中编程 nftables/iptables 规则。四、生成结果解读Sidecar 配置条目的字段结构genyaml config输出的本质是一个agentconfig.Sidecar结构体的 YAML 序列化见 pkg/agentconfig/sidecar.go 的字段定义与 JSON 标签。该条目正是 agent 在telepresence-agentsConfigMap 中的一行配置——traffic-manager 通过 ConfigMaptmconfig.CfgConfigMapName即名为traffic-manager的 ConfigMap见 pkg/tmconfig/configmap.go维护所有 agent 的配置webhook 注入与手动注入最终都会产生这类条目。以-w my-app生成为例输出大致形如agentImage: ghcr.io/telepresenceio/tel2:2.20.0 agentName: my-app logLevel: INFO namespace: my-ns workloadName: my-app workloadKind: Deployment managerHost: traffic-manager.ambassador.svc.cluster.local managerPort: 8081 containers: - name: app envPrefix: A_ mountPoint: /tel_app_mounts/app intercepts: - containerPortName: http serviceName: my-app servicePortName: http servicePort: 80 targetPortNumeric: false protocol: TCP containerPort: 8080 agentPort: 9900关键字段说明均为 Sidecar/Container/Intercept 结构体的 JSON 字段见 sidecar.goagentImagetraffic-agent 镜像完整名来自--agent-image。agentName/workloadName/workloadKind标识该 agent 服务的 workload 及来源类型。managerHost/managerPortagent 连接 traffic-manager 的地址与端口managerHost由 manager 命名空间与集群域推导。logLevelagent 侧日志级别。containers[]workload 中每个可拦截容器的配置。每个Container包含name、envPrefix基于容器序号生成的大写字母前缀如A_、B_见 pkg/agentmap/capsbase26.go、mountPoint远程挂载根路径默认前缀/tel_app_mounts、intercepts[]。intercepts[]端口映射的核心。每个Intercept记录服务端口与容器端口的映射关系serviceName/serviceUID/servicePortName/servicePort来自 Service 定义、targetPortNumericService 的 targetPort 是否为数字、protocolTCP 等 L4 协议、appProtocolL7 协议、containerPort/containerPortName被拦截的容器端口、agentPortagent 实际监听端口默认从 9900 起递增、headless服务是否无头、inactivePort无拦截时的回退端口。replace替换策略取值ReplacePolicyInterceptagent 接收所有端口流量并按需转发、ReplacePolicyContaineragent 整体替换应用容器、ReplacePolicyInactive不干扰任何端口见 sidecar.go。manual: true源码中生成后显式设置cfg.Manual truegenyaml.go标记该配置为手工创建。五、底层生成逻辑配置是怎么推导出来的genyaml config的核心由 pkg/agentmap/generator.go 的GeneratorConfig.Generate实现generator.go。理解它的推导过程有助于判断什么情况下会生成出什么样的配置拒绝拦截 traffic-manager 自身如果 workload 的 label 匹配apptraffic-manager, telepresencemanagerTrafficManagerSelector直接报错generator.go。端口冲突检查遍历 Pod 内所有应用容器若某个容器端口与--agent-port相同则报错generator.go。发现关联 Service通过FindServicesForPod找到 Pod 对应的 Service并支持telepresence.io/inject-service-name注解显式指定generator.go。建立端口映射对每个 Service 端口用findContainerMatchingPort匹配到应用容器端口生成InterceptagentPort从--agent-port起始、每个新容器端口递增 1agentPortNumberFuncgenerator.go。处理无 Service 的端口支持telepresence.io/inject-container-ports注解值all或逗号分隔的端口列表为没有 Service 前置的容器端口也生成 interceptappendServiceLessAgentContainerConfigsgenerator.go。数值端口若未在容器中显式声明会自动合成一个名为port-base26的容器端口。为所有容器生成条目即使某个容器没有可拦截端口也会追加一个不含 intercepts 的Container配置因为它们可能是分发容器dispatching container或ingest的候选generator.go。处理 mount 策略与 inactive 端口根据--mount-policies相关注解解析挂载策略并支持telepresence.io/inject-inactive-port注解为唯一被拦截端口指定无拦截时的回退端口generator.go。生成完成后run还会把WatchRetryInterval固定为 10 秒genyaml.go然后序列化输出。六、手工注入时 annotations 与 config 的关系genyaml annotations子命令生成的 Pod 元数据注解中最关键的是telepresence.io/agent-config常量annotation.Config见 pkg/annotation/annotation.go它携带genyaml config生成的 Sidecar 配置的紧凑 JSON通过agentconfig.MarshalTight序列化会剥离agentImage、pullPolicy等创建期字段见 sidecar.go。同时还会写入telepresence.io/inject-traffic-agent: enabledtelepresence.io/manually-injected: true。这三者共同让集群侧把该 workload 识别为已手动注入 agentgenyaml.go。也就是说genyaml config生成的条目既是 ConfigMap 中的配置来源也是annotations、container等后续子命令的输入-a/--agent参数是整个手工注入流程的数据中枢。七、常见问题与注意事项两个输入来源必须二选一--input与--workload互斥同时给出会被视为参数错误都不给则报错。本地文件只接受 Deployment / ReplicaSet / StatefulSet其他 kind 会报错需先把 workload 转成这三种类型之一。端口冲突是硬错误应用容器已占用--agent-port指定的端口时生成失败请调整--agent-port。current version占位符会被自动替换默认--agent-image会替换为客户端实际版本若显式传镜像请使用完整的repo/image:tag格式。namespace 解析优先级--namespace kubeconfig 当前 context 的 namespace default。需要 kubeconfig即使只使用--input从本地文件读取命令仍会初始化集群客户端并校验 kubeconfig context请确保当前 kubeconfig 可用、且目标集群信息正确。何时需要 initcontainer只有 headless Service 或数字 targetPort 的拦截才需要 init 容器普通命名端口的拦截不需要。优先使用 webhook 注入器如命令帮助所示手工注入仅应在确有必要的场景使用日常开发请让 Telepresence 的 webhook 注入器按需配置 traffic-agent。八、小结telepresence genyaml config把为 workload 手工注入 traffic-agent这一复杂过程的第一步——生成telepresence-agentsConfigMap 条目——变成了一个参数化、可复现的命令。通过--input/--workload选择数据来源通过--agent-image、--agent-port、--manager-port、--manager-namespace、--loglevel等参数控制生成结果其底层复用与 webhook 注入完全相同的agentmap.Generator推导逻辑保证手动生成的配置与自动注入的配置行为一致。掌握该命令配合genyaml annotations / container / initcontainer / volume即可在不依赖 webhook 的情况下完成完整的 traffic-agent 手工注入。相关源码与文档入口命令实现pkg/client/cli/cmd/genyaml.go配置生成器pkg/agentmap/generator.goSidecar 配置结构pkg/agentconfig/sidecar.go注解常量定义pkg/annotation/annotation.gotraffic-manager ConfigMap 管理pkg/tmconfig/configmap.go命令帮助文档docs/reference/cli/telepresence_genyaml_config.md、docs/reference/cli/telepresence_genyaml.md赞分享云原生开发工具微服务网络【免费下载链接】telepresenceLocal development against a remote Kubernetes or OpenShift cluster项目地址https://gitcode.com/gh_mirrors/te/telepresence点击查看免费下载相关推荐Telepresence genyaml 实战手工生成 traffic-agent 注入 YAML 的完整指南Telepresence genyaml 实战手工生成 traffic agent 注入 YAML 的完整指南 Telepresence 的 genyaml云原生开发工具微服务网络Telepresence genyaml initcontainer 实战指南手动生成 traffic-agent Init 容器 YAMLTelepresence genyaml initcontainer 实战指南手动生成 traffic agent Init 容器 YAML 本篇技术指南围绕云原生开发工具微服务网络ego-lite安全吗数据本地存储与隐私边界完整解读ego lite安全吗数据本地存储与隐私边界完整解读 ego lite 是一款专为 AI agent 设计的浏览器自动化工具它让 Codex、Claude云原生开发工具微服务网络上一篇Tweepy跨平台兼容性Windows、macOS与Linux行为差异下一篇Astral去中心化组网工具架构深入Clean Architecture signals_flutter响应式状态管理实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考