feat(cli): add okactl command-line tool for sandbox operations by Liquorice-Ma · Pull Request #497 · openkruise/agents

Liquorice-Ma · 2026-06-03T11:28:14Z

Ⅰ. Describe what this PR does

Add a new CLI component agent-cli — a kubectl-style command-line tool for common sandbox operations, eliminating the need to hand-write YAML or use kubectl edit.

Three commands are introduced:

agent-cli scale sandboxset --replicas=N — Scale a SandboxSet's replica count via JSON Merge Patch (atomic, no optimistic-lock conflicts).
agent-cli set image sandboxset container=image [...] — Update one or more container images in a SandboxSet's inline template. Detects TemplateRef usage and guides users to modify the SandboxTemplate directly.
agent-cli restart sandbox [-c container ...] — Restart containers in a running Sandbox by creating a SandboxContainerRestart CR. If no -c flags are specified, all user containers are restarted.
The restart command follows a CRD-driven pattern (inspired by OpenKruise's ContainerRecreateRequest):

CLI creates a SandboxContainerRestart CR
A new controller watches these CRs and executes container restarts via kubectl exec kill -TERM 1
The CR tracks per-container status (Pending → Succeeded/Failed) and supports TTL-based auto-cleanup
New CRD: SandboxContainerRestart (shortName: scr) with support for:

Failure policies (Fail / Ignore)
Ordered or parallel restart
Active deadline timeout
TTL-based auto-cleanup after completion

Ⅱ. Does this pull request fix one issue?

NONE

Ⅲ. Describe how to verify it

Build the CLI:

go build -o agent-cli ./cmd/agent-cli/
Scale a SandboxSet:

./agent-cli scale sandboxset my-sbs --replicas=5 -n sandbox-system
Update container images:

./agent-cli set image sandboxset my-sbs main=nginx:2.0 sidecar=envoy:2.0 -n sandbox-system
Restart containers in a Sandbox:

Restart specific containers

./agent-cli restart sandbox my-sbx -c main -c sidecar -n sandbox-system

Restart all user containers

./agent-cli restart sandbox my-sbx -n sandbox-system
Run unit tests:

go test ./pkg/cli/... ./pkg/controller/sandboxcontainerrestart/...

Ⅳ. Special notes for reviews

The compiled binary agent-cli (47MB) is included in this commit and should be removed before merge — it should be built via CI instead.
SandboxContainerRestart uses dynamic.Interface in the CLI because the generated clientset does not yet include this new type. After running code-gen, this can be switched to a typed client.
The orderedRecreate and minStartedSeconds strategy fields are defined in the CRD spec but not yet implemented in the controller — these are reserved for future iterations.
After merge, make generate manifests should be run to generate proper deepcopy functions and CRD YAML (the current types include hand-written DeepCopyObject stubs).

kruise-bot · 2026-06-03T11:28:20Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign zmberg for approval by writing /assign @zmberg in a comment. For more information see:The Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

codecov · 2026-06-03T11:32:47Z

Codecov Report

❌ Patch coverage is 88.56209% with 70 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.13%. Comparing base (1ee08c4) to head (af064e3).
⚠️ Report is 47 commits behind head on master.

Files with missing lines	Patch %	Lines
pkg/cli/create.go	83.85%	15 Missing and 11 partials ⚠️
pkg/cli/setimage.go	89.94%	11 Missing and 6 partials ⚠️
pkg/cli/restart.go	86.88%	10 Missing and 6 partials ⚠️
pkg/cli/options.go	86.66%	3 Missing and 3 partials ⚠️
pkg/cli/scale.go	94.33%	2 Missing and 1 partial ⚠️
pkg/cli/status.go	96.72%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #497      +/-   ##
==========================================
+ Coverage   78.34%   80.13%   +1.79%     
==========================================
  Files         162      208      +46     
  Lines       11739    15299    +3560     
==========================================
+ Hits         9197    12260    +3063     
- Misses       2187     2587     +400     
- Partials      355      452      +97

Flag	Coverage Δ
unittests	`80.13% <88.56%> (+1.79%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

furykerry · 2026-06-04T02:29:44Z

+
+OpenKruise Agents 项目原有四个组件（controller、manager、gateway、runtime），都是长运行服务。日常运维中，对 SandboxSet 的扩缩容、镜像更新、容器重启等操作只能通过 `kubectl edit` 或手写 YAML 完成，操作繁琐且容易出错。
+
+为此，我们新增了第五个组件 **agent-cli** —— 一个 kubectl 风格的命令行工具，提供三个核心命令：


consider rename to okactl

furykerry · 2026-06-04T02:30:35Z

+
+前两个命令（scale、set image）是**纯客户端操作**，直接通过 K8s API 修改 SandboxSet CR，由已有的 SandboxSet controller 自动处理变更。
+
+第三个命令（restart）采用了**CRD 驱动模式**（参照 OpenKruise 的 ContainerRecreateRequest）：CLI 创建一个 `SandboxContainerRestart` CR，新增的 controller 监听并执行实际的容器重启操作。


cli create CRR is enough, no need to create SandboxContainerRestart CR

furykerry · 2026-06-04T02:32:21Z

@@ -0,0 +1,227 @@
+# agent-cli 命令行工具设计与实现文档


plz put the proposal in docs/proposals, and rewrite the design in English for wider audience

feat(cli): add okactl command-line tool for sandbox operations fix(cli): add in-cluster config support for okactl running inside Pods Update okactl binary okactl scale/setimage/restart -h

…ndboxSet updates

Add create suo subcommand that creates SandboxUpdateOps to batch update container images of claimed sandboxes by label selector. Includes auto-cleanup of existing SUOs, container name validation, and correct PodTemplateSpec-level patch structure. Also adds proposal doc for the create suo feature.

- Add E2E tests for scale, set image, create suo, and restart commands - Add dedicated e2e-okactl.yaml workflow running on kind cluster - Add unit tests to meet 80% coverage requirement - Fix set image optimistic lock conflict with retry.RetryOnConflict

… display - Add top-level 'okactl status' command group with 'sbs' and 'suo' subcommands - status sbs: show SandboxSet rolling update progress with auto-diagnosis - status suo: show SandboxUpdateOps batch update progress - Both support --wait flag for polling until completion - Add cobra Aliases for resource short names (sandboxset/sbs, sandboxupdateops/suo) - Customize cobra usage template to display subcommand aliases in help output - Remove 'set image status' subcommand (replaced by top-level 'status sbs') - Update set image examples to reference 'okactl status sbs' - Add developer manual for okactl CLI - Add proposal document for status command design - Add unit tests (coverage: 85.2%) and E2E tests for new commands Signed-off-by: 马赫 <Yurong.mh@alibaba-inc.com>

furykerry

plz never submit binary to the repo

furykerry · 2026-06-23T13:17:51Z

+	}
+
+	var deleted []string
+	for i := range list.Items {


deleteActiveSandboxUpdateOps deletes ALL SUOs, not just active ones, plz Only delete SUOs with Phase == Pending || Phase == Updating

furykerry · 2026-06-24T01:29:35Z

+	}
+
+	if sbx.Spec.Template == nil {
+		return nil


plz fetch the referenced SandboxTemplate to validate if Template nil

furykerry · 2026-06-24T01:34:59Z

+
+// diagnoseSandboxSetUpdate checks sandboxes belonging to a SandboxSet and reports any issues.
+// It builds a kubernetes client to inspect pod status when sandbox messages are empty.
+func diagnoseSandboxSetUpdate(globalOpts *GlobalOptions, sbs *agentsv1alpha1.SandboxSet, reported *map[string]bool) {


ach diagnosis call creates two new REST clients via globalOpts.AgentsClient() and globalOpts.KubeClient(), which involves re-reading kubeconfig and establishing new TLS connections. In --wait mode this happens every 3 poll cycles (~9s), consider pass the already-created clients as parameters to diagnoseSandboxSetUpdate.

furykerry · 2026-06-24T01:36:03Z

+}
+
+// formatSuoImagePairs formats a map of container=image pairs as a slice of "container=image" strings.
+func formatSuoImagePairs(images map[string]string) []string {


ormatSuoImagePairs() and buildSuoImagePatch() generate Non-deterministic output from map iteration, consider sort keys before iteration in both functions.

furykerry · 2026-06-24T01:41:57Z

+}
+
+// parseContainerImages parses "container=image" pairs and returns a map.
+func parseContainerImages(args []string) (map[string]string, error) {


setimage.go and create.go duplicate parseContainerImages / parseSuoContainerImages， Consider extracting a shared parseImageArgs() to reduce duplication.

furykerry · 2026-06-24T01:49:37Z

+okactl status sbs my-pool --wait
+
+# Batch update images for claimed sandboxes
+okactl create suo -l app=my-app app=nginx:1.25


is it possible to considate create suo command with set image

okactl set image -l app=my-app app=nginx:1.25

Originally set image supported both sbs and sbx, but create suo was split out in an earlier review so that set image only handles SandboxSet while claimed sandboxes are updated via SUO.

furykerry · 2026-06-24T01:49:47Z

+okactl set image sbs my-pool app=nginx:1.25
+
+# Check update progress (or wait for completion)
+okactl status sbs my-pool --wait


--wait should be the option of set image not status

Binary is now distributed via GitHub Releases instead of committing to the repository. Signed-off-by: 马赫 <Yurong.mh@alibaba-inc.com>

fix UT

- Use apierrors.IsNotFound instead of string matching in waitForSUODeletion - Replace parseSuoSelectorToMap with metav1.ParseToLabelSelector for full label selector syntax support (key in (v1,v2), key!=value, etc.) - Validate container names against all matching sandboxes instead of only the first; warn on partial mismatch, error only when missing from all - Add Running phase check to restart command before creating CRR - Remove --wait flag from status command (belongs to set image only) - Sync developer manual and proposal documents Signed-off-by: 马赫 <Yurong.mh@alibaba-inc.com>

kruise-bot requested review from AiRanthem, furykerry and zmberg June 3, 2026 11:28

kruise-bot added the size/XXL label Jun 3, 2026

furykerry reviewed Jun 4, 2026

View reviewed changes

Liquorice-Ma changed the title ~~新增agent-cli命令行工具~~ feat(cli): add okactl command-line tool for sandbox operations Jun 5, 2026

add okactl command-line tool for sandbox operations

4405ca1

feat(cli): add okactl command-line tool for sandbox operations fix(cli): add in-cluster config support for okactl running inside Pods Update okactl binary okactl scale/setimage/restart -h

Liquorice-Ma force-pushed the agents-cli branch 4 times, most recently from 920a645 to 57d6ff2 Compare June 15, 2026 03:48

feat(cli): add set image status subcommand with auto-diagnosis for Sa…

06fdf31

…ndboxSet updates

Liquorice-Ma force-pushed the agents-cli branch 2 times, most recently from 06fb203 to b48e3df Compare June 22, 2026 06:42

Liquorice-Ma force-pushed the agents-cli branch from b48e3df to e9396b6 Compare June 22, 2026 07:00

Liquorice-Ma force-pushed the agents-cli branch 2 times, most recently from 59cca84 to cbfe589 Compare June 22, 2026 09:37

Liquorice-Ma force-pushed the agents-cli branch from 693cc47 to cca229d Compare June 23, 2026 04:48

furykerry reviewed Jun 23, 2026

View reviewed changes

fix:okactl binary version

b5eaf4f

furykerry reviewed Jun 24, 2026

View reviewed changes

马赫 added 2 commits June 24, 2026 12:01

chore: remove okactl binary from repo, add to .gitignore

7d8aa63

Binary is now distributed via GitHub Releases instead of committing to the repository. Signed-off-by: 马赫 <Yurong.mh@alibaba-inc.com>

Addressed 6 review comments, 1 remaining.

b4a4e7b

fix UT

Liquorice-Ma force-pushed the agents-cli branch from 4d52f18 to b4a4e7b Compare June 24, 2026 06:08


		OpenKruise Agents 项目原有四个组件（controller、manager、gateway、runtime），都是长运行服务。日常运维中，对 SandboxSet 的扩缩容、镜像更新、容器重启等操作只能通过 `kubectl edit` 或手写 YAML 完成，操作繁琐且容易出错。

		为此，我们新增了第五个组件 agent-cli —— 一个 kubectl 风格的命令行工具，提供三个核心命令：


		前两个命令（scale、set image）是纯客户端操作，直接通过 K8s API 修改 SandboxSet CR，由已有的 SandboxSet controller 自动处理变更。

		第三个命令（restart）采用了CRD 驱动模式（参照 OpenKruise 的 ContainerRecreateRequest）：CLI 创建一个 `SandboxContainerRestart` CR，新增的 controller 监听并执行实际的容器重启操作。

		@@ -0,0 +1,227 @@
		# agent-cli 命令行工具设计与实现文档

Uh oh!

Conversation

Liquorice-Ma commented Jun 3, 2026

Ⅰ. Describe what this PR does

Ⅱ. Does this pull request fix one issue?

Ⅲ. Describe how to verify it

Restart specific containers

Restart all user containers

Ⅳ. Special notes for reviews

Uh oh!

kruise-bot commented Jun 3, 2026

Uh oh!

codecov Bot commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

furykerry left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov Bot commented Jun 3, 2026 •

edited

Loading