Add `--ns-follows-kube-context` global flag for using the kubeconfig context namespace by jtyr · Pull Request #5831 · fluxcd/flux2

jtyr · 2026-04-10T07:29:47Z

Problem

The flux CLI ignores the namespace set in the current kubeconfig context and always defaults to flux-system when --namespace is not explicitly provided. This means users who set a namespace via kubectl config set-context --current --namespace=... still have to pass -n on every flux command.

Fix: #3453

Fix

Resolve the namespace from the kubeconfig context when neither --namespace nor FLUX_SYSTEM_NAMESPACE is set. The flux-system default is preserved as the final fallback.

The resulting priority order (highest to lowest):

--namespace / -n flag
FLUX_SYSTEM_NAMESPACE environment variable
Kubeconfig context namespace
flux-system

The context lookup runs in PersistentPreRunE (after flag parsing), so it correctly respects --context and --kubeconfig flags when determining which context to read from.

Testing

Added unit tests covering:

Namespace returned from the current context
--context flag selecting a different context's namespace
Context with no namespace set (empty string)
Non-existent context
FLUX_SYSTEM_NAMESPACE taking precedence over context namespace
--namespace flag taking precedence over context namespace
Fallback to flux-system when context has no namespace

stefanprodan · 2026-04-10T07:38:02Z

This is a major breaking change that we can not accept. Imagine how many CI pipelines and custom scripts we are going to break with this, e.g. you have flux bootstrap in your pipeline, the default namespace in kubeconfig is to some namespace, with this change new clusters will end up with Flux in the selected namespace instead of flux-system.

matheuscscp · 2026-04-10T08:08:25Z

We had lots of discussions around this over the years. This is a bug that became expected behavior at this point, so we cannot break it.

However, across discussions someone suggested an env var for opting into this behavior, which would not be a breaking change and I'd be ok with it. Env var or flag, not sure what's best, though.

jtyr · 2026-04-10T08:08:49Z

Thanks for the feedback, @stefanprodan. I understand your concern.

This behavior was discussed and classified as a bug in #3453, with the consensus being that the kubeconfig context namespace should be respected (see #3453 (comment)). That said, I understand the concern about breaking existing CI pipelines and scripts that rely on flux-system being the implicit default.

Would an opt-in approach work for now? For example, introducing a FLUX_NS_FOLLOWS_KUBE_CONTEXT environment variable that users can set to enable the context namespace resolution, while keeping the current behavior as the default. This way existing workflows remain unaffected and users who want this can explicitly opt in, with the option to make it the default in a future major version.

Or would you prefer a different approach entirely?

jtyr · 2026-04-10T08:14:05Z

Thanks for joining the discussion, @matheuscscp. How about supporting both?

A --ns-follows-kube-context flag, which can also be set via an alias (alias flux='/usr/bin/flux --ns-follows-kube-context')
A FLUX_NS_FOLLOWS_KUBE_CONTEXT environment variable (export FLUX_NS_FOLLOWS_KUBE_CONTEXT=1)

This follows the existing pattern where FLUX_SYSTEM_NAMESPACE provides an env var alternative. The flag gives per-command control, while the env var allows setting it globally in a shell profile or CI environment.

Would that be acceptable?

matheuscscp · 2026-04-10T08:22:08Z

I have no objections to this solution

jtyr · 2026-04-10T13:23:44Z

@matheuscscp @stefanprodan I have updated the implementation to make the context namespace resolution opt-in. It can be enabled via one of the following:

--ns-follows-kube-context flag (e.g. alias flux='flux --ns-follows-kube-context')
FLUX_NS_FOLLOWS_KUBE_CONTEXT env var (e.g. export FLUX_NS_FOLLOWS_KUBE_CONTEXT=1)

Without either of these, the existing behavior is preserved (flux-system remains the default).

matheuscscp

LGTM

makkes · 2026-04-13T08:36:10Z

