feat(deploy): support for package namespace override flag #3889

brandtkeller · 2025-06-03T21:12:43Z

Description

This pull request adds support for a --namespace flag in the deploy operation - allowing users with a single-namespace package to deploy the package multiple times to multiple isolated namespaces. This is the implementation for proposal ZEP-0017.

Constraints

This does not support package namespace overrides for ZarfInitConfig packages.

Design Choices

Use of ZarfPackage methods for validating a package has only declared a single namespace & updating all package components to the target namespace
Add NamespaceOverride as a new field under DeployedPackage
- Use of functional options for setting namespace - while it is exposed - helps provide a mechanism where the signature of existing cluster methods do not need to be modified.
- Exposing the NamespaceOverride field with json tags allows us to store it in the package state secret. Any call to cluster.GetDeployedZarfPackages will have the information innately.
- Ensures secret delineation should not conflict by not using package name solely for secret identification.
- formats overriden state secret with zarf-package-my-package-override-namespacename such that the collisions should only occur in a very specific edgecase.
Logic/Testing for config file override is included
Updates DeployedPackage and remaining "k8s" types to state package.
Backwards compatible with older versions of Zarf - allowing for package list/inspect operations without panic.

Related Issue

Fixes #2407

Checklist before merging

Test, docs, adr added or updated as needed
Contributor Guide Steps followed

Signed-off-by: Brandt Keller <[email protected]>

netlify · 2025-06-03T21:12:48Z

✅ Deploy Preview for zarf-docs canceled.

Name	Link
🔨 Latest commit	`36d60f1`
🔍 Latest deploy log	https://app.netlify.com/projects/zarf-docs/deploys/684893a1e2105b0009675390

codecov · 2025-06-03T21:15:29Z

Codecov Report

Attention: Patch coverage is 19.25926% with 109 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/internal/packager2/deploy.go	0.00%	25 Missing ⚠️
src/api/v1alpha1/package.go	0.00%	19 Missing ⚠️
src/cmd/package.go	33.33%	16 Missing ⚠️
src/pkg/cluster/zarf.go	48.14%	14 Missing ⚠️
src/pkg/message/connect.go	0.00%	10 Missing ⚠️
src/pkg/state/state.go	0.00%	10 Missing ⚠️
src/internal/packager2/packager2.go	0.00%	6 Missing ⚠️
src/internal/packager2/remove.go	0.00%	4 Missing ⚠️
src/internal/packager/helm/post-render.go	0.00%	2 Missing ⚠️
src/cmd/connect.go	0.00%	1 Missing ⚠️
... and 2 more

Files with missing lines	Coverage Δ
src/cmd/viper.go	`53.08% <ø> (ø)`
src/internal/packager2/load.go	`57.55% <100.00%> (ø)`
src/pkg/cluster/tunnel.go	`10.08% <100.00%> (ø)`
src/cmd/connect.go	`32.63% <0.00%> (ø)`
src/cmd/crane.go	`29.82% <0.00%> (ø)`
src/internal/packager/helm/chart.go	`1.29% <0.00%> (ø)`
src/internal/packager/helm/post-render.go	`0.00% <0.00%> (ø)`
src/internal/packager2/remove.go	`0.00% <0.00%> (ø)`
src/internal/packager2/packager2.go	`14.28% <0.00%> (-3.90%)`	⬇️
src/pkg/message/connect.go	`0.00% <0.00%> (ø)`
... and 5 more

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Signed-off-by: Brandt Keller <[email protected]>

…espace

src/test/e2e/40_namespace_override_test.go

AustinAbro321

A few nits on an overall simple & elegant solution

src/api/v1alpha1/package.go

src/config/lang/english.go

src/test/e2e/40_namespace_override_test.go

Signed-off-by: Brandt Keller <[email protected]>

…espace

Signed-off-by: Brandt Keller <[email protected]>

…de support Signed-off-by: Brandt Keller <[email protected]>

AustinAbro321

I like the change in direction, a few suggestions + calls for unit tests

src/internal/packager2/deploy.go

AustinAbro321 · 2025-06-09T10:57:43Z

src/config/lang/english.go


 	CmdPackageMirrorFlagComponents = "Comma-separated list of components to mirror.  This list will be respected regardless of a component's 'required' or 'default' status.  Globbing component names with '*' and deselecting components with a leading '-' are also supported."
 	CmdPackageMirrorFlagNoChecksum = "Turns off the addition of a checksum to image tags (as would be used by the Zarf Agent) while mirroring images."

 	CmdPackageInspectFlagSbomOut    = "Specify an output directory for the SBOMs from the inspected Zarf package"
 	CmdPackageInspectFlagListImages = "List images in the package (prints to stdout)"
