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.
Tip
Found an issue in this template or looking for how to contribute? Check out the Contributing Guidelines
After creating a repo from the UDS Package Template, follow Making it your own documentation in order to customize the template for a new application package.
- Replace some common placeholders
| 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 |
- Review, determine your need, and update
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.
| 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. 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. |
- Almost there...
mv README-template.md README.mdrm -rf tasks/template.yaml- Remove extra lines from tasks.yaml
- Follow the
CODEOWNERS-template.mdto update yourCODEOWNERSfile.
You are ready to start integrating (and testing with CI) your application with UDS Core!
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.
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.)
Note
As a template repository, the 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.
This template repository is part of Defense Unicorns' Unicorn Delivery Service and follows the contributing guidelines outlined in that repositories' CONTRIBUTING.md file.
Feel free to open a new issue for any defects or feature requests.