support running karmada-agent out-of-cluster by driegel1 · Pull Request #7821 · karmada-io/karmada

driegel1 · 2026-08-11T20:06:53Z

⚠️ 🚧 ⚒️ 💀 *** TESTING IN PROGRESS *** 💀 ⚒️ 🚧 ⚠️

What type of PR is this?*
/kind feature

What this PR does / why we need it:

Addresses #7601. Adds a --register-cluster boolean flag (default true) to karmada-agent. When set to
false, the agent skips self-registration and instead validates that the member cluster is
already registered with the Karmada control plane before starting its Pull-mode controllers.

This supports environments where cluster registration is managed by an external system (e.g. Bloomberg's
managed Karmada platform) rather than by the agent itself. The agent can already connect to a
member cluster out-of-cluster via the existing --kubeconfig flag; the only missing piece was
the ability to decouple registration from the agent's runtime, which this flag provides.

When --register-cluster=false, the agent verifies the pre-registered cluster satisfied all of the following:

It exists on the control plane
It is not being deleted
Its spec.syncMode is Pull
Its spec.id (if set) matches the member cluster's ID

The default (--register-cluster=true) is unchanged and fully backward-compatible.

Which issue(s) this PR fixes:
Fixes #7601

Special notes for your reviewer:

Minimal-footprint change: the existing self-registration block in run() is wrapped in an
if opts.RegisterCluster { ... } else { ... }; no controller wiring or config plumbing was
changed. Out-of-cluster member connectivity relies on the pre-existing --kubeconfig flag.
Unit tests added for validateExternallyRegisteredCluster covering: happy path, missing
cluster, cluster being deleted, wrong sync mode, ID mismatch, and missing kube-system
namespace.
docs/command-line-flags/karmada-agent.md regenerated via hack/update-command-line-flags.sh.
go build, go test ./cmd/agent/..., go vet, and hack/verify-command-line-flags.sh all pass.

Does this PR introduce a user-facing change?:

`karmada-agent`: Introduced the `--register-cluster` flag (default `true`). When set to `false`, the agent skips self-registration and validates that the member cluster is already registered (in Pull mode) before running its controllers.

codecov-commenter · 2026-08-11T20:27:45Z

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 32.07547% with 36 lines in your changes missing coverage. Please review.
✅ Project coverage is 42.22%. Comparing base (1c27857) to head (dc21ffb).
⚠️ Report is 10 commits behind head on master.

Files with missing lines	Patch %	Lines
cmd/agent/app/agent.go	0.00%	35 Missing ⚠️
cmd/agent/app/options/options.go	0.00%	1 Missing ⚠️
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #7821      +/-   ##
==========================================
+ Coverage   42.07%   42.22%   +0.14%     
==========================================
  Files         879      880       +1     
  Lines       54852    54907      +55     
==========================================
+ Hits        23081    23182     +101     
+ Misses      30026    29978      -48     
- Partials     1745     1747       +2

Flag	Coverage Δ
unittests	`42.22% <32.07%> (+0.14%)`	⬆️

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.

jabellard · 2026-08-12T21:23:07Z

/assign

Signed-off-by: driegel1 <driegel1@bloomberg.net>

karmada-bot · 2026-08-13T16:04:45Z

[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 ask for approval from jabellard. For more information see the 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

Copilot

Pull request overview

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Adds a --register-cluster flag to allow karmada-agent to run out-of-cluster without performing self-registration, instead validating a pre-registered Pull-mode cluster.

Changes:

Introduces --register-cluster (default true) and wires it into agent startup logic.
Adds validateExternallyRegisteredCluster to verify pre-registration invariants when self-registration is disabled.
Adds unit tests for the new validation logic and regenerates the CLI flags documentation.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/command-line-flags/karmada-agent.md	Documents the new `--register-cluster` flag and its behavior.
cmd/agent/app/registration.go	Adds validation logic for externally registered (Pull-mode) clusters.
cmd/agent/app/registration_test.go	Adds unit tests for the new external-registration validation.
cmd/agent/app/options/options.go	Adds `RegisterCluster` option and exposes it as a CLI flag.
cmd/agent/app/agent.go	Gates self-registration behind `opts.RegisterCluster`; runs validation when disabled.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+		},
+	}
+
+	for _, tt := range tests {


jabellard · 2026-08-13T17:13:17Z

 	fs.DurationVar(&o.CertRotationCheckingInterval, "cert-rotation-checking-interval", 5*time.Minute, "The interval of checking if the certificate need to be rotated. This is only applicable if cert rotation is enabled")
 	fs.Float64Var(&o.CertRotationRemainingTimeThreshold, "cert-rotation-remaining-time-threshold", 0.2, "The threshold of remaining time of the valid certificate. This is only applicable if cert rotation is enabled.")
 	fs.StringVar(&o.KarmadaKubeconfigNamespace, "karmada-kubeconfig-namespace", "karmada-system", "Namespace of the secret containing karmada-agent certificate. This is only applicable if cert rotation is enabled.")
+	fs.BoolVar(&o.RegisterCluster, "register-cluster", true, "Whether to register the member cluster with the Karmada control plane on startup. Set to false when the cluster is pre-registered by an external process; the agent will then only validate the existing Pull-mode registration and run its controllers.")


Good that this is backwards compatible.

jabellard · 2026-08-13T17:32:01Z

+		return fmt.Errorf("cluster %q has SyncMode %q, expected %q for an externally registered cluster", opts.ClusterName, cluster.Spec.SyncMode, clusterv1alpha1.Pull)
+	}
+
+	clusterID, err := util.ObtainClusterID(memberKubeClient)


I think we can drop the cluster ID check. The ID is an optional field that may not always be set. Also this util function does not take into account the fact that there's multiple ways in which it can be set.

Ref: https://github.com/karmada-io/karmada/blob/release-1.18/pkg/apis/cluster/types.go#L64

Or maybe we can make the util function more robust.

@RainbowMango , what do you think?

jabellard

Generally looks good. Left a couple of comments.

jabellard · 2026-08-13T17:42:13Z

Hey @driegel1. We can perform some e2e tests locally using the local-up script.

I think we need to test that:

This change does not break anything when a member is registered in pull mode. The script will setup a Karmada instance instance that's joined to 3 member clusters, one of which is registered in pull mode. All three member clusters should be in the ready state once the script runs to completion. Then we can propagate a deployment to all member clusters and verify it makes it to the pull-mode member.
The verification logic on startup works when the cluster is registered with the control plane by an external system. For that scenario, we can:

Patch the running agent in the Kind member cluster to explicitly set the new flag to false. This will trigger a rolling restart of the agent
Look at the logs to make sure we see the successful verification check log on startup
Deploy a new deployment to all member clusters and make sure it also makes it to the pull-mode member

jabellard · 2026-08-13T17:42:52Z

/retest

jabellard · 2026-08-13T17:43:08Z

/cc @RainbowMango for another look

karmada-bot · 2026-08-13T17:43:12Z

@jabellard: GitHub didn't allow me to request PR reviews from the following users: for, another, look.

Note that only karmada-io members and repo collaborators can review this PR, and authors cannot review their own PRs.

Details

In response to this:

/cc @RainbowMango for another look

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

jabellard · 2026-08-13T17:54:33Z

Hey @driegel1. We can perform some e2e tests locally using the local-up script.

I think we need to test that:

This change does not break anything when a member is registered in pull mode. The script will setup a Karmada instance instance that's joined to 3 member clusters, one of which is registered in pull mode. All three member clusters should be in the ready state once the script runs to completion. Then we can propagate a deployment to all member clusters and verify it makes it to the pull-mode member.

The verification logic on startup works when the cluster is registered with the control plane by an external system. For that scenario, we can:

Patch the running agent in the Kind member cluster to explicitly set the new flag to false. This will trigger a rolling restart of the agent

Look at the logs to make sure we see the successful verification check log on startup

Deploy a new deployment to all member clusters and make sure it also makes it to the pull-mode member

And to test a missing registration failure on startup, we can:

Scale down the agent deployment to zero in the member cluster.
Delete the cluster object in the control plane
Scale the agent back up and it should go into a crash loop on start up.

RainbowMango · 2026-08-14T02:01:24Z

/assign
Adding to my queue! Thanks.

karmada-bot added kind/feature Categorizes issue or PR as related to a new feature. do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. labels Aug 11, 2026

karmada-bot requested review from Tingtal and lonelyCZ August 11, 2026 20:06

karmada-bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Aug 11, 2026

karmada-bot assigned jabellard Aug 12, 2026

support running karmada-agent out-of-cluster

dc21ffb

Signed-off-by: driegel1 <driegel1@bloomberg.net>

driegel1 force-pushed the feature/7601-out-of-cluster-karmada-agent branch from b1a21bb to dc21ffb Compare August 13, 2026 16:04

driegel1 marked this pull request as ready for review August 13, 2026 16:11

Copilot AI lite review requested due to automatic review settings August 13, 2026 16:11

karmada-bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Aug 13, 2026

Copilot AI reviewed Aug 13, 2026

View reviewed changes

Comment thread cmd/agent/app/registration_test.go

},

}

for _, tt := range tests {

Copilot started reviewing on behalf of driegel1 August 13, 2026 16:29 View session

jabellard reviewed Aug 13, 2026

View reviewed changes

karmada-bot requested a review from RainbowMango August 13, 2026 17:43

karmada-bot assigned RainbowMango Aug 14, 2026

Navigation Menu

Uh oh!

support running karmada-agent out-of-cluster - #7821

support running karmada-agent out-of-cluster#7821
driegel1 wants to merge 1 commit into
karmada-io:masterfrom
driegel1:feature/7601-out-of-cluster-karmada-agent

driegel1 commented Aug 11, 2026 •

edited

Loading

Uh oh!

codecov-commenter commented Aug 11, 2026 •

edited

Loading

Uh oh!

jabellard commented Aug 12, 2026

Uh oh!

karmada-bot commented Aug 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

jabellard Aug 13, 2026

Uh oh!

jabellard Aug 13, 2026

Uh oh!

jabellard left a comment

Uh oh!

jabellard commented Aug 13, 2026

Uh oh!

jabellard commented Aug 13, 2026

Uh oh!

jabellard commented Aug 13, 2026

Uh oh!

karmada-bot commented Aug 13, 2026

Uh oh!

jabellard commented Aug 13, 2026

Uh oh!

RainbowMango commented Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Uh oh!

Conversation

driegel1 commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

jabellard commented Aug 12, 2026

Uh oh!

karmada-bot commented Aug 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

jabellard Aug 13, 2026

Choose a reason for hiding this comment

Uh oh!

jabellard Aug 13, 2026

Choose a reason for hiding this comment

Uh oh!

jabellard left a comment

Choose a reason for hiding this comment

Uh oh!

jabellard commented Aug 13, 2026

Uh oh!

jabellard commented Aug 13, 2026

Uh oh!

jabellard commented Aug 13, 2026

Uh oh!

karmada-bot commented Aug 13, 2026

Uh oh!

jabellard commented Aug 13, 2026

Uh oh!

RainbowMango commented Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

driegel1 commented Aug 11, 2026 •

edited

Loading

codecov-commenter commented Aug 11, 2026 •

edited

Loading