Velero ark server 命令指南v0.5.0 CLI 参考与服务器启动实现解析【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero本文以 Velero 仓库中 v0.5.0 历史文档 ark_server.md 为主体完整梳理ark server现为velero server命令的用途、全部命令行选项及继承自父命令的 klog 参数并结合当前仓库源码pkg/cmd/server/server.go、pkg/cmd/server/config/config.go解析服务器从进程启动到控制器就绪的完整调用链帮助读者理解这一命令的参数含义、默认值以及底层启动时序。一、命令定位运行 VeleroArk服务器在 v0.5.0 时期的 CLI 参考文档中ark server的定位非常明确Run the ark server运行 ark 服务器用法格式为ark server [flags]当时项目名为 Heptio ArkCLI 根命令ark的定位是“Back up and restore Kubernetes cluster resources”备份和恢复 Kubernetes 集群资源与kubectl类似的命令组织方式在 ark.md 的 Synopsis 中有描述。ark server负责启动控制面进程监听集群中的备份/恢复相关自定义资源驱动备份执行、恢复执行、存储位置校验、垃圾回收等一系列控制器。需要注意的是命名沿革当前仓库中该命令已更名为velero server。从源码看pkg/cmd/server/server.go 中NewCommand构造的 cobra 命令定义为var command cobra.Command{ Use: server, Short: Run the velero server, Long: Run the velero server, Hidden: true, ... }命令入口由 cmd/velero/velero.go 的main函数调用velero.NewCommand(baseName).Execute()驱动。当前版本中该命令被标记为Hidden: true即不出现在 CLI 帮助列表中——因为在生产部署中服务器由 Deployment 以容器内进程方式拉起而非用户直接在终端执行这与 v0.5.0 时代它作为正式 CLI 子命令出现见 v0.5.0 文档 ark.md 的 SEE ALSO 列表有所不同。二、命令自身选项v0.5.0 文档原文v0.5.0 文档给出的ark server自身选项只有两个-h, --help help for server --log-level the level at which to log. Valid values are debug, info, warning, error, fatal, panic. (default info)-h, --help打印帮助信息由 cobra 框架自动生成。--log-level日志级别合法取值为debug, info, warning, error, fatal, panic默认info。日志级别的实现佐证在当前仓库中日志级别由config.LogLevel*logging.LevelFlag类型承载默认值为logrus.InfoLevel并在 pkg/cmd/server/config/config.go 的BindFlags中绑定到--log-level标志LogLevel: logging.LogLevelFlag(logrus.InfoLevel), ... flags.Var(c.LogLevel, log-level, fmt.Sprintf(The level at which to log. Valid values are %s., strings.Join(c.LogLevel.AllowedValues(), , )))服务器启动时会将其打印到启动日志中logger.Infof(setting log-level to %s, strings.ToUpper(logLevel.String()))见 pkg/cmd/server/server.go 中NewCommand的Run函数。同时为保证 go-plugin 插件进程的日志不污染 stderr代码显式将log.SetOutput(os.Stdout)与logrus.SetOutput(os.Stdout)统一指向 stdout使云日志平台不会把这些行标记为错误。三、继承自父命令的选项klog 与 kubeconfigv0.5.0 文档还列出了ark server继承自父命令的一组选项这些全部来自 Kubernetes 生态的通用基础设施——klog日志库的 gflag 以及根命令注册的 kubeconfig 参数--alsologtostderr log to standard error as well as files --kubeconfig string Path to the kubeconfig file to use to talk to the Kubernetes apiserver. If unset, try the environment variable KUBECONFIG, as well as in-cluster configuration --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 --logtostderr log to standard error instead of files --stderrthreshold severity logs at or above this threshold go to stderr (default 2) -v, --v Level log level for V logs --vmodule moduleSpec comma-separated list of patternN settings for file-filtered logging各参数含义如下参数作用--alsologtostderr日志在写文件的同时也输出到 stderr--kubeconfig指定与 Kubernetes API Server 通信所用的 kubeconfig 路径未设置时回退到环境变量KUBECONFIG再回退到集群内配置in-cluster configuration--log_backtrace_at当某个文件:行号的日志被触发时打印堆栈跟踪默认:0表示禁用--log_dir非空时日志文件写入该目录--logtostderr日志输出到 stderr 而非文件--stderrthreshold达到或超过该严重程度的日志额外写入 stderr默认 2对应 Error-v, --vklog 的 V-level 详细日志级别--vmodule按“patternN”逗号分隔列表对指定文件做精细化日志级别控制从源码结构看klog相关标志由客户端库在初始化时全局注册pkg/cmd/server/server.go中显式调用klog.SetLogger(...)将 klog 输出接入 Velero 的 logrus 日志器注释说明klog.Logger is used by k8s.io/client-go--kubeconfig则由 CLI 根命令的客户端工厂注册。这些参数对ark server/velero server的意义主要是让服务器进程复用 kubectl 式的 kubeconfig 解析优先级命令行参数 →KUBECONFIG环境变量 → 集群内 ServiceAccount 配置。四、服务器启动流程从进程到控制器源码级解析理解了参数含义之后下面结合当前仓库源码说明执行server命令后实际发生的事情。整体调用链为NewCommand→newServer→server.run()→runControllers全部位于 pkg/cmd/server/server.go。4.1 配置校验与客户端构建newServernewServer在启动控制器之前完成一系列 fail-fast 校验上传器类型校验uploader.ValidateUploaderType(config.UploaderType)默认值为 Kopia见 pkg/cmd/server/config/config.go 中UploaderType: uploader.KopiaTypeAPI 客户端限流参数校验client-qps必须为正数默认 100、client-burst必须为正数默认 100、client-page-size不得为负默认 500分别通过f.SetClientQPS/f.SetClientBurst注入客户端工厂插件发现在config.PluginDir默认/plugins目录中执行pluginRegistry.DiscoverPlugins()扫描 Velero 插件二进制仓库配置 JSON 校验若设置了--backup-repository-configmap或--repo-maintenance-job-configmap会通过kube.VerifyJSONConfigs提前校验 ConfigMap 中的 JSON 合法性Scheme 注册注册 Velero v1、v2alpha1 API 组以及 corev1、CSI VolumeSnapshotv1 与 v1beta2 VGS、batch/v1、apps/v1 等类型controller-runtime Manager 创建带重试最多 10 次、每次间隔 1 秒缓存仅限制在 Velero 安装命名空间内。4.2 运行前检查runserver.run()按以下顺序执行见 pkg/cmd/server/server.go 的run方法信号处理signals.CancelOnShutdown注册优雅退出若设置了--profiler-address默认localhost:6060另起协程运行 pprof 分析器命名空间存在性检查namespaceExists通过 CoreV1 API 确认备份/恢复资源所在的命名空间存在注释说明其目的在于“could be different from the namespace where the Velero server pod runs”因此 fail fastDiscovery Helper 初始化initDiscoveryHelper创建 API 发现助手并启动协程每5 分钟调用一次Refresh()刷新资源发现缓存CRD 存在性检查veleroResourcesExist通过 discovery 核对 v1 与 v2alpha1 两个 API 组的全部自定义资源是否已安装缺失时错误信息会提示“apply config/crd/v1/bases/.yaml, config/crd/v2alpha1/bases.yaml to update the custom resource definitions”Node Agent 检查checkNodeAgent分别检查 Linux 与 Windows 节点上是否存在 velero node agent DaemonSet缺失时仅告警pod volume 备份/恢复与 data mover 功能依赖它仓库管理器初始化initRepoManager确保公共仓库密钥 Secret 存在repokey.EnsureCommonRepositoryKey并创建RepoLocker、Ensurer与repomanager.Manager控制器运行前准备setupBeforeControllerRun完成三件事——markInProgressCRsFailed把上一轮进程重启时处于 in-progress 状态的 Backup/Restore CR 标记为失败避免资源永久卡住setDefaultBackupLocation若配置了--default-backup-storage-location默认值default将其对应 BSL 的spec.default置为 true找不到时仅告警校验全局备份卷策略 ConfigMap--global-backup-volume-policies-configmap的合法性使配置错误尽早暴露。4.3 控制器启动runControllersrunControllers是启动流程的最后一环Prometheus 指标服务器在--metrics-address默认:8085上以独立 HTTP server 提供/metrics端点promhttp.Handler()并注册metrics.ServerMetrics控制器启停控制可启用的运行时控制器共 14 个backup、backup-deletion、backup-finalizer、backup-operations、backup-repo、backup-sync、download-request、garbage-collection、restore、restore-operations、schedule、server-status-request、restore-finalizer、backup-queue常量定义见 pkg/constant/constant.go可通过--disable-controllers关闭合法取值列表由config.DisableableControllers维护若传入了非法名称removeControllers会直接log.Fatal让进程退出Restore-only 模式--restore-only会额外禁用 backup、backup-deletion、backup-finalizer、backup-operations、garbage-collection、schedule 控制器该标志已在当前版本标记为 DEPRECATED建议使用只读的备份存储位置不可禁用的控制器BSL 控制器、PodVolumeBackup/PodVolumeRestore 相关逻辑node agent DaemonSet 依赖 PVB/PVR不在禁用列表中代码注释明确说明 “BSL controller is mandatory for Velero to work”各 Reconciler 装配依次为 BSL、Backup构建backup.NewKubernetesBackupper注入 podvolume 工厂、钩子执行器、插件管理器、对象存储 getter 等、BackupDeletion、BackupOperations、BackupFinalizer、BackupRepo、BackupSync、RestoreOperations、DownloadRequest、GC、Restore构建restore.NewKubernetesRestorer、Schedule、ServerStatusRequest、RestoreFinalizer、BackupQueue 调用SetupWithManager备份解压上限若设置了--max-backup-extraction-size单位 MB通过archive.SetMaxExtractionSize全局生效默认 16GB见 flag 描述最后s.mgr.Start(s.ctx)启动 controller-runtime Manager进入事件驱动的运行态。五、服务器关键配置参数与默认值当前实现v0.5.0 文档只列出了--help与--log-level而当前仓库中server命令通过 pkg/cmd/server/config/config.go 的Config.BindFlags暴露了完整参数集。下表整理了对理解服务器行为最关键的参数及其默认值均取自GetDefaultConfig与常量定义参数默认值说明--log-levelinfo日志级别合法值 debug/info/warning/error/fatal/panic--log-format由FormatFlag定义日志输出格式--plugin-dir/pluginsVelero 插件所在目录--metrics-address:8085Prometheus 指标暴露地址--profiler-addresslocalhost:6060pprof 分析器地址--client-qps/--client-burst100/100服务器访问 Kubernetes API 的速率与突发上限--client-page-size500备份时 list 对象的分页大小0 表示禁用分页--backup-sync-period1m将对象存储中的备份同步为集群内 Backup CR 的周期BSL 未显式指定时的默认值--store-validation-frequency1m校验存储位置有效性的周期0s表示禁用--default-backup-ttl720h30 天备份默认的垃圾回收保留时长--fs-backup-timeout240mpod volume 文件系统备份/恢复的超时时间--terminating-resource-timeout10m恢复时等待 PV/Namespace 终止的超时--resource-timeout10m未被其他具体超时覆盖的资源操作超时--default-csi-snapshot-timeout10mCSI 快照等待超时--default-item-operation-timeout4h异步 BackupItemActions/RestoreItemActions 的完成超时--garbage-collection-frequency按配置过期备份垃圾回收的执行周期--item-operation-sync-frequency10sflag 描述备份/恢复处理完成后轮询操作状态的频率--default-volume-snapshot-locations空各卷供应商到默认快照位置的映射provider1:location-01,...--concurrent-backups/--item-block-worker-count1/1并发处理备份数 / ItemBlock 处理工作线程数--max-concurrent-k8s-connections30与 kube-apiserver 的最大并发连接数--disable-controllers空启动时禁用的控制器列表见 4.3 节--restore-onlyfalse仅恢复模式已废弃建议改用只读备份存储位置--backup-repository-configmap/--repo-maintenance-job-configmap空备份仓库配置 / 仓库维护 Job 配置所在的 ConfigMap 名--global-backup-volume-policies-configmap空全局备份卷策略 ConfigMap 名启动时校验--default-resource-modifier-configmap空应用于所有恢复的默认资源修改规则 ConfigMap 名--max-backup-extraction-size16GB备份数据解压大小上限MB六、延伸阅读与验证路径历史文档原文site/content/docs/v0.5.0/cli-reference/ark_server.md、site/content/docs/v0.5.0/cli-reference/ark.mdv0.5.0 版 CLI 参考命令名仍为ark服务器命令实现pkg/cmd/server/server.goNewCommand、newServer、run、runControllers全部参数与默认值pkg/cmd/server/config/config.goConfig结构体、GetDefaultConfig、BindFlags控制器实现pkg/controller/ 目录下的backup_controller.go、restore_controller.go、schedule_controller.go、gc_controller.go等CLI 入口cmd/velero/velero.go可禁用控制器常量pkg/constant/constant.go。适用前提说明v0.5.0 文档描述的是项目更名前Heptio Ark 时期的ark server命令面当时仅暴露--help与--log-level两个专属选项当前仓库中的velero server命令参数集已大幅扩展并且命令在 CLI 帮助中被隐藏。若以当前仓库部署 Velero服务器参数应通过 Deployment 容器 args 配置本文第四节与第五节的默认值即取自当前实现可直接用于核对部署清单。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