+	CmdPackageInspectFlagNamespace  = "[Alpha] Override the namespace for package inspection. Requires the package to have been deployed using the namespace override."


Requires feels like the wrong verb here. Maybe something like Applicable only to in-cluster packages deployed to a dynamic namespace. Ditto for remove

That is fair! modified to potentially meet this intent.

AustinAbro321 · 2025-06-09T11:06:36Z

src/cmd/package.go

+	if opts.NamespaceOverride != "" {
+		nsCount := pkgLayout.Pkg.GetUniqueNamespaceCount()
+		if nsCount > 1 {
+			return nil, fmt.Errorf("package contains %d namespaces, cannot override namespace to %s", nsCount, opts.NamespaceOverride)
+		}
+		pkgLayout.Pkg.SetPackageNamespace(opts.NamespaceOverride)
+	}


I get why we validate and set the package namespace early here, but we should also validate and set the package namespace at the CLI level. Currently, Deploy accepts the NamespaceOverride opt, but if someone is calling the function purely at the SDK level, then it will only have an impact on the secret, not on the namespace the package is deployed to. To avoid duplication, one option would be to make a common function in packager2 both deploy and the cli can call.

Great points - I tested a few different strategies for locality of the namespace override identifiers and ultimately landed on your thoughts as well. Isolating the logic in a common function and then duplicating across CLI/SDK to meet parity while primarily isolating the core logic to DeployOptions and Deploy().

src/cmd/package_test.go

src/internal/packager2/remove.go

src/internal/packager2/load.go

src/pkg/cluster/zarf.go

Signed-off-by: Brandt Keller <[email protected]>

AustinAbro321

One small nit, otherwise lgtm

AustinAbro321 · 2025-06-10T12:37:05Z

site/src/content/docs/commands/zarf_package_remove.md

@@ -24,6 +24,7 @@ zarf package remove { PACKAGE_SOURCE | PACKAGE_NAME } --confirm [flags]
      --components string           Comma-separated list of components to remove.  This list will be respected regardless of a component's 'required' or 'default' status.  Globbing component names with '*' and deselecting components with a leading '-' are also supported.
      --confirm                     REQUIRED. Confirm the removal action to prevent accidental deletions
  -h, --help                        help for remove
+  -n, --namespace string            [Alpha] Override the namespace for package removal. Applicable only to packages deployed using the namespace override flag.


If we're adding the -n shorthand we should add it to the other commands. Also we should just say the "namespace flag" instead of "namespace override flag" imo.

Signed-off-by: Brandt Keller <[email protected]>

…espace

Racer159 · 2025-06-10T19:12:37Z

😈

brandtkeller · 2025-06-10T20:05:32Z

@Racer159 you raised a good point that a constraint behind this is that it does not support init-packages to-date. We'd need to rewire all of the hardcoded assumptions around the zarf namespace, state, etc.

Signed-off-by: Brandt Keller <[email protected]>

brandtkeller added 3 commits June 3, 2025 16:57

feat(deploy): support for package namespace overrides

f419580

Signed-off-by: Brandt Keller <[email protected]>

feat(deploy): e2e test for namespace overrides

424ae0a

Signed-off-by: Brandt Keller <[email protected]>

feat(deploy): switch to load/layout options definition

5027a4e

Signed-off-by: Brandt Keller <[email protected]>

brandtkeller self-assigned this Jun 3, 2025

brandtkeller added 3 commits June 3, 2025 21:30

chore(docs): update documentation for new deploy flag

ed80936

Signed-off-by: Brandt Keller <[email protected]>

fix(package): update namespace logic without pointer

26c040d

Signed-off-by: Brandt Keller <[email protected]>

Merge branch 'main' of github.com:zarf-dev/zarf into 2407_package_nam…

e3c0bb2

…espace

brandtkeller marked this pull request as ready for review June 3, 2025 22:05

brandtkeller requested review from a team as code owners June 3, 2025 22:05

brandtkeller commented Jun 3, 2025

View reviewed changes

src/test/e2e/40_namespace_override_test.go Outdated Show resolved Hide resolved

AustinAbro321 requested changes Jun 4, 2025

View reviewed changes

src/api/v1alpha1/package.go Outdated Show resolved Hide resolved

src/config/lang/english.go Outdated Show resolved Hide resolved

src/test/e2e/40_namespace_override_test.go Outdated Show resolved Hide resolved

