UDS Package Requirements

UDS Packages must meet a set of standards to ensure they are secure, maintainable, and compatible with UDS Core. This page defines those standards using RFC-2119 terminology: MUST indicates a mandatory requirement, SHOULD a strong recommendation, and MAY an optional practice.

Note

Use this page as a pre-publish checklist for UDS Packages. UDS Packages are Zarf Packages that are integrated with the UDS Core platform and follow additional standards to ensure consistency - not everything Zarf can do can be in a UDS Package.

For step-by-step guidance on building a package that meets these requirements, see Create a UDS Package.

These requirements are mandatory for Defense Unicorns engineers. For external maintainers, they are strongly recommended to promote consistency, quality, and security across the UDS ecosystem.

Security, policy, and hardening

• MUST minimize the scope and number of exemptions, to only what is absolutely required by the application. UDS Packages MAY make use of the UDS Exemption custom resource for exempting any Pepr policies, but in doing so they MUST document rationale for the exemptions. Exemptions should be documented in docs/justifications.md of the UDS Package repository.
• MUST declaratively implement any available application hardening guidelines by default.
• SHOULD consider security options during implementation to provide the most secure default possible (i.e. SAML w/SCIM vs OIDC).

Packaging lifecycle and configuration

• MUST be declaratively defined as a Zarf package.
• MUST integrate declaratively (i.e. no clickops) with the UDS Operator.
• MUST be capable of operating within the airgap (internet-disconnected).
• MUST not use local commands outside of coreutils or ./zarf self references within zarf actions.
• MUST use Helm charts for rendering Kubernetes resources. When available and suitable for UDS packaging, an upstream chart MUST be used. When using an upstream chart, UDS-specific configurations SHOULD be encapsulated in a separate config Helm chart.

  This keeps the package structure clean and maintainable by separating concerns into inspectable units. Using upstream charts also makes it easier to incorporate upstream changes over time.

• MUST (except if the application provides no application metrics) implement monitors for each application metrics endpoint using its built-in chart monitors, monitor key, or manual monitors in the config chart. Monitor Resource
• MUST include package documentation in a root-level docs folder (for configuration and dependencies) and include it in the Zarf package under the documentation key.
• MUST include application metadata for UDS Registry publishing. See Package Metadata.
• SHOULD follow the Package Values guidance for exposing package configuration.

  Zarf Values is currently an Alpha feature and may change as it matures (see zarf-dev/zarf#3946). This guidance will evolve with the feature and as such, packages MAY still use Zarf Variables. If you adopt Values today, feedback in the Zarf repository is strongly encouraged.

• SHOULD limit the use of Zarf Variables and prioritize configuring packages via Zarf Values.

  This ensures that the package has more flexibility and avoids any side effect issues of Zarf’s ### templating (which is planned to be deprecated and removed once Zarf Values is stable).

• SHOULD implement or allow for multiple flavors (ideally with common definitions in a common directory).

  This allows for different images or configurations to be delivered consistently to customers.

Networking and service mesh

• MUST define network policies under the allow key as required in the UDS Package Custom Resource. These policies MUST adhere to the principle of least privilege, permitting only strictly necessary traffic.
• MUST define any external interfaces under the expose key in the UDS Package Custom Resource.
• MUST not rely on exposed interfaces (e.g., .uds.dev) being accessible from the deployment environment (bastion or pipeline).
• MUST deploy and operate successfully with Istio enabled.
• SHOULD use Istio Ambient unless specific technical constraints require otherwise.
• MAY use Istio Sidecars, when Istio Ambient is not technically feasible. Must document the specific technical constraints in docs/justifications.md if using Sidecars.
• SHOULD avoid workarounds with Istio such as disabling strict mTLS peer authentication.
• MAY template network policy keys to provide flexibility for customers to configure.

Identity and access management

• MUST use and create a Keycloak client through the sso key for any UDS Package providing an end-user login. SSO Resource
• SHOULD name the Keycloak client <App> Login (i.e. Mattermost Login) to provide login UX consistency.
• SHOULD clearly mark the Keycloak client id with the group and app name uds-<group>-<application> (i.e. uds-swf-mattermost) to provide consistency in the Keycloak UI.
• MAY end any generated Keycloak client secrets with sso to easily locate them when querying the cluster.
• MAY template Keycloak fields to provide flexibility for customers to configure.

Testing

• MUST implement Journey testing, covering the basic user flows and features of the application. (see Testing Guidelines)
• MUST implement Upgrade Testing to ensure that the current development package works when deployed over the previously released one. (see Testing Guidelines)

Package maintenance

• MUST be actively maintained by the package maintainers identified in CODEOWNERS.
• MUST have a dependency management bot (such as renovate) configured to open PRs to update the core package and support dependencies.
• MUST publish the package to the standard package registry, using a namespace and name that clearly identifies the application (e.g., ghcr.io/uds-packages/neuvector).
• SHOULD be created from the UDS Package Template.
• SHOULD lint configurations with appropriate tooling, such as yamllint and zarf dev lint.

Versioning

• MUST use the versioning scheme described below. If the scheme does not apply (for example, a monorepo like UDS Core), use Semantic Versioning 2.0.0 instead.
• MUST version consistently across flavors. Flavors should differ in image bases or builds, not application versions.
• SHOULD prepend git tags with a v to distinguish them from other tags, while leaving OCI tags as the raw version.

Example versioning scheme

Versions follow the format <upstream-app-version>-uds.<uds-sub-version>.

• upstream-app-version — the version of the application itself.
• uds-sub-version — the UDS release number, it starts at 0 and increments with each release that doesn’t change the app version.

Example where App Version for Reference package is 0.1.0 and the App Version stays the same: • First UDS release 0.1.0-uds.0 • Second UDS release 0.1.0-uds.1

Example where App Version increments from 0.1.0 -> 0.2.0: • First UDS release 0.2.0-uds.0

Tip

Ready to create your own package? See the Packaging Applications how-to guides for step-by-step guidance.