diff --git a/README.md b/README.md index e0304a1b..59c1e51e 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![Build Status](https://img.shields.io/github/actions/workflow/status/defenseunicorns/uds-common/release.yaml)](https://github.com/defenseunicorns/uds-common/actions/workflows/release.yaml) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/defenseunicorns/uds-common/badge)](https://api.securityscorecards.dev/projects/github.com/defenseunicorns/uds-common) -This repo acts as a UDS Package Framework that contains common configuration, tasks and documentation useful for building downstream UDS Packages. It defines and helps consumers implement [UDS package practices](./docs/package_integration/uds-package-practices.md) within their specific package repositories and is intended to help streamline keeping those practices up to date over time. +This repo acts as a UDS Package Framework that contains common configuration, tasks and documentation useful for building downstream UDS Packages. It defines and helps consumers implement [UDS package practices](./docs/uds-packages/requirements/uds-package-requirements.md) within their specific package repositories and is intended to help streamline keeping those practices up to date over time. ## Contents diff --git a/docs/made-for-uds-bronze.svg b/docs/assets/made-for-uds-bronze.svg similarity index 100% rename from docs/made-for-uds-bronze.svg rename to docs/assets/made-for-uds-bronze.svg diff --git a/docs/made-for-uds-gold.svg b/docs/assets/made-for-uds-gold.svg similarity index 100% rename from docs/made-for-uds-gold.svg rename to docs/assets/made-for-uds-gold.svg diff --git a/docs/made-for-uds-silver.svg b/docs/assets/made-for-uds-silver.svg similarity index 100% rename from docs/made-for-uds-silver.svg rename to docs/assets/made-for-uds-silver.svg diff --git a/docs/made-for-uds.svg b/docs/assets/made-for-uds.svg similarity index 100% rename from docs/made-for-uds.svg rename to docs/assets/made-for-uds.svg diff --git a/docs/package_integration/.images/cmd-pallete.png b/docs/uds-packages/.images/cmd-pallete.png similarity index 100% rename from docs/package_integration/.images/cmd-pallete.png rename to docs/uds-packages/.images/cmd-pallete.png diff --git a/docs/package_integration/development-ide-configuration.md b/docs/uds-packages/development/development-ide-configuration.md similarity index 100% rename from docs/package_integration/development-ide-configuration.md rename to docs/uds-packages/development/development-ide-configuration.md diff --git a/docs/package_integration/guide.md b/docs/uds-packages/guide.md similarity index 96% rename from docs/package_integration/guide.md rename to docs/uds-packages/guide.md index 9deeed7a..4812ff1e 100644 --- a/docs/package_integration/guide.md +++ b/docs/uds-packages/guide.md @@ -2,7 +2,7 @@ ## Introduction -This guide is intended for developers integrating applications with UDS (Unicorn Delivery Service). It provides an overview of the integration process, key considerations, and resources to ensure a smooth integration. +This guide is intended for developers integrating applications with UDS (Unicorn Delivery Service). It provides an overview of the integration process, key considerations, and resources to ensure a smooth integration. If you are familiar with UDS Package creation, [Badging Requirements](./requirements/uds-package-requirements.md) may be more relevant. Integrating a Package fundamentally means: 1. Creating a repository `uds-package-` from [uds-package-template](https://github.com/defenseunicorns/uds-package-template) diff --git a/docs/uds-packages/guidelines/metadata-guidelines.md b/docs/uds-packages/guidelines/metadata-guidelines.md new file mode 100644 index 00000000..3eb5a244 --- /dev/null +++ b/docs/uds-packages/guidelines/metadata-guidelines.md @@ -0,0 +1,7 @@ +# Application Metadata + +When a uds-package [achieves a badge](../requirements/uds-package-requirements.md), it is eligible for inclusion and publishing on the Airgap App Store [apps.uds.is](https://apps.uds.is). _(soon apps.defenseunicorns.com [#170](https://github.com/defenseunicorns/uds-marketplace/issues/170))_ + +Packages listed on the App Store include some metadata describing the package. [zarf-dev/zarf#2976](https://github.com/zarf-dev/zarf/issues/2976) introduces annotations, which will be leveraged to provide this metadata. Until released, the metadata will be stored in a separate file in the App Store repository. + +Instructions on creating Application Metadata can be found in [uds-appstore Contributing Guide](https://github.com/defenseunicorns/uds-appstore/blob/main/CONTRIBUTING.md#app-store-package-metadata) diff --git a/docs/package_integration/oscal-guidelines.md b/docs/uds-packages/guidelines/oscal-guidelines.md similarity index 100% rename from docs/package_integration/oscal-guidelines.md rename to docs/uds-packages/guidelines/oscal-guidelines.md diff --git a/docs/package_integration/testing-guidelines.md b/docs/uds-packages/guidelines/testing-guidelines.md similarity index 100% rename from docs/package_integration/testing-guidelines.md rename to docs/uds-packages/guidelines/testing-guidelines.md diff --git a/docs/package_integration/uds-package-practices.md b/docs/uds-packages/requirements/uds-package-requirements.md similarity index 88% rename from docs/package_integration/uds-package-practices.md rename to docs/uds-packages/requirements/uds-package-requirements.md index cd0921d3..4eb71f35 100644 --- a/docs/package_integration/uds-package-practices.md +++ b/docs/uds-packages/requirements/uds-package-requirements.md @@ -1,10 +1,12 @@ -# UDS Package Practices +# UDS Package Standards and Badging Requirements -This document describes the standards for [Made for UDS](https://github.com/defenseunicorns/uds-core) badging. It is not a comprehensive guide to creating UDS Packages and assumes familiarity with the UDS ecosystem and UDS Package Custom Resource. If you are unfamiliar with these concepts, please first refer to the [package integration guide](guide.md) providing more detailed information. +This document describes the standards for [Made for UDS](https://github.com/defenseunicorns/uds-core) badging. It is not a comprehensive guide to creating UDS Packages and assumes familiarity with the UDS ecosystem and UDS Package Custom Resource. If you are unfamiliar with these concepts, please first refer to the [package integration guide](../guide.md) providing more detailed information. Made for UDS Packages integrate with services and features of [UDS Core](https://github.com/defenseunicorns/uds-core), through the [UDS `Package` custom resource](https://github.com/defenseunicorns/uds-core/blob/main/src/pepr/operator/README.md#example-uds-package-cr). These packages can be one of three tiers: -[Gold](https://github.com/defenseunicorns/uds-core), [Silver](https://github.com/defenseunicorns/uds-core), or [bronze](https://github.com/defenseunicorns/uds-core). +[Gold](https://github.com/defenseunicorns/uds-core) +[Silver](https://github.com/defenseunicorns/uds-core) +[bronze](https://github.com/defenseunicorns/uds-core) > [!IMPORTANT] > Packages should aim for Gold by default and only _SETTLE_ for lesser tiers of Bronze and Silver. @@ -23,7 +25,7 @@ _a Gold UDS Package implements best-effort 0-cve images, configuration hardening Gold Packages: - **Must** satisfy all the requirements of [Silver](#silver) packages -- **Must** include OSCAL-component control mapping and responses for the application. see [OSCAL Guidelines](oscal-guidelines.md) +- **Must** include OSCAL-component control mapping and responses for the application. see [OSCAL Guidelines](../guidelines/oscal-guidelines.md) - **Must** minimize the scope and number of the exemptions to only what is absolutely required by the application - UDS Packages **may** make use of the [UDS `Exemption` custom resource](https://github.com/defenseunicorns/uds-core/blob/main/src/pepr/operator/README.md#example-uds-exemption-cr) for exempting any Pepr policies, but in doing so they **Must** document rationale for the exemptions - **Must** declaratively implement any available application hardening guidelines by default (Example: [GitLab Hardening guidelines](https://docs.gitlab.com/ee/security/hardening.html)) @@ -63,8 +65,8 @@ Bronze packages: - **Must** be declaratively bundled in a [Zarf package](https://docs.zarf.dev/ref/create/) - **Must** define any external interfaces under the `expose` key in the [UDS Package Custom Resource](https://github.com/defenseunicorns/uds-core/blob/main/docs/configuration/uds-operator.md) - **Must** deploy and operate successfully with Istio injection enabled in the namespace. -- **Must** implement Journey testing, covering the basic user flows and features of the application (see [Testing Guidelines](./testing-guidelines.md)) -- **Must** implement Upgrade Testing to ensure that the current development package works when deployed over the previously released one. (see [Testing Guidelines](./testing-guidelines.md)) +- **Must** implement Journey testing, covering the basic user flows and features of the application (see [Testing Guidelines](../guidelines/testing-guidelines.md)) +- **Must** implement Upgrade Testing to ensure that the current development package works when deployed over the previously released one. (see [Testing Guidelines](../guidelines/testing-guidelines.md)) - **Must** be capable of operating within an internet-disconnected (air-gapped) environment - **Must** be actively maintained by the package maintainers identified in CODEOWNERS [see #CODEOWNERS section for more information](#codeowners) - **Must** be versioned using the UDS Package [Versioning scheme](#versioning) @@ -74,6 +76,7 @@ Bronze packages: - **Must** release its package to the `ghcr.io/defenseunicorns/packages/` namespace as the application's name (i.e. `ghcr.io/defenseunicorns/packages/uds/mattermost`). - **Must** not make the assumption that the `expose` interfaces are accessible to the bastion or pipeline deploying the package (i.e. `*.uds.dev`). > If web requests need to be made they should be done through a `Job` or `./uds zarf tools kubectl exec` as appropriate. +- **Must** include application [metadata for Airgap App Store](../guidelines/metadata.md) publishing - **Should** lint their configurations with appropriate tooling, such as [`yamllint`](https://github.com/adrienverge/yamllint) and [`zarf dev lint`](https://docs.zarf.dev/commands/zarf_dev_lint/). ## Badging