src/test/e2e/40_namespace_override_test.go Outdated Show resolved Hide resolved

brandtkeller added 3 commits June 4, 2025 13:24

fix(deploy): revising logic to support logic/test comments

8163128

Signed-off-by: Brandt Keller <[email protected]>

chore(docs): generate docs updates

2745b19

Signed-off-by: Brandt Keller <[email protected]>

Merge branch 'main' of github.com:zarf-dev/zarf into 2407_package_nam…

7633f1e

…espace

brandtkeller requested a review from AustinAbro321 June 4, 2025 14:21

brandtkeller added 3 commits June 4, 2025 16:17

feat(remove): support for tarball namespace-override removal

10329e9

Signed-off-by: Brandt Keller <[email protected]>

chore(docs): add doccomments for remove options

e909d0c

Signed-off-by: Brandt Keller <[email protected]>

fix(test): support for tarball/deployed package removal permutations

681bd82

Signed-off-by: Brandt Keller <[email protected]>

brandtkeller marked this pull request as draft June 4, 2025 18:36

brandtkeller added 5 commits June 4, 2025 21:42

wip(deploy): temporary home for functional options

1a851d0

Signed-off-by: Brandt Keller <[email protected]>

WIP: prove the process - then integrate experiments

75eeea4

Signed-off-by: Brandt Keller <[email protected]>

feat(state): update DeployedPackages to the State package

505314c

Signed-off-by: Brandt Keller <[email protected]>

Merge main into feature branch 2407_package_namespace

d84baef

Signed-off-by: Brandt Keller <[email protected]>

fix(test): update testing and naming conventions

f5a4159

Signed-off-by: Brandt Keller <[email protected]>

brandtkeller mentioned this pull request Jun 6, 2025

refactor: move zarf state structs from src/types -> src/pkg/state #3897

Merged

2 tasks

brandtkeller added 2 commits June 6, 2025 19:19

merge main into feature branch 2407_package_namespace

ad09a86

Signed-off-by: Brandt Keller <[email protected]>

feat(inspect): support for package inspect with namespace override

06f7645

Signed-off-by: Brandt Keller <[email protected]>

chore(docs): generate docs for inspect commands with namespace overri…

d490941

…de support Signed-off-by: Brandt Keller <[email protected]>

brandtkeller marked this pull request as ready for review June 6, 2025 21:15

AustinAbro321 requested changes Jun 9, 2025

View reviewed changes

brandtkeller added 5 commits June 9, 2025 17:38

merge main into feature branch 2407_package_namespace

8943f12

Signed-off-by: Brandt Keller <[email protected]>

feat(pacakge): support for common namespace override

9bef4cb

Signed-off-by: Brandt Keller <[email protected]>

feat(load): support namespace override during get/load package

b027027

Signed-off-by: Brandt Keller <[email protected]>

feat(deploy): isolate override logic to deploy operations

17af409

Signed-off-by: Brandt Keller <[email protected]>

chore(docs): update documentation

70277cf

Signed-off-by: Brandt Keller <[email protected]>

AustinAbro321 requested changes Jun 10, 2025

View reviewed changes

brandtkeller added 2 commits June 10, 2025 15:57

chore(docs): update command flags and docs accordingly

684ba21

Signed-off-by: Brandt Keller <[email protected]>

Merge branch 'main' of github.com:zarf-dev/zarf into 2407_package_nam…

0baf3ef

…espace

Merge main into feature branch 2407_package_namespace

36d60f1

Signed-off-by: Brandt Keller <[email protected]>

feat(deploy): support for package namespace override flag #3889

Are you sure you want to change the base?

feat(deploy): support for package namespace override flag #3889

Uh oh!

Conversation

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

Uh oh!

Description

Constraints

Design Choices

Related Issue

Checklist before merging

Uh oh!

netlify bot commented Jun 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for zarf-docs canceled.

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

Uh oh!

AustinAbro321 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AustinAbro321 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AustinAbro321 Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

brandtkeller Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

AustinAbro321 Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

brandtkeller Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AustinAbro321 left a comment

Choose a reason for hiding this comment

Uh oh!

AustinAbro321 Jun 10, 2025

Choose a reason for hiding this comment

Uh oh!

Racer159 commented Jun 10, 2025

Uh oh!

brandtkeller commented Jun 10, 2025

Uh oh!

Uh oh!

brandtkeller commented Jun 3, 2025 •

edited

Loading

netlify bot commented Jun 3, 2025 •

edited

Loading

codecov bot commented Jun 3, 2025 •

edited

Loading