diff --git a/.github/ISSUE_TEMPLATE/badge_status.md b/.github/ISSUE_TEMPLATE/badge_status.md deleted file mode 100644 index e293f0f..0000000 --- a/.github/ISSUE_TEMPLATE/badge_status.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -name: Badge Status -about: Easy way to track the status towards each level of badging -title: '' -labels: '' -assignees: '' ---- - -## Gold: [Gold](https://github.com/defenseunicorns/uds-core) - -_a Gold UDS Package implements best-effort 0-cve images, configuration hardening, and meets the unicorn guarantee out of the box with zero additional effort._ - -- [ ] **Must** satisfy all the requirements of [Silver](https://github.com/defenseunicorns/uds-common/blob/main/docs/uds-packages/requirements/uds-package-requirements.md#silver) packages -- [ ] **Must** include OSCAL-component control mapping and responses for the application. see [OSCAL Guidelines](https://github.com/defenseunicorns/uds-common/blob/main/docs/uds-packages/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)) -- [ ] **Must** release a unicorn flavor package, providing a minimal CVE baseline - -## Silver: [Silver](https://github.com/defenseunicorns/uds-core) - -_a Silver UDS Package integrates with the main features of the UDS Operator, is documented, maintained, and can be confidently operated in production._ - -Silver packages: - -- [ ] **Must** satisfy all the requirements of [Bronze](https://github.com/defenseunicorns/uds-common/blob/main/docs/uds-packages/requirements/uds-package-requirements.md#bronze) Packages -- [ ] **Must** define network policies under the `allow` key as required in the [UDS Package Custom Resource](https://github.com/defenseunicorns/uds-core/blob/main/docs/reference/configuration/uds-operator.md) -- [ ] **Must** (except if the application provides no end user login) use and create a Keycloak client through the `sso` key. [UDS Package Custom Resource](https://github.com/defenseunicorns/uds-core/blob/main/docs/reference/configuration/uds-operator.md) -- [ ] **Must** (except if the application provides no application metrics) implement monitors for each application metrics endpoint using it's built-in chart monitors, `monitor` key, or manual monitors in the config chart. -- [ ] **Must** integrate declaratively (i.e. no clickops) with the UDS Operator -- [ ] **Should** expose all configuration (`uds.dev` CRs, additional `Secrets`/`ConfigMap`s, etc) through a Helm chart (ideally in a `chart` or `charts` directory). - > This allows UDS bundles to override configuration with Helm overrides and enables downstream teams to fully control their bundle configurations. -- [ ] **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. -- [ ] **Should** avoid workarounds with Istio such as disabling strict mTLS peer authentication. -- [ ] **Should** minimize network policies to specific selectors needed for Ingress/Egress traffic. -- [ ] **Should** consider security options during implementation to provide the most secure default possible (i.e. SAML w/SCIM vs OIDC). -- [ ] **Should** name the Keycloak client ` Login` (i.e. `Mattermost Login`) to provide login UX consistency. -- [ ] **Should** clearly mark the Keycloak client id with the group and app name `uds--` (i.e. `uds-swf-mattermost`) to provide consistency in the Keycloak UI. -- [ ] **Should** limit the use of Zarf variable templates and prioritize configuring packages via Helm value overrides. - > This ensures that the package is configured the same way that the bundle would be and avoids any side effect issues of Zarf's `###` templating. -- [ ] **May** template network policy keys to provide flexibility for delivery customers to configure. -- [ ] **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 delivery customers to configure. - -## Bronze: [Bronze](https://github.com/defenseunicorns/uds-core) - -_a Bronze UDS Package meets the minimum requirements and becomes compatible, but not optimal or fully integrated, with UDS. It is not ready to run in production without significant caveats._ - -Bronze packages: - -- [ ] **Should** be created from the [UDS Package Template](https://github.com/uds-packages/template) -- [ ] **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/reference/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](https://github.com/defenseunicorns/uds-common/blob/main/docs/uds-packages/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](https://github.com/defenseunicorns/uds-common/blob/main/docs/uds-packages/guidelines/testing-guidelines.md)) -- [ ] **Must** be capable of operating within an airgap (internet-disconnected) environment -- [ ] **Must** be actively maintained by the package maintainers identified in CODEOWNERS [see #CODEOWNERS section for more information](https://github.com/defenseunicorns/uds-common/blob/main/docs/uds-packages/requirements/uds-package-requirements.md#codeowners) -- [ ] **Must** be versioned using the UDS Package [Versioning scheme](https://github.com/defenseunicorns/uds-common/blob/main/docs/uds-packages/requirements/uds-package-requirements.md#versioning) -- [ ] **Must** contain documentation under a `docs` folder at the root that describes how to configure the package and outlines package dependencies. - > This allows users of the package to learn more about exposed configuration - it is recommended to make the entrypoint for configuration configuration.md. -- [ ] **Must** have a dependency management bot (such as renovate) configured to open PRs to update the core package and support dependencies. -- [ ] **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](https://github.com/defenseunicorns/uds-common/blob/main/docs/uds-packages/guidelines/metadata-guidelines.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/). -- [ ] **Should** release a unicorn flavor package, providing a minimal CVE baseline - -## Exceptions - -Add a subbullet below the task that needs the exception and provide your reasoning - -- [ ] **Should** you need to provide an exception - - ❌ **EXCEPTION:** This is an example of how to provide an exception and its reasoning diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index d35438a..7d57096 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -24,4 +24,4 @@ Other: ### Severity/Priority ### Additional Context -Add any other context or screenshots about the technical debt here. +Add any other context or screenshots about the bug here. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 39d271a..9eb8071 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -17,4 +17,4 @@ Relates to # ## Checklist before merging - [ ] Test, docs, adr added or updated as needed -- [ ] [Contributor Guide Steps](https://github.com/uds-packages/#TEMPLATE_APPLICATION_NAME#/blob/main/CONTRIBUTING.md#developer-workflow) followed +- [ ] [Contributor Guide Steps](https://github.com/uds-packages/#TEMPLATE_APPLICATION_NAME#/blob/main/CONTRIBUTING.md) followed diff --git a/.github/workflows/auto-update.yaml b/.github/workflows/auto-update.yaml index a3f0654..94eca57 100644 --- a/.github/workflows/auto-update.yaml +++ b/.github/workflows/auto-update.yaml @@ -11,6 +11,7 @@ on: permissions: contents: write # Allows writing content to the repository. packages: read # Allows reading the content of the repository's packages. + pull-requests: write # Allows creating or updating pull requests. # Abort prior jobs in the same workflow / PR concurrency: diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 04cbdae..94f7910 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -22,7 +22,7 @@ jobs: id-token: write strategy: matrix: - flavor: [upstream, registry1, unicorn] + flavor: [upstream] architecture: [amd64, arm64] exclude: - flavor: registry1 diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 239168d..2283911 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -40,7 +40,7 @@ jobs: fail-fast: false matrix: type: [install, upgrade] - flavor: [upstream, unicorn, registry1] + flavor: [upstream] uses: defenseunicorns/uds-common/.github/workflows/callable-test.yaml@1614a9f51fbf1f21e7a28020702773d9bdefd8fe # v1.24.5 with: timeout: 30 diff --git a/CODEOWNERS-template.md b/CODEOWNERS-template.md index df760c0..4df7732 100644 --- a/CODEOWNERS-template.md +++ b/CODEOWNERS-template.md @@ -1,37 +1,32 @@ -The current `CODEOWNERS` file that exists, is to denote who owns this `uds-package-template`. If you are creating a new package from this template, you can copy / paste one of the below examples into the `CODEOWNERS` file, then modify the string to fit your needs. After updating the `CODEOWNERS` file to your liking, you can delete this file. +# Configuring CODEOWNERS for your package -The `CODEOWNERS` file should follow the below format, you can even just copy / paste the exact text into the `CODEOWNERS` file. +The `CODEOWNERS` file in this repo denotes who owns the template itself. When creating a new package, replace its contents with one of the patterns below, then delete this file. -``` -* @uds-packages/uds-foundry -# * @additional-team - as appropriate - -/CODEOWNERS @jeff-mccoy @daveworth -/LICENS* @jeff-mccoy @austenbryan -``` +> [!IMPORTANT] +> Use GitHub team handles (e.g., `@uds-packages/uds-foundry`), not individual user handles. Teams stay current as people join and leave; pinning to individuals leaves reviews orphaned and creates approval bottlenecks. -If you would like to add optional package reviewers, such as the creator of the app, you can append creators after `uds-foundry` - -For instance, you could handle this like below: +## Standard pattern ``` -* @defenseunicorns/uds-foundry @name-of-creator/s @name-of-established-known-team +* @uds-packages/uds-foundry @creator-team -/CODEOWNERS @jeff-mccoy @daveworth +/CODEOWNERS @jeff-mccoy @daveworth /LICENS* @jeff-mccoy @austenbryan ``` -Keeping the reviewers on one line, like the above format, makes it easier on Bullpen to approve Support / Maintenance PRs on a package. -This format with everything on one line, enables an `OR` for package approvers. So, `uds-foundry` OR `@name-of-creator/s` could approve a PR. +This combines `uds-foundry` with the package's creator team on a single line — either team can approve a PR (OR semantics). Replace `@creator-team` with the GitHub team handle for the group that built the package. + +The `/CODEOWNERS` and `/LICENS*` lines pin those files to Defense Unicorns release engineering — keep them as-is. +## Requiring approval from every group (AND) -If you break the lines up like the below, then it becomes an `AND`. So, it would take both `uds-foundry` AND `@name-or-creator/s` to approve a PR. +If every team must weigh in before a PR can merge, put each owner on its own `*` line. ``` -* @defenseunicorns/uds-foundry -* @name-of-creator/s #optional during package creation to enable velocity -* @name-of-established-known-team #optional addition to "uds-foundry" +* @uds-packages/uds-foundry +* @creator-team +* @other-team -/CODEOWNERS @jeff-mccoy @daveworth +/CODEOWNERS @jeff-mccoy @daveworth /LICENS* @jeff-mccoy @austenbryan ``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 89dbea1..d2673fe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,4 +2,4 @@ Thank you for your interest in this Defense Unicorns UDS Package! -This package is part of Defense Unicorns' Unicorn Delivery Service and follows the contributing guidelines outlined in that repositories' [CONTRIBUTING.md](https://github.com/defenseunicorns/uds-common/blob/main/CONTRIBUTING.md) file. +This package is part of Defense Unicorns' Unicorn Delivery Service and follows the contributing guidelines outlined in [uds-common's CONTRIBUTING.md](https://github.com/defenseunicorns/uds-common/blob/main/CONTRIBUTING.md). diff --git a/README-template.md b/README-template.md index 671539a..47ee530 100644 --- a/README-template.md +++ b/README-template.md @@ -1,36 +1,31 @@ # UDS Package #TEMPLATE_APPLICATION_DISPLAY_NAME# -This package is designed to be deployed on [UDS Core](https://github.com/defenseunicorns/uds-core) and is based on the upstream [#TEMPLATE_APPLICATION_DISPLAY_NAME#](#TEMPLATE_CHART_REPO#) chart. +This package deploys [#TEMPLATE_APPLICATION_DISPLAY_NAME#](#TEMPLATE_CHART_REPO#) on [UDS Core](https://github.com/defenseunicorns/uds-core). -> INSERT HERE 1-2 sentence summary of what the application does. +> 1-2 sentence summary of what the application does. -## Pre-requisites +## Prerequisites -The #TEMPLATE_APPLICATION_DISPLAY_NAME# Package expects to be deployed on top of [UDS Core](https://github.com/defenseunicorns/uds-core) with the dependencies listed below being configured prior to deployment. - -#### Dependency information - -Add any dependency information here +This package expects to be deployed on top of [UDS Core](https://github.com/defenseunicorns/uds-core). Document any additional dependencies (databases, operators, etc.) here. ## Flavors -| Flavor | Description | Example Creation | -| ------ | ----------- | ---------------- | -| `upstream` | Uses upstream images within the package. | `zarf package create . -f upstream` | -| `registry1` | Uses images from registry1.dso.mil within the package | `zarf package create . -f registry1` | -| `unicorn` | Uses images from rapidfort within the package | `zarf package create . -f unicorn` | +This package ships an `upstream` flavor by default. Add `registry1` or `unicorn` flavors as needed — see [`zarf.yaml`](./zarf.yaml). ## Releases -The released packages can be found in [ghcr](https://github.com/uds-packages/#TEMPLATE_APPLICATION_NAME#/pkgs/container/#TEMPLATE_APPLICATION_NAME#). +Released packages are available in [GHCR](https://github.com/uds-packages/#TEMPLATE_APPLICATION_NAME#/pkgs/container/#TEMPLATE_APPLICATION_NAME#). -## UDS Tasks (for local dev and CI) +## Local development -*For local dev, this requires you install [uds-cli](https://github.com/defenseunicorns/uds-cli?tab=readme-ov-file#install) +Requires the [UDS CLI](https://github.com/defenseunicorns/uds-cli?tab=readme-ov-file#install). -> [!TIP] -> To get a list of tasks to run you can use `uds run --list`! +```bash +uds run default # spin up a local k3d cluster, build, and deploy +uds run dev # iterate on an existing cluster +uds run --list # show all available tasks +``` ## Contributing -Please see the [CONTRIBUTING.md](./CONTRIBUTING.md) +See [CONTRIBUTING.md](./CONTRIBUTING.md). diff --git a/README.md b/README.md index 5a9cd9e..73ea721 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,41 @@ # UDS Package Template -UDS package template is a starting point for creating a new UDS package. It includes a basic structure for a UDS package and a set of tasks to help you get started. +A starting point for creating a new [UDS Package](https://docs.defenseunicorns.com/core/concepts/configuration-and-packaging/package-requirements/) on [UDS Core](https://github.com/defenseunicorns/uds-core). > [!TIP] -> Found an issue in this template or looking for how to contribute? Check out the [Contributing Guidelines](#contributing) +> Found an issue with the template or want to contribute? See [Contributing](#contributing). -After creating a repo from the UDS Package Template, follow [Making it your own](#make-it-your-own) documentation in order to customize the template for a new application package. +## Creating a package from this template -## Make it your own +The canonical guide for turning this scaffolding into a working package is [Create a UDS Package](https://docs.defenseunicorns.com/core/how-to-guides/packaging-applications/create-uds-package/). It walks through the placeholder substitution, Zarf and chart configuration, the `Package` CR, and the dev/test bundle. -1. Replace some common placeholders +After working through that guide, finish the template-specific cleanup below. -| value | replace_with | example | -| ------------------------------------- | --------------------------- | ------------------------------------------------------ | -| `#TEMPLATE_APPLICATION_NAME#` | application name | nginx, mattermost, cert-manager, etc... | -| `#TEMPLATE_APPLICATION_DISPLAY_NAME#` | application name for humans | NGINX, Mattermost Cert Manager, etc... | -| `#TEMPLATE_CHART_REPO#` | chart repository URL | `https://charts.jetstack.io/` | -| `#UDS_PACKAGE_REPO#` | package repository URL | `https://github.com/defenseunicorns/uds-package-nginx` | +## Template cleanup checklist -2. Review, determine your need, and update +These items are specific to this template repo and aren't covered in the canonical doc: -The following files will need to be customized for the application being packaged and include things like dependencies and application specific helm values. Examples have been included for reference. +- [ ] Remove the `ci-setup` task from [`tasks.yaml`](./tasks.yaml). It exists only so this template's own CI can validate the scaffolding using podinfo. To remove: + - Delete the `ci-setup` task block, including the two `#### Template CI: Remove ... ####` comment markers that wrap it. + - Delete the `- task: ci-setup` line under the `test-install` task. +- [ ] `mv README-template.md README.md` and customize for your package. +- [ ] Update `CODEOWNERS` following the guidance in `CODEOWNERS-template.md`, then `rm CODEOWNERS-template.md`. +- [ ] If your application has a UI, rename `tests/template-application-name.test.ts` to `tests/.test.ts` and customize it for your app. If your application has no UI, delete `tests/template-application-name.test.ts`, `tests/auth.setup.ts`, and the `ui` task in [`tasks/test.yaml`](./tasks/test.yaml). +- [ ] When ready to publish your first release, uncomment [`releaser.yaml`](./releaser.yaml) and set the version. Add `registry1` / `unicorn` entries if you've added those flavors. -| File/Directory | Function | New Package ToDos | -| :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| .github/ | **CICD** pipeline specification | If the package requires any workflow customizations, such as needing specific runners testing other flavors, they can be customized. Else the template values should work fine. | -| adr/ | **DOCS**: Architecture Design Records. | Record any architectural decisions per the format found in this directory. | -| bundle/ | **DEV/TEST**: Test/example UDS bundle used to test the UDS package with UDS core. Should include any required dependencies and configuration needed for a test deployment. | Update fields to match this app's name, version, etc. | -| chart/ | **CHART**: Contains helm chart for [UDS Package custom resources](https://github.com/defenseunicorns/uds-core/blob/main/docs/reference/configuration/uds-operator/overview.md). Used to configure things like SSO, Virtual Services, Network Polices, etc. Can also contain any extra K8s manifests which need deployed before/after the main application. | Customize UDS configuration chart for application. At a minimum it should include a uds-package that provisions required network policies and any required SSO configuration. | -| common/zarf.yaml | **ZARF PACKAGE**: Root zarf package definition for _this app_ conventionally placed in `common/`. The root-level `zarf.yaml` imports this by explicit reference to this file path. | Customize to include application images, helm chart, variables, version, etc. | -| docs/ | **DOCS**: Package specific documentation such as detailed configuration info that is too indepth to go in the README | Add documentation. | -| src/ | **DEV/TEST**: New/bespoke Zarf packages to support dev/test bundle. These must exist before the main package is deployed, but are not part of it. One use-case is creating the namespace where Minio can deploy secrets _before_ the app that would otherwise create that namespace comes to exist. Other use-cases are databases (probably should be it's own UDS package) and some secrets. | Add custom Zarf packages as necessary. | -| tasks/ | **DEV/TEST**: UDS filename-scoped tasks. | Add tasks as necessary to support your development loop. The templated tasks are often sufficient. | -| tasks/tests.yaml | **DEV/TEST**: UDS tasks defined for testing the package deployed. | Customize based on application resource names and types, playwright tests that need to run, and/or custom resources that the application manages. | -| tests/ | **DEV/TEST**: Test files included are examples only since testing is very application specific and may include UI testing with playwright, testing custom resources being deployed in cluster, or other types of tests not included in the examples. | If application creates resources in cluster based on custom resources (example applications: cert-manager, trust-manager, database operators, etc), then test data can include a zarf package that deploys a custom resource so tests can ensure the application is creating resources as expected `tests/optional-example-zarf-tests/*`.

