diff --git a/0017-chart-namespace-overrides/README.md b/0017-chart-namespace-overrides/README.md new file mode 100644 index 0000000..1b11d59 --- /dev/null +++ b/0017-chart-namespace-overrides/README.md @@ -0,0 +1,298 @@ + + +# ZEP-0017: Chart Namespace Overrides + + + + + + +- [Summary](#summary) +- [Motivation](#motivation) + - [Goals](#goals) + - [Non-Goals](#non-goals) +- [Proposal](#proposal) + - [User Stories (Optional)](#user-stories-optional) + - [Story 1](#story-1) + - [Story 2](#story-2) + - [Risks and Mitigations](#risks-and-mitigations) +- [Design Details](#design-details) + - [Test Plan](#test-plan) + - [Prerequisite testing updates](#prerequisite-testing-updates) + - [Unit tests](#unit-tests) + - [e2e tests](#e2e-tests) + - [Graduation Criteria](#graduation-criteria) + - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy) + - [Version Skew Strategy](#version-skew-strategy) +- [Implementation History](#implementation-history) +- [Drawbacks](#drawbacks) +- [Alternatives](#alternatives) +- [Infrastructure Needed (Optional)](#infrastructure-needed-optional) + + +## Summary + +This ZEP proposes to enable a namespace override for charts similar to the namespace override [functionality available in UDS CLI](https://uds.defenseunicorns.com/reference/bundles/overrides/#namespace). This would allow namespaces of charts within a Zarf package to be overridden so that multiples of the same Zarf package could be deployed to the same cluster under different namespaces (without needing to maintain variants of the same package). + +## Motivation + +Doing this allows more flexibility with certain Zarf packages where you may want to have multiples of them installed in the cluster with slightly different configurations (such as [GitLab Runners](https://github.com/defenseunicorns/uds-package-gitlab-runner)). Right now the release namespace of any chart has to be hardcoded into the package and will be overwritten even if the chart allows namespace overrides for some objects within the chart. The current behavior is also different from what Helm does by default which may not be what users of Zarf expect (Helm allows the use of the `namespace` flag on install to set the Chart's namespace without it needing to be baked into the Chart). + +### Goals + +- Provide a way for a Zarf package containing Helm Charts to be easily installed more than once with different configurations + +### Non-Goals + +- Move away from the declarative nature of Zarf packages + +## Proposal + +The proposed solution is to add a deploy configuration option that has a `map[string]string` referencing the names of charts within the Zarf Package correlated with their overridden namespaces. + +### User Stories (Optional) + +#### Story 1 + +**As** Jacquline **I want** to be able to set namespace overrides **so that** I can install the same package with different configurations in different namespaces. + +##### Option 1 (Flatter Namespaces) + +**Given** I have a Zarf Package with a chart named `my_chart` in a component named `my_component` +**When** I deploy that package with a `zarf-config.yaml` like the below*: +```yaml +package: + deploy: + namespaces: + my_component: + my_chart: new-namespace +``` +**Then** Zarf will change the chart's release namespace to `new-namespace` + +**Given** I have a Zarf Package with a chart named `my_chart` in a component named `my_component` +**When** I deploy that package with a `--namespace` like the below: +```yaml +zarf package deploy zarf-package-test.tar.zst --namespace my_component.my_chart=new-namespace +``` +**Then** Zarf will change the chart's release namespace to `new-namespace` + +##### Option 2 (UDS CLI Style) + +**Given** I have a Zarf Package with a chart named `my_chart` in a component named `my_component` +**When** I deploy that package with a `zarf-config.yaml` like the below*: +```yaml +package: + deploy: + overrides: + my_component: + my_chart: + namespace: new-namespace +``` +**Then** Zarf will change the chart's release namespace to `new-namespace` + +**Given** I have a Zarf Package with a chart named `my_chart` in a component named `my_component` +**When** I deploy that package with a `--overrides` like the below: +```yaml +zarf package deploy zarf-package-test.tar.zst --overrides my_component.my_chart.namespace=new-namespace +``` +**Then** Zarf will change the chart's release namespace to `new-namespace` + +##### Option 3 (Zarf Variable Style) + +**Given** I have a Zarf Package with a chart named `my_chart` in a component named `my_component` +**And** the chart's namespace is set as the variable `MY_CHART_NAMESPACE` +**When** I deploy that package with a `zarf-config.yaml` like the below*: +```yaml +package: + deploy: + set: + MY_CHART_NAMESPACE: new-namespace +``` +**Then** Zarf will change the chart's release namespace to `new-namespace` + +**Given** I have a Zarf Package with a chart named `my_chart` in a component named `my_component` +**And** the chart's namespace is set as the variable `MY_CHART_NAMESPACE` +**When** I deploy that package with a `--set` like the below: +```yaml +zarf package deploy zarf-package-test.tar.zst --set MY_CHART_NAMESPACE=new-namespace +``` +**Then** Zarf will change the chart's release namespace to `new-namespace` + +##### Option 4 (Prefix/Suffix Style) + +**Given** I have a Zarf Package with a chart deploying to `my-namespace` +**When** I deploy that package with a `zarf-config.yaml` like the below*: +```yaml +package: + deploy: + namespace-prefix: new- + namespace-suffix: -kitteh +``` +**Then** Zarf will change the chart's release namespace to `new-my-namespace-kitteh` + +**Given** I have a Zarf Package with a chart deploying to `my-namespace` +**When** I deploy that package with a `--set` like the below: +```yaml +zarf package deploy zarf-package-test.tar.zst --namespace-prefix new- --namespace-suffix -kitteh +``` +**Then** Zarf will change the chart's release namespace to `new-my-namespace-kitteh` + +##### Option 5 (Package Namespace Style) + +TODO: (@WSTARR) - this one is a little more wishy washy but captures some more input from folks + +**Given** I have a Zarf Package that implements a new package `namespace` field +``` +kind: ZarfPackageConfig +metadata: + name: test + namespace: my-namespace +``` +**And** That package has resources that reference the package namespace +``` + charts: + - name: my-chart + namespace: {{ .Package.Namespace }} +``` +**When** I deploy that package with a `zarf-config.yaml` like the below*: +```yaml +package: + deploy: + namespace: new-namespace +``` +**Then** Zarf will change the chart's release namespace to `new-namespace` + +**Given** I have a Zarf Package that implements a new package `namespace` field +``` +kind: ZarfPackageConfig +metadata: + name: my-package + namespace: my-namespace +``` +**And** That package has resources that reference the package namespace +``` + charts: + - name: my-chart + namespace: {{ .Package.Namespace }} +``` +**When** I deploy that package with a `--set` like the below: +```yaml +zarf package deploy zarf-package-test.tar.zst --namespace new-namespace +``` +**Then** Zarf will change the chart's release namespace to `new-namespace` + +### Risks and Mitigations + +TODO - (@WSTARR) + +## Design Details + +TODO - (@WSTARR) + +This proposal will affect the release namespace of a chart (or manifest) so that the Helm release secrets and any templates that use the `.Release.Namespace` template would use the newly provided namespace. This would ensure that charts wouldn't affect the history or objects of prior deployments and would be able to properly install alongside one another. This would not affect namespaces that are defined under .Values as those would still be controlled by the package configuration and Zarf variables as they are today. + +### Test Plan + +[X] I/we understand the owners of the involved components may require updates to +existing tests to make this code solid enough prior to committing the changes necessary +to implement this proposal. + +##### Prerequisite testing updates + +NA - This is a modification of existing behavior that should not require prerequisite testing updates. + +##### Unit tests + +TODO - (@WSTARR) + +##### e2e tests + +TODO - (@WSTARR) + +### Graduation Criteria + +TODO - (@WSTARR) + +### Upgrade / Downgrade Strategy + +NA - There would be no upgrade / downgrade of cluster installed components + +### Version Skew Strategy + +NA - This proposal doesn't impact how Zarf's components interact + +## Implementation History + + + +## Drawbacks + +TODO - (@WSTARR) + +## Alternatives + +TODO - (@WSTARR) + +## Infrastructure Needed (Optional) + +NA - This change requires no additional infrastructure as it is internal to Zarf's operation. diff --git a/0017-chart-namespace-overrides/zep.yaml b/0017-chart-namespace-overrides/zep.yaml new file mode 100644 index 0000000..02774d6 --- /dev/null +++ b/0017-chart-namespace-overrides/zep.yaml @@ -0,0 +1,25 @@ +schema-version: 1.0.0 + +title: Chart Namespace Overrides +zep-number: 0017 +authors: + - "@racer159" +status: implementable +creation-date: 2025-02-03 +reviewers: + - "@zarf-dev" +approvers: + - "@zarf-dev" + +# The target maturity stage in the current dev cycle for this ZEP. +stage: alpha + +# The most recent milestone for which work toward delivery of this ZEP has been +# done. This can be the current (upcoming) milestone, if it is being actively +# worked on. +latest-milestone: NA + +# The milestone at which this feature was, or is targeted to be, at each stage. +milestone: + alpha: "TBD" + stable: "v1.0"