+		// explicitly set and FLUX_SYSTEM_NAMESPACE env var is not set,
+		// respect the namespace from the kubeconfig context.
+		if (rootArgs.nsFollowsKubeContext || os.Getenv("FLUX_NS_FOLLOWS_KUBE_CONTEXT") != "") &&
+			!cmd.Flags().Changed("namespace") && os.Getenv("FLUX_SYSTEM_NAMESPACE") == "" {


I'm not sure I understand why FLUX_SYSTEM_NAMESPACE is checked here. I don't always care about that as my Flux resources may be scattered across multiple namespaces on the cluster. Why should this generally disregard the kubeconfig NS if FLUX_SYSTEM_NAMESPACE is set?

Yeah, if FLUX_SYSTEM_NAMESPACE is not used when e.g. -n is set, then it makes no sense to be checked here, good catch!

Fixed in the last commit.

makkes · 2026-04-13T08:37:57Z

+			expectedNamespace: "context-ns",
+		},
+		{
+			name:              "FLUX_SYSTEM_NAMESPACE takes precedence over context namespace",


I don't believe this should be the expected behaviour as explained above.

Fixed in the last commit.

jtyr · 2026-04-20T07:06:38Z

@stefanprodan Please could you review this again?

jtyr · 2026-04-28T08:46:05Z

@stefanprodan @matheuscscp Any idea why the E2E test is failing?

matheuscscp · 2026-04-28T10:55:01Z

@stefanprodan @matheuscscp Any idea why the E2E test is failing?

@jtyr I investigated this for a while with Opus 4.7 and this is how far I got:

  Failure: The Run tests step (make test --tags=unit) fails in cmd/flux with:                                                                                                                                 
  - TestTrace/* — "deployments.apps 'podinfo' not found" (and similar for HelmRelease)                                                                                                                        
  - TestTree/* — "kustomizations... 'flux-system' not found"                                                                                                                                                  
                                                            
  Root cause: the new test file cmd/flux/main_context_ns_test.go (added in the PR) leaks state into subsequent tests. I reproduced it locally:                                                                
                                                                                                                                                                                                              
  - TestTrace alone → passes                                                                                                                                                                                  
  - TestContextNamespaceOptIn alone → passes                                                                                                                                                                  
  - Both together → TestTrace fails with "not found" against the envtest API server                                                                                                                           
                                                                                                                                                                                                              
  The new TestContextNamespaceOptIn test mutates the package-global kubeconfigArgs (a *genericclioptions.ConfigFlags): swaps KubeConfig/Context pointers, calls configureDefaultNamespace(), calls            
  getKubeconfigContextNamespace() (which invokes kubeconfigArgs.ToRawKubeConfigLoader()). Even though the test's t.Cleanup restores the visible pointer fields, ConfigFlags internally caches a clientConfig  
  (see cli-runtime/pkg/genericclioptions/config_flags.go — clientConfig + clientConfigLock), and that cache is not reset. The cached loader was bound to the per-subtest temp kubeconfig (which got           
  t.TempDir-deleted), and bisecting the 6 subtests shows the failure only triggers when multiple subtests run together — consistent with cumulative cache poisoning.

  Fix direction: the new test shouldn't mutate the package-global kubeconfigArgs. Either build a local *genericclioptions.ConfigFlags for the test (e.g. genericclioptions.NewConfigFlags(false)) and refactor
   getKubeconfigContextNamespace to take it as a parameter, or have cleanup replace kubeconfigArgs with a freshly constructed instance (and then re-kubeconfigArgs.KubeConfig = &testEnv.kubeConfigPath) so
  the internal cache is discarded.

jtyr · 2026-04-28T11:38:04Z

Thanks for providing the analysis, @matheuscscp. I have refactored getKubeconfigContextNamespace to take a *genericclioptions.ConfigFlags parameter, eliminating its dependency on the package-global kubeconfigArgs. The getKubeconfigContextNamespace, called from PersistentPreRunE, now passes kubeconfigArgs explicitly. Tests now construct their own local genericclioptions.NewConfigFlags(false) instance per subtest. This means:

The internal clientConfig cache lives only on the local instance.
No mutation of kubeconfigArgs whatsoever.
No t.Cleanup needed for kubeconfigArgs state restoration.
Subsequent tests like TestTrace and TestTree see a clean global kubeconfigArgs.

Please run the tests again so we can see if it passes now.

jtyr · 2026-04-28T20:40:07Z

Cool, tests pass now. Can we merge it now? ;o)

matheuscscp · 2026-04-28T21:50:54Z

This is a major breaking change that we can not accept. Imagine how many CI pipelines and custom scripts we are going to break with this, e.g. you have flux bootstrap in your pipeline, the default namespace in kubeconfig is to some namespace, with this change new clusters will end up with Flux in the selected namespace instead of flux-system.

@stefanprodan The implementation is no longer a breaking change, it's opt-in now. Can we merge?

matheuscscp · 2026-04-29T07:25:52Z

@jtyr Please squash the commits into one matching the PR title and force-push so we can merge 🙏

jtyr · 2026-04-30T07:19:24Z

@matheuscscp I have squashed the commits 👍

Signed-off-by: Jiri Tyr <jiri.tyr@gmail.com>

matheuscscp · 2026-04-30T09:00:23Z

@jtyr Thanks very much! You may not realize, but this is quite a feature! Probably top 10 requested by users historically. We should do a bit of noise about it! Can you please open a PR here: https://github.com/fluxcd/website/blob/main/content/en/roadmap.md?plain=1#L108-L113

makkes · 2026-04-30T13:26:04Z

Absolutely agree that this is a feature much longed for! Thanks @jtyr.

jtyr force-pushed the jtyr-context-ns branch 2 times, most recently from 168c848 to 78b99e0 Compare April 10, 2026 07:34

jtyr force-pushed the jtyr-context-ns branch from 78b99e0 to 642533e Compare April 10, 2026 08:00

jtyr force-pushed the jtyr-context-ns branch 3 times, most recently from e16ed58 to a1ddbb5 Compare April 10, 2026 13:22

matheuscscp approved these changes Apr 10, 2026

View reviewed changes

jtyr force-pushed the jtyr-context-ns branch 2 times, most recently from bb43542 to 39e6c46 Compare April 13, 2026 07:40

makkes reviewed Apr 13, 2026

View reviewed changes

jtyr force-pushed the jtyr-context-ns branch 2 times, most recently from 7cd113a to cde48c1 Compare April 13, 2026 17:13

makkes approved these changes Apr 14, 2026

View reviewed changes

jtyr force-pushed the jtyr-context-ns branch from cde48c1 to 33d2168 Compare April 22, 2026 13:12

stefanprodan approved these changes Apr 29, 2026

View reviewed changes

stefanprodan changed the title ~~Respect kubeconfig context namespace~~ Add --ns-follows-kube-context global flag for using the kubeconfig context namespace Apr 29, 2026

stefanprodan added the enhancement New feature or request label Apr 29, 2026

jtyr force-pushed the jtyr-context-ns branch from de17330 to aae7027 Compare April 29, 2026 07:30

Respect kubeconfig context namespace

c031d0c

Signed-off-by: Jiri Tyr <jiri.tyr@gmail.com>

jtyr force-pushed the jtyr-context-ns branch from aae7027 to c031d0c Compare April 30, 2026 07:19

matheuscscp merged commit c8b4c4c into fluxcd:main Apr 30, 2026
6 checks passed

jybp mentioned this pull request Apr 30, 2026

Add an en var to use the namespace declared in the kubeconfig context #5297

Closed

Conversation

jtyr commented Apr 10, 2026 • edited by stefanprodan Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Fix

Testing

Uh oh!

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

Uh oh!

Uh oh!

matheuscscp commented Apr 10, 2026

Uh oh!

jtyr commented Apr 10, 2026

Uh oh!

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

Uh oh!

Uh oh!

matheuscscp commented Apr 10, 2026

Uh oh!

jtyr commented Apr 10, 2026

Uh oh!

matheuscscp left a comment

Choose a reason for hiding this comment

Uh oh!

makkes Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

matheuscscp Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

jtyr Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

makkes Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

jtyr Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

jtyr commented Apr 20, 2026

Uh oh!

jtyr commented Apr 28, 2026

Uh oh!

matheuscscp commented Apr 28, 2026

Uh oh!

jtyr commented Apr 28, 2026

Uh oh!

jtyr commented Apr 28, 2026

Uh oh!

matheuscscp commented Apr 28, 2026

Uh oh!

matheuscscp commented Apr 29, 2026

Uh oh!

jtyr commented Apr 30, 2026

Uh oh!

Uh oh!

matheuscscp commented Apr 30, 2026

Uh oh!

makkes commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jtyr commented Apr 10, 2026 •

edited by stefanprodan

Loading

stefanprodan commented Apr 10, 2026 •

edited

Loading

jtyr commented Apr 10, 2026 •

edited

Loading