If application has an exposed web interface to test, then customize these files for playwright to authenticate and test application endpoints. Rename template-application-name to match your application name `tests/template-application-name.test.ts` `tests/auth.setup.ts` | -| .gitlab-ci.yml | **CICD**: Pipeline specification for GitLab | If the package requires any workflow customizations, such as needing specific runners testing other flavors, they can be customized. Else the template values should work fine. | -| README.md | **DOCS**: UDS package README. | Replace contents of README.md with README-template.md and customize for application being packaged when done following this README's guidance. | -| releaser.yaml | **CICD**: File that defines the current version for each flavor. | When ready to release, delete any flavors not applicable to project, set versions to correct ones for each flavor, and uncomment lines | -| renovate.json | **CICD**: Custom rules for renovate to update things. | Add any custom package rules if needed for renovate to properly update things such as repo1 packages. Includes an example. | -| zarf.yaml | **ZARF PACKAGE**: top-level Zarf package definition. | Copy from `common/zarf.yaml` the settings you'd like to expose for changes, much like a top-level values.yaml file. Often flavors, images, and variables are also specified primarily here, not in `common/zarf.yaml`. | +## Engineers external to Defense Unicorns -3. Almost there... - - `mv README-template.md README.md` - - `rm -rf tasks/template.yaml` - - Remove extra lines from [tasks.yaml](./tasks.yaml) - - Follow the `CODEOWNERS-template.md` to update your `CODEOWNERS` file. +These files are specific to Defense Unicorns infrastructure and may not apply to your situation: -You are ready to start integrating (and testing with CI) your application with UDS Core! - -## Releasing - -When you're ready to release your package, you'll need to modify the `releaser.yaml` file to include the correct versions of your package's flavors. If your package doesn't have a flavor, just delete it from the releaser.yaml file. When you're actually ready to have a release tagged and a package pushed to GHCR, uncomment the contents of the file. - -## Engineers External to Defense Unicorns - -For engineers that are external to the Defense Unicorns organization, the following files may not be applicable to your situation, and can be modified or removed. - - releaser.yaml - - .gitlab-ci.yml - - renovate.json - - .github/workflows (the workflows are still applicable, but the runners, tokens, and secrets will have to be updated to reflect your environment.) +- `releaser.yaml` +- `renovate.json` +- `.github/workflows` — the workflows are reusable, but runners, tokens, and secrets need to be updated to match your environment. ## Contributing > [!NOTE] -> As a template repository, the [CONTRIBUTING.md](./CONTRIBUTING.md) file is a part of the template and NOT the contributing guidelines for this repository. The contributing guidelines for this repository are articulated here. +> As a template repository, the [CONTRIBUTING.md](./CONTRIBUTING.md) file is part of the *template* — not the contributing guidelines for this repository itself. -This template repository is part of Defense Unicorns' Unicorn Delivery Service and follows the contributing guidelines outlined in that repositories' [CONTRIBUTING.md](https://github.com/defenseunicorns/uds-common/blob/main/CONTRIBUTING.md) file. +This template repository is part of Defense Unicorns' Unicorn Delivery Service and follows the contributing guidelines in [`uds-common/CONTRIBUTING.md`](https://github.com/defenseunicorns/uds-common/blob/main/CONTRIBUTING.md). -Feel free to [open a new issue](https://github.com/defenseunicorns/uds-package-template/issues/new/choose) for any defects or feature requests. +[Open an issue](https://github.com/uds-packages/template/issues/new/choose) for defects or feature requests. diff --git a/adr/0001-record-architecture-decisions.md b/adr/0001-record-architecture-decisions.md index 60c36e5..b03bf9c 100644 --- a/adr/0001-record-architecture-decisions.md +++ b/adr/0001-record-architecture-decisions.md @@ -1,6 +1,6 @@ # 1. Record architecture decisions -Date: 20224-02-04 +Date: 2024-02-04 ## Status diff --git a/bundle/uds-bundle.yaml b/bundle/uds-bundle.yaml index ec1a3a0..5aaf243 100644 --- a/bundle/uds-bundle.yaml +++ b/bundle/uds-bundle.yaml @@ -8,11 +8,6 @@ metadata: version: dev packages: - # #TEMPLATE_APPLICATION_NAME# has a dependency on some-application - # - name: some-application - # repository: ghcr.io/defenseunicorns/packages/uds/some-application - # ref: 0.1.3-upstream - - name: #TEMPLATE_APPLICATION_NAME# path: ../ ref: dev diff --git a/bundle/uds-config.yaml b/bundle/uds-config.yaml index e4cf9cf..2067cc5 100644 --- a/bundle/uds-config.yaml +++ b/bundle/uds-config.yaml @@ -1,9 +1,2 @@ # Copyright 2024 Defense Unicorns # SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Defense-Unicorns-Commercial - -# variables: -# some-application: -# EXAMPLE_DEP_PACKAGE_VAR: true -# #TEMPLATE_APPLICATION_NAME#: -# EXAMPLE_DB_USERNAME: my-postgres-user -# EXAMPLE_DB_ENDPOINT: postgres diff --git a/chart/Chart.yaml b/chart/Chart.yaml index b6f0342..ab254ba 100644 --- a/chart/Chart.yaml +++ b/chart/Chart.yaml @@ -3,7 +3,7 @@ apiVersion: v2 name: uds-#TEMPLATE_APPLICATION_NAME#-config -description: uds-#TEMPLATE_APPLICATION_NAME#-config +description: UDS configuration chart for uds-#TEMPLATE_APPLICATION_NAME#-config # A chart can be either an 'application' or a 'library' chart. # diff --git a/chart/templates/template-sso-secret.yaml b/chart/templates/template-sso-secret.yaml deleted file mode 100644 index bbe493a..0000000 --- a/chart/templates/template-sso-secret.yaml +++ /dev/null @@ -1,18 +0,0 @@ -# Copyright 2024 Defense Unicorns -# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Defense-Unicorns-Commercial - -# This secret will be used if sso is disabled, instead of the templated one in uds-package.yaml. -# #TEMPLATE_APPLICATION_DISPLAY_NAME# needs to mount the secret and creating it this way avoids creating an unnecessary -# client in the keycloak realm and unnecessary secret data in the cluster. -{{- if not .Values.sso.enabled }} - -apiVersion: v1 -kind: Secret -metadata: - name: {{ .Values.sso.secretName }} - namespace: {{ .Release.Namespace }} -type: "Opaque" -stringData: - #TEMPLATE_APPLICATION_NAME#.sso.config.key: | - example.saml.enabled: {{ .Values.sso.enabled }} -{{- end }} diff --git a/chart/templates/uds-package.yaml b/chart/templates/uds-package.yaml index f476e02..cec7fe1 100644 --- a/chart/templates/uds-package.yaml +++ b/chart/templates/uds-package.yaml @@ -6,36 +6,9 @@ kind: Package metadata: name: #TEMPLATE_APPLICATION_NAME# namespace: {{ .Release.Namespace }} +# Full Package CR spec reference: +# https://docs.defenseunicorns.com/core/reference/operator--crds/packages-v1alpha1-cr/ spec: - {{- if .Values.sso.enabled }} - sso: - - name: #TEMPLATE_APPLICATION_DISPLAY_NAME# Login - clientId: uds-package-#TEMPLATE_APPLICATION_NAME# - redirectUris: - - "https://#TEMPLATE_APPLICATION_NAME#.{{ .Values.domain }}/oauth2/callback/saml" - protocol: saml - defaultClientScopes: - - "mapper-saml-email-email" - - "mapper-saml-username-login" - - "mapper-saml-username-name" - - attributes: - saml.client.signature: "false" - - secretName: {{ .Values.sso.secretName }} - # This secret template configures sso for the application. Will need updated based on application required configuration - secretTemplate: - #TEMPLATE_APPLICATION_NAME#.sso.config.key: | - example.auth.saml.enabled: {{ .Values.sso.enabled }} - example.auth.saml.applicationId: clientField(clientId) - example.auth.saml.providerName: {{ .Values.sso.saml.providerName }} - example.auth.saml.providerId: https://sso.{{ .Values.domain }}/realms/uds - example.auth.saml.loginUrl: https://sso.{{ .Values.domain }}/realms/uds/protocol/saml - example.auth.saml.user.login: login - example.auth.saml.user.name: name - example.auth.saml.user.email: email - example.auth.saml.certificate.secured: clientField(samlIdpCertificate) - {{- end }} # Customize network policies and expose services via istio network: serviceMesh: @@ -46,7 +19,7 @@ spec: app: #TEMPLATE_APPLICATION_NAME# gateway: tenant host: #TEMPLATE_APPLICATION_NAME# - port: 1234 + port: #TEMPLATE_APPLICATION_PORT# uptime: checks: paths: diff --git a/chart/values.yaml b/chart/values.yaml index 3bea752..bb299fe 100644 --- a/chart/values.yaml +++ b/chart/values.yaml @@ -1,29 +1,6 @@ # Copyright 2024 Defense Unicorns # SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Defense-Unicorns-Commercial -# Example values from UDS package repo template -domain: "###ZARF_VAR_DOMAIN###" -sso: - enabled: false - protocol: saml - secretName: #TEMPLATE_APPLICATION_NAME#-sso - adminGroups: ["/#TEMPLATE_APPLICATION_DISPLAY_NAME# Admin", "/UDS Core/Admin"] - saml: - providerName: "#TEMPLATE_APPLICATION_DISPLAY_NAME#" # Support for custom `network.allow` entries on the Package CR +# https://docs.defenseunicorns.com/core/how-to-guides/networking/define-network-access/ additionalNetworkAllow: [] -# # Notice no `remoteGenerated` field here on custom internal rule -# - direction: Ingress -# selector: -# app: jenkins -# remoteNamespace: jenkins -# remoteSelector: -# app: jenkins -# port: 8180 -# description: "Ingress from Jenkins" -# # No `remoteNamespace`, `remoteSelector`, or `port` fields on rule to `remoteGenerated` -# - direction: Egress -# selector: -# app: webservice -# remoteGenerated: Anywhere -# description: "Egress from #TEMPLATE_APPLICATION_NAME#" diff --git a/common/zarf.yaml b/common/zarf.yaml index 83443a7..747dae1 100644 --- a/common/zarf.yaml +++ b/common/zarf.yaml @@ -22,8 +22,3 @@ components: version: 1.2.3 valuesFiles: - ../values/common-values.yaml - -# You only need onDeploy.after.wait.cluster actions for non-UDS resources — items Zarf can’t automatically interpret, such as: -# Custom CRDs from third-party operators that don’t use kstatus -# External systems like databases, services, or Helm hooks -# Reference example implementation: https://docs.zarf.dev/ref/actions/#wait-action-configuration diff --git a/releaser.yaml b/releaser.yaml index fe4b5e7..ca36744 100644 --- a/releaser.yaml +++ b/releaser.yaml @@ -5,9 +5,3 @@ # - name: upstream # # renovate-uds: datasource=docker depName=upstream/image # version: 0.1.0-uds.0 -# - name: registry1 -# # renovate-uds: datasource=docker depName=registry1.dso.mil/ironbank/image -# version: 0.1.0-uds.0 -# - name: unicorn -# # renovate-uds: datasource=docker depName=quay.io/rfcurated/image extractVersion=^(?\d+\.\d+\.\d+)(?:-.*)?$ -# version: 0.1.0-uds.0 diff --git a/tasks.yaml b/tasks.yaml index 6829180..b152709 100644 --- a/tasks.yaml +++ b/tasks.yaml @@ -9,9 +9,7 @@ includes: - deploy: https://raw.githubusercontent.com/defenseunicorns/uds-common/v1.24.5/tasks/deploy.yaml - setup: https://raw.githubusercontent.com/defenseunicorns/uds-common/v1.24.5/tasks/setup.yaml - actions: https://raw.githubusercontent.com/defenseunicorns/uds-common/v1.24.5/tasks/actions.yaml - - badge: https://raw.githubusercontent.com/defenseunicorns/uds-common/v1.24.5/tasks/badge.yaml - upgrade: https://raw.githubusercontent.com/defenseunicorns/uds-common/v1.24.5/tasks/upgrade.yaml - - compliance: https://raw.githubusercontent.com/defenseunicorns/uds-common/v1.24.5/tasks/compliance.yaml - publish: https://raw.githubusercontent.com/defenseunicorns/uds-common/v1.24.5/tasks/publish.yaml tasks: @@ -34,7 +32,7 @@ tasks: actions: - task: create:test-bundle - task: deploy:test-bundle - - task: setup:create-doug-user + - task: setup:keycloak-user - task: test:all - name: dev @@ -44,11 +42,60 @@ tasks: - task: create:test-bundle - task: deploy:test-bundle -# CI will execute the following (via uds-common/.github/workflows/callable-test.yaml) so they need to be here with these names +#### Template CI: Remove this comment, the below block, and the `ci-setup` under `test-install` when building a package #### + - name: ci-setup + description: Populate template with podinfo values for CI validation + actions: + - cmd: | + set -e + + APP_NAME="podinfo" + DISPLAY_NAME="Podinfo" + CHART_URL="oci://ghcr.io/stefanprodan/charts/podinfo" + CHART_VERSION="6.7.1" + APP_IMAGE="ghcr.io/stefanprodan/podinfo:6.7.1" + APP_PORT="9898" + + # Replace template placeholders across files + find . -type f \( -name "*.yaml" -o -name "*.yml" -o -name "*.ts" -o -name "*.json" -o -name "*.md" \) \ + -not -path "./.git/*" -not -path "*/node_modules/*" -print0 | \ + xargs -0 perl -pi -e " + s/#TEMPLATE_APPLICATION_NAME#/${APP_NAME}/g; + s/#TEMPLATE_APPLICATION_DISPLAY_NAME#/${DISPLAY_NAME}/g; + s/#TEMPLATE_APPLICATION_PORT#/${APP_PORT}/g; + s|#TEMPLATE_CHART_REPO#|${CHART_URL}|g; + s|#UDS_PACKAGE_REPO#|https://github.com/stefanprodan/podinfo|g; + " + + # Patch common/zarf.yaml + yq -i ".components[0].charts[1].version = \"${CHART_VERSION}\"" common/zarf.yaml + yq -i 'del(.components[0].charts[1].gitPath)' common/zarf.yaml + + # Patch zarf.yaml, set podinfo image + yq -i "(.components[] | select(.only.flavor == \"upstream\")).images = [\"${APP_IMAGE}\"]" zarf.yaml + yq -i 'del(.components[] | select(.only.flavor == "unicorn"))' zarf.yaml + yq -i 'del(.components[] | select(.only.flavor == "registry1"))' zarf.yaml + yq -i '.variables = [{"name": "DOMAIN", "default": "uds.dev"}]' zarf.yaml + # Patch uds-package.yaml: add SSO + Authservice (podinfo has no native OIDC), allow-all network policy + perl -i -0pe 's|( # Customize network policies and expose services via istio)| sso:\n - name: Podinfo\n clientId: uds-podinfo\n redirectUris:\n - "https://podinfo.uds.dev/login"\n enableAuthserviceSelector:\n app.kubernetes.io/name: podinfo\n$1|' chart/templates/uds-package.yaml + perl -pi -e 's/remoteGenerated: IntraNamespace/remoteGenerated: Anywhere/g' chart/templates/uds-package.yaml + + # Point auth.setup.ts at the root path (Authservice intercepts all routes) + perl -pi -e 's|/example/endpoint|/|g' tests/auth.setup.ts + + # Rename template test file + mv tests/template-application-name.test.ts "tests/${APP_NAME}.test.ts" 2>/dev/null || true + + echo "CI setup complete: template populated with ${APP_NAME} values" + +#### Template CI: Remove this comment, the above block, and the `ci-setup` under `test-install` when building a package #### + +# CI will execute the following (via uds-common/.github/workflows/callable-test.yaml) so they need to be here with these names - name: test-install description: Test deploying the current branch to a new cluster actions: + - task: ci-setup # remove this when building a package - task: create-dev-package - task: setup:k3d-test-cluster - task: create-deploy-test-bundle diff --git a/tasks/test.yaml b/tasks/test.yaml index dd9ac7b..68b5f6a 100644 --- a/tasks/test.yaml +++ b/tasks/test.yaml @@ -5,7 +5,6 @@ tasks: - name: all actions: - task: health-check - # - task: custom-resource-test - task: ingress - task: ui @@ -20,41 +19,9 @@ tasks: namespace: #TEMPLATE_APPLICATION_NAME# condition: Available - # # If application manages custom resources, then test creating custom resources - # - name: custom-resource-test - # description: Test creating a custom resource - # actions: - # # Create test zarf package - # - cmd: | - # ./uds zarf package create --confirm - # dir: tests/optional-example-zarf-tests - # # Generate some kind of test data. In this example it is a certificate - # - cmd: | - # openssl req -x509 -newkey rsa:4096 -keyout testCA.key \ - # -out testCA.pem -sha256 -days 3650 -nodes -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname" - # dir: tests/optional-example-zarf-tests - # # Deploy package with test data - # - cmd: | - # ./uds zarf package deploy \ - # --set EXAMPLE_SECRET_VALUE="$(cat testCA.pem | base64 -w 0)" \ - # zarf-package-example-zarf-tests-"${UDS_ARCH}"-0.0.1.tar.zst \ - # --confirm - # dir: tests/optional-example-zarf-tests - # # Ensure expected resource is generated in some namespace. In this example it is checking for a configmap - # - description: Ensure configmap is created in target namespace - # wait: - # cluster: - # kind: configmap - # name: example-configmap - # namespace: example-ns - # # Cleanup files used to generate test data - # - cmd: | - # rm testCA.key testCA.pem - # dir: tests/optional-example-zarf-tests - - name: ingress actions: - - description: #TEMPLATE_APPLICATION_DISPLAY_NAME# UI Status Check + - description: "#TEMPLATE_APPLICATION_DISPLAY_NAME# Ingress Status Check" maxRetries: 30 cmd: | STATUS=$(curl -L -o /dev/null -s -w "%{http_code}\n" https://#TEMPLATE_APPLICATION_NAME#.uds.dev) diff --git a/tests/auth.setup.ts b/tests/auth.setup.ts index ef3ea24..8bea410 100644 --- a/tests/auth.setup.ts +++ b/tests/auth.setup.ts @@ -8,13 +8,13 @@ import { authFile } from './playwright.config'; // Customize endpoints for application being tested setup('authenticate', async ({ page, context }) => { - await page.goto('/example/endpoint'); + await page.goto("/example/endpoint"); - await page.getByLabel('Username or email').fill('doug'); - await page.getByLabel('Password').fill('unicorn123!@#UN'); - await page.getByRole('button', { name: "Sign In" }).click(); + await page.getByLabel("Username or email").fill("doug"); + await page.getByLabel("Password").fill("unicorn123!@#UN"); // password is from the setup:keycloak-user task + await page.getByRole("button", { name: "Sign In" }).click(); - await page.waitForURL('/example/endpoint'); // successful redirect + await page.waitForURL("/example/endpoint"); // successful redirect // ensure auth cookies were set const cookies = await context.cookies(); @@ -28,5 +28,5 @@ setup('authenticate', async ({ page, context }) => { await page.context().storageState({ path: authFile }); - await expect(page).toHaveURL('/example/endpoint'); + await expect(page).toHaveURL("/example/endpoint"); }) diff --git a/tests/optional-example-zarf-tests/example-custom-resource.yaml b/tests/optional-example-zarf-tests/example-custom-resource.yaml deleted file mode 100644 index 6ca6f92..0000000 --- a/tests/optional-example-zarf-tests/example-custom-resource.yaml +++ /dev/null @@ -1,9 +0,0 @@ -# Copyright 2024 Defense Unicorns -# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Defense-Unicorns-Commercial - -apiVersion: example-custom-resource.io/v1alpha1 -kind: example-custom-resource -metadata: - name: example-custom-resource -spec: -# custom resource spec diff --git a/tests/optional-example-zarf-tests/example-secret.yaml b/tests/optional-example-zarf-tests/example-secret.yaml deleted file mode 100644 index fe1ec22..0000000 --- a/tests/optional-example-zarf-tests/example-secret.yaml +++ /dev/null @@ -1,11 +0,0 @@ -# Copyright 2024 Defense Unicorns -# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Defense-Unicorns-Commercial - -apiVersion: v1 -kind: Secret -metadata: - name: example-secret - namespace: test-ns -type: kubernetes.io/opaque -data: - chain.crt: "###ZARF_VAR_EXAMPLE_SECRET_VALUE###" diff --git a/tests/optional-example-zarf-tests/zarf.yaml b/tests/optional-example-zarf-tests/zarf.yaml deleted file mode 100644 index 574e94f..0000000 --- a/tests/optional-example-zarf-tests/zarf.yaml +++ /dev/null @@ -1,32 +0,0 @@ -# Copyright 2024 Defense Unicorns -# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Defense-Unicorns-Commercial - -# yaml-language-server: $schema=https://raw.githubusercontent.com/defenseunicorns/zarf/main/zarf.schema.json -kind: ZarfPackageConfig -metadata: - name: example-zarf-tests - description: "Example zarf package for testing functionality of operators and other services deployed by UDS package" - architecture: "amd64" - version: "0.0.1" - -variables: - - name: EXAMPLE_SECRET_VALUE - description: "Some data needed for testing functionality" - -components: - # Create secret containing example secret value - - name: example-secret - required: true - manifests: - - name: example-secret - namespace: test-ns - files: - - example-secret.yaml - # Create some custom resource used by operator or service - - name: example-custom-resource - required: true - manifests: - - name: example-custom-resource - namespace: test-ns - files: - - example-custom-resource.yaml diff --git a/tests/template-application-name.test.ts b/tests/template-application-name.test.ts index 3a8915e..390e0ff 100644 --- a/tests/template-application-name.test.ts +++ b/tests/template-application-name.test.ts @@ -5,22 +5,10 @@ import { test, expect } from "@playwright/test"; -// Customize tests for application being tested. Example given for reference - -function randomProjectName() { - return `uds-package-#TEMPLATE_APPLICATION_NAME#-${Math.floor((Math.random() * 1000))}`; -} - -test('create a project', async ({ page }) => { - await page.goto('/projects/create'); - - const projectName = randomProjectName(); - - await page.getByRole('button', { name: 'Manually' }).click(); - await page.getByLabel('Project display name*').fill(projectName); - await page.getByRole('button', { name: 'Set Up' }).click(); - - await expect(page).toHaveURL(`/dashboard?id=${projectName}`); - - await expect(page.getByRole('heading', { level: 1 })).toContainText(projectName); +// Replace this with journey tests for your application. +// See https://playwright.dev/docs/writing-tests for guidance on selectors, +// assertions, and authentication. +test('homepage loads', async ({ page }) => { + const response = await page.goto('/'); + expect(response?.status()).toBeLessThan(400); }); diff --git a/values/common-values.yaml b/values/common-values.yaml index fd2d601..98e9cfb 100644 --- a/values/common-values.yaml +++ b/values/common-values.yaml @@ -2,17 +2,3 @@ # SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Defense-Unicorns-Commercial # Values common to all flavors - -# Example variables from UDS package repo template. Update to relevant variables after templating -# imagePullSecrets: -# - name: "private-registry" - -# postgresql: -# enabled: false -# postgresqlServer: ###ZARF_VAR_EXAMPLE_DB_ENDPOINT### -# existingSecret: "example-postgres" -# existingSecretPasswordKey: "password" -# postgresqlUsername: ###ZARF_VAR_EXAMPLE_DB_USERNAME### -# postgresqlDatabase: ###ZARF_VAR_EXAMPLE_DB_NAME### -# service: -# port: 5432 diff --git a/values/registry1-values.yaml b/values/registry1-values.yaml deleted file mode 100644 index 52d8fe4..0000000 --- a/values/registry1-values.yaml +++ /dev/null @@ -1,9 +0,0 @@ -# Copyright 2024 Defense Unicorns -# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Defense-Unicorns-Commercial - -# Values for registry1 flavor - -# Example variables from UDS package repo template. Update to relevant variables after templating -# image: -# repository: registry1.dso.mil/image -# tag: 1.2.3 diff --git a/values/unicorn-values.yaml b/values/unicorn-values.yaml deleted file mode 100644 index 59cb46f..0000000 --- a/values/unicorn-values.yaml +++ /dev/null @@ -1,9 +0,0 @@ -# Copyright 2024 Defense Unicorns -# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Defense-Unicorns-Commercial - -# Values for unicorn flavor - -# Example variables from UDS package repo template. Update to relevant variables after templating -# image: -# repository: quay.io/rfcurated -# tag: 1.2.3 diff --git a/values/upstream-values.yaml b/values/upstream-values.yaml index 03a1e91..b690619 100644 --- a/values/upstream-values.yaml +++ b/values/upstream-values.yaml @@ -2,8 +2,3 @@ # SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Defense-Unicorns-Commercial # Values for upstream flavor - -# Example variables from UDS package repo template. Update to relevant variables after templating -# image: -# repository: upstream/image -# tag: 1.2.3 diff --git a/zarf.yaml b/zarf.yaml index b20fa0a..e424ad5 100644 --- a/zarf.yaml +++ b/zarf.yaml @@ -15,14 +15,8 @@ metadata: dev.uds.icon: "" variables: - - name: EXAMPLE_VARIABLES - default: "examples" - name: DOMAIN default: "uds.dev" - - name: EXAMPLE_DB_USERNAME - default: "example_username" - - name: EXAMPLE_DB_ENDPOINT - default: "example_db_endpoint" components: - name: #TEMPLATE_APPLICATION_NAME# @@ -37,31 +31,3 @@ components: valuesFiles: - values/upstream-values.yaml images: [] - - - name: #TEMPLATE_APPLICATION_NAME# - required: true - description: "Deploy #TEMPLATE_APPLICATION_DISPLAY_NAME#" - import: - path: common - only: - flavor: registry1 - cluster: - architecture: amd64 - charts: - - name: #TEMPLATE_APPLICATION_NAME# - valuesFiles: - - values/registry1-values.yaml - images: [] - - - name: #TEMPLATE_APPLICATION_NAME# - required: true - description: "Deploy #TEMPLATE_APPLICATION_DISPLAY_NAME#" - import: - path: common - only: - flavor: unicorn - charts: - - name: #TEMPLATE_APPLICATION_NAME# - valuesFiles: - - values/unicorn-values.yaml - images: []