diff --git a/0023-zarf-named-configs/README.md b/0023-zarf-named-configs/README.md new file mode 100644 index 0000000..0d357bd --- /dev/null +++ b/0023-zarf-named-configs/README.md @@ -0,0 +1,254 @@ + + +# ZEP-0023: Zarf Named Configs + + + + + + +- [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 allow configuration specific to a Zarf package deployment to be named, versioned and published to a registry so that it can simplify the deployment experience for end users. + +## Motivation + +This proposal comes from a desire to even further lower the barrier to entry for the deploy persona by pre-baking some deployment configuration for a Zarf package into named configurations that can be selected from. In some environments a user deploying a Zarf package may not have system administrator experience and an SRE may want to pre-configure the package for them to make the package even more declarative and easier to manage. Additionally many Zarf packages cross security domains and might not be able to contain their related configuration inside the package at create time. Having a way to marry the package with the configuration within the deployment environment would help with this as well. Some packages also may have a set of configurations that could be selected from (i.e. `device1`, `device2`, `device3`) that would be useful to manage sets of similar but different deployments. + +### Goals + +- Provide a way for Zarf packages to reference pre-baked configurations during deployments +- Enhance the declarative design of Zarf + +### Non-Goals + +- Provide configuration outside of the deployment of the package (i.e. geared towards the Ashton persona) +- Include security relevant deployment configuration in the registry (i.e. package signing keys) + +## Proposal + +The proposed solution introduces a new named configuration type to Zarf to allow for a managed way to provide deployment configuration for a package. This would include most options that are available in a `zarf-config` file under `package.deploy` including the new options mentioned in [ZEP-0021](../0021-zarf-values/README.md) and [ZEP-0017](../0017-chart-namespace-overrides/README.md). This file would be tied to a specific Zarf package name and version in addition to its own name and version. This configuration could then be published in a registry and/or be referenced on `zarf package deploy` or `zarf dev deploy`. + +### User Stories (Optional) + +#### Story 1 + +**As** Jacquline **I want** to be able to pre-bake package configuration **so that** I can provide a more declarative package to Ashton. + +**Given** I have a Zarf Package created from the below: +```yaml +metadata: + kind: ZarfPackageConfig + name: example + version: 0.1.0 + namespace: example + +variables: + - name: EXAMPLE + +values: + - values-default.yaml + +components: + - name: first + ... + - name: second + ... +``` +**And** I have a new configuration published from the following +```yaml +# option 1 +kind: ZarfNamedConfig +# option 2 +kind: ZarfDeployConfig +# option 3 +kind: ZarfConfig +metadata: + name: example-config + version: 0.1.0 + +package: + name: example + version: 0.1.0 + +components: [ first ] + +namespace: new-namespace + +set: + EXAMPLE: example + +values: + - values-override.yaml + +adopt-existing-resources: true +``` +**When** I deploy that package with a `--config` like the below: +```bash +zarf package deploy oci://my-registry/example:0.1.0 --config oci://my-registry/example-config:0.1.0 +``` +**Then** Zarf will set the deploy options in accordance with the referenced config + +### Risks and Mitigations + +This would make it easy to potentially accidentally store secrets in the registry which is not desireable. We should add documentation about this and potentially prevent the storage of variables that are marked `sensitive` in named configs. + +## Design Details + + +Named configs would be created and published through a set of new CLI commands (`zarf config create` and `zarf config publish`). This would pull together any referenced files or necessary artifacts and either create a local `tar.zst` or publish an OCI reference similar to a package. This config would then be referenced and applied during a package deployment. + +Because package configurations refer to packages a `zarf config list oci:///` command would also be added that, for an OCI reference, would list the available named configs for that package. + +### 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 + +Unit tests would need to be added to ensure that the config was passed into the package deploy library interface correctly. + +##### e2e tests + +Additional end to end tests would need to be added to ensure that the CLI flags and Viper config properly configured Zarf to use the published config. Config publishing from the CLI would also need to be tested. + +### Graduation Criteria + +Pending review / community input these changes would be moved from alpha status and be marked as stable within Zarf's Package definition. This would be based on user adoption of the feature and confidence in its continued stability. + +### Upgrade / Downgrade Strategy + +NA - There would be no upgrade / downgrade of cluster installed components + +### Version Skew Strategy + +NA - This proposal is an entirely new feature and does not impact existing behavior + +## Implementation History + + + +## Drawbacks + +This is limited to only the package deployment options and does not allow for the full range of options that one may want to change in a Zarf package. This means that while an SRE can set configuration for a package they cannot override the package contents in any way and would need to contact the original package creator for assistance. + +## Alternatives + +Similar to [ZEP-0017](../0017-chart-namespace-overrides/README.md) we could allow for Zarf package remixing: + +**Given** I have a Zarf Package with a chart named `my-chart` in a component named `my-component` +**And** I have a new ZarfRemixConfig created from the following +```yaml +kind: ZarfRemixConfig +metadata: + name: test-override + version: 0.1.0 + ref: oci://my-registry/test:0.1.0 + +remix: + my-component: + my-chart: + namespace: new-namespace +``` +**When** I create a new package from that with: +```bash +zarf package create zarf-remix.yaml +``` +**Then** Zarf will change the chart's release namespace to `new-namespace` in the new package +**And When** I deploy that package +**Then** the chart will be in the `new-namespace` namespace. + +To allow multiple configured packages to be created from one base package. This has the potential though to introduce Zarf package sprawl and could clog a registry with references to Zarf packages that are mostly the same. + +## Infrastructure Needed (Optional) + +NA - This change requires no additional infrastructure as it is internal to Zarf's operation. diff --git a/0023-zarf-named-configs/zep.yaml b/0023-zarf-named-configs/zep.yaml new file mode 100644 index 0000000..9c305e1 --- /dev/null +++ b/0023-zarf-named-configs/zep.yaml @@ -0,0 +1,29 @@ +schema-version: 1.0.0 + +title: Zarf Named Configs +zep-number: 0023 +authors: + - "@racer159" +status: implementable +creation-date: 2025-04-01 +reviewers: + - "@zarf-dev" +approvers: + - "@zarf-dev" + +see also: + - "/0021-zarf-values" + - "/0017-chart-namespace-overrides" + +# 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: "NA" + stable: "v1.0"