企业官网建设流程全解析

Karpenter 开发环境搭建与开发者工作流实战指南

【免费下载链接】karpenter-provider-awsKarpenter is a Kubernetes Node Autoscaler built for flexibility, performance, and simplicity.项目地址: https://gitcode.com/GitHub_Trending/ka/karpenter-provider-aws

本指南面向希望为 Karpenter（karpenter-provider-aws）贡献代码的开发者，系统讲解从零搭建本地开发环境、进入“编码—构建—部署—调试”循环、以及使用 pprof 进行性能剖析的完整流程。读完本文，你将掌握make驱动的开发工作流（run/apply/delete/image/test/presubmit）、AWS ECR 镜像仓库配置方法，以及 metrics 与日志调试技巧，可直接复用于日常开发与问题排查。

开发依赖与工具链安装

Karpenter 是一个 Go 语言编写的 Kubernetes 控制器，其开发环境依赖以下基础工具：

其中“其余工具”并非手写安装，而是由仓库根目录下的 Makefile 中的toolchain目标调用 hack/toolchain.sh 一次性安装。从脚本源码看，它通过go install安装了项目开发所需的完整 CLI 工具集，包括：

• ko（v0.18.1）：基于 Go 源码构建 OCI 镜像并推送，是make image的核心工具；
• golangci-lint（v2.12.2）：静态检查与 lint；
• controller-gen（v0.21.0）：生成 CRD 与 DeepCopy 代码；
• setup-envtest：下载并软链 kubebuilder 测试环境二进制（默认 K8S_VERSION=1.34.x，安装到/usr/local/kubebuilder/bin）；
• ginkgo（v2.32.0）：单元测试与 e2e 测试的运行框架；
• yq（v4.52.5）、helm-docs、cosign、crane、oras、hugo、govulncheck、actionlint、go-licenses、goveralls等。

提示：脚本运行后会检查 Go 的bin目录是否在PATH中，若未包含会提示执行export PATH="$PATH:${GOPATH:-$HOME/go}/bin"，请留意该输出。

环境特定配置：以 AWS ECR 为例

开发 Karpenter 需要为控制器组件准备一个镜像仓库。官方推荐使用 AWS ECR，并按“多个项目共用一个dev仓库、用镜像摘要（digest）而非 tag 引用”的方式管理。

先创建 ECR 仓库（建议开启镜像扫描scanOnPush=true）：

aws ecr create-repository \ --repository-name dev \ --image-scanning-configuration scanOnPush=true \ --region "${AWS_DEFAULT_REGION}"

创建完成后，让 Docker 守护进程登录该仓库，并设置KO_DOCKER_REPO环境变量指向它：

export KO_DOCKER_REPO="${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_DEFAULT_REGION}.amazonaws.com/dev" aws ecr get-login-password --region "${AWS_DEFAULT_REGION}" | docker login --username AWS --password-stdin "${KO_DOCKER_REPO}"

在 Makefile 中可以看到KO_DOCKER_REPO的默认值正是${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_DEFAULT_REGION}.amazonaws.com/dev，与上述约定一致；同时它还会通过aws sts get-caller-identity自动解析AWS_ACCOUNT_ID。确保运行make命令前：

• 已配置有效的 AWS 凭证（本地开发时用于生成 CRD 清单、拉取定价数据等）；
• 集群具备从该 ECR 仓库拉取镜像的权限（如通过 IRSA 或节点 IAM 角色）。

开发循环：编码到验证的标准节奏

开发者的标准循环如下：

1. 安装依赖：
   • 运行make codegen重新生成 yaml 清单（该目标定义见 Makefile，其背后是 hack/codegen.sh，基于 AWS API 响应生成带宽、价格、VPC 限制等数据文件）。注意：该命令需要可用的 AWS 凭证；
   • 运行make toolchain安装构建与测试所需的 CLI 工具。
2. 准备个人开发镜像仓库（见上文 ECR 配置），并确保$KO_DOCKER_REPO指向该仓库。
3. 编写代码后，执行构建与部署（见下节）。

在集群中快速部署（make apply）

make apply会完成“校验 → 构建镜像 → 部署到~/.kube/config指定集群”的完整链路。从 Makefile 的源码可见其实际执行的动作：

apply: verify image kubectl apply -f ./pkg/apis/crds/ helm upgrade --install karpenter charts/karpenter --namespace ${KARPENTER_NAMESPACE} \ $(HELM_OPTS) \ --set controller.image.repository=$(IMG_REPOSITORY) \ --set controller.image.tag=$(IMG_TAG) \ --set controller.image.digest=$(IMG_DIGEST)

即：先依次执行verify（依赖整理、代码生成、CRD 同步、lint、git 工作区检查）和image（用 ko 构建并推送镜像），再应用 pkg/apis/crds 下的 CRD，最后通过 charts/karpenter 这个 Helm Chart 完成部署，并精确指定镜像仓库、tag 与 digest。

make apply还默认注入了大量 Helm 参数（见 HELM_OPTS），包括：

• 服务账号的 IAM Role ARN（${CLUSTER_NAME}-karpenter）；
• settings.clusterName、settings.interruptionQueue；
• 控制器资源 requests/limits（CPU 1、内存 1Gi）；
• 一组 feature gates（nodeRepair、reservedCapacity、spotToSpotConsolidation、nodeOverlay、staticCapacity、capacityBuffer）；
• 默认logLevel=debug（对应下文的日志级别说明）。

卸载控制器则使用：

make delete # Uninstall Karpenter

其实现为helm uninstall karpenter --namespace ${KARPENTER_NAMESPACE}（见 Makefile），命名空间默认是kube-system（Makefile）。

在本地直接运行控制器（make run）

若不想把控制器部署进集群，而是希望在本机以 Go 二进制方式运行、直接连到~/.kube/config指定的集群，使用：

make run

从 Makefile 的实现看，该目标会：

1. 先kubectl apply -f ./pkg/apis/crds/确保最新 CRD 已安装；
2. 设置SYSTEM_NAMESPACE、CLUSTER_NAME、INTERRUPTION_QUEUE、FEATURE_GATES、AWS_FEATURE_GATES、LOG_LEVEL=debug等环境变量；
3. 执行go run ./cmd/controller/main.go启动控制器（关闭了 leader election，便于本地调试）。

这适合需要快速迭代、希望直接观察控制器日志与行为（如调度、漂移检测、中断处理）的场景。

仅构建并发布镜像（make image）

如果只想构建控制器镜像并推送到镜像仓库、暂不部署 Helm Release，运行：

make image # build and push the karpenter images

该目标（Makefile）使用ko build --bare从github.com/aws/karpenter-provider-aws/cmd/controller直接构建镜像，并解析出IMG_REPOSITORY、IMG_TAG、IMG_DIGEST供apply使用。注意构建时会注入sigs.k8s.io/karpenter/pkg/operator.Version这个版本变量（见 Makefile），版本来自git describe --tags。

本地替换 kubernetes-sigs/karpenter 依赖

Karpenter 控制器依赖核心调度库sigs.k8s.io/karpenter。若你同时改动了上游核心代码并希望在本仓库验证，可通过go mod的 replace 指令将依赖指向本地路径：

go mod edit -replace sigs.k8s.io/karpenter=$PATH_TO_KUBERNETES_SIGS_KARPENTER

将$PATH_TO_KUBERNETES_SIGS_KARPENTER替换为本地相对或绝对路径后，再执行上述镜像构建即可。注意：必须先将 go.mod 的改动提交（commit），make image才会真正生效，因为镜像构建读取的是工作区中已固化的依赖版本。恢复上游依赖时，可将 update-karpenter 目标作为参考：go get -u sigs.k8s.io/karpenter@HEAD后go mod tidy。

提交前全量检查（make presubmit）

每次提交前建议运行：

make presubmit # run codegen, lint, and tests

该目标定义于 Makefile：presubmit: verify test，等价于依次执行完整校验（依赖、代码生成、CRD 同步、lint、git 工作区洁净度检查）与全部单元测试，是 CI 的核心步骤。

单元测试与 E2E 测试

单元测试

make test # E2E correctness tests

实际执行（Makefile）的是go test ./pkg/...，并附加覆盖率采集（-cover -coverprofile=coverage.out）与 Ginkgo 参数（--ginkgo.randomize-all、--ginkgo.vv），支持通过FOCUS/SKIP环境变量筛选用例。生成覆盖率报告后可运行make coverage用go tool cover生成 HTML 查看。

此外，仓库还提供了make deflake（带--race竞态检测并循环执行直到失败）用于排查偶发失败用例，以及make benchmark（-tags=test_performance性能基准测试）等测试辅助目标。

E2E 测试

make test只是单元测试；针对真实集群的端到端测试位于 test/suites 目录（涵盖 ami、consolidation、drift、interruption、ipv6、scheduling、storage 等场景），通过make e2etests运行：

e2etests: ## Run the e2e suite against your local cluster cd test && CLUSTER_ENDPOINT=${CLUSTER_ENDPOINT} ... go test -p 1 -count 1 -timeout 12h -v ./suites/$(...)/...

其中TEST_SUITE变量用于指定某个套件目录（默认...即全部），套件所需的默认 EC2NodeClass / NodePool 资源位于 test/pkg/environment/aws/default_ec2nodeclass.yaml 与 test/pkg/environment/aws/default_nodepool.yaml，可据此了解 e2e 依赖的集群前置条件。

调试技巧：日志级别、Metrics 与日志跟踪

修改日志级别

默认情况下make apply通过 Helm 参数把日志级别设为debug（见 HELM_OPTS 中的--set logLevel=debug），以输出最详细的调度与控制器日志。如需调整，可在 Helm 安装/升级时覆盖：

--set logLevel=debug

关于日志级别的合法取值，可以参考 Settings 配置参考 中LOG_LEVEL条目：可选debug、info、error，默认值为info——也就是说，生产环境默认是 info 级别，开发时显式使用 debug 才能看到更完整的内部决策过程。

调试 Metrics

Karpenter 在METRICS_PORT（默认 8080，见 Settings 配置参考）上暴露控制器自身运行指标，可通过 port-forward 在本机浏览器查看：

macOS：

open http://localhost:8080/metrics && kubectl port-forward service/karpenter -n kube-system 8080

Linux：

gio open http://localhost:8080/metrics && kubectl port-forward service/karpenter -n karpenter 8080

注意两处命令的命名空间差异：macOS 示例使用kube-system，Linux 示例使用karpenter。实际命名空间以你部署时KARPENTER_NAMESPACE（默认kube-system，见 Makefile）为准，请按你的部署环境调整。

高效跟踪控制器日志

除了直接kubectl logs，文档推荐使用 Stern 这类多 pod 聚合日志工具，一条命令即可跟随所有 Karpenter 控制器副本的日志：

stern -n karpenter -l app.kubernetes.io/name=karpenter

该 label 选择器与 Helm Chart 中 Karpenter 组件的标准标签一致，可按需将-n karpenter替换为实际命名空间。

使用 pprof 进行性能剖析

当在 Settings 配置参考 中启用 profiling（对应ENABLE_PROFILING/--enable-profiling配置项）后，Karpenter 会在 metrics 端口上暴露 Go 标准的 pprof 调试端点，可用于分析控制器内存与 CPU 热点。

前置准备

brew install graphviz go install github.com/google/pprof@latest

graphviz用于 pprof 生成调用图（graph）视图，pprof工具本身也建议通过go install安装最新版。

采集并可视化 profile

# 1. 连接 metrics 端点（默认 8080 端口） kubectl port-forward service/karpenter -n karpenter 8080 # 2. 打开 pprof 索引页查看可用端点 open http://localhost:8080/debug/pprof/ # 3. 可视化内存堆快照 go tool pprof -http 0.0.0.0:9000 localhost:8080/debug/pprof/heap # 4. 可视化 CPU 剖析（采样 60 秒） go tool pprof -http 0.0.0.0:9000 "localhost:8080/debug/pprof/profile?seconds=60"

要点：

• 先执行kubectl port-forward将集群内 8080 端口映射到本地，再通过localhost:8080访问；
• -http 0.0.0.0:9000会在本机 9000 端口启动一个交互式 Web UI，支持火焰图、调用图、源码级热点标注等多种视图；
• 内存剖析用heap端点（快照式），CPU 剖析用profile端点并配合seconds=60指定采样时长；
• 剖析端点与业务 metrics 共用同一端口，因此启用 profiling 时请留意端口安全边界。

常用 Make 目标速查

以下目标均定义于仓库根目录 Makefile，可使用make help查看全部带注释的目标：

完整的开发环境配置、构建部署与调试细节，还可参考本仓库 website/content/en/v1.12/contributing 下的其他贡献者文档（如 design-guide.md、documentation-updates.md），以便在动手开发前对齐设计与文档规范。

【免费下载链接】karpenter-provider-awsKarpenter is a Kubernetes Node Autoscaler built for flexibility, performance, and simplicity.项目地址: https://gitcode.com/GitHub_Trending/ka/karpenter-provider-aws