Support multi-cluster deployments (Central + SecuredCluster on separate clusters) by AlexVulaj · Pull Request #105 · stackrox/roxie

AlexVulaj · 2026-04-17T17:44:09Z

Summary

Roxie currently assumes Central and SecuredCluster are deployed on the same Kubernetes cluster. Many ACS customers and internal teams run a hub + spoke architecture where Central lives on one cluster and one or more SecuredClusters are deployed to separate clusters. This PR adds multi-cluster support so that roxie can deploy a SecuredCluster that points to a Central running on a different cluster.

Users set the SecuredCluster CR's centralEndpoint directly via config file:

# spoke-config.yaml
securedCluster:
  spec:
    centralEndpoint: "central.example.com:443"

ROX_ADMIN_PASSWORD=<admin-password> \
ROX_CA_CERT_FILE=<path-to-ca-cert> \
roxie deploy secured-cluster -t 4.9.2 -c spoke-config.yaml

When spec.centralEndpoint is provided, roxie preserves it. When it is not set, roxie defaults to the internal central.<namespace>.svc:443 endpoint, preserving full backward compatibility. Authentication to Central for CRS generation uses the existing ROX_ADMIN_PASSWORD and ROX_CA_CERT_FILE environment variables.

Testing

Single-cluster deploy on GKE (regression test): verified default behavior is unchanged
Multi-cluster deploy on GKE (new feature): Central on cluster A, SecuredCluster on cluster B with spec.centralEndpoint pointing to cluster A — both deployed and connected successfully, sensor logs confirmed connection to remote Central

Closes #99

davdhacs · 2026-04-17T20:53:28Z

This will be very helpful for Infra and e2e testing. In Infra/Automation, we've had a long-term todo of adding multi-cluster capability to the demo (ansible scripts) and repeated asks/investigations on various teams have looked at multi-cluster deploys for automated testing.
+1

AlexVulaj · 2026-04-22T12:57:50Z

Holding this PR until we can have further discussions around the UX of the feature.

…te clusters)

AlexVulaj · 2026-05-14T13:33:09Z

Ready for re-review @porridge @mclasmeier

mclasmeier · 2026-05-15T06:43:01Z


+	if deploySettings.SecuredCluster.CentralEndpoint != "" {
+		if !components.IncludesSensor() {
+			return errors.New("securedCluster.centralEndpoint can only be used when deploying secured-cluster")


I'm not sure about this kind of validation.

I have always thought that roxie just takes what it needs from the provided config. Even if it has a full configuration for component A and only deployment of component B is requested, the config should be usable unmodified.

This validation step would prevent the user from using a single, merged configuration, no?

Fair point here, a single merged config should be usable regardless of which component is being deployed. I'll drop this validation.

mclasmeier · 2026-05-15T06:45:16Z

 // SecuredClusterConfig holds deployment settings for the SecuredCluster component.
 type SecuredClusterConfig struct {
 	Namespace           string                 `yaml:"namespace,omitempty"`
+	CentralEndpoint     string                 `yaml:"centralEndpoint,omitempty"`


Thought about this since yesterday and I keep coming back to the question: why not simply use spec["centralEndpoint"]? This is already a field in the CR and if we want to keep roxie a relative light-weight layer on top of our operator-based installation, we could naturally just use the existing spec field.

Good call - let's just use the spec.centralEndpoint field and I'll adjust ConfigureSpec to only set the internal default when spec.centralEndpoint isn't already provided.

mclasmeier · 2026-05-15T06:48:42Z

+
+1. Deploy Central on the hub cluster:
+```bash
+MAIN_IMAGE_TAG=4.9.2 ./roxie deploy central


For the (new) docs, I think we should prever roxie deploy -t <version> over MAIN_IMAGE_TAG, which was primarily added for backwards compat reasons with deployment scripts.

mclasmeier · 2026-05-15T06:50:59Z

+ROX_ADMIN_PASSWORD=<admin-password> \
+ROX_CA_CERT_FILE=<path-to-ca-cert> \
+./roxie deploy secured-cluster \
+  --set securedCluster.centralEndpoint=<central-loadbalancer-ip>:443


The external endpoint is also contained in some environment variable written by roxie, right?

Yep! roxie sets API_ENDPOINT (along with a few others) in the subshell environment.

mclasmeier · 2026-05-15T06:53:15Z

+  --set securedCluster.centralEndpoint=<central-loadbalancer-ip>:443
+```
+
+> **Note:** The Central endpoint is printed during deployment. If you are in the roxie subshell,


Ah, there it comes.

Maybe move this a bit up, because the above instructions as written direct the user to this mode?

Maybe also mention that for some use cases (automation), --envrc might be the better fit?

porridge

FTR I don't have anything to add over what @mclasmeier wrote.

…ndpoint; update README examples

coderabbitai · 2026-05-26T13:56:43Z

📝 Walkthrough

Walkthrough

This PR enables hub-and-spoke multi-cluster deployments by allowing an explicit centralEndpoint to be specified when deploying SecuredCluster to a separate cluster. The configuration logic respects user-provided values while supplying internal defaults, test coverage validates the precedence rules, and user documentation explains the deployment pattern.

Changes

Multi-cluster deployment support

Layer / File(s)	Summary
Central endpoint configuration and validation `internal/deployer/config.go`, `internal/deployer/central_endpoint_test.go`	`SecuredClusterConfig.ConfigureSpec` now conditionally sets `spec.centralEndpoint` only when absent, preserving any user-provided value; test cases validate default construction, namespace customization, user-input preservation, and precedence behavior.
Summary display and user documentation `internal/deployer/deployer.go`, `README.md`	Deployment summary conditionally prints the Central Endpoint when a non-default value is configured; README documents the hub-and-spoke workflow with step-by-step instructions for deploying Central and SecuredCluster on separate clusters.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A hub speaks to spokes across the lands so far,
Where Central shines bright like a guiding star.
No longer one cluster holds all the weight—
Multi-cluster deployments now seal their fate!
Your endpoint now carries the message with care. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title clearly and concisely summarizes the main change—adding support for multi-cluster deployments where Central and SecuredCluster run on separate clusters, which is the primary objective of this changeset.
Linked Issues check	✅ Passed	The pull request fully addresses the requirements from issue `#99`: it enables multi-cluster deployments via a configurable centralEndpoint property, supports hub-and-spoke topology, and maintains backward compatibility when the property is not set.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing multi-cluster deployment support: README documentation for hub-and-spoke setup, config logic to handle centralEndpoint, tests validating the behavior, and deployment summary updates—no out-of-scope modifications detected.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch multi-cluster-support

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

AlexVulaj requested review from mclasmeier and porridge April 17, 2026 17:44

AlexVulaj self-assigned this Apr 17, 2026

AlexVulaj force-pushed the multi-cluster-support branch 4 times, most recently from 49fa237 to a0ffb80 Compare April 17, 2026 18:28

porridge reviewed Apr 20, 2026

View reviewed changes

Comment thread README.md Outdated

AlexVulaj requested a review from porridge April 20, 2026 14:08

AlexVulaj force-pushed the multi-cluster-support branch from 31a0cfc to ce1d010 Compare April 20, 2026 14:22

mclasmeier reviewed Apr 20, 2026

View reviewed changes

Comment thread cmd/deploy.go Outdated

AlexVulaj force-pushed the multi-cluster-support branch from ce1d010 to 1817bee Compare April 20, 2026 15:38

AlexVulaj mentioned this pull request Apr 22, 2026

Proposal: Consolidate roxie deployment config in a single "config" file #113

Closed

AlexVulaj force-pushed the multi-cluster-support branch from 1817bee to d81f08c Compare May 5, 2026 18:12

AlexVulaj added 2 commits May 13, 2026 10:14

Support multi-cluster deployments (Central + SecuredCluster on separa…

0d12d44

…te clusters)

Add subshell note to multi-cluster README section

0fdf763

AlexVulaj force-pushed the multi-cluster-support branch 2 times, most recently from 99c5975 to 7755974 Compare May 13, 2026 17:32

AlexVulaj requested a review from mclasmeier May 13, 2026 17:33

Migrate multi-cluster from CLI flags to config property

954384a

AlexVulaj force-pushed the multi-cluster-support branch from 7755974 to 954384a Compare May 13, 2026 18:06

mclasmeier reviewed May 15, 2026

View reviewed changes

porridge reviewed May 18, 2026

View reviewed changes

Drop top-level CentralEndpoint config field in favor of spec.centralE…

c80aa1d

…ndpoint; update README examples

Conversation

AlexVulaj commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing

Uh oh!

davdhacs commented Apr 17, 2026

Uh oh!

Uh oh!

Uh oh!

AlexVulaj commented Apr 22, 2026

Uh oh!

AlexVulaj commented May 14, 2026

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!

porridge left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

❌ Failed checks (1 warning)

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AlexVulaj commented Apr 17, 2026 •

edited

Loading

coderabbitai Bot commented May 26, 2026 •

edited

Loading