From 86c2a7e06ae423b91db92b3f84c17a5a73410a2b Mon Sep 17 00:00:00 2001 From: UnicornChance Date: Wed, 15 May 2024 11:54:33 -0600 Subject: [PATCH 01/26] initial pass at integrating docs with uds repo --- docs/_index.md | 13 ++ docs/{anatomy.md => bundle-anatomy.md} | 8 +- docs/bundle-overrides/_index.md | 69 +++++++ docs/bundle-overrides/overrides.md | 170 ++++++++++++++++++ docs/configuration.md | 36 ++++ docs/installation.md | 170 ++++++++++++++++++ docs/uds-runner/_index.md | 0 docs/uds-runner/keyconcepts/_index.md | 5 + docs/uds-runner/keyconcepts/actions.md | 60 +++++++ docs/uds-runner/keyconcepts/files.md | 25 +++ docs/uds-runner/keyconcepts/includes.md | 25 +++ docs/uds-runner/keyconcepts/task-inputs.md | 61 +++++++ docs/uds-runner/keyconcepts/tasks.md | 52 ++++++ .../keyconcepts/variables-concepts.md | 77 ++++++++ docs/uds-runner/keyconcepts/wait.md | 23 +++ docs/uds-runner/runner.md | 45 +++++ docs/variables.md | 55 ++++++ 17 files changed, 893 insertions(+), 1 deletion(-) create mode 100644 docs/_index.md rename docs/{anatomy.md => bundle-anatomy.md} (55%) create mode 100644 docs/bundle-overrides/_index.md create mode 100644 docs/bundle-overrides/overrides.md create mode 100644 docs/configuration.md create mode 100644 docs/installation.md create mode 100644 docs/uds-runner/_index.md create mode 100644 docs/uds-runner/keyconcepts/_index.md create mode 100644 docs/uds-runner/keyconcepts/actions.md create mode 100644 docs/uds-runner/keyconcepts/files.md create mode 100644 docs/uds-runner/keyconcepts/includes.md create mode 100644 docs/uds-runner/keyconcepts/task-inputs.md create mode 100644 docs/uds-runner/keyconcepts/tasks.md create mode 100644 docs/uds-runner/keyconcepts/variables-concepts.md create mode 100644 docs/uds-runner/keyconcepts/wait.md create mode 100644 docs/uds-runner/runner.md create mode 100644 docs/variables.md diff --git a/docs/_index.md b/docs/_index.md new file mode 100644 index 00000000..0bdfd6fe --- /dev/null +++ b/docs/_index.md @@ -0,0 +1,13 @@ +--- +title: Overview +linkTitle: UDS CLI Guide +type: docs +menu: + main: + weight: 30 +--- + +The [UDS CLI](https://github.com/defenseunicorns/uds-cli) is the primary interface for users to interact with various components within the UDS landscape. It streamlines the deployment process of mission applications and secure infrastructure, simplifying tasks involved in running mission applications while maintaining regulatory compliance in a unified and efficient manner. + +The UDS CLI simplifies deployment by bundling multiple Zarf Packages into a single deployable artifact. This process ensures that UDS Bundles, which encompass infrastructure, platform, and mission applications, can be efficiently deployed within any Mission Hero's system environment. Additionally, the UDS CLI extends its capabilities to Pepr, where multiple Pepr applications are bundled and deployed as a single Pepr Module to support UDS Bundles during runtime. + diff --git a/docs/anatomy.md b/docs/bundle-anatomy.md similarity index 55% rename from docs/anatomy.md rename to docs/bundle-anatomy.md index f6f69b97..2819b289 100644 --- a/docs/anatomy.md +++ b/docs/bundle-anatomy.md @@ -1,4 +1,10 @@ -## Bundle Anatomy +--- +title: Bundle Anatomy +type: docs +weight: 5 +--- + +## Bunble Anatomy A UDS Bundle is an OCI artifact with the following form: ![](.images/uds-bundle.png) diff --git a/docs/bundle-overrides/_index.md b/docs/bundle-overrides/_index.md new file mode 100644 index 00000000..3aa514f5 --- /dev/null +++ b/docs/bundle-overrides/_index.md @@ -0,0 +1,69 @@ +--- +title: Bundle Overrides Quickstart +type: docs +weight: 4 +--- + +Consider the following `zarf.yaml` and `values.yaml` which deploys [`podinfo`](https://github.com/stefanprodan/podinfo) with a set of custom values: + +```yaml +# zarf.yaml +kind: ZarfPackageConfig +metadata: + name: helm-overrides-package + version: 0.0.1 + +components: + - name: helm-overrides-component + required: true + charts: + - name: podinfo + version: 6.4.0 + namespace: podinfo + url: https://github.com/stefanprodan/podinfo.git + gitPath: charts/podinfo + valuesFiles: + - values.yaml + images: + - ghcr.io/stefanprodan/podinfo:6.4.0 +--- +# values.yaml +replicaCount: 1 +ui: + color: blue +``` + +The bundle overrides feature allows users to override the values specified in Zarf Packages: + +```yaml +kind: UDSBundle +metadata: + name: helm-overrides + description: testing a bundle with Helm overrides + version: 0.0.1 + +packages: + - name: helm-overrides-package + path: "path/to/pkg" + ref: 0.0.1 + + overrides: + helm-overrides-component: + podinfo: + values: + - path: "replicaCount" + value: 2 + variables: + - name: UI_COLOR + path: "ui.color" + description: "Set the color for podinfo's UI" + default: "purple" +``` + +This bundle facilitates the deployment of the `helm-overrides-package` Zarf Package while offering the ability to override specific values, such as `replicaCount` and `ui.color`, within the `podinfo` chart. Once the bundle has been created, these values remain immutable. However, during deployment, users have the flexibility to override variables such as `UI_COLOR` by either utilizing an environment variable named `UDS_UI_COLOR` or by explicitly specifying the override in a `uds-config.yaml` file, as demonstrated below: + +```yaml +variables: + helm-overrides-package: + UI_COLOR: green +``` diff --git a/docs/bundle-overrides/overrides.md b/docs/bundle-overrides/overrides.md new file mode 100644 index 00000000..29b3cec3 --- /dev/null +++ b/docs/bundle-overrides/overrides.md @@ -0,0 +1,170 @@ +--- +title: Overrides +type: docs +weight: 1 +--- + +## Syntax + +Consider the following bundle `overrides`: + +```yaml +packages: + - name: helm-overrides-package + path: "path/to/pkg" + ref: 0.0.1 + + overrides: + helm-overrides-component: # component name inside of the helm-overrides-package Zarf pkg + podinfo: # chart name from the helm-overrides-component component + values: + - path: "replicaCount" + value: 2 + variables: + - name: UI_COLOR + path: "ui.color" + description: "Set the color for podinfo's UI" + default: "purple" +``` + +In the above example, the Zarf Package `helm-overrides-package` has a specific component named `helm-overrides-component`, which contains a Helm chart named `podinfo`. Notably, these names serve as keys in the `overrides` block. Within the `podinfo` chart, the `replicaCount` value has been overridden to `2`, and a variable named `UI_COLOR` is specifically overridden to the color `purple`. + +## Values + +In the `overrides` block, you will find a list of path and value pairs. This feature enables users to override values within the underlying Helm chart of a Zarf Package component. + +{{% alert-note %}} +Please note that these values are initially set by the authors of the bundle and, once the bundle has been created, they **cannot be modified**. +{{% /alert-note %}} + +### Path + +The path employs dot notation to indicate the location of a value intended for overriding within the base Helm chart. For example, in the `podinfo` chart, the `replicaCount` path is situated at the highest level of the [`podinfo values.yaml`](https://github.com/stefanprodan/podinfo/blob/master/charts/podinfo/values.yaml) so the path is expressed as `replicaCount`. Conversely, the `ui.color` path is found beneath the `ui` key, so the designated path is expressed as `ui.color`. + +### Value + +The `value` represents the content to be set at the specified `path`. It can include straightforward data types like numbers and strings, but it is also versatile enough to handle intricate structures such as lists and objects. For example: + +```yaml +... + overrides: + helm-overrides-component: + podinfo: + values: + - path: "podinfo.tolerations" + value: + - key: "unicorn" + operator: "Equal" + value: "defense" + effect: "NoSchedule" + - path: podinfo.podAnnotations + value: + customAnnotation: "customValue" +``` + +When using a variable exported from another package, you can use its value to set another variable using the syntax `${...}`. In the following example, the `COLOR` variable is used to establish the value of `podinfo.ui.color`. + +```yaml +kind: UDSBundle +metadata: + name: export-vars + description: Example for using an imported variable to set an overrides value + version: 0.0.1 + +packages: + - name: output-var + repository: localhost:888/output-var + ref: 0.0.1 + exports: + - name: COLOR + + - name: helm-overrides + path: "../../packages/helm" + ref: 0.0.1 + + overrides: + podinfo-component: + unicorn-podinfo: + values: + - path: "podinfo.replicaCount" + value: 1 + - path: "podinfo.ui.color" + value: ${COLOR} +``` + +## Variables + +Variables function similarly to values, enabling users to override configurations within a Zarf Package component's underlying Helm chart. They also share a similar syntax. However, unlike values, variables offer the flexibility of being overridden dynamically during deploy time. For example, consider the following `variables`: + +```yaml +... + overrides: + helm-overrides-component: + podinfo: + variables: + - name: UI_COLOR + path: "ui.color" + description: "Set the color for podinfo's UI" + default: "purple" +``` + +There are three ways to override the `UI_COLOR` variable: + +- **UDS Config:** Create a `uds-config.yaml` file within the bundle's directory and specify the variables you wish to override. To modify the `UI_COLOR` variable, create a `uds-config.yaml`. For example: + +```yaml + variables: + helm-overrides-package: + ui_color: green +``` + +Note that the variable for `UI_COLOR` can be either upper or lower case. + +- **Environment Variables:** Create an environment variable prefixed with `UDS_` followed by the variable name. For example, to override the `UI_COLOR` variable, you would create an environment variable named `UDS_UI_COLOR` and assign it the desired value. + +Note that the environment variables hold precedence over variables specified in the `uds-config.yaml` configuration file. + +- **`--set` Flag:** Override a variable using the UDS CLI's `--set` flag. For example, the override the `UI_COLOR` variable, run one of the following commands: + +```cli +# by default ui_color will apply to all packages in the bundle +uds deploy example-bundle --set ui_color=green + +# to specify a specific package that the variable should apply to you can prepend th package name to the variable +uds deploy example-bundle --set helm-overrides-package.ui_color=green +``` + +{{% alert-note %}} +When using Helm override variables and Zarf variables, which share the same `--set` syntax, exercise caution with variable naming to prevent conflicts. +{{% /alert-note %}} + +### Variable Precendence + +Variable precedence is as follows: + +1. Environment variables. +2. `uds-config.yaml` variables. +3. Variables that are `default` in the `uds-bundle.yaml`. + +## Namespace + +Users can specify a namespace for a packaged Helm chart to be installed in. For instance, to deploy a chart in the `custom-podinfo` namespace, specify the `namespace` in the `overrides` block: + +```yaml +kind: UDSBundle +metadata: + name: example-bundle + version: 0.0.1 + +packages: + - name: helm-overrides-package + path: "../../packages/helm" + ref: 0.0.1" + overrides: + podinfo-component: + unicorn-podinfo: + namespace: custom-podinfo # custom namespace! + values: + - path: "podinfo.replicaCount" + value: 1 +``` diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 00000000..f2b42a7b --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,36 @@ +--- +title: CLI Configuration +type: docs +weight: 2 +--- + +## Configuration + +The UDS CLI can be easily configured through a `uds-config.yaml` file, offering flexibility in placement either within the current working directory or via the specification of an environment variable named `UDS_CONFIG`. The fundamental structure of the `uds-config.yaml` file is outlined below: + +```yaml +options: + log_level: debug + architecture: arm64 + no_log_file: false + no_progress: false + uds_cache: /tmp/uds-cache + tmp_dir: /tmp/tmp_dir + insecure: false + oci_concurrency: 3 + +shared: + domain: uds.dev # shared across all packages in a bundle + +variables: + my-zarf-package: # name of Zarf package + ui_color: green # key is not case sensitive and refers to name of Zarf variable + UI_MSG: "Hello Unicorn" + hosts: # variables can be complex types such as lists and maps + - host: burning.boats + paths: + - path: "/" + pathType: "Prefix" +``` + +The `options` key contains UDS CLI options that are not specific to a particular Zarf Package. The `variables` key contains variables that are specific to a particular Zarf Package. If there is a need to share insensitive variables across multiple Zarf Packages, the `shared` key can be used. In this case, the `shared` key represents the variable name, and the value is the variable's intended value. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..84857cfb --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,170 @@ +--- +title: Quickstart Guide +type: docs +weight: 1 +--- + +## Install UDS CLI + +Homebrew is the recommended installation method: + +```git +brew tap defenseunicorns/tap && brew install uds +``` + +{{% alert-note %}} +Please note that UDS CLI Binaries are also included with each [GitHub release.](https://github.com/defenseunicorns/uds-cli/releases) +{{% /alert-note %}} + +## Quickstart Guide + +The UDS-CLI's primary feature is the ability to deploy multiple, independent Zarf Packages. To create a `UDSBundle` containing Zarf Packages, you can use the following `uds-bundle.yaml` file as a template: + +```yaml +kind: UDSBundle +metadata: + name: example + description: an example UDS bundle + version: 0.0.1 + +packages: + - name: init + repository: ghcr.io/defenseunicorns/packages/init + ref: v0.33.0 + optionalComponents: + - git-server + - name: podinfo + repository: ghcr.io/defenseunicorns/uds-cli/podinfo + ref: 0.0.1 +``` + +In this example, the `UDSBundle` named "example" deploys the Zarf Init Package and Podinfo. The packages listed under the `packages` section can be sourced either locally or from an OCI registry. Please see this [comprehensive example](https://github.com/defenseunicorns/uds-cli/blob/main/src/test/bundles/03-local-and-remote/uds-bundle.yaml) deploying both local and remote Zarf Packages. Additional `UDSBundle` examples can be explored in the [`src/test/bundles`](https://github.com/defenseunicorns/uds-cli/tree/main/src/test/bundles) folder. + +### Declarative Syntax + +The syntax of a `uds-bundle.yaml` file is entirely declarative. As a result, the UDS CLI does not prompt users to deploy optional components included in a Zarf Package. If there is a desire to deploy an optional Zarf component, it must be explicitly specified within the `optionalComponents` key of a specific `package`. + +### UDS Support + +When utilizing the UDS CLI for `deploy`, `inspect`, `remove`, and `pull` commands, the tool incorporates shorthand functionality for streamlined interaction with the Defense Unicorns organization on the GitHub Container Registry (GHCR). By default, paths are automatically expanded to the Defense Unicorns organization on GHCR, unless otherwise specified. For example: + +`uds deploy unicorn-bundle:v0.1.0` is functionally equivalent to `uds deploy ghcr.io/defenseunicorns/packages/uds/bundles/unicorn-bundle:v0.1.0` + +The matching and expansion of bundles is ordered as follows: + +1. Local with a `tar.zst` extension. +2. Remote path: `oci://ghcr.io/defenseunicorns/packages/uds/bundles/`. +3. Remote path: `oci://ghcr.io/defenseunicorns/packages/delivery/`. +4. Remote path: `oci://ghcr.io/defenseunicorns/packages/`. + +If the bundle is not local, the UDS CLI will sequentially check path 2, path 3, and so forth, for the remote bundle artifact. This behavior can be overridden by explicitly specifying the full path to the bundle artifact, as demonstrated in the example: `uds deploy ghcr.io/defenseunicorns/dev/path/dev-bundle:v0.1.0`. + +### Bundle Create + +The `uds create` command pulls the necessary Zarf Packages from the registry and bundles them into an OCI artifact. + +There are two ways to create UDS Bundles: + +- Inside an OCI registry: `uds create -o ghcr.io/defenseunicorns/dev`. +- Locally on your filesystem: `uds create `. + +{{% alert-note %}} +The `--insecure` flag is necessary when engaging with a local registry; however, it is not required when operating with secure, remote registries such as GHCR. +{{% /alert-note %}} + +### Bundle Deploy + +The `uds deploy` command deploys the UDS Bundle. + +There are two ways to deploy UDS Bundles: + +- From an OCI registry: `uds deploy ghcr.io/defenseunicorns/dev/:`. +- From your local filesystem: `uds deploy uds-bundle-.tar.zst`. + +#### Specifying Packages Using `--packages` + +By default, the deployment process includes all packages within the specified bundle. However, you have the option to selectively deploy specific packages from the bundle using the `--packages` flag. + +For example: `uds deploy uds-bundle-.tar.zst --packages init,nginx`. + +In this example, only the `init` and `nginx` packages from the specified bundle will be deployed. + +#### Resuming Bundle Deploys Using `--resume` + +By default, the deployment process includes all packages within the bundle, irrespective of whether they have been previously deployed. However, users have the option to selectively deploy only those packages that have not been deployed before, achieved by utilizing the `--resume` flag. + +For example: `uds deploy uds-bundle-.tar.zst --resume`. + +This command signifies a deployment operation where only the packages within the specified bundle that have not been deployed previously will be processed. + +### Bundle Inspect + +The `uds inspect` command inspects the `uds-bundle.yaml` of a bundle. + +There are two ways to inspect UDS Bundles: + +- From an OCI registry: `uds inspect oci://ghcr.io/defenseunicorns/dev/:`. +- From your local filesystem: `uds inspect uds-bundle-.tar.zst`. + +#### Viewing Software Bill of Materials (SBOM) + +The `uds inspect` command offers two additional flags for extracting and viewing the SBOM: + +- To output the SBOM as a tar file, use: `uds inspect ... --sbom`. +- To output the SBOM into a directory as individual files, use: `uds inspect ... --sbom --extract`. + +This functionality utilizes the `sboms.tar` within the underlying Zarf Packages to generate a new artifact named `bundle-sboms.tar`. This artifact consolidates all SBOMs from the Zarf Packages within the bundle. + +### Bundle Publish + +To publish local bundles to an OCI registry, utilize the following command format: `uds publish .tar.zst oci://`. + +For example: `uds publish uds-bundle-example-arm64-0.0.1.tar.zst oci://ghcr.io/github_user`. + +### Bundle Remove + +The `uds remove` command will remove the UDS Bundle. + +There are two ways to remove UDS Bundles: + +- From an OCI registry: `uds remove oci://ghcr.io/defenseunicorns/dev/: --confirm`. +- From your local filesystem: `uds remove uds-bundle-.tar.zst --confirm`. + +By default, the removal operation targets all packages within the bundle. However, users have the flexibility to selectively remove specific packages from the bundle by employing the `--packages` flag. + +For instance, the following command removes only the `init` and `nginx` packages from the bundle: `uds remove uds-bundle-.tar.zst --packages init,nginx`. + +### Logs + +The `uds logs` command can be used to view the most recent logs of a bundle operation. + +{{% alert-note %}} +Depending on your OS temporary directory and file settings, recent logs are purged after a certain amount of time, so this command may return an error if the logs are no longer available. Currently, `uds logs` is compatible only with `uds deploy`. While it may function with other operations, compatibility is not guaranteed. +{{% /alert-note %}} + +## Zarf Integration + +The UDS CLI incorporates a vendored version of Zarf within its binary distribution. To leverage the Zarf functionality, execute the command `uds zarf `. For instance, to generate a Zarf Package, run the command `uds zarf package create `. Similarly, for utilizing the [air gap toolset](https://docs.zarf.dev/commands/zarf_tools/) provided by Zarf, execute `uds zarf tools `. + +### Development Mode + +In development mode, you can accelerate development and testing cycles for UDS Bundles. The `uds dev deploy` command facilitates the deployment of a UDS Bundle in development mode. If a local Zarf Package is missing, this command will generate the required Zarf Package for you, assuming that both the `zarf.yaml` file and the Zarf Package are located in the same directory. Additionally, it will create your bundle and deploy the Zarf Packages in [`YOLO`](https://docs.zarf.dev/faq#what-is-yolo-mode-and-why-would-i-use-it) mode, eliminating the need to execute `zarf init`. + +{{% alert-note %}} +Currently, development mode only works with local bundles. +{{% /alert-note %}} + +## Bundle Architecture and Multi-Arch Support + +There are several ways to specify the architecture of a bundle: + +- Setting `--architecture` or `-a` flag during `uds ...` operations: `uds create --architecture arm64`. +- Setting the `metadata.architecture` key in a `uds-bundle.yaml`. +- Setting a `UDS_ARCHITECTURE` environment variable. +- Setting the `options.architecture` key in a `uds-config.yaml`. + +{{% alert-note %}} +Setting the `--architecture` flag takes precedence over all other methods of specifying the architecture. +{{% /alert-note %}} + +UDS CLI supports multi-arch bundles. This means you can push bundles with different architectures to the same remote OCI repository, at the same tag. For example, you can push both an `amd64` and `arm64` bundle to `ghcr.io//:0.0.1`. diff --git a/docs/uds-runner/_index.md b/docs/uds-runner/_index.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/uds-runner/keyconcepts/_index.md b/docs/uds-runner/keyconcepts/_index.md new file mode 100644 index 00000000..b06a891f --- /dev/null +++ b/docs/uds-runner/keyconcepts/_index.md @@ -0,0 +1,5 @@ +--- +title: Key Concepts +type: docs +weight: 6 +--- \ No newline at end of file diff --git a/docs/uds-runner/keyconcepts/actions.md b/docs/uds-runner/keyconcepts/actions.md new file mode 100644 index 00000000..e6fce867 --- /dev/null +++ b/docs/uds-runner/keyconcepts/actions.md @@ -0,0 +1,60 @@ +--- +title: Actions +type: docs +weight: 8 +--- + +Actions are the underlying operations that a task will perform. Each action under the `actions` key has a unique syntax. + +### Task + +A `task` can reference a task, thus making tasks composable: + +```yaml +tasks: + - name: foo + actions: + - task: bar + - name: bar + actions: + - task: baz + - name: baz + actions: + - cmd: "echo task foo is composed of task bar which is composed of task baz!" +``` + +In the example given above, the task named `foo` invokes a task labeled `bar`, which in turn triggers a task named `baz`. This `baz` task is responsible for outputting information to the console. + +### CMD + +Actions have the capability to execute arbitrary Bash commands, including in-line scripts. Additionally, the output of a command can be stored in a variable by utilizing the `setVariables` key: + +```yaml +tasks: + - name: foo + actions: + - cmd: echo -n 'dHdvIHdlZWtzIG5vIHByb2JsZW0=' | base64 -d + setVariables: + - name: FOO +``` + +This task will decode the base64 string and set the value as a variable named `FOO` that can be used in other tasks. + +Command blocks can have several other properties including: + +- `description`: description of the command. +- `mute`: boolean value to mute the output of a command. +- `dir`: the directory to run the command in. +- `env`: list of environment variables to run for this `cmd` block only: + +```yaml +tasks: + - name: foo + actions: + - cmd: echo ${BAR} + env: + - BAR=bar +``` + +- `maxRetries`: number of times to retry the command. +- `maxTotalSeconds`: max number of seconds the command can run until it is killed; takes precendence over `maxRetries`. diff --git a/docs/uds-runner/keyconcepts/files.md b/docs/uds-runner/keyconcepts/files.md new file mode 100644 index 00000000..7b6739f2 --- /dev/null +++ b/docs/uds-runner/keyconcepts/files.md @@ -0,0 +1,25 @@ +--- +title: Files +type: docs +weight: 10 +--- + +The `files` key is used to copy local or remote files to the current working directory: + +```yaml +tasks: + - name: copy-local + files: + - source: /tmp/foo + target: foo + - name: copy-remote + files: + - source: https://cataas.com/cat + target: cat.jpeg +``` + +`files` blocks can also use the following attributes: + +- `executable`: boolean value indicating if the file is executable. +- `shasum`: SHA string to verify the integrity of the file. +- `symlinks`: list of strings referring to symlink the file to. diff --git a/docs/uds-runner/keyconcepts/includes.md b/docs/uds-runner/keyconcepts/includes.md new file mode 100644 index 00000000..44c871ae --- /dev/null +++ b/docs/uds-runner/keyconcepts/includes.md @@ -0,0 +1,25 @@ +--- +title: Includes +type: docs +weight: 12 +--- + +The `includes` key serves the purpose of importing tasks from either local or remote task files. This functionality proves beneficial for sharing common tasks among various task files. When importing a task from a local task file, the path is relative to the current file. During task execution, both the tasks within the file and the `includes` tasks undergo processing to prevent any potential infinite loop references. This ensures a seamless and efficient task execution process: + +```yaml +includes: + - local: ./path/to/tasks-to-import.yaml + - remote: https://raw.githubusercontent.com/defenseunicorns/uds-cli/main/src/test/tasks/remote-import-tasks.yaml + +tasks: + - name: import-local + actions: + - task: local:some-local-task + - name: import-remote + actions: + - task: remote:echo-var +``` + +It's important to be aware that task files included in a project can also include additional task files. However, there is a specific constraint to consider: + +- If a task file includes a remote task file, it is crucial to note that the included remote task file cannot, in turn, include any local task files. diff --git a/docs/uds-runner/keyconcepts/task-inputs.md b/docs/uds-runner/keyconcepts/task-inputs.md new file mode 100644 index 00000000..7a663c3b --- /dev/null +++ b/docs/uds-runner/keyconcepts/task-inputs.md @@ -0,0 +1,61 @@ +--- +title: Task Inputs and Reusable Tasks +type: docs +weight: 13 +--- + +While the expectation is for tasks to be reusable, there are instances where you may need to create a task that accommodates various inputs for reuse. To create such a versatile task, include an `inputs` key featuring a mapping of inputs to the task: + +```yaml +tasks: + - name: echo-var + inputs: + hello-input: + default: hello world + description: This is an input to the echo-var task + deprecated-input: + default: foo + description: this is a input from a previous version of this task + deprecatedMessage: this input is deprecated, use hello-input instead + actions: + # to use the input, reference it using INPUT_ in all caps + - cmd: echo $INPUT_HELLO_INPUT + + - name: use-echo-var + actions: + - task: echo-var + with: + # hello-input is the name of the input in the echo-var task, hello-unicorn is the value we want to pass in + hello-input: hello unicorn +``` + +In the provided example, the `echo-var` task is configured to receive an input named `hello-input` and display it on the console. It's worth noting that the `input` can be assigned a `default` value. Subsequently, the `use-echo-var` task invokes `echo-var` with an alternative input value, specified through the `with` key. In this example, the input `hello unicorn` is passed to the `hello-input` input. + +It's important to highlight the presence of the `deprecated-input` input, which comes with a `deprecatedMessage` attribute. This attribute serves the purpose of signaling that the input is deprecated and should be avoided. Should a task be executed with a deprecated input, a warning message will be printed to the console. + +### Templates + +When creating a task with `inputs` you can use [Go templates](https://pkg.go.dev/text/template#hdr-Functions) in that task's `actions`. For example: + +```yaml +tasks: + - name: length-of-inputs + inputs: + hello-input: + default: hello world + description: This is an input to the echo-var task + another-input: + default: another world + actions: + # index and len are go template functions, while .inputs is map representing the inputs to the task + - cmd: echo ${{ index .inputs "hello-input" | len }} + - cmd: echo ${{ index .inputs "another-input" | len }} + + - name: len + actions: + - task: length-of-inputs + with: + hello-input: hello unicorn +``` + +Running `uds run len` will print the length of the inputs to `hello-input` and `another-input` to the console. diff --git a/docs/uds-runner/keyconcepts/tasks.md b/docs/uds-runner/keyconcepts/tasks.md new file mode 100644 index 00000000..d0bee33d --- /dev/null +++ b/docs/uds-runner/keyconcepts/tasks.md @@ -0,0 +1,52 @@ +--- +title: Tasks +type: docs +weight: 7 +--- + +Tasks serve as the foundational components of the UDS Runner, defining the operations to be executed. Within the `tasks.yaml` file, the `tasks` key at the root level delineates a list of tasks scheduled for execution. The specific operations carried out by each task are detailed under the `actions` key: + +```yaml +tasks: + - name: all-the-tasks + actions: + - task: make-build-dir + - task: install-deps +``` + +In the above example, the name of the task is "all-the-tasks", and it is composed of multiple sub-tasks to run. These sub-tasks would also be defined in the list of `tasks`: + +```yaml +tasks: + - name: default + actions: + - cmd: echo "run default task" + + - name: all-the-tasks + actions: + - task: make-build-dir + - task: install-deps + + - name: make-build-dir + actions: + - cmd: mkdir -p build + + - name: install-deps + actions: + - cmd: go mod tidy +``` + +Using the UDS CLI, these tasks can be run individually: + +```cli +uds run all-the-tasks # runs all-the-tasks, which calls make-build-dir and install-deps +uds run make-build-dir # only runs make-build-dir +``` + +### Default Tasks + +In the provided example above, there is a special type of task known as the default task. This task is optional and can be used as the common entry point for your tasks. When attempting to execute the `default` task, you can exclude the task name from the run command: + +```cli +uds run +``` diff --git a/docs/uds-runner/keyconcepts/variables-concepts.md b/docs/uds-runner/keyconcepts/variables-concepts.md new file mode 100644 index 00000000..8d702cb7 --- /dev/null +++ b/docs/uds-runner/keyconcepts/variables-concepts.md @@ -0,0 +1,77 @@ +--- +title: Variables +type: docs +weight: 9 +--- + +Variables can be defined in several ways: + +- At the top of the `tasks.yaml`: + +```yaml +variables: + - name: FOO + default: foo + +tasks: ... +``` + +- As the output of a `cmd`: + +```yaml +variables: + - name: FOO + default: foo +tasks: + - name: foo + actions: + - cmd: uname -m + mute: true + setVariables: + - name: FOO + - cmd: echo ${FOO} +``` + +- As an environment variable, it is recommended to prefix them with `UDS_`. In the given example, creating an environment variable `UDS_FOO=bar` would result in the `FOO` variable being set to `bar`. +- Using the `--set` flag in the CLI: + +```cli +uds run foo --set FOO=bar +``` + +To use a variable, reference it using `${VAR_NAME}` + +Note that variables also have the following attributes when setting them with YAML: + +- `sensitive`: boolean value indicating if a variable should be visible in output. +- `default`: default value of a variable. + - In the provided example, if the variable `FOO` lacks a default value and you set the environment variable `UDS_FOO=bar`, the default value will be configured as `bar`. + +### Environment Variable Files + +To incorporate a file containing environment variables into a task and load them for use, utilize the `envPath` key within the task configuration. This key facilitates the loading of all environment variables from the specified file into both the task being invoked and its subsequent child tasks: + +```yaml +tasks: + - name: env + actions: + - cmd: echo $FOO + - cmd: echo $UDS_ARCH + - task: echo-env + - name: echo-env + envPath: ./path/to/.env + actions: + - cmd: echo different task $FOO +``` + +### Variable Precendence + +Variable precedence is as follows, from least to most specific: + +- Variable defaults set in YAML. +- Environment variables prefixed with `UDS_`. +- Variables set with the `--set` flag in the CLI. + +{{% alert-note %}} +Variables established using the `--set` flag take precedence over variables from all other outlined sources. +{{% /alert-note %}} diff --git a/docs/uds-runner/keyconcepts/wait.md b/docs/uds-runner/keyconcepts/wait.md new file mode 100644 index 00000000..cf60b4b1 --- /dev/null +++ b/docs/uds-runner/keyconcepts/wait.md @@ -0,0 +1,23 @@ +--- +title: Wait +type: docs +weight: 11 +--- + +The `wait` key function serves to halt the execution, effectively pausing the program until a specified resource becomes available. This resource could include anything from network responses to Kubernetes operations: + +```yaml +tasks: + - name: network-response + wait: + network: + protocol: https + address: 1.1.1.1 + code: 200 + - name: configmap-creation + wait: + cluster: + kind: configmap + name: simple-configmap + namespace: foo +``` diff --git a/docs/uds-runner/runner.md b/docs/uds-runner/runner.md new file mode 100644 index 00000000..f4cc1b4e --- /dev/null +++ b/docs/uds-runner/runner.md @@ -0,0 +1,45 @@ +--- +title: UDS Runner +type: docs +weight: 5 +--- + +The UDS Runner enables UDS Bundle developers to automate UDS builds and execute routine shell tasks. The UDS CLI contains vendors and configures the [`maru-runner`](https://github.com/defenseunicorns/maru-runner) build tool to support simple compiling and building of UDS Bundles. + +## Quickstart + +### Running a Task + +To run a task from a `tasks.yaml` execute the following command: + +```yaml +uds run +``` + +To run a task from a specific tasks file, execute the following command: + +```yaml +uds run -f +``` + +{{% alert-note %}} +The [maru documentation](https://github.com/defenseunicorns/maru-runner?tab=readme-ov-file#maru-runner) describes how to build the `tasks.yaml` files to configure the UDS Runner. +{{% /alert-note %}} + +### Variables Set With Environment Variables + +When running a `tasks.yaml` with `uds run my-task` variables can be set using environment prefixed with `UDS_`. For example, running `UDS_FOO=bar uds run echo-foo` on the following task will echo `bar`: + +```yaml +variables: + - name: FOO + default: foo +tasks: + - name: echo-foo + actions: + - cmd: echo ${FOO} +``` + +### No Zarf Dependency + +Considering that the UDS CLI also vendors [Zarf](https://docs.zarf.dev/), there is no need to have Zarf installed on your system. diff --git a/docs/variables.md b/docs/variables.md new file mode 100644 index 00000000..0a34c570 --- /dev/null +++ b/docs/variables.md @@ -0,0 +1,55 @@ +--- +title: CLI Variables +type: docs +weight: 3 +--- + +## Importing and Exporting Variables + +Zarf Package variables can be passed between Zarf Packages, see the example below: + +```yaml +kind: UDSBundle +metadata: + name: simple-vars + description: show how vars work + version: 0.0.1 + +packages: + - name: output-var + repository: localhost:888/output-var + ref: 0.0.1 + exports: + - name: OUTPUT + - name: receive-var + repository: localhost:888/receive-var + ref: 0.0.1 + imports: + - name: OUTPUT + package: output-var +``` + +In Zarf Packages, variables intended for accessibility by other packages are situated within the `export` block of the respective Zarf Package. By default, all variables marked for `export` are globally accessible to all packages within a bundle. However, when dealing with potential variable name collisions or when a specific exported variable needs to be consumed by another package, the `imports` key can be used. This key facilitates the explicit association of both the variable name and the package from which it is exported. + +In the provided example, the `OUTPUT` variable is generated as part of a Zarf Action within the `output-var` package. The `receive-var` package, in turn, anticipates the availability of a variable named `OUTPUT` and explicitly imports it using the `imports` key. + +## Sharing Variables + +To streamline the configuration of Zarf Variables across multiple packages within a bundle, consider employing environment variables prefixed with `UDS_`. This approach eliminates the need to repetitively set variables using import/export syntax. For instance, if several packages share a common variable, such as `DOMAIN`, you can set it once using a `UDS_DOMAIN` environment variable, and it will automatically apply to all packages in the bundle. Alternatively, a similar configuration can be achieved using the `shared` key in the `uds-config.yaml` file. + +On deploy, package variables can also be set using the `--set` flag. When the package name is excluded from the key, for example: `--set super=true`, the variable is applied to all packages. If the package name is included in the key, for example: `--set cool-package.super=true`, the variable exclusively applies to the specified package. This provides a flexible mechanism for targeted configuration adjustments during deployment. + +## Variable Precedence and Specificity + +Within a bundle, variables can originate from four distinct sources, each with a specified order of precedence ranging from the least to the most specific. These sources are outlined below: + +- Variables declared in a Zarf Package. +- Variables that have been `import` from a bundles package's `export`. +- Varaibles configured in the `shared` key in a `uds-config.yaml`. +- Variables configured in the `variables` key in a `uds-config.yaml`. +- Variables set with an environment variable prefixed with `UDS_`, for example: `UDS_OUTPUT`. +- Variables set using the `--set` flag when executing the `uds deploy` command. + +{{% alert-note %}} +Variables established using the `--set` flag take precedence over variables from all other outlined sources. +{{% /alert-note %}} From 509dcee25ba37d7987b82905db74200bc82b7883 Mon Sep 17 00:00:00 2001 From: UnicornChance Date: Wed, 15 May 2024 13:01:41 -0600 Subject: [PATCH 02/26] fix: link to image --- docs/bundle-anatomy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/bundle-anatomy.md b/docs/bundle-anatomy.md index 2819b289..701a38f9 100644 --- a/docs/bundle-anatomy.md +++ b/docs/bundle-anatomy.md @@ -7,4 +7,4 @@ weight: 5 ## Bunble Anatomy A UDS Bundle is an OCI artifact with the following form: -![](.images/uds-bundle.png) +![](https://github.com/defenseunicorns/uds-cli/blob/main/docs/.images/uds-bundle.png) From 66d4a48e38a6491673a27bfc5f86e397312a1b1e Mon Sep 17 00:00:00 2001 From: UnicornChance Date: Wed, 15 May 2024 13:26:08 -0600 Subject: [PATCH 03/26] iterate --- docs/bundle-anatomy.md | 7 ++- docs/uds-runner/_index.md | 5 +++ docs/uds-runner/{keyconcepts => }/actions.md | 2 +- docs/uds-runner/{keyconcepts => }/files.md | 2 +- docs/uds-runner/{keyconcepts => }/includes.md | 2 +- docs/uds-runner/keyconcepts/_index.md | 5 --- docs/uds-runner/runner.md | 45 ------------------- .../{keyconcepts => }/task-inputs.md | 2 +- docs/uds-runner/{keyconcepts => }/tasks.md | 2 +- .../{keyconcepts => }/variables-concepts.md | 2 +- docs/uds-runner/{keyconcepts => }/wait.md | 2 +- 11 files changed, 18 insertions(+), 58 deletions(-) rename docs/uds-runner/{keyconcepts => }/actions.md (99%) rename docs/uds-runner/{keyconcepts => }/files.md (98%) rename docs/uds-runner/{keyconcepts => }/includes.md (99%) delete mode 100644 docs/uds-runner/keyconcepts/_index.md delete mode 100644 docs/uds-runner/runner.md rename docs/uds-runner/{keyconcepts => }/task-inputs.md (99%) rename docs/uds-runner/{keyconcepts => }/tasks.md (99%) rename docs/uds-runner/{keyconcepts => }/variables-concepts.md (99%) rename docs/uds-runner/{keyconcepts => }/wait.md (97%) diff --git a/docs/bundle-anatomy.md b/docs/bundle-anatomy.md index 701a38f9..2e8ebc6a 100644 --- a/docs/bundle-anatomy.md +++ b/docs/bundle-anatomy.md @@ -7,4 +7,9 @@ weight: 5 ## Bunble Anatomy A UDS Bundle is an OCI artifact with the following form: -![](https://github.com/defenseunicorns/uds-cli/blob/main/docs/.images/uds-bundle.png) +{{ $image := resources.GetRemote "https://github.com/defenseunicorns/uds-cli/blob/main/docs/.images/uds-bundle.png" }} + +{{ $image := .Resources.GetMatch "sunset.jpg" }} +{{ with $image }} + +{{ end }} diff --git a/docs/uds-runner/_index.md b/docs/uds-runner/_index.md index e69de29b..84725fa6 100644 --- a/docs/uds-runner/_index.md +++ b/docs/uds-runner/_index.md @@ -0,0 +1,5 @@ +--- +title: Key Concepts +type: docs +weight: 1 +--- \ No newline at end of file diff --git a/docs/uds-runner/keyconcepts/actions.md b/docs/uds-runner/actions.md similarity index 99% rename from docs/uds-runner/keyconcepts/actions.md rename to docs/uds-runner/actions.md index e6fce867..d29de550 100644 --- a/docs/uds-runner/keyconcepts/actions.md +++ b/docs/uds-runner/actions.md @@ -1,7 +1,7 @@ --- title: Actions type: docs -weight: 8 +weight: 2 --- Actions are the underlying operations that a task will perform. Each action under the `actions` key has a unique syntax. diff --git a/docs/uds-runner/keyconcepts/files.md b/docs/uds-runner/files.md similarity index 98% rename from docs/uds-runner/keyconcepts/files.md rename to docs/uds-runner/files.md index 7b6739f2..352805af 100644 --- a/docs/uds-runner/keyconcepts/files.md +++ b/docs/uds-runner/files.md @@ -1,7 +1,7 @@ --- title: Files type: docs -weight: 10 +weight: 4 --- The `files` key is used to copy local or remote files to the current working directory: diff --git a/docs/uds-runner/keyconcepts/includes.md b/docs/uds-runner/includes.md similarity index 99% rename from docs/uds-runner/keyconcepts/includes.md rename to docs/uds-runner/includes.md index 44c871ae..5f81cfc3 100644 --- a/docs/uds-runner/keyconcepts/includes.md +++ b/docs/uds-runner/includes.md @@ -1,7 +1,7 @@ --- title: Includes type: docs -weight: 12 +weight: 6 --- The `includes` key serves the purpose of importing tasks from either local or remote task files. This functionality proves beneficial for sharing common tasks among various task files. When importing a task from a local task file, the path is relative to the current file. During task execution, both the tasks within the file and the `includes` tasks undergo processing to prevent any potential infinite loop references. This ensures a seamless and efficient task execution process: diff --git a/docs/uds-runner/keyconcepts/_index.md b/docs/uds-runner/keyconcepts/_index.md deleted file mode 100644 index b06a891f..00000000 --- a/docs/uds-runner/keyconcepts/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Key Concepts -type: docs -weight: 6 ---- \ No newline at end of file diff --git a/docs/uds-runner/runner.md b/docs/uds-runner/runner.md deleted file mode 100644 index f4cc1b4e..00000000 --- a/docs/uds-runner/runner.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: UDS Runner -type: docs -weight: 5 ---- - -The UDS Runner enables UDS Bundle developers to automate UDS builds and execute routine shell tasks. The UDS CLI contains vendors and configures the [`maru-runner`](https://github.com/defenseunicorns/maru-runner) build tool to support simple compiling and building of UDS Bundles. - -## Quickstart - -### Running a Task - -To run a task from a `tasks.yaml` execute the following command: - -```yaml -uds run -``` - -To run a task from a specific tasks file, execute the following command: - -```yaml -uds run -f -``` - -{{% alert-note %}} -The [maru documentation](https://github.com/defenseunicorns/maru-runner?tab=readme-ov-file#maru-runner) describes how to build the `tasks.yaml` files to configure the UDS Runner. -{{% /alert-note %}} - -### Variables Set With Environment Variables - -When running a `tasks.yaml` with `uds run my-task` variables can be set using environment prefixed with `UDS_`. For example, running `UDS_FOO=bar uds run echo-foo` on the following task will echo `bar`: - -```yaml -variables: - - name: FOO - default: foo -tasks: - - name: echo-foo - actions: - - cmd: echo ${FOO} -``` - -### No Zarf Dependency - -Considering that the UDS CLI also vendors [Zarf](https://docs.zarf.dev/), there is no need to have Zarf installed on your system. diff --git a/docs/uds-runner/keyconcepts/task-inputs.md b/docs/uds-runner/task-inputs.md similarity index 99% rename from docs/uds-runner/keyconcepts/task-inputs.md rename to docs/uds-runner/task-inputs.md index 7a663c3b..bf6c0bd8 100644 --- a/docs/uds-runner/keyconcepts/task-inputs.md +++ b/docs/uds-runner/task-inputs.md @@ -1,7 +1,7 @@ --- title: Task Inputs and Reusable Tasks type: docs -weight: 13 +weight: 7 --- While the expectation is for tasks to be reusable, there are instances where you may need to create a task that accommodates various inputs for reuse. To create such a versatile task, include an `inputs` key featuring a mapping of inputs to the task: diff --git a/docs/uds-runner/keyconcepts/tasks.md b/docs/uds-runner/tasks.md similarity index 99% rename from docs/uds-runner/keyconcepts/tasks.md rename to docs/uds-runner/tasks.md index d0bee33d..2cb8f20a 100644 --- a/docs/uds-runner/keyconcepts/tasks.md +++ b/docs/uds-runner/tasks.md @@ -1,7 +1,7 @@ --- title: Tasks type: docs -weight: 7 +weight: 1 --- Tasks serve as the foundational components of the UDS Runner, defining the operations to be executed. Within the `tasks.yaml` file, the `tasks` key at the root level delineates a list of tasks scheduled for execution. The specific operations carried out by each task are detailed under the `actions` key: diff --git a/docs/uds-runner/keyconcepts/variables-concepts.md b/docs/uds-runner/variables-concepts.md similarity index 99% rename from docs/uds-runner/keyconcepts/variables-concepts.md rename to docs/uds-runner/variables-concepts.md index 8d702cb7..8105be15 100644 --- a/docs/uds-runner/keyconcepts/variables-concepts.md +++ b/docs/uds-runner/variables-concepts.md @@ -1,7 +1,7 @@ --- title: Variables type: docs -weight: 9 +weight: 3 --- Variables can be defined in several ways: diff --git a/docs/uds-runner/keyconcepts/wait.md b/docs/uds-runner/wait.md similarity index 97% rename from docs/uds-runner/keyconcepts/wait.md rename to docs/uds-runner/wait.md index cf60b4b1..b043e4b2 100644 --- a/docs/uds-runner/keyconcepts/wait.md +++ b/docs/uds-runner/wait.md @@ -1,7 +1,7 @@ --- title: Wait type: docs -weight: 11 +weight: 5 --- The `wait` key function serves to halt the execution, effectively pausing the program until a specified resource becomes available. This resource could include anything from network responses to Kubernetes operations: From eacb62a750c340859c2c900e3340ef792e9f530e Mon Sep 17 00:00:00 2001 From: UnicornChance Date: Wed, 15 May 2024 13:39:42 -0600 Subject: [PATCH 04/26] images fix maybe --- docs/bundle-anatomy.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/bundle-anatomy.md b/docs/bundle-anatomy.md index 2e8ebc6a..bc4605e1 100644 --- a/docs/bundle-anatomy.md +++ b/docs/bundle-anatomy.md @@ -8,8 +8,3 @@ weight: 5 A UDS Bundle is an OCI artifact with the following form: {{ $image := resources.GetRemote "https://github.com/defenseunicorns/uds-cli/blob/main/docs/.images/uds-bundle.png" }} - -{{ $image := .Resources.GetMatch "sunset.jpg" }} -{{ with $image }} - -{{ end }} From 2e98a7cdf353306c733eb1b890416abeb37740d0 Mon Sep 17 00:00:00 2001 From: UnicornChance Date: Wed, 15 May 2024 13:53:47 -0600 Subject: [PATCH 05/26] revert changes to imag --- docs/bundle-anatomy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/bundle-anatomy.md b/docs/bundle-anatomy.md index bc4605e1..701a38f9 100644 --- a/docs/bundle-anatomy.md +++ b/docs/bundle-anatomy.md @@ -7,4 +7,4 @@ weight: 5 ## Bunble Anatomy A UDS Bundle is an OCI artifact with the following form: -{{ $image := resources.GetRemote "https://github.com/defenseunicorns/uds-cli/blob/main/docs/.images/uds-bundle.png" }} +![](https://github.com/defenseunicorns/uds-cli/blob/main/docs/.images/uds-bundle.png) From b6085412f86125d6835e5736d911ac2a3478051e Mon Sep 17 00:00:00 2001 From: UnicornChance Date: Wed, 15 May 2024 13:58:33 -0600 Subject: [PATCH 06/26] image fix --- docs/bundle-anatomy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/bundle-anatomy.md b/docs/bundle-anatomy.md index 701a38f9..19f9bb6c 100644 --- a/docs/bundle-anatomy.md +++ b/docs/bundle-anatomy.md @@ -7,4 +7,4 @@ weight: 5 ## Bunble Anatomy A UDS Bundle is an OCI artifact with the following form: -![](https://github.com/defenseunicorns/uds-cli/blob/main/docs/.images/uds-bundle.png) +![](https://github.com/defenseunicorns/uds-cli/blob/main/docs/.images/uds-bundle.png?raw=true) From 04698d0d937ab55ab07db864f85ff7a3e4b519d5 Mon Sep 17 00:00:00 2001 From: UnicornChance Date: Wed, 15 May 2024 16:08:17 -0600 Subject: [PATCH 07/26] fix: update ordering --- docs/bundle-anatomy.md | 2 +- docs/bundle-overrides/_index.md | 2 +- docs/uds-runner/_index.md | 34 ++++++++++++++++++++++++++++++--- 3 files changed, 33 insertions(+), 5 deletions(-) diff --git a/docs/bundle-anatomy.md b/docs/bundle-anatomy.md index 19f9bb6c..140b8e91 100644 --- a/docs/bundle-anatomy.md +++ b/docs/bundle-anatomy.md @@ -1,7 +1,7 @@ --- title: Bundle Anatomy type: docs -weight: 5 +weight: 6 --- ## Bunble Anatomy diff --git a/docs/bundle-overrides/_index.md b/docs/bundle-overrides/_index.md index 3aa514f5..19f684c9 100644 --- a/docs/bundle-overrides/_index.md +++ b/docs/bundle-overrides/_index.md @@ -1,7 +1,7 @@ --- title: Bundle Overrides Quickstart type: docs -weight: 4 +weight: 5 --- Consider the following `zarf.yaml` and `values.yaml` which deploys [`podinfo`](https://github.com/stefanprodan/podinfo) with a set of custom values: diff --git a/docs/uds-runner/_index.md b/docs/uds-runner/_index.md index 84725fa6..28eb9d8d 100644 --- a/docs/uds-runner/_index.md +++ b/docs/uds-runner/_index.md @@ -1,5 +1,33 @@ --- -title: Key Concepts +title: UDS Runner type: docs -weight: 1 ---- \ No newline at end of file +weight: 4 +--- + +The UDS Runner enables UDS Bundle developers to automate UDS builds and execute routine shell tasks. The UDS CLI contains vendors and configures the maru-runner build tool to support simple compiling and building of UDS Bundles. +Quickstart +Running a Task + +To run a task from a tasks.yaml execute the following command: + +uds run + +To run a task from a specific tasks file, execute the following command: + +uds run -f + +{{% alert-note %}} The maru documentation describes how to build the tasks.yaml files to configure the UDS Runner. {{% /alert-note %}} +Variables Set With Environment Variables + +When running a tasks.yaml with uds run my-task variables can be set using environment prefixed with UDS_. For example, running UDS_FOO=bar uds run echo-foo on the following task will echo bar: + +variables: + - name: FOO + default: foo +tasks: + - name: echo-foo + actions: + - cmd: echo ${FOO} + +No Zarf Dependency +Considering that the UDS CLI also vendors Zarf, there is no need to have Zarf installed on your system. \ No newline at end of file From 234f74ac081a8fa29cd3381d23b31497d77f3f8c Mon Sep 17 00:00:00 2001 From: UnicornChance Date: Thu, 16 May 2024 11:17:18 -0600 Subject: [PATCH 08/26] fix: add go.mod for docs dir --- docs/go.mod | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 docs/go.mod diff --git a/docs/go.mod b/docs/go.mod new file mode 100644 index 00000000..fe427fbb --- /dev/null +++ b/docs/go.mod @@ -0,0 +1,3 @@ +module github.com/defenseunicorns/uds-cli/docs + +go 1.20 \ No newline at end of file From ad0212b12f626046c0f1899bca817516139a6718 Mon Sep 17 00:00:00 2001 From: UnicornChance Date: Wed, 29 May 2024 08:12:41 -0600 Subject: [PATCH 09/26] fix: remove go mod in favor of git cloning --- docs/go.mod | 3 --- 1 file changed, 3 deletions(-) delete mode 100644 docs/go.mod diff --git a/docs/go.mod b/docs/go.mod deleted file mode 100644 index fe427fbb..00000000 --- a/docs/go.mod +++ /dev/null @@ -1,3 +0,0 @@ -module github.com/defenseunicorns/uds-cli/docs - -go 1.20 \ No newline at end of file From ec0c262daf05c08abdfacd79b1f1baffbb9c7c62 Mon Sep 17 00:00:00 2001 From: UnicornChance Date: Wed, 29 May 2024 15:33:25 -0600 Subject: [PATCH 10/26] fix: linting whitespace --- docs/_index.md | 1 - docs/uds-runner/_index.md | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/_index.md b/docs/_index.md index 0bdfd6fe..a2252ce0 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -10,4 +10,3 @@ menu: The [UDS CLI](https://github.com/defenseunicorns/uds-cli) is the primary interface for users to interact with various components within the UDS landscape. It streamlines the deployment process of mission applications and secure infrastructure, simplifying tasks involved in running mission applications while maintaining regulatory compliance in a unified and efficient manner. The UDS CLI simplifies deployment by bundling multiple Zarf Packages into a single deployable artifact. This process ensures that UDS Bundles, which encompass infrastructure, platform, and mission applications, can be efficiently deployed within any Mission Hero's system environment. Additionally, the UDS CLI extends its capabilities to Pepr, where multiple Pepr applications are bundled and deployed as a single Pepr Module to support UDS Bundles during runtime. - diff --git a/docs/uds-runner/_index.md b/docs/uds-runner/_index.md index 28eb9d8d..3299d28c 100644 --- a/docs/uds-runner/_index.md +++ b/docs/uds-runner/_index.md @@ -30,4 +30,4 @@ tasks: - cmd: echo ${FOO} No Zarf Dependency -Considering that the UDS CLI also vendors Zarf, there is no need to have Zarf installed on your system. \ No newline at end of file +Considering that the UDS CLI also vendors Zarf, there is no need to have Zarf installed on your system. From cd4208f41fd010d1849db34419424a7001e121ae Mon Sep 17 00:00:00 2001 From: unclegedd Date: Fri, 7 Jun 2024 10:11:05 -0500 Subject: [PATCH 11/26] WIP: removing runner subsections --- docs/runner.md | 59 -------------------- docs/uds-runner/_index.md | 53 ++++++++++++++---- docs/uds-runner/actions.md | 60 --------------------- docs/uds-runner/files.md | 25 --------- docs/uds-runner/includes.md | 25 --------- docs/uds-runner/task-inputs.md | 61 --------------------- docs/uds-runner/tasks.md | 52 ------------------ docs/uds-runner/variables-concepts.md | 77 --------------------------- docs/uds-runner/wait.md | 23 -------- 9 files changed, 42 insertions(+), 393 deletions(-) delete mode 100644 docs/uds-runner/actions.md delete mode 100644 docs/uds-runner/files.md delete mode 100644 docs/uds-runner/includes.md delete mode 100644 docs/uds-runner/task-inputs.md delete mode 100644 docs/uds-runner/tasks.md delete mode 100644 docs/uds-runner/variables-concepts.md delete mode 100644 docs/uds-runner/wait.md diff --git a/docs/runner.md b/docs/runner.md index db641c26..e69de29b 100644 --- a/docs/runner.md +++ b/docs/runner.md @@ -1,59 +0,0 @@ -# UDS Runner - -UDS CLI contains vendors and configures the [maru-runner](https://github.com/defenseunicorns/maru-runner) build tool to make compiling and building UDS bundles simple. - - -## Quickstart - -#### Running a Task -To run a task from a `tasks.yaml`: -``` -uds run -``` - -#### Running a Task from a specific tasks file -``` -uds run -f -``` - - -The Maru [docs](https://github.com/defenseunicorns/maru-runner) describe how to build `tasks.yaml` files to configure the runner. The functionality in UDS CLI is mostly identical with the following exceptions - -### Variables Set with Environment Variables -When running a `tasks.yaml` with `uds run my-task` you can set variables using environment prefixed with `UDS_` - -For example, running `UDS_FOO=bar uds run echo-foo` on the following task will echo `bar`. - -```yaml -variables: - - name: FOO - default: foo -tasks: - - name: echo-foo - actions: - - cmd: echo ${FOO} -``` - -### Running UDS and Zarf Commands -To run `uds` commands from within a task, you can invoke your system `uds` binary using the `./uds` syntax. Similarly, UDS CLI vendors Zarf, and tasks can run vendored Zarf commands using `./zarf`. For example: -```yaml -tasks: -- name: default - actions: - - cmd: ./uds inspect k3d-core-istio-dev:0.16.1 # uses system uds - - cmd: ./zarf tools kubectl get pods -A # uses vendored Zarf -``` - -### Architecture Environment Variable -When running tasks with `uds run`, there is a special `UDS_ARCH` environment variable accessible within tasks that is automatically set to your system architecture, but is also configurable with a `UDS_ARCHITECTURE` environmental variable. For example: -``` -tasks: -- name: print-arch - actions: - - cmd: echo ${UDS_ARCH} -``` -- Running `uds run print-arch` will echo your local system architecture -- Running `UDS_ARCHITECTURE=amd64 uds run print-arch` will echo "amd64" - -### No Dependency on Zarf -Since UDS CLI also vendors [Zarf](https://github.com/defenseunicorns/zarf), there is no need to also have Zarf installed on your system. diff --git a/docs/uds-runner/_index.md b/docs/uds-runner/_index.md index 3299d28c..37c2b8a1 100644 --- a/docs/uds-runner/_index.md +++ b/docs/uds-runner/_index.md @@ -3,24 +3,33 @@ title: UDS Runner type: docs weight: 4 --- +# UDS Runner -The UDS Runner enables UDS Bundle developers to automate UDS builds and execute routine shell tasks. The UDS CLI contains vendors and configures the maru-runner build tool to support simple compiling and building of UDS Bundles. -Quickstart -Running a Task +UDS CLI contains vendors and configures the [maru-runner](https://github.com/defenseunicorns/maru-runner) build tool to make compiling and building UDS bundles simple. -To run a task from a tasks.yaml execute the following command: -uds run +## Quickstart -To run a task from a specific tasks file, execute the following command: +#### Running a Task +To run a task from a `tasks.yaml`: +``` +uds run +``` +#### Running a Task from a specific tasks file +``` uds run -f +``` + + +The Maru [docs](https://github.com/defenseunicorns/maru-runner) describe how to build `tasks.yaml` files to configure the runner. The functionality in UDS CLI is mostly identical with the following exceptions -{{% alert-note %}} The maru documentation describes how to build the tasks.yaml files to configure the UDS Runner. {{% /alert-note %}} -Variables Set With Environment Variables +### Variables Set with Environment Variables +When running a `tasks.yaml` with `uds run my-task` you can set variables using environment prefixed with `UDS_` -When running a tasks.yaml with uds run my-task variables can be set using environment prefixed with UDS_. For example, running UDS_FOO=bar uds run echo-foo on the following task will echo bar: +For example, running `UDS_FOO=bar uds run echo-foo` on the following task will echo `bar`. +```yaml variables: - name: FOO default: foo @@ -28,6 +37,28 @@ tasks: - name: echo-foo actions: - cmd: echo ${FOO} +``` + +### Running UDS and Zarf Commands +To run `uds` commands from within a task, you can invoke your system `uds` binary using the `./uds` syntax. Similarly, UDS CLI vendors Zarf, and tasks can run vendored Zarf commands using `./zarf`. For example: +```yaml +tasks: +- name: default + actions: + - cmd: ./uds inspect k3d-core-istio-dev:0.16.1 # uses system uds + - cmd: ./zarf tools kubectl get pods -A # uses vendored Zarf +``` + +### Architecture Environment Variable +When running tasks with `uds run`, there is a special `UDS_ARCH` environment variable accessible within tasks that is automatically set to your system architecture, but is also configurable with a `UDS_ARCHITECTURE` environmental variable. For example: +``` +tasks: +- name: print-arch + actions: + - cmd: echo ${UDS_ARCH} +``` +- Running `uds run print-arch` will echo your local system architecture +- Running `UDS_ARCHITECTURE=amd64 uds run print-arch` will echo "amd64" -No Zarf Dependency -Considering that the UDS CLI also vendors Zarf, there is no need to have Zarf installed on your system. +### No Dependency on Zarf +Since UDS CLI also vendors [Zarf](https://github.com/defenseunicorns/zarf), there is no need to also have Zarf installed on your system. diff --git a/docs/uds-runner/actions.md b/docs/uds-runner/actions.md deleted file mode 100644 index d29de550..00000000 --- a/docs/uds-runner/actions.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Actions -type: docs -weight: 2 ---- - -Actions are the underlying operations that a task will perform. Each action under the `actions` key has a unique syntax. - -### Task - -A `task` can reference a task, thus making tasks composable: - -```yaml -tasks: - - name: foo - actions: - - task: bar - - name: bar - actions: - - task: baz - - name: baz - actions: - - cmd: "echo task foo is composed of task bar which is composed of task baz!" -``` - -In the example given above, the task named `foo` invokes a task labeled `bar`, which in turn triggers a task named `baz`. This `baz` task is responsible for outputting information to the console. - -### CMD - -Actions have the capability to execute arbitrary Bash commands, including in-line scripts. Additionally, the output of a command can be stored in a variable by utilizing the `setVariables` key: - -```yaml -tasks: - - name: foo - actions: - - cmd: echo -n 'dHdvIHdlZWtzIG5vIHByb2JsZW0=' | base64 -d - setVariables: - - name: FOO -``` - -This task will decode the base64 string and set the value as a variable named `FOO` that can be used in other tasks. - -Command blocks can have several other properties including: - -- `description`: description of the command. -- `mute`: boolean value to mute the output of a command. -- `dir`: the directory to run the command in. -- `env`: list of environment variables to run for this `cmd` block only: - -```yaml -tasks: - - name: foo - actions: - - cmd: echo ${BAR} - env: - - BAR=bar -``` - -- `maxRetries`: number of times to retry the command. -- `maxTotalSeconds`: max number of seconds the command can run until it is killed; takes precendence over `maxRetries`. diff --git a/docs/uds-runner/files.md b/docs/uds-runner/files.md deleted file mode 100644 index 352805af..00000000 --- a/docs/uds-runner/files.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Files -type: docs -weight: 4 ---- - -The `files` key is used to copy local or remote files to the current working directory: - -```yaml -tasks: - - name: copy-local - files: - - source: /tmp/foo - target: foo - - name: copy-remote - files: - - source: https://cataas.com/cat - target: cat.jpeg -``` - -`files` blocks can also use the following attributes: - -- `executable`: boolean value indicating if the file is executable. -- `shasum`: SHA string to verify the integrity of the file. -- `symlinks`: list of strings referring to symlink the file to. diff --git a/docs/uds-runner/includes.md b/docs/uds-runner/includes.md deleted file mode 100644 index 5f81cfc3..00000000 --- a/docs/uds-runner/includes.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Includes -type: docs -weight: 6 ---- - -The `includes` key serves the purpose of importing tasks from either local or remote task files. This functionality proves beneficial for sharing common tasks among various task files. When importing a task from a local task file, the path is relative to the current file. During task execution, both the tasks within the file and the `includes` tasks undergo processing to prevent any potential infinite loop references. This ensures a seamless and efficient task execution process: - -```yaml -includes: - - local: ./path/to/tasks-to-import.yaml - - remote: https://raw.githubusercontent.com/defenseunicorns/uds-cli/main/src/test/tasks/remote-import-tasks.yaml - -tasks: - - name: import-local - actions: - - task: local:some-local-task - - name: import-remote - actions: - - task: remote:echo-var -``` - -It's important to be aware that task files included in a project can also include additional task files. However, there is a specific constraint to consider: - -- If a task file includes a remote task file, it is crucial to note that the included remote task file cannot, in turn, include any local task files. diff --git a/docs/uds-runner/task-inputs.md b/docs/uds-runner/task-inputs.md deleted file mode 100644 index bf6c0bd8..00000000 --- a/docs/uds-runner/task-inputs.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Task Inputs and Reusable Tasks -type: docs -weight: 7 ---- - -While the expectation is for tasks to be reusable, there are instances where you may need to create a task that accommodates various inputs for reuse. To create such a versatile task, include an `inputs` key featuring a mapping of inputs to the task: - -```yaml -tasks: - - name: echo-var - inputs: - hello-input: - default: hello world - description: This is an input to the echo-var task - deprecated-input: - default: foo - description: this is a input from a previous version of this task - deprecatedMessage: this input is deprecated, use hello-input instead - actions: - # to use the input, reference it using INPUT_ in all caps - - cmd: echo $INPUT_HELLO_INPUT - - - name: use-echo-var - actions: - - task: echo-var - with: - # hello-input is the name of the input in the echo-var task, hello-unicorn is the value we want to pass in - hello-input: hello unicorn -``` - -In the provided example, the `echo-var` task is configured to receive an input named `hello-input` and display it on the console. It's worth noting that the `input` can be assigned a `default` value. Subsequently, the `use-echo-var` task invokes `echo-var` with an alternative input value, specified through the `with` key. In this example, the input `hello unicorn` is passed to the `hello-input` input. - -It's important to highlight the presence of the `deprecated-input` input, which comes with a `deprecatedMessage` attribute. This attribute serves the purpose of signaling that the input is deprecated and should be avoided. Should a task be executed with a deprecated input, a warning message will be printed to the console. - -### Templates - -When creating a task with `inputs` you can use [Go templates](https://pkg.go.dev/text/template#hdr-Functions) in that task's `actions`. For example: - -```yaml -tasks: - - name: length-of-inputs - inputs: - hello-input: - default: hello world - description: This is an input to the echo-var task - another-input: - default: another world - actions: - # index and len are go template functions, while .inputs is map representing the inputs to the task - - cmd: echo ${{ index .inputs "hello-input" | len }} - - cmd: echo ${{ index .inputs "another-input" | len }} - - - name: len - actions: - - task: length-of-inputs - with: - hello-input: hello unicorn -``` - -Running `uds run len` will print the length of the inputs to `hello-input` and `another-input` to the console. diff --git a/docs/uds-runner/tasks.md b/docs/uds-runner/tasks.md deleted file mode 100644 index 2cb8f20a..00000000 --- a/docs/uds-runner/tasks.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Tasks -type: docs -weight: 1 ---- - -Tasks serve as the foundational components of the UDS Runner, defining the operations to be executed. Within the `tasks.yaml` file, the `tasks` key at the root level delineates a list of tasks scheduled for execution. The specific operations carried out by each task are detailed under the `actions` key: - -```yaml -tasks: - - name: all-the-tasks - actions: - - task: make-build-dir - - task: install-deps -``` - -In the above example, the name of the task is "all-the-tasks", and it is composed of multiple sub-tasks to run. These sub-tasks would also be defined in the list of `tasks`: - -```yaml -tasks: - - name: default - actions: - - cmd: echo "run default task" - - - name: all-the-tasks - actions: - - task: make-build-dir - - task: install-deps - - - name: make-build-dir - actions: - - cmd: mkdir -p build - - - name: install-deps - actions: - - cmd: go mod tidy -``` - -Using the UDS CLI, these tasks can be run individually: - -```cli -uds run all-the-tasks # runs all-the-tasks, which calls make-build-dir and install-deps -uds run make-build-dir # only runs make-build-dir -``` - -### Default Tasks - -In the provided example above, there is a special type of task known as the default task. This task is optional and can be used as the common entry point for your tasks. When attempting to execute the `default` task, you can exclude the task name from the run command: - -```cli -uds run -``` diff --git a/docs/uds-runner/variables-concepts.md b/docs/uds-runner/variables-concepts.md deleted file mode 100644 index 8105be15..00000000 --- a/docs/uds-runner/variables-concepts.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Variables -type: docs -weight: 3 ---- - -Variables can be defined in several ways: - -- At the top of the `tasks.yaml`: - -```yaml -variables: - - name: FOO - default: foo - -tasks: ... -``` - -- As the output of a `cmd`: - -```yaml -variables: - - name: FOO - default: foo -tasks: - - name: foo - actions: - - cmd: uname -m - mute: true - setVariables: - - name: FOO - - cmd: echo ${FOO} -``` - -- As an environment variable, it is recommended to prefix them with `UDS_`. In the given example, creating an environment variable `UDS_FOO=bar` would result in the `FOO` variable being set to `bar`. -- Using the `--set` flag in the CLI: - -```cli -uds run foo --set FOO=bar -``` - -To use a variable, reference it using `${VAR_NAME}` - -Note that variables also have the following attributes when setting them with YAML: - -- `sensitive`: boolean value indicating if a variable should be visible in output. -- `default`: default value of a variable. - - In the provided example, if the variable `FOO` lacks a default value and you set the environment variable `UDS_FOO=bar`, the default value will be configured as `bar`. - -### Environment Variable Files - -To incorporate a file containing environment variables into a task and load them for use, utilize the `envPath` key within the task configuration. This key facilitates the loading of all environment variables from the specified file into both the task being invoked and its subsequent child tasks: - -```yaml -tasks: - - name: env - actions: - - cmd: echo $FOO - - cmd: echo $UDS_ARCH - - task: echo-env - - name: echo-env - envPath: ./path/to/.env - actions: - - cmd: echo different task $FOO -``` - -### Variable Precendence - -Variable precedence is as follows, from least to most specific: - -- Variable defaults set in YAML. -- Environment variables prefixed with `UDS_`. -- Variables set with the `--set` flag in the CLI. - -{{% alert-note %}} -Variables established using the `--set` flag take precedence over variables from all other outlined sources. -{{% /alert-note %}} diff --git a/docs/uds-runner/wait.md b/docs/uds-runner/wait.md deleted file mode 100644 index b043e4b2..00000000 --- a/docs/uds-runner/wait.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Wait -type: docs -weight: 5 ---- - -The `wait` key function serves to halt the execution, effectively pausing the program until a specified resource becomes available. This resource could include anything from network responses to Kubernetes operations: - -```yaml -tasks: - - name: network-response - wait: - network: - protocol: https - address: 1.1.1.1 - code: 200 - - name: configmap-creation - wait: - cluster: - kind: configmap - name: simple-configmap - namespace: foo -``` From b23a227c8248225c2eba07bfdf84f7e8dc5c9cbb Mon Sep 17 00:00:00 2001 From: unclegedd Date: Fri, 7 Jun 2024 10:17:43 -0500 Subject: [PATCH 12/26] WIP: remove runner title --- docs/uds-runner/_index.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/uds-runner/_index.md b/docs/uds-runner/_index.md index 37c2b8a1..6b7debd6 100644 --- a/docs/uds-runner/_index.md +++ b/docs/uds-runner/_index.md @@ -3,8 +3,6 @@ title: UDS Runner type: docs weight: 4 --- -# UDS Runner - UDS CLI contains vendors and configures the [maru-runner](https://github.com/defenseunicorns/maru-runner) build tool to make compiling and building UDS bundles simple. From d1be87baf26e147c9177e85a4c1116fe2865e751 Mon Sep 17 00:00:00 2001 From: unclegedd Date: Fri, 7 Jun 2024 10:33:50 -0500 Subject: [PATCH 13/26] WIP: add quickstart --- docs/installation.md | 170 ----------------------- docs/quickstart.md | 321 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 321 insertions(+), 170 deletions(-) delete mode 100644 docs/installation.md create mode 100644 docs/quickstart.md diff --git a/docs/installation.md b/docs/installation.md deleted file mode 100644 index 84857cfb..00000000 --- a/docs/installation.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Quickstart Guide -type: docs -weight: 1 ---- - -## Install UDS CLI - -Homebrew is the recommended installation method: - -```git -brew tap defenseunicorns/tap && brew install uds -``` - -{{% alert-note %}} -Please note that UDS CLI Binaries are also included with each [GitHub release.](https://github.com/defenseunicorns/uds-cli/releases) -{{% /alert-note %}} - -## Quickstart Guide - -The UDS-CLI's primary feature is the ability to deploy multiple, independent Zarf Packages. To create a `UDSBundle` containing Zarf Packages, you can use the following `uds-bundle.yaml` file as a template: - -```yaml -kind: UDSBundle -metadata: - name: example - description: an example UDS bundle - version: 0.0.1 - -packages: - - name: init - repository: ghcr.io/defenseunicorns/packages/init - ref: v0.33.0 - optionalComponents: - - git-server - - name: podinfo - repository: ghcr.io/defenseunicorns/uds-cli/podinfo - ref: 0.0.1 -``` - -In this example, the `UDSBundle` named "example" deploys the Zarf Init Package and Podinfo. The packages listed under the `packages` section can be sourced either locally or from an OCI registry. Please see this [comprehensive example](https://github.com/defenseunicorns/uds-cli/blob/main/src/test/bundles/03-local-and-remote/uds-bundle.yaml) deploying both local and remote Zarf Packages. Additional `UDSBundle` examples can be explored in the [`src/test/bundles`](https://github.com/defenseunicorns/uds-cli/tree/main/src/test/bundles) folder. - -### Declarative Syntax - -The syntax of a `uds-bundle.yaml` file is entirely declarative. As a result, the UDS CLI does not prompt users to deploy optional components included in a Zarf Package. If there is a desire to deploy an optional Zarf component, it must be explicitly specified within the `optionalComponents` key of a specific `package`. - -### UDS Support - -When utilizing the UDS CLI for `deploy`, `inspect`, `remove`, and `pull` commands, the tool incorporates shorthand functionality for streamlined interaction with the Defense Unicorns organization on the GitHub Container Registry (GHCR). By default, paths are automatically expanded to the Defense Unicorns organization on GHCR, unless otherwise specified. For example: - -`uds deploy unicorn-bundle:v0.1.0` is functionally equivalent to `uds deploy ghcr.io/defenseunicorns/packages/uds/bundles/unicorn-bundle:v0.1.0` - -The matching and expansion of bundles is ordered as follows: - -1. Local with a `tar.zst` extension. -2. Remote path: `oci://ghcr.io/defenseunicorns/packages/uds/bundles/`. -3. Remote path: `oci://ghcr.io/defenseunicorns/packages/delivery/`. -4. Remote path: `oci://ghcr.io/defenseunicorns/packages/`. - -If the bundle is not local, the UDS CLI will sequentially check path 2, path 3, and so forth, for the remote bundle artifact. This behavior can be overridden by explicitly specifying the full path to the bundle artifact, as demonstrated in the example: `uds deploy ghcr.io/defenseunicorns/dev/path/dev-bundle:v0.1.0`. - -### Bundle Create - -The `uds create` command pulls the necessary Zarf Packages from the registry and bundles them into an OCI artifact. - -There are two ways to create UDS Bundles: - -- Inside an OCI registry: `uds create -o ghcr.io/defenseunicorns/dev`. -- Locally on your filesystem: `uds create `. - -{{% alert-note %}} -The `--insecure` flag is necessary when engaging with a local registry; however, it is not required when operating with secure, remote registries such as GHCR. -{{% /alert-note %}} - -### Bundle Deploy - -The `uds deploy` command deploys the UDS Bundle. - -There are two ways to deploy UDS Bundles: - -- From an OCI registry: `uds deploy ghcr.io/defenseunicorns/dev/:`. -- From your local filesystem: `uds deploy uds-bundle-.tar.zst`. - -#### Specifying Packages Using `--packages` - -By default, the deployment process includes all packages within the specified bundle. However, you have the option to selectively deploy specific packages from the bundle using the `--packages` flag. - -For example: `uds deploy uds-bundle-.tar.zst --packages init,nginx`. - -In this example, only the `init` and `nginx` packages from the specified bundle will be deployed. - -#### Resuming Bundle Deploys Using `--resume` - -By default, the deployment process includes all packages within the bundle, irrespective of whether they have been previously deployed. However, users have the option to selectively deploy only those packages that have not been deployed before, achieved by utilizing the `--resume` flag. - -For example: `uds deploy uds-bundle-.tar.zst --resume`. - -This command signifies a deployment operation where only the packages within the specified bundle that have not been deployed previously will be processed. - -### Bundle Inspect - -The `uds inspect` command inspects the `uds-bundle.yaml` of a bundle. - -There are two ways to inspect UDS Bundles: - -- From an OCI registry: `uds inspect oci://ghcr.io/defenseunicorns/dev/:`. -- From your local filesystem: `uds inspect uds-bundle-.tar.zst`. - -#### Viewing Software Bill of Materials (SBOM) - -The `uds inspect` command offers two additional flags for extracting and viewing the SBOM: - -- To output the SBOM as a tar file, use: `uds inspect ... --sbom`. -- To output the SBOM into a directory as individual files, use: `uds inspect ... --sbom --extract`. - -This functionality utilizes the `sboms.tar` within the underlying Zarf Packages to generate a new artifact named `bundle-sboms.tar`. This artifact consolidates all SBOMs from the Zarf Packages within the bundle. - -### Bundle Publish - -To publish local bundles to an OCI registry, utilize the following command format: `uds publish .tar.zst oci://`. - -For example: `uds publish uds-bundle-example-arm64-0.0.1.tar.zst oci://ghcr.io/github_user`. - -### Bundle Remove - -The `uds remove` command will remove the UDS Bundle. - -There are two ways to remove UDS Bundles: - -- From an OCI registry: `uds remove oci://ghcr.io/defenseunicorns/dev/: --confirm`. -- From your local filesystem: `uds remove uds-bundle-.tar.zst --confirm`. - -By default, the removal operation targets all packages within the bundle. However, users have the flexibility to selectively remove specific packages from the bundle by employing the `--packages` flag. - -For instance, the following command removes only the `init` and `nginx` packages from the bundle: `uds remove uds-bundle-.tar.zst --packages init,nginx`. - -### Logs - -The `uds logs` command can be used to view the most recent logs of a bundle operation. - -{{% alert-note %}} -Depending on your OS temporary directory and file settings, recent logs are purged after a certain amount of time, so this command may return an error if the logs are no longer available. Currently, `uds logs` is compatible only with `uds deploy`. While it may function with other operations, compatibility is not guaranteed. -{{% /alert-note %}} - -## Zarf Integration - -The UDS CLI incorporates a vendored version of Zarf within its binary distribution. To leverage the Zarf functionality, execute the command `uds zarf `. For instance, to generate a Zarf Package, run the command `uds zarf package create `. Similarly, for utilizing the [air gap toolset](https://docs.zarf.dev/commands/zarf_tools/) provided by Zarf, execute `uds zarf tools `. - -### Development Mode - -In development mode, you can accelerate development and testing cycles for UDS Bundles. The `uds dev deploy` command facilitates the deployment of a UDS Bundle in development mode. If a local Zarf Package is missing, this command will generate the required Zarf Package for you, assuming that both the `zarf.yaml` file and the Zarf Package are located in the same directory. Additionally, it will create your bundle and deploy the Zarf Packages in [`YOLO`](https://docs.zarf.dev/faq#what-is-yolo-mode-and-why-would-i-use-it) mode, eliminating the need to execute `zarf init`. - -{{% alert-note %}} -Currently, development mode only works with local bundles. -{{% /alert-note %}} - -## Bundle Architecture and Multi-Arch Support - -There are several ways to specify the architecture of a bundle: - -- Setting `--architecture` or `-a` flag during `uds ...` operations: `uds create --architecture arm64`. -- Setting the `metadata.architecture` key in a `uds-bundle.yaml`. -- Setting a `UDS_ARCHITECTURE` environment variable. -- Setting the `options.architecture` key in a `uds-config.yaml`. - -{{% alert-note %}} -Setting the `--architecture` flag takes precedence over all other methods of specifying the architecture. -{{% /alert-note %}} - -UDS CLI supports multi-arch bundles. This means you can push bundles with different architectures to the same remote OCI repository, at the same tag. For example, you can push both an `amd64` and `arm64` bundle to `ghcr.io//:0.0.1`. diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 00000000..4d99455d --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,321 @@ +--- +title: Quickstart Guide +type: docs +weight: 1 +--- + +## Install +Recommended installation method is with Brew: +``` +brew tap defenseunicorns/tap && brew install uds +``` +UDS CLI Binaries are also included with each [Github Release](https://github.com/defenseunicorns/uds-cli/releases) + +## Contributing +Build instructions and contributing docs are located in [CONTRIBUTING.md](CONTRIBUTING.md). + +## Quickstart +The UDS-CLI's flagship feature is deploying multiple, independent Zarf packages. To create a `UDSBundle` of Zarf packages, create a `uds-bundle.yaml` file like so: + +```yaml +kind: UDSBundle +metadata: + name: example + description: an example UDS bundle + version: 0.0.1 + +packages: + - name: init + repository: ghcr.io/defenseunicorns/packages/init + ref: v0.33.0 + optionalComponents: + - git-server + - name: podinfo + repository: ghcr.io/defenseunicorns/uds-cli/podinfo + ref: 0.0.1 +``` +The above `UDSBundle` deploys the Zarf init package and podinfo. + +The packages referenced in `packages` can exist either locally or in an OCI registry. See [here](src/test/packages/03-local-and-remote) for an example that deploys both local and remote Zarf packages. More `UDSBundle` examples can be found in the [src/test/bundles](src/test/bundles) folder. + +#### Declarative Syntax +The syntax of a `uds-bundle.yaml` is entirely declarative. As a result, the UDS CLI will not prompt users to deploy optional components in a Zarf package. If you want to deploy an optional Zarf component, it must be specified in the `optionalComponents` key of a particular `package`. + +#### First-class UDS Support +When running `deploy`,`inspect`,`remove`, and `pull` commands, UDS CLI contains shorthand for interacting with the Defense Unicorns org on GHCR. Specifically, unless otherwise specified, paths will automatically be expanded to the Defense Unicorns org on GHCR. For example: +- `uds deploy unicorn-bundle:v0.1.0` is equivalent to `uds deploy ghcr.io/defenseunicorns/packages/uds/bundles/unicorn-bundle:v0.1.0` + +The bundle matching and expansion is ordered as follows: +1. Local with a `tar.zst` extension +2. Remote path: `oci://ghcr.io/defenseunicorns/packages/uds/bundles/` +3. Remote path: `oci://ghcr.io/defenseunicorns/packages/delivery/` +4. Remote path: `oci://ghcr.io/defenseunicorns/packages/` + +That is to say, if the bundle is not local, UDS CLI will check path 2, path 3, etc for the remote bundle artifact. This behavior can be overriden by specifying the full path to the bundle artifact, for example `uds deploy ghcr.io/defenseunicorns/dev/path/dev-bundle:v0.1.0`. + +### Bundle Create +Pulls the Zarf packages from the registry and bundles them into an OCI artifact. + +There are 2 ways to create Bundles: +1. Inside an OCI registry: `uds create -o ghcr.io/defenseunicorns/dev` +1. Locally on your filesystem: `uds create ` + +> [!NOTE] +> The `--insecure` flag is necessary when interacting with a local registry, but not from secure, remote registries such as GHCR. + +### Bundle Deploy +Deploys the bundle + +There are 2 ways to deploy Bundles: +1. From an OCI registry: `uds deploy ghcr.io/defenseunicorns/dev/:` +1. From your local filesystem: `uds deploy uds-bundle-.tar.zst` + +#### Specifying Packages using `--packages` +By default all the packages in the bundle are deployed, but you can also deploy only certain packages in the bundle by using the `--packages` flag. + +As an example: `uds deploy uds-bundle-.tar.zst --packages init,nginx` + +#### Resuming Bundle Deploys using `--resume` +By default all the packages in the bundle are deployed, regardless of if they have already been deployed, but you can also choose to only deploy packages that have not already been deployed by using the `--resume` flag + +As an example: `uds deploy uds-bundle-.tar.zst --resume` + +### Bundle Inspect +Inspect the `uds-bundle.yaml` of a bundle +1. From an OCI registry: `uds inspect oci://ghcr.io/defenseunicorns/dev/:` +1. From your local filesystem: `uds inspect uds-bundle-.tar.zst` + +#### Viewing Images in a Bundle +It is possible derive images from a `uds-bundle.yaml`. This can be useful for situations where you need to know what images will be bundled before you actually create the bundle. This is accomplished with the `--list-images`. For example: + +`uds inspect ./uds-bundle.yaml --list-images` + +This command will return a list of images derived from the bundle's packages and taking into account optional and required package components. + +#### Viewing SBOMs +There are 2 additional flags for the `uds inspect` command you can use to extract and view SBOMs: +- Output the SBOMs as a tar file: `uds inspect ... --sbom` +- Output SBOMs into a directory as files: `uds inspect ... --sbom --extract` + +This functionality will use the `sboms.tar` of the underlying Zarf packages to create new a `bundle-sboms.tar` artifact containing all SBOMs from the Zarf packages in the bundle. + +### Bundle Publish +Local bundles can be published to an OCI registry like so: +`uds publish .tar.zst oci:// ` + +As an example: `uds publish uds-bundle-example-arm64-0.0.1.tar.zst oci://ghcr.io/github_user` + +### Bundle Remove +Removes the bundle + +There are 2 ways to remove Bundles: +1. From an OCI registry: `uds remove oci://ghcr.io/defenseunicorns/dev/: --confirm` +1. From your local filesystem: `uds remove uds-bundle-.tar.zst --confirm` + +By default all the packages in the bundle are removed, but you can also remove only certain packages in the bundle by using the `--packages` flag. + +As an example: `uds remove uds-bundle-.tar.zst --packages init,nginx` + +### Logs + +> [!NOTE] +> Only works with `uds deploy` for now, may work for other operations but isn't guaranteed. + +The `uds logs` command can be used to view the most recent logs of a bundle operation. Note that depending on your OS temporary directory and file settings, recent logs are purged after a certain amount of time, so this command may return an error if the logs are no longer available. + +## Bundle Architecture and Multi-Arch Support +There are several ways to specify the architecture of a bundle according to the following precedence: +1. Setting `--architecture` or `-a` flag during `uds ...` operations: `uds create --architecture arm64` +2. Setting a `UDS_ARCHITECTURE` environment variable +3. Setting the `options.architecture` key in a `uds-config.yaml` +4. Setting the `metadata.architecture` key in a `uds-bundle.yaml` + +This means that setting the `--architecture` flag takes precedence over all other methods of specifying the architecture. + +UDS CLI supports multi-arch bundles. This means you can push bundles with different architectures to the same remote OCI repository, at the same tag. For example, you can push both an `amd64` and `arm64` bundle to `ghcr.io//:0.0.1`. + +### Architecture Validation +When deploying a local bundle, the bundle's architecture will be used for comparison against the cluster architecture to ensure compatability. If deploying a remote bundle, by default the bundle is pulled based on system architecture, which is then checked against the cluster. + +> [!NOTE] +> It is possible to override the bundle architecture used at validation time by using the `--architecture` / `-a` flag. + +If, for example, you have a multi-arch remote bundle that you want to deploy from an arm64 machine to an amd64 cluster, the validation with fail because the system arch does not match the cluster arch. However, you can pull the correct bundle version by specificying the arch with the command line architecture flag. + +e.g. +`uds deploy -a amd64 --confirm` + +## Configuration +The UDS CLI can be configured with a `uds-config.yaml` file. This file can be placed in the current working directory or specified with an environment variable called `UDS_CONFIG`. The basic structure of the `uds-config.yaml` is as follows: +```yaml +options: + log_level: debug + architecture: arm64 + no_log_file: false + no_progress: false + uds_cache: /tmp/uds-cache + tmp_dir: /tmp/tmp_dir + insecure: false + oci_concurrency: 3 + +shared: + domain: uds.dev # shared across all packages in a bundle + +variables: + my-zarf-package: # name of Zarf package + ui_color: green # key is not case sensitive and refers to name of Zarf variable + UI_MSG: "Hello Unicorn" + hosts: # variables can be complex types such as lists and maps + - host: burning.boats + paths: + - path: "/" + pathType: "Prefix" +``` +The `options` key contains UDS CLI options that are not specific to a particular Zarf package. The `variables` key contains variables that are specific to a particular Zarf package. If you want to share insensitive variables across multiple Zarf packages, you can use the `shared` key, where the key is the variable name and the value is the variable value. + +## Sharing Variables +### Importing/Exporting Variables +Zarf package variables can be passed between Zarf packages: +```yaml +kind: UDSBundle +metadata: + name: simple-vars + description: show how vars work + version: 0.0.1 + +packages: + - name: output-var + repository: localhost:888/output-var + ref: 0.0.1 + exports: + - name: OUTPUT + - name: receive-var + repository: localhost:888/receive-var + ref: 0.0.1 + imports: + - name: OUTPUT + package: output-var +``` + +Variables that you want to make available to other packages are in the `export` block of the Zarf package to export a variable from. By default, all exported variables are available to all of the packages in a bundle. To have another package ingest a specific exported variable, like in the case of variable name collisions, use the `imports` key to name both the `variable` and `package` that the variable is exported from, like in the example above. + +In the example above, the `OUTPUT` variable is created as part of a Zarf Action in the [output-var](src/test/packages/zarf/no-cluster/output-var) package, and the [receive-var](src/test/packages/zarf/no-cluster/receive-var) package expects a variable called `OUTPUT`. + +### Sharing Variables Across Multiple Packages +If a Zarf variable has the same name in multiple packages and you don't want to set it multiple times via the import/export syntax, you can set an environment variable prefixed with `UDS_` and it will be applied to all the Zarf packages in a bundle. For example, if multiple packages require a `DOMAIN` variable, you could set it once with a `UDS_DOMAIN` environment variable and it would be applied to all packages. Note that this can also be done with the `shared` key in the `uds-config.yaml` file. + +On deploy, you can also set package variables by using the `--set` flag. If the package name isn't included in the key +(example: `--set super=true`) the variable will get applied to all of the packages. If the package name is included in the key (example: `--set cool-package.super=true`) the variable will only get applied to that package. + +### Variable Precedence and Specificity +In a bundle, variables can come from 4 sources. Those sources and their precedence are shown below in order of least to most specificity: +- Variables declared in a Zarf pkg +- Variables `import`'ed from a bundle package's `export` +- Variables configured in the `shared` key in a `uds-config.yaml` +- Variables configured in the `variables` key in a `uds-config.yaml` +- Variables set with an environment variable prefixed with `UDS_` (ex. `UDS_OUTPUT`) +- Variables set using the `--set` flag when running the `uds deploy` command + +That is to say, variables set using the `--set` flag take precedence over all other variable sources. + + +## Duplicate Packages And Naming + +It is possible to deploy multiple instances of the same Zarf package in a bundle. For example, the following `uds-bundle.yaml` deploys 3 instances of the [helm-overrides](src/test/packages/helm/zarf.yaml) Zarf packags: +```yaml +kind: UDSBundle +metadata: + name: duplicates + description: testing a bundle with duplicate packages in specified namespaces + version: 0.0.1 + +packages: + - name: helm-overrides + repository: localhost:5000/helm-overrides + ref: 0.0.1 + overrides: + podinfo-component: + unicorn-podinfo: # name of Helm chart + namespace: podinfo-ns + + # note the unique name and namespace + - name: helm-overrides-duplicate + repository: localhost:5000/helm-overrides + ref: 0.0.1 + overrides: + podinfo-component: + unicorn-podinfo: + namespace: another-podinfo-ns + + # note the unique name, namespace and the path to the Zarf package tarball + - name: helm-overrides-local-duplicate + path: src/test/packages/helm/zarf-package-helm-overrides-arm64-0.0.1.tar.zst + ref: 0.0.1 + overrides: + podinfo-component: + unicorn-podinfo: + namespace: yet-another-podinfo-ns +``` + +The naming conventions for deploying duplicate packages are as follows: +1. The `name` field of the package in the `uds-bundle.yaml` must be unique +1. The duplicate packages must be deployed in different namespaces +1. In order to deploy duplicates of local packages, the `path` field must point to a Zarf package tarball instead of to a folder. + +> [!NOTE] +> Today the duplicate packages feature is only supported for packages with Helm charts. This is because Helm charts' [namespaces can be overridden](docs/overrides.md#namespace) at deploy time. + +## Zarf Integration +UDS CLI includes a vendored version of Zarf inside of its binary. To use Zarf, simply run `uds zarf `. For example, to create a Zarf package, run `uds zarf create `, or to use the [airgap tooling](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_tools) that Zarf provides, run `uds zarf tools `. + +## Dev Mode + +> [!NOTE] +> Dev mode is a BETA feature + +Dev mode facilitates faster dev cycles when developing and testing bundles + +``` +uds dev deploy | +``` + +The `dev deploy` command performs the following operations + +- If local bundle: Creates Zarf packages for all local packages in a bundle + - Creates the Zarf tarball in the same directory as the `zarf.yaml` + - Will only create the Zarf tarball if one does not already exist + - Ignores any `kind: ZarfInitConfig` packages in the bundle + - Creates a bundle from the newly created Zarf packages +- Deploys the bundle in [YOLO](https://docs.zarf.dev/faq/#what-is-yolo-mode-and-why-would-i-use-it) mode, eliminating the need to do a `zarf init` + +## Scan + +> [!NOTE] +> Scan is an ALPHA feature. +> Trivy is a prerequisite for scanning container images and filesystem for vulnerabilities. You can find more information and installation instructions at [Trivy's official documentation](https://aquasecurity.github.io/trivy). + + +The `scan` command is used to scan a Zarf package for vulnerabilities and generate a report. This command is currently in ALPHA. + +### Usage + +To use the `scan` command, run: + +```sh +uds scan --org --package-name --tag [options] +``` + +### Required Parameters +- `--org` or `-o`: Organization name (default: `defenseunicorns`) +- `--package-name` or `-n`: Name of the package (e.g., `packages/uds/gitlab-runner`) +- `--tag` or `-g`: Tag name (e.g., `16.10.0-uds.0-upstream`) +- `--output-file` or `-f`: Output file for CSV results + +### Optional Parameters +- `--docker-username` or `-u`: Docker username for registry access, accepts CSV values +- `--docker-password` or `-p`: Docker password for registry access, accepts CSV values + +### Example Usage +```sh +uds scan -o defenseunicorns -n packages/uds/gitlab-runner -g 16.10.0-uds.0-upstream -u docker-username -p docker-password -f gitlab-runner.csv +``` From 8392cefa87877543cf79ee604bcd20e4a0ac490e Mon Sep 17 00:00:00 2001 From: unclegedd Date: Fri, 7 Jun 2024 10:36:11 -0500 Subject: [PATCH 14/26] WIP: add overrides --- docs/bundle-overrides/_index.md | 251 ++++++++++++++++++++++++++++- docs/bundle-overrides/overrides.md | 170 ------------------- 2 files changed, 246 insertions(+), 175 deletions(-) delete mode 100644 docs/bundle-overrides/overrides.md diff --git a/docs/bundle-overrides/_index.md b/docs/bundle-overrides/_index.md index 19f684c9..7fcfa93e 100644 --- a/docs/bundle-overrides/_index.md +++ b/docs/bundle-overrides/_index.md @@ -1,10 +1,15 @@ --- -title: Bundle Overrides Quickstart +title: Bundle Overrides type: docs weight: 5 --- -Consider the following `zarf.yaml` and `values.yaml` which deploys [`podinfo`](https://github.com/stefanprodan/podinfo) with a set of custom values: +Bundle overrides provide a mechanism to customize Helm charts inside of Zarf packages. + +## Quickstart + +Consider the following `zarf.yaml` and `values.yaml` which deploys [podinfo](https://github.com/stefanprodan/podinfo) +with a couple of custom values: ```yaml # zarf.yaml @@ -33,8 +38,7 @@ ui: color: blue ``` -The bundle overrides feature allows users to override the values specified in Zarf Packages: - +The bundle overrides feature allows users to override the values specified in Zarf packages. For example: ```yaml kind: UDSBundle metadata: @@ -50,6 +54,8 @@ packages: overrides: helm-overrides-component: podinfo: + valuesFiles: + - file: values.yaml values: - path: "replicaCount" value: 2 @@ -60,10 +66,245 @@ packages: default: "purple" ``` -This bundle facilitates the deployment of the `helm-overrides-package` Zarf Package while offering the ability to override specific values, such as `replicaCount` and `ui.color`, within the `podinfo` chart. Once the bundle has been created, these values remain immutable. However, during deployment, users have the flexibility to override variables such as `UI_COLOR` by either utilizing an environment variable named `UDS_UI_COLOR` or by explicitly specifying the override in a `uds-config.yaml` file, as demonstrated below: +```yaml +#values.yaml +podAnnotations: + customAnnotation: "customValue" +``` + +This bundle will deploy the `helm-overrides-package` Zarf package and override the `replicaCount`, `ui.color`, and `podAnnotations` values in the `podinfo` chart. The `values` can't be modified after the bundle has been created. However, at deploy time, users can override the `UI_COLOR` and other `variables` using a environment variable called `UDS_UI_COLOR` or by specifying it in a `uds-config.yaml` like so: ```yaml variables: helm-overrides-package: UI_COLOR: green ``` + +## Overrides + +### Syntax + +Consider the following bundle `overrides`: + +```yaml +packages: + - name: helm-overrides-package + path: "path/to/pkg" + ref: 0.0.1 + + overrides: + helm-overrides-component: # component name inside of the helm-overrides-package Zarf pkg + podinfo: # chart name from the helm-overrides-component component + valuesFiles: + - file: values.yaml + values: + - path: "replicaCount" + value: 2 + variables: + - name: UI_COLOR + path: "ui.color" + description: "Set the color for podinfo's UI" + default: "purple" +``` + +```yaml +#values.yaml +podAnnotations: + customAnnotation: "customValue" +``` +In this example, the `helm-overrides-package` Zarf package has a component called `helm-overrides-component` which contains a Helm chart called `podinfo`; note how these names are keys in the `overrides` block. The `podinfo` chart has a `replicaCount` value that is overridden to `2`, a `podAnnotations` value that is overridden to include `customAnnotation: "customValue"` and a variable called `UI_COLOR` that is overridden to `purple`. + +### Values Files + +The `valuesFiles` in an `overrides` block are a list of `file`'s. It allows users to override multiple values in a Zarf package component's underlying Helm chart, by providing a file with those values instead of having to include them all indiviually in the `overrides` block. + +### Values + +The `values` in an `overrides` block are a list of `path` and `value` pairs. They allow users to override values in a Zarf package component's underlying Helm chart. Note that values are specified by bundle authors and **cannot be modified** after the bundle has been created. + +#### Path + +The `path` uses dot notation to specify the location of a value to override in the underlying Helm chart. For example, the `replicaCount` path in the `podinfo` chart is located at the top-level of the [podinfo values.yaml](https://github.com/stefanprodan/podinfo/blob/master/charts/podinfo/values.yaml), so the path is simply `replicaCount`, while the `ui.color` path is located under the `ui` key, so the path is `ui.color`. + +#### Value + +The `value` is the value to set at the `path`. Values can be simple values such as numbers and strings, as well as, complex lists and objects, for example: +```yaml +... + overrides: + helm-overrides-component: + podinfo: + values: + - path: "podinfo.tolerations" + value: + - key: "unicorn" + operator: "Equal" + value: "defense" + effect: "NoSchedule" + - path: podinfo.podAnnotations + value: + customAnnotation: "customValue" +``` +If using a variable that has been [exported](../README.md#importingexporting-variables) from another package, that variable can also be used to set a value, using the syntax `${...}`. In the example below the `COLOR` variable is being used to set the `podinfo.ui.color` value. +```yaml +kind: UDSBundle +metadata: + name: example-bundle + description: Example for using an imported variable to set an overrides value + version: 0.0.1 + +packages: + - name: output-var + repository: localhost:888/output-var + ref: 0.0.1 + exports: + - name: COLOR + + - name: helm-overrides-package + path: "../../packages/helm" + ref: 0.0.1 + + overrides: + podinfo-component: + unicorn-podinfo: + values: + - path: "podinfo.replicaCount" + value: 1 + - path: "podinfo.ui.color" + value: ${COLOR} +``` + +#### Value Precedence +Value precedence is as follows: +1. The `values` in an `overrides` block +1. `values` set in the last `valuesFile` (if more than one specified) +1. `values` set in the previous `valuesFile` (if more than one specified) + +### Variables +Variables are similar to [values](#values) in that they allow users to override values in a Zarf package component's underlying Helm chart; they also share a similar syntax. However, unlike `values`, `variables` can be overridden at deploy time. For example, consider the `variables` key in the following `uds-bundle.yaml`: + +```yaml +kind: UDSBundle +metadata: + name: example-bundle + version: 0.0.1 + +packages: + - name: helm-overrides-package + path: "../../packages/helm" + ref: 0.0.1" + overrides: + podinfo-component: + unicorn-podinfo: + variables: + - name: UI_COLOR + path: "ui.color" + description: "Set the color for podinfo's UI" + default: "purple" +``` + +There are 3 ways to override the `UI_COLOR` variable: + +1. **UDS config**: you can create a `uds-config.yaml` file in the same directory as the bundle and specify the variable to override. For example, to override the `UI_COLOR` variable, you can create a `uds-config.yaml`: + + ```yaml + variables: + helm-overrides-package: + ui_color: green # Note that the variable for `UI_COLOR` can be upper or lowercase + ``` + +1. **Environment variables**: you can create an environment variable prefixed with `UDS_` and the name of the variable. For example, to override the `UI_COLOR` variable, you can create an environment variable called `UDS_UI_COLOR` and set it to the desired value. Note that environment variables take precedence over `uds-config.yaml` variables. + +1. **--set Flag**: you can also override the variable using the CLI's `--set` flag. For example, to override the `UI_COLOR` variable, you can run one of the following commands: + + ```bash + # by default ui_color will apply to all packages in the bundle + uds deploy example-bundle --set ui_color=green + + # to specify a specific package that the variable should apply to you can prepend th package name to the variable + uds deploy example-bundle --set helm-overrides-package.ui_color=green + ``` + + > **:warning: Warning**: Because Helm override variables and Zarf variables share the same --set syntax, be careful with variable names to avoid conflicts. + +> [!NOTE] +> A variable that is not overridden by any of the methods above and has no default will be ignored. + +#### Variable Precedence +Variable precedence is as follows: +1. The `--set` flag +1. Environment variables +1. `uds-config.yaml` variables +1. Variables `default` in the`uds-bundle.yaml` + +#### Variable Types +Variables can be of either type `raw` or `file`. The type will default to raw if not set explicitly. + +> [!WARNING] +> If a variable is set to accept a file as its value, but is missing the `file` type, then the file will not be processed. + +```yaml +kind: UDSBundle +metadata: + name: example-bundle + version: 0.0.1 + +packages: + - name: helm-overrides-package + path: "../../packages/helm" + ref: 0.0.1 + overrides: + podinfo-component: + unicorn-podinfo: + variables: + - name: UI_COLOR + path: "ui.color" + description: "variable UI_COLOR accepts a raw value (e.g. a string, int, map) like "purple", which is passed to the ui.color helm path" + type: raw + - name: test_secret + path: "testSecret" + description: "variable TEST_SECRET will resolve to the contents of a file (e.g. test.cert), which gets passed to the testSecret helm path" + type: file +``` + +**File Paths** + +If a file path is not absolute, it will be set as relative to the `uds-config.yaml` directory. + +e.g. the following `uds-config.yaml` is in [`src/test/bundles/07-helm-overrides/variable-files/`](../src/test/bundles/07-helm-overrides/variable-files/uds-config.yaml) +```yaml +variables: + helm-overrides: + test_secret: test.cert +``` + +This means when `test.cert` is evalutated it will first be appended to the config path like so `src/test/bundles/07-helm-overrides/variable-files/test.cert`. + +If the file path is already set to the same relative path as the config, then no merging will take place. + +> [!NOTE] +> UDS CLI does not encrypt or base64 encode any file contents before passing said data to Zarf or Helm. +> For example, if the file contains a key to be used in a Kubernetes secret, it must be base64 encoded before being ingested by UDS CLI. + + +### Namespace +It's also possible to specify a namespace for a packaged Helm chart to be installed in. For example, to deploy the a chart in the `custom-podinfo` namespace, you can specify the `namespace` in the `overrides` block: + +```yaml +kind: UDSBundle +metadata: + name: example-bundle + version: 0.0.1 + +packages: + - name: helm-overrides-package + path: "../../packages/helm" + ref: 0.0.1" + overrides: + podinfo-component: + unicorn-podinfo: + namespace: custom-podinfo # custom namespace! + values: + - path: "podinfo.replicaCount" + value: 1 +``` diff --git a/docs/bundle-overrides/overrides.md b/docs/bundle-overrides/overrides.md deleted file mode 100644 index 29b3cec3..00000000 --- a/docs/bundle-overrides/overrides.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Overrides -type: docs -weight: 1 ---- - -## Syntax - -Consider the following bundle `overrides`: - -```yaml -packages: - - name: helm-overrides-package - path: "path/to/pkg" - ref: 0.0.1 - - overrides: - helm-overrides-component: # component name inside of the helm-overrides-package Zarf pkg - podinfo: # chart name from the helm-overrides-component component - values: - - path: "replicaCount" - value: 2 - variables: - - name: UI_COLOR - path: "ui.color" - description: "Set the color for podinfo's UI" - default: "purple" -``` - -In the above example, the Zarf Package `helm-overrides-package` has a specific component named `helm-overrides-component`, which contains a Helm chart named `podinfo`. Notably, these names serve as keys in the `overrides` block. Within the `podinfo` chart, the `replicaCount` value has been overridden to `2`, and a variable named `UI_COLOR` is specifically overridden to the color `purple`. - -## Values - -In the `overrides` block, you will find a list of path and value pairs. This feature enables users to override values within the underlying Helm chart of a Zarf Package component. - -{{% alert-note %}} -Please note that these values are initially set by the authors of the bundle and, once the bundle has been created, they **cannot be modified**. -{{% /alert-note %}} - -### Path - -The path employs dot notation to indicate the location of a value intended for overriding within the base Helm chart. For example, in the `podinfo` chart, the `replicaCount` path is situated at the highest level of the [`podinfo values.yaml`](https://github.com/stefanprodan/podinfo/blob/master/charts/podinfo/values.yaml) so the path is expressed as `replicaCount`. Conversely, the `ui.color` path is found beneath the `ui` key, so the designated path is expressed as `ui.color`. - -### Value - -The `value` represents the content to be set at the specified `path`. It can include straightforward data types like numbers and strings, but it is also versatile enough to handle intricate structures such as lists and objects. For example: - -```yaml -... - overrides: - helm-overrides-component: - podinfo: - values: - - path: "podinfo.tolerations" - value: - - key: "unicorn" - operator: "Equal" - value: "defense" - effect: "NoSchedule" - - path: podinfo.podAnnotations - value: - customAnnotation: "customValue" -``` - -When using a variable exported from another package, you can use its value to set another variable using the syntax `${...}`. In the following example, the `COLOR` variable is used to establish the value of `podinfo.ui.color`. - -```yaml -kind: UDSBundle -metadata: - name: export-vars - description: Example for using an imported variable to set an overrides value - version: 0.0.1 - -packages: - - name: output-var - repository: localhost:888/output-var - ref: 0.0.1 - exports: - - name: COLOR - - - name: helm-overrides - path: "../../packages/helm" - ref: 0.0.1 - - overrides: - podinfo-component: - unicorn-podinfo: - values: - - path: "podinfo.replicaCount" - value: 1 - - path: "podinfo.ui.color" - value: ${COLOR} -``` - -## Variables - -Variables function similarly to values, enabling users to override configurations within a Zarf Package component's underlying Helm chart. They also share a similar syntax. However, unlike values, variables offer the flexibility of being overridden dynamically during deploy time. For example, consider the following `variables`: - -```yaml -... - overrides: - helm-overrides-component: - podinfo: - variables: - - name: UI_COLOR - path: "ui.color" - description: "Set the color for podinfo's UI" - default: "purple" -``` - -There are three ways to override the `UI_COLOR` variable: - -- **UDS Config:** Create a `uds-config.yaml` file within the bundle's directory and specify the variables you wish to override. To modify the `UI_COLOR` variable, create a `uds-config.yaml`. For example: - -```yaml - variables: - helm-overrides-package: - ui_color: green -``` - -Note that the variable for `UI_COLOR` can be either upper or lower case. - -- **Environment Variables:** Create an environment variable prefixed with `UDS_` followed by the variable name. For example, to override the `UI_COLOR` variable, you would create an environment variable named `UDS_UI_COLOR` and assign it the desired value. - -Note that the environment variables hold precedence over variables specified in the `uds-config.yaml` configuration file. - -- **`--set` Flag:** Override a variable using the UDS CLI's `--set` flag. For example, the override the `UI_COLOR` variable, run one of the following commands: - -```cli -# by default ui_color will apply to all packages in the bundle -uds deploy example-bundle --set ui_color=green - -# to specify a specific package that the variable should apply to you can prepend th package name to the variable -uds deploy example-bundle --set helm-overrides-package.ui_color=green -``` - -{{% alert-note %}} -When using Helm override variables and Zarf variables, which share the same `--set` syntax, exercise caution with variable naming to prevent conflicts. -{{% /alert-note %}} - -### Variable Precendence - -Variable precedence is as follows: - -1. Environment variables. -2. `uds-config.yaml` variables. -3. Variables that are `default` in the `uds-bundle.yaml`. - -## Namespace - -Users can specify a namespace for a packaged Helm chart to be installed in. For instance, to deploy a chart in the `custom-podinfo` namespace, specify the `namespace` in the `overrides` block: - -```yaml -kind: UDSBundle -metadata: - name: example-bundle - version: 0.0.1 - -packages: - - name: helm-overrides-package - path: "../../packages/helm" - ref: 0.0.1" - overrides: - podinfo-component: - unicorn-podinfo: - namespace: custom-podinfo # custom namespace! - values: - - path: "podinfo.replicaCount" - value: 1 -``` From 604d838eb0b0104e8321e51ea03b7445dea2a7bb Mon Sep 17 00:00:00 2001 From: unclegedd Date: Fri, 7 Jun 2024 10:44:19 -0500 Subject: [PATCH 15/26] WIP: more refactor --- docs/configuration.md | 36 ------------ ...{quickstart.md => quickstart-and-usage.md} | 2 +- docs/variables.md | 55 ------------------- 3 files changed, 1 insertion(+), 92 deletions(-) delete mode 100644 docs/configuration.md rename docs/{quickstart.md => quickstart-and-usage.md} (99%) delete mode 100644 docs/variables.md diff --git a/docs/configuration.md b/docs/configuration.md deleted file mode 100644 index f2b42a7b..00000000 --- a/docs/configuration.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: CLI Configuration -type: docs -weight: 2 ---- - -## Configuration - -The UDS CLI can be easily configured through a `uds-config.yaml` file, offering flexibility in placement either within the current working directory or via the specification of an environment variable named `UDS_CONFIG`. The fundamental structure of the `uds-config.yaml` file is outlined below: - -```yaml -options: - log_level: debug - architecture: arm64 - no_log_file: false - no_progress: false - uds_cache: /tmp/uds-cache - tmp_dir: /tmp/tmp_dir - insecure: false - oci_concurrency: 3 - -shared: - domain: uds.dev # shared across all packages in a bundle - -variables: - my-zarf-package: # name of Zarf package - ui_color: green # key is not case sensitive and refers to name of Zarf variable - UI_MSG: "Hello Unicorn" - hosts: # variables can be complex types such as lists and maps - - host: burning.boats - paths: - - path: "/" - pathType: "Prefix" -``` - -The `options` key contains UDS CLI options that are not specific to a particular Zarf Package. The `variables` key contains variables that are specific to a particular Zarf Package. If there is a need to share insensitive variables across multiple Zarf Packages, the `shared` key can be used. In this case, the `shared` key represents the variable name, and the value is the variable's intended value. diff --git a/docs/quickstart.md b/docs/quickstart-and-usage.md similarity index 99% rename from docs/quickstart.md rename to docs/quickstart-and-usage.md index 4d99455d..d7779a21 100644 --- a/docs/quickstart.md +++ b/docs/quickstart-and-usage.md @@ -1,5 +1,5 @@ --- -title: Quickstart Guide +title: Quickstart and Usage type: docs weight: 1 --- diff --git a/docs/variables.md b/docs/variables.md deleted file mode 100644 index 0a34c570..00000000 --- a/docs/variables.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: CLI Variables -type: docs -weight: 3 ---- - -## Importing and Exporting Variables - -Zarf Package variables can be passed between Zarf Packages, see the example below: - -```yaml -kind: UDSBundle -metadata: - name: simple-vars - description: show how vars work - version: 0.0.1 - -packages: - - name: output-var - repository: localhost:888/output-var - ref: 0.0.1 - exports: - - name: OUTPUT - - name: receive-var - repository: localhost:888/receive-var - ref: 0.0.1 - imports: - - name: OUTPUT - package: output-var -``` - -In Zarf Packages, variables intended for accessibility by other packages are situated within the `export` block of the respective Zarf Package. By default, all variables marked for `export` are globally accessible to all packages within a bundle. However, when dealing with potential variable name collisions or when a specific exported variable needs to be consumed by another package, the `imports` key can be used. This key facilitates the explicit association of both the variable name and the package from which it is exported. - -In the provided example, the `OUTPUT` variable is generated as part of a Zarf Action within the `output-var` package. The `receive-var` package, in turn, anticipates the availability of a variable named `OUTPUT` and explicitly imports it using the `imports` key. - -## Sharing Variables - -To streamline the configuration of Zarf Variables across multiple packages within a bundle, consider employing environment variables prefixed with `UDS_`. This approach eliminates the need to repetitively set variables using import/export syntax. For instance, if several packages share a common variable, such as `DOMAIN`, you can set it once using a `UDS_DOMAIN` environment variable, and it will automatically apply to all packages in the bundle. Alternatively, a similar configuration can be achieved using the `shared` key in the `uds-config.yaml` file. - -On deploy, package variables can also be set using the `--set` flag. When the package name is excluded from the key, for example: `--set super=true`, the variable is applied to all packages. If the package name is included in the key, for example: `--set cool-package.super=true`, the variable exclusively applies to the specified package. This provides a flexible mechanism for targeted configuration adjustments during deployment. - -## Variable Precedence and Specificity - -Within a bundle, variables can originate from four distinct sources, each with a specified order of precedence ranging from the least to the most specific. These sources are outlined below: - -- Variables declared in a Zarf Package. -- Variables that have been `import` from a bundles package's `export`. -- Varaibles configured in the `shared` key in a `uds-config.yaml`. -- Variables configured in the `variables` key in a `uds-config.yaml`. -- Variables set with an environment variable prefixed with `UDS_`, for example: `UDS_OUTPUT`. -- Variables set using the `--set` flag when executing the `uds deploy` command. - -{{% alert-note %}} -Variables established using the `--set` flag take precedence over variables from all other outlined sources. -{{% /alert-note %}} From 5c8a530f981e6773f4145b6242761456e213f340 Mon Sep 17 00:00:00 2001 From: unclegedd Date: Fri, 7 Jun 2024 10:49:37 -0500 Subject: [PATCH 16/26] i feel good about this --- docs/bundle-overrides/_index.md | 310 -------------------------------- docs/overrides.md | 7 +- docs/runner.md | 62 +++++++ docs/uds-runner/_index.md | 62 ------- 4 files changed, 67 insertions(+), 374 deletions(-) delete mode 100644 docs/bundle-overrides/_index.md delete mode 100644 docs/uds-runner/_index.md diff --git a/docs/bundle-overrides/_index.md b/docs/bundle-overrides/_index.md deleted file mode 100644 index 7fcfa93e..00000000 --- a/docs/bundle-overrides/_index.md +++ /dev/null @@ -1,310 +0,0 @@ ---- -title: Bundle Overrides -type: docs -weight: 5 ---- - -Bundle overrides provide a mechanism to customize Helm charts inside of Zarf packages. - -## Quickstart - -Consider the following `zarf.yaml` and `values.yaml` which deploys [podinfo](https://github.com/stefanprodan/podinfo) -with a couple of custom values: - -```yaml -# zarf.yaml -kind: ZarfPackageConfig -metadata: - name: helm-overrides-package - version: 0.0.1 - -components: - - name: helm-overrides-component - required: true - charts: - - name: podinfo - version: 6.4.0 - namespace: podinfo - url: https://github.com/stefanprodan/podinfo.git - gitPath: charts/podinfo - valuesFiles: - - values.yaml - images: - - ghcr.io/stefanprodan/podinfo:6.4.0 ---- -# values.yaml -replicaCount: 1 -ui: - color: blue -``` - -The bundle overrides feature allows users to override the values specified in Zarf packages. For example: -```yaml -kind: UDSBundle -metadata: - name: helm-overrides - description: testing a bundle with Helm overrides - version: 0.0.1 - -packages: - - name: helm-overrides-package - path: "path/to/pkg" - ref: 0.0.1 - - overrides: - helm-overrides-component: - podinfo: - valuesFiles: - - file: values.yaml - values: - - path: "replicaCount" - value: 2 - variables: - - name: UI_COLOR - path: "ui.color" - description: "Set the color for podinfo's UI" - default: "purple" -``` - -```yaml -#values.yaml -podAnnotations: - customAnnotation: "customValue" -``` - -This bundle will deploy the `helm-overrides-package` Zarf package and override the `replicaCount`, `ui.color`, and `podAnnotations` values in the `podinfo` chart. The `values` can't be modified after the bundle has been created. However, at deploy time, users can override the `UI_COLOR` and other `variables` using a environment variable called `UDS_UI_COLOR` or by specifying it in a `uds-config.yaml` like so: - -```yaml -variables: - helm-overrides-package: - UI_COLOR: green -``` - -## Overrides - -### Syntax - -Consider the following bundle `overrides`: - -```yaml -packages: - - name: helm-overrides-package - path: "path/to/pkg" - ref: 0.0.1 - - overrides: - helm-overrides-component: # component name inside of the helm-overrides-package Zarf pkg - podinfo: # chart name from the helm-overrides-component component - valuesFiles: - - file: values.yaml - values: - - path: "replicaCount" - value: 2 - variables: - - name: UI_COLOR - path: "ui.color" - description: "Set the color for podinfo's UI" - default: "purple" -``` - -```yaml -#values.yaml -podAnnotations: - customAnnotation: "customValue" -``` -In this example, the `helm-overrides-package` Zarf package has a component called `helm-overrides-component` which contains a Helm chart called `podinfo`; note how these names are keys in the `overrides` block. The `podinfo` chart has a `replicaCount` value that is overridden to `2`, a `podAnnotations` value that is overridden to include `customAnnotation: "customValue"` and a variable called `UI_COLOR` that is overridden to `purple`. - -### Values Files - -The `valuesFiles` in an `overrides` block are a list of `file`'s. It allows users to override multiple values in a Zarf package component's underlying Helm chart, by providing a file with those values instead of having to include them all indiviually in the `overrides` block. - -### Values - -The `values` in an `overrides` block are a list of `path` and `value` pairs. They allow users to override values in a Zarf package component's underlying Helm chart. Note that values are specified by bundle authors and **cannot be modified** after the bundle has been created. - -#### Path - -The `path` uses dot notation to specify the location of a value to override in the underlying Helm chart. For example, the `replicaCount` path in the `podinfo` chart is located at the top-level of the [podinfo values.yaml](https://github.com/stefanprodan/podinfo/blob/master/charts/podinfo/values.yaml), so the path is simply `replicaCount`, while the `ui.color` path is located under the `ui` key, so the path is `ui.color`. - -#### Value - -The `value` is the value to set at the `path`. Values can be simple values such as numbers and strings, as well as, complex lists and objects, for example: -```yaml -... - overrides: - helm-overrides-component: - podinfo: - values: - - path: "podinfo.tolerations" - value: - - key: "unicorn" - operator: "Equal" - value: "defense" - effect: "NoSchedule" - - path: podinfo.podAnnotations - value: - customAnnotation: "customValue" -``` -If using a variable that has been [exported](../README.md#importingexporting-variables) from another package, that variable can also be used to set a value, using the syntax `${...}`. In the example below the `COLOR` variable is being used to set the `podinfo.ui.color` value. -```yaml -kind: UDSBundle -metadata: - name: example-bundle - description: Example for using an imported variable to set an overrides value - version: 0.0.1 - -packages: - - name: output-var - repository: localhost:888/output-var - ref: 0.0.1 - exports: - - name: COLOR - - - name: helm-overrides-package - path: "../../packages/helm" - ref: 0.0.1 - - overrides: - podinfo-component: - unicorn-podinfo: - values: - - path: "podinfo.replicaCount" - value: 1 - - path: "podinfo.ui.color" - value: ${COLOR} -``` - -#### Value Precedence -Value precedence is as follows: -1. The `values` in an `overrides` block -1. `values` set in the last `valuesFile` (if more than one specified) -1. `values` set in the previous `valuesFile` (if more than one specified) - -### Variables -Variables are similar to [values](#values) in that they allow users to override values in a Zarf package component's underlying Helm chart; they also share a similar syntax. However, unlike `values`, `variables` can be overridden at deploy time. For example, consider the `variables` key in the following `uds-bundle.yaml`: - -```yaml -kind: UDSBundle -metadata: - name: example-bundle - version: 0.0.1 - -packages: - - name: helm-overrides-package - path: "../../packages/helm" - ref: 0.0.1" - overrides: - podinfo-component: - unicorn-podinfo: - variables: - - name: UI_COLOR - path: "ui.color" - description: "Set the color for podinfo's UI" - default: "purple" -``` - -There are 3 ways to override the `UI_COLOR` variable: - -1. **UDS config**: you can create a `uds-config.yaml` file in the same directory as the bundle and specify the variable to override. For example, to override the `UI_COLOR` variable, you can create a `uds-config.yaml`: - - ```yaml - variables: - helm-overrides-package: - ui_color: green # Note that the variable for `UI_COLOR` can be upper or lowercase - ``` - -1. **Environment variables**: you can create an environment variable prefixed with `UDS_` and the name of the variable. For example, to override the `UI_COLOR` variable, you can create an environment variable called `UDS_UI_COLOR` and set it to the desired value. Note that environment variables take precedence over `uds-config.yaml` variables. - -1. **--set Flag**: you can also override the variable using the CLI's `--set` flag. For example, to override the `UI_COLOR` variable, you can run one of the following commands: - - ```bash - # by default ui_color will apply to all packages in the bundle - uds deploy example-bundle --set ui_color=green - - # to specify a specific package that the variable should apply to you can prepend th package name to the variable - uds deploy example-bundle --set helm-overrides-package.ui_color=green - ``` - - > **:warning: Warning**: Because Helm override variables and Zarf variables share the same --set syntax, be careful with variable names to avoid conflicts. - -> [!NOTE] -> A variable that is not overridden by any of the methods above and has no default will be ignored. - -#### Variable Precedence -Variable precedence is as follows: -1. The `--set` flag -1. Environment variables -1. `uds-config.yaml` variables -1. Variables `default` in the`uds-bundle.yaml` - -#### Variable Types -Variables can be of either type `raw` or `file`. The type will default to raw if not set explicitly. - -> [!WARNING] -> If a variable is set to accept a file as its value, but is missing the `file` type, then the file will not be processed. - -```yaml -kind: UDSBundle -metadata: - name: example-bundle - version: 0.0.1 - -packages: - - name: helm-overrides-package - path: "../../packages/helm" - ref: 0.0.1 - overrides: - podinfo-component: - unicorn-podinfo: - variables: - - name: UI_COLOR - path: "ui.color" - description: "variable UI_COLOR accepts a raw value (e.g. a string, int, map) like "purple", which is passed to the ui.color helm path" - type: raw - - name: test_secret - path: "testSecret" - description: "variable TEST_SECRET will resolve to the contents of a file (e.g. test.cert), which gets passed to the testSecret helm path" - type: file -``` - -**File Paths** - -If a file path is not absolute, it will be set as relative to the `uds-config.yaml` directory. - -e.g. the following `uds-config.yaml` is in [`src/test/bundles/07-helm-overrides/variable-files/`](../src/test/bundles/07-helm-overrides/variable-files/uds-config.yaml) -```yaml -variables: - helm-overrides: - test_secret: test.cert -``` - -This means when `test.cert` is evalutated it will first be appended to the config path like so `src/test/bundles/07-helm-overrides/variable-files/test.cert`. - -If the file path is already set to the same relative path as the config, then no merging will take place. - -> [!NOTE] -> UDS CLI does not encrypt or base64 encode any file contents before passing said data to Zarf or Helm. -> For example, if the file contains a key to be used in a Kubernetes secret, it must be base64 encoded before being ingested by UDS CLI. - - -### Namespace -It's also possible to specify a namespace for a packaged Helm chart to be installed in. For example, to deploy the a chart in the `custom-podinfo` namespace, you can specify the `namespace` in the `overrides` block: - -```yaml -kind: UDSBundle -metadata: - name: example-bundle - version: 0.0.1 - -packages: - - name: helm-overrides-package - path: "../../packages/helm" - ref: 0.0.1" - overrides: - podinfo-component: - unicorn-podinfo: - namespace: custom-podinfo # custom namespace! - values: - - path: "podinfo.replicaCount" - value: 1 -``` diff --git a/docs/overrides.md b/docs/overrides.md index 9aaf0e1b..aabfd262 100644 --- a/docs/overrides.md +++ b/docs/overrides.md @@ -1,5 +1,8 @@ -# Bundle Overrides - +--- +title: Bundle Overrides +type: docs +weight: 5 +--- Bundle overrides provide a mechanism to customize Helm charts inside of Zarf packages. ## Table of Contents diff --git a/docs/runner.md b/docs/runner.md index e69de29b..6b7debd6 100644 --- a/docs/runner.md +++ b/docs/runner.md @@ -0,0 +1,62 @@ +--- +title: UDS Runner +type: docs +weight: 4 +--- +UDS CLI contains vendors and configures the [maru-runner](https://github.com/defenseunicorns/maru-runner) build tool to make compiling and building UDS bundles simple. + + +## Quickstart + +#### Running a Task +To run a task from a `tasks.yaml`: +``` +uds run +``` + +#### Running a Task from a specific tasks file +``` +uds run -f +``` + + +The Maru [docs](https://github.com/defenseunicorns/maru-runner) describe how to build `tasks.yaml` files to configure the runner. The functionality in UDS CLI is mostly identical with the following exceptions + +### Variables Set with Environment Variables +When running a `tasks.yaml` with `uds run my-task` you can set variables using environment prefixed with `UDS_` + +For example, running `UDS_FOO=bar uds run echo-foo` on the following task will echo `bar`. + +```yaml +variables: + - name: FOO + default: foo +tasks: + - name: echo-foo + actions: + - cmd: echo ${FOO} +``` + +### Running UDS and Zarf Commands +To run `uds` commands from within a task, you can invoke your system `uds` binary using the `./uds` syntax. Similarly, UDS CLI vendors Zarf, and tasks can run vendored Zarf commands using `./zarf`. For example: +```yaml +tasks: +- name: default + actions: + - cmd: ./uds inspect k3d-core-istio-dev:0.16.1 # uses system uds + - cmd: ./zarf tools kubectl get pods -A # uses vendored Zarf +``` + +### Architecture Environment Variable +When running tasks with `uds run`, there is a special `UDS_ARCH` environment variable accessible within tasks that is automatically set to your system architecture, but is also configurable with a `UDS_ARCHITECTURE` environmental variable. For example: +``` +tasks: +- name: print-arch + actions: + - cmd: echo ${UDS_ARCH} +``` +- Running `uds run print-arch` will echo your local system architecture +- Running `UDS_ARCHITECTURE=amd64 uds run print-arch` will echo "amd64" + +### No Dependency on Zarf +Since UDS CLI also vendors [Zarf](https://github.com/defenseunicorns/zarf), there is no need to also have Zarf installed on your system. diff --git a/docs/uds-runner/_index.md b/docs/uds-runner/_index.md deleted file mode 100644 index 6b7debd6..00000000 --- a/docs/uds-runner/_index.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: UDS Runner -type: docs -weight: 4 ---- -UDS CLI contains vendors and configures the [maru-runner](https://github.com/defenseunicorns/maru-runner) build tool to make compiling and building UDS bundles simple. - - -## Quickstart - -#### Running a Task -To run a task from a `tasks.yaml`: -``` -uds run -``` - -#### Running a Task from a specific tasks file -``` -uds run -f -``` - - -The Maru [docs](https://github.com/defenseunicorns/maru-runner) describe how to build `tasks.yaml` files to configure the runner. The functionality in UDS CLI is mostly identical with the following exceptions - -### Variables Set with Environment Variables -When running a `tasks.yaml` with `uds run my-task` you can set variables using environment prefixed with `UDS_` - -For example, running `UDS_FOO=bar uds run echo-foo` on the following task will echo `bar`. - -```yaml -variables: - - name: FOO - default: foo -tasks: - - name: echo-foo - actions: - - cmd: echo ${FOO} -``` - -### Running UDS and Zarf Commands -To run `uds` commands from within a task, you can invoke your system `uds` binary using the `./uds` syntax. Similarly, UDS CLI vendors Zarf, and tasks can run vendored Zarf commands using `./zarf`. For example: -```yaml -tasks: -- name: default - actions: - - cmd: ./uds inspect k3d-core-istio-dev:0.16.1 # uses system uds - - cmd: ./zarf tools kubectl get pods -A # uses vendored Zarf -``` - -### Architecture Environment Variable -When running tasks with `uds run`, there is a special `UDS_ARCH` environment variable accessible within tasks that is automatically set to your system architecture, but is also configurable with a `UDS_ARCHITECTURE` environmental variable. For example: -``` -tasks: -- name: print-arch - actions: - - cmd: echo ${UDS_ARCH} -``` -- Running `uds run print-arch` will echo your local system architecture -- Running `UDS_ARCHITECTURE=amd64 uds run print-arch` will echo "amd64" - -### No Dependency on Zarf -Since UDS CLI also vendors [Zarf](https://github.com/defenseunicorns/zarf), there is no need to also have Zarf installed on your system. From f7356127e28b5cf0418cb55e615fbb2a142df5de Mon Sep 17 00:00:00 2001 From: unclegedd Date: Fri, 7 Jun 2024 10:50:35 -0500 Subject: [PATCH 17/26] no more table of contents --- docs/overrides.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/overrides.md b/docs/overrides.md index aabfd262..b8be923f 100644 --- a/docs/overrides.md +++ b/docs/overrides.md @@ -5,15 +5,6 @@ weight: 5 --- Bundle overrides provide a mechanism to customize Helm charts inside of Zarf packages. -## Table of Contents - -1. [Quickstart](#quickstart) -1. [Overrides](#variables) - - [Syntax](#syntax) - - [Values](#values) - - [Variables](#variables) - - [Namespace](#namespace) - ## Quickstart Consider the following `zarf.yaml` and `values.yaml` which deploys [podinfo](https://github.com/stefanprodan/podinfo) From cd3928a60039c6c64121d50675f0a60e89ba18fe Mon Sep 17 00:00:00 2001 From: TristanHoladay <40547442+TristanHoladay@users.noreply.github.com> Date: Fri, 7 Jun 2024 10:42:09 -0600 Subject: [PATCH 18/26] fix links and note syntax --- docs/overrides.md | 19 +++++++++------- docs/quickstart-and-usage.md | 44 ++++++++++++++++++++---------------- 2 files changed, 36 insertions(+), 27 deletions(-) diff --git a/docs/overrides.md b/docs/overrides.md index b8be923f..04fa8686 100644 --- a/docs/overrides.md +++ b/docs/overrides.md @@ -236,8 +236,9 @@ There are 3 ways to override the `UI_COLOR` variable: > **:warning: Warning**: Because Helm override variables and Zarf variables share the same --set syntax, be careful with variable names to avoid conflicts. -> [!NOTE] -> A variable that is not overridden by any of the methods above and has no default will be ignored. +{{% alert-note %}} +A variable that is not overridden by any of the methods above and has no default will be ignored. +{{% /alert-note %}} #### Variable Precedence Variable precedence is as follows: @@ -249,8 +250,9 @@ Variable precedence is as follows: #### Variable Types Variables can be of either type `raw` or `file`. The type will default to raw if not set explicitly. -> [!WARNING] -> If a variable is set to accept a file as its value, but is missing the `file` type, then the file will not be processed. +{{% alert-caution %}} +If a variable is set to accept a file as its value, but is missing the `file` type, then the file will not be processed. +{{% /alert-caution %}} ```yaml kind: UDSBundle @@ -280,7 +282,7 @@ packages: If a file path is not absolute, it will be set as relative to the `uds-config.yaml` directory. -e.g. the following `uds-config.yaml` is in [`src/test/bundles/07-helm-overrides/variable-files/`](../src/test/bundles/07-helm-overrides/variable-files/uds-config.yaml) +e.g. the following `uds-config.yaml` is in [`src/test/bundles/07-helm-overrides/variable-files/`](https://github.com/defenseunicorns/uds-cli/blob/uds-cli-docs/src/test/bundles/07-helm-overrides/uds-config.yaml) ```yaml variables: helm-overrides: @@ -291,10 +293,11 @@ This means when `test.cert` is evaluated it will first be appended to the config If the file path is already set to the same relative path as the config, then no merging will take place. -> [!NOTE] -> UDS CLI does not encrypt or base64 encode any file contents before passing said data to Zarf or Helm. -> For example, if the file contains a key to be used in a Kubernetes secret, it must be base64 encoded before being ingested by UDS CLI. +{{% alert-note %}} +UDS CLI does not encrypt or base64 encode any file contents before passing said data to Zarf or Helm. +For example, if the file contains a key to be used in a Kubernetes secret, it must be base64 encoded before being ingested by UDS CLI. +{{% /alert-note %}} ### Namespace It's also possible to specify a namespace for a packaged Helm chart to be installed in. For example, to deploy the a chart in the `custom-podinfo` namespace, you can specify the `namespace` in the `overrides` block: diff --git a/docs/quickstart-and-usage.md b/docs/quickstart-and-usage.md index d7779a21..3e99c58f 100644 --- a/docs/quickstart-and-usage.md +++ b/docs/quickstart-and-usage.md @@ -12,7 +12,7 @@ brew tap defenseunicorns/tap && brew install uds UDS CLI Binaries are also included with each [Github Release](https://github.com/defenseunicorns/uds-cli/releases) ## Contributing -Build instructions and contributing docs are located in [CONTRIBUTING.md](CONTRIBUTING.md). +Build instructions and contributing docs are located in [CONTRIBUTING.md](https://github.com/defenseunicorns/uds-cli/blob/main/CONTRIBUTING.md). ## Quickstart The UDS-CLI's flagship feature is deploying multiple, independent Zarf packages. To create a `UDSBundle` of Zarf packages, create a `uds-bundle.yaml` file like so: @@ -36,7 +36,7 @@ packages: ``` The above `UDSBundle` deploys the Zarf init package and podinfo. -The packages referenced in `packages` can exist either locally or in an OCI registry. See [here](src/test/packages/03-local-and-remote) for an example that deploys both local and remote Zarf packages. More `UDSBundle` examples can be found in the [src/test/bundles](src/test/bundles) folder. +The packages referenced in `packages` can exist either locally or in an OCI registry. See [here](https://github.com/defenseunicorns/uds-cli/tree/main/src/test/bundles/03-local-and-remote) for an example that deploys both local and remote Zarf packages. More `UDSBundle` examples can be found in the [src/test/bundles](https://github.com/defenseunicorns/uds-cli/tree/main/src/test/bundles) folder. #### Declarative Syntax The syntax of a `uds-bundle.yaml` is entirely declarative. As a result, the UDS CLI will not prompt users to deploy optional components in a Zarf package. If you want to deploy an optional Zarf component, it must be specified in the `optionalComponents` key of a particular `package`. @@ -60,8 +60,9 @@ There are 2 ways to create Bundles: 1. Inside an OCI registry: `uds create -o ghcr.io/defenseunicorns/dev` 1. Locally on your filesystem: `uds create ` -> [!NOTE] -> The `--insecure` flag is necessary when interacting with a local registry, but not from secure, remote registries such as GHCR. +{{% alert-note %}} +The `--insecure` flag is necessary when interacting with a local registry, but not from secure, remote registries such as GHCR. +{{% /alert-note %}} ### Bundle Deploy Deploys the bundle @@ -118,8 +119,9 @@ As an example: `uds remove uds-bundle-.tar.zst --packages init,nginx` ### Logs -> [!NOTE] -> Only works with `uds deploy` for now, may work for other operations but isn't guaranteed. +{{% alert-note %}} +Only works with `uds deploy` for now, may work for other operations but isn't guaranteed. +{{% /alert-note %}} The `uds logs` command can be used to view the most recent logs of a bundle operation. Note that depending on your OS temporary directory and file settings, recent logs are purged after a certain amount of time, so this command may return an error if the logs are no longer available. @@ -137,8 +139,9 @@ UDS CLI supports multi-arch bundles. This means you can push bundles with differ ### Architecture Validation When deploying a local bundle, the bundle's architecture will be used for comparison against the cluster architecture to ensure compatability. If deploying a remote bundle, by default the bundle is pulled based on system architecture, which is then checked against the cluster. -> [!NOTE] -> It is possible to override the bundle architecture used at validation time by using the `--architecture` / `-a` flag. +{{% alert-note %}} +It is possible to override the bundle architecture used at validation time by using the `--architecture` / `-a` flag. +{{% /alert-note %}} If, for example, you have a multi-arch remote bundle that you want to deploy from an arm64 machine to an amd64 cluster, the validation with fail because the system arch does not match the cluster arch. However, you can pull the correct bundle version by specificying the arch with the command line architecture flag. @@ -199,7 +202,7 @@ packages: Variables that you want to make available to other packages are in the `export` block of the Zarf package to export a variable from. By default, all exported variables are available to all of the packages in a bundle. To have another package ingest a specific exported variable, like in the case of variable name collisions, use the `imports` key to name both the `variable` and `package` that the variable is exported from, like in the example above. -In the example above, the `OUTPUT` variable is created as part of a Zarf Action in the [output-var](src/test/packages/zarf/no-cluster/output-var) package, and the [receive-var](src/test/packages/zarf/no-cluster/receive-var) package expects a variable called `OUTPUT`. +In the example above, the `OUTPUT` variable is created as part of a Zarf Action in the [output-var](https://github.com/defenseunicorns/uds-cli/tree/main/src/test/packages/no-cluster/output-var) package, and the [receive-var]([src/test/packages/zarf/no-cluster/receive-var](https://github.com/defenseunicorns/uds-cli/tree/main/src/test/packages/no-cluster/receive-var)) package expects a variable called `OUTPUT`. ### Sharing Variables Across Multiple Packages If a Zarf variable has the same name in multiple packages and you don't want to set it multiple times via the import/export syntax, you can set an environment variable prefixed with `UDS_` and it will be applied to all the Zarf packages in a bundle. For example, if multiple packages require a `DOMAIN` variable, you could set it once with a `UDS_DOMAIN` environment variable and it would be applied to all packages. Note that this can also be done with the `shared` key in the `uds-config.yaml` file. @@ -221,7 +224,7 @@ That is to say, variables set using the `--set` flag take precedence over all ot ## Duplicate Packages And Naming -It is possible to deploy multiple instances of the same Zarf package in a bundle. For example, the following `uds-bundle.yaml` deploys 3 instances of the [helm-overrides](src/test/packages/helm/zarf.yaml) Zarf packags: +It is possible to deploy multiple instances of the same Zarf package in a bundle. For example, the following `uds-bundle.yaml` deploys 3 instances of the [helm-overrides](https://github.com/defenseunicorns/uds-cli/blob/main/src/test/packages/helm/zarf.yaml) Zarf packags: ```yaml kind: UDSBundle metadata: @@ -259,19 +262,21 @@ packages: The naming conventions for deploying duplicate packages are as follows: 1. The `name` field of the package in the `uds-bundle.yaml` must be unique -1. The duplicate packages must be deployed in different namespaces -1. In order to deploy duplicates of local packages, the `path` field must point to a Zarf package tarball instead of to a folder. +2. The duplicate packages must be deployed in different namespaces +3. In order to deploy duplicates of local packages, the `path` field must point to a Zarf package tarball instead of to a folder. -> [!NOTE] -> Today the duplicate packages feature is only supported for packages with Helm charts. This is because Helm charts' [namespaces can be overridden](docs/overrides.md#namespace) at deploy time. +{{% alert-note %}} +Today the duplicate packages feature is only supported for packages with Helm charts. This is because Helm charts' [namespaces can be overridden](https://github.com/defenseunicorns/uds-cli/blob/main/docs/overrides.md) at deploy time. +{{% /alert-note %}} ## Zarf Integration UDS CLI includes a vendored version of Zarf inside of its binary. To use Zarf, simply run `uds zarf `. For example, to create a Zarf package, run `uds zarf create `, or to use the [airgap tooling](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_tools) that Zarf provides, run `uds zarf tools `. ## Dev Mode -> [!NOTE] -> Dev mode is a BETA feature +{{% alert-caution %}} +Dev mode is a BETA feature +{{% /alert-caution %}} Dev mode facilitates faster dev cycles when developing and testing bundles @@ -290,9 +295,10 @@ The `dev deploy` command performs the following operations ## Scan -> [!NOTE] -> Scan is an ALPHA feature. -> Trivy is a prerequisite for scanning container images and filesystem for vulnerabilities. You can find more information and installation instructions at [Trivy's official documentation](https://aquasecurity.github.io/trivy). +{{% alert-caution %}} +Scan is an ALPHA feature. +Trivy is a prerequisite for scanning container images and filesystem for vulnerabilities. You can find more information and installation instructions at [Trivy's official documentation](https://aquasecurity.github.io/trivy). +{{% /alert-caution %}} The `scan` command is used to scan a Zarf package for vulnerabilities and generate a report. This command is currently in ALPHA. From a8c562404563b8b7dc21466aa6577b071cac6067 Mon Sep 17 00:00:00 2001 From: TristanHoladay <40547442+TristanHoladay@users.noreply.github.com> Date: Fri, 7 Jun 2024 11:12:53 -0600 Subject: [PATCH 19/26] link fix --- docs/quickstart-and-usage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/quickstart-and-usage.md b/docs/quickstart-and-usage.md index 3e99c58f..3196390a 100644 --- a/docs/quickstart-and-usage.md +++ b/docs/quickstart-and-usage.md @@ -202,7 +202,7 @@ packages: Variables that you want to make available to other packages are in the `export` block of the Zarf package to export a variable from. By default, all exported variables are available to all of the packages in a bundle. To have another package ingest a specific exported variable, like in the case of variable name collisions, use the `imports` key to name both the `variable` and `package` that the variable is exported from, like in the example above. -In the example above, the `OUTPUT` variable is created as part of a Zarf Action in the [output-var](https://github.com/defenseunicorns/uds-cli/tree/main/src/test/packages/no-cluster/output-var) package, and the [receive-var]([src/test/packages/zarf/no-cluster/receive-var](https://github.com/defenseunicorns/uds-cli/tree/main/src/test/packages/no-cluster/receive-var)) package expects a variable called `OUTPUT`. +In the example above, the `OUTPUT` variable is created as part of a Zarf Action in the [output-var](https://github.com/defenseunicorns/uds-cli/tree/main/src/test/packages/no-cluster/output-var) package, and the [receive-var](https://github.com/defenseunicorns/uds-cli/tree/main/src/test/packages/no-cluster/receive-var) package expects a variable called `OUTPUT`. ### Sharing Variables Across Multiple Packages If a Zarf variable has the same name in multiple packages and you don't want to set it multiple times via the import/export syntax, you can set an environment variable prefixed with `UDS_` and it will be applied to all the Zarf packages in a bundle. For example, if multiple packages require a `DOMAIN` variable, you could set it once with a `UDS_DOMAIN` environment variable and it would be applied to all packages. Note that this can also be done with the `shared` key in the `uds-config.yaml` file. From 079c4d3f71ad804f911371475930083fab969405 Mon Sep 17 00:00:00 2001 From: TristanHoladay <40547442+TristanHoladay@users.noreply.github.com> Date: Fri, 7 Jun 2024 12:35:35 -0600 Subject: [PATCH 20/26] lint fix --- docs/overrides.md | 6 +++--- docs/quickstart-and-usage.md | 20 ++++++++++---------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/overrides.md b/docs/overrides.md index 04fa8686..6948ec75 100644 --- a/docs/overrides.md +++ b/docs/overrides.md @@ -238,7 +238,7 @@ There are 3 ways to override the `UI_COLOR` variable: {{% alert-note %}} A variable that is not overridden by any of the methods above and has no default will be ignored. -{{% /alert-note %}} +{{% /alert-note %}} #### Variable Precedence Variable precedence is as follows: @@ -252,7 +252,7 @@ Variables can be of either type `raw` or `file`. The type will default to raw if {{% alert-caution %}} If a variable is set to accept a file as its value, but is missing the `file` type, then the file will not be processed. -{{% /alert-caution %}} +{{% /alert-caution %}} ```yaml kind: UDSBundle @@ -297,7 +297,7 @@ If the file path is already set to the same relative path as the config, then no UDS CLI does not encrypt or base64 encode any file contents before passing said data to Zarf or Helm. For example, if the file contains a key to be used in a Kubernetes secret, it must be base64 encoded before being ingested by UDS CLI. -{{% /alert-note %}} +{{% /alert-note %}} ### Namespace It's also possible to specify a namespace for a packaged Helm chart to be installed in. For example, to deploy the a chart in the `custom-podinfo` namespace, you can specify the `namespace` in the `overrides` block: diff --git a/docs/quickstart-and-usage.md b/docs/quickstart-and-usage.md index 3196390a..480db116 100644 --- a/docs/quickstart-and-usage.md +++ b/docs/quickstart-and-usage.md @@ -62,7 +62,7 @@ There are 2 ways to create Bundles: {{% alert-note %}} The `--insecure` flag is necessary when interacting with a local registry, but not from secure, remote registries such as GHCR. -{{% /alert-note %}} +{{% /alert-note %}} ### Bundle Deploy Deploys the bundle @@ -119,9 +119,9 @@ As an example: `uds remove uds-bundle-.tar.zst --packages init,nginx` ### Logs -{{% alert-note %}} +{{% alert-note %}} Only works with `uds deploy` for now, may work for other operations but isn't guaranteed. -{{% /alert-note %}} +{{% /alert-note %}} The `uds logs` command can be used to view the most recent logs of a bundle operation. Note that depending on your OS temporary directory and file settings, recent logs are purged after a certain amount of time, so this command may return an error if the logs are no longer available. @@ -139,9 +139,9 @@ UDS CLI supports multi-arch bundles. This means you can push bundles with differ ### Architecture Validation When deploying a local bundle, the bundle's architecture will be used for comparison against the cluster architecture to ensure compatability. If deploying a remote bundle, by default the bundle is pulled based on system architecture, which is then checked against the cluster. -{{% alert-note %}} +{{% alert-note %}} It is possible to override the bundle architecture used at validation time by using the `--architecture` / `-a` flag. -{{% /alert-note %}} +{{% /alert-note %}} If, for example, you have a multi-arch remote bundle that you want to deploy from an arm64 machine to an amd64 cluster, the validation with fail because the system arch does not match the cluster arch. However, you can pull the correct bundle version by specificying the arch with the command line architecture flag. @@ -265,9 +265,9 @@ The naming conventions for deploying duplicate packages are as follows: 2. The duplicate packages must be deployed in different namespaces 3. In order to deploy duplicates of local packages, the `path` field must point to a Zarf package tarball instead of to a folder. -{{% alert-note %}} +{{% alert-note %}} Today the duplicate packages feature is only supported for packages with Helm charts. This is because Helm charts' [namespaces can be overridden](https://github.com/defenseunicorns/uds-cli/blob/main/docs/overrides.md) at deploy time. -{{% /alert-note %}} +{{% /alert-note %}} ## Zarf Integration UDS CLI includes a vendored version of Zarf inside of its binary. To use Zarf, simply run `uds zarf `. For example, to create a Zarf package, run `uds zarf create `, or to use the [airgap tooling](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_tools) that Zarf provides, run `uds zarf tools `. @@ -276,7 +276,7 @@ UDS CLI includes a vendored version of Zarf inside of its binary. To use Zarf, s {{% alert-caution %}} Dev mode is a BETA feature -{{% /alert-caution %}} +{{% /alert-caution %}} Dev mode facilitates faster dev cycles when developing and testing bundles @@ -295,10 +295,10 @@ The `dev deploy` command performs the following operations ## Scan -{{% alert-caution %}} +{{% alert-caution %}} Scan is an ALPHA feature. Trivy is a prerequisite for scanning container images and filesystem for vulnerabilities. You can find more information and installation instructions at [Trivy's official documentation](https://aquasecurity.github.io/trivy). -{{% /alert-caution %}} +{{% /alert-caution %}} The `scan` command is used to scan a Zarf package for vulnerabilities and generate a report. This command is currently in ALPHA. From 7ef462458f47041cf0d62a6e9da2d9f66e4aab4f Mon Sep 17 00:00:00 2001 From: unclegedd Date: Fri, 7 Jun 2024 14:10:30 -0500 Subject: [PATCH 21/26] update dev mode docs --- docs/quickstart-and-usage.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/quickstart-and-usage.md b/docs/quickstart-and-usage.md index 480db116..52ab1447 100644 --- a/docs/quickstart-and-usage.md +++ b/docs/quickstart-and-usage.md @@ -274,9 +274,7 @@ UDS CLI includes a vendored version of Zarf inside of its binary. To use Zarf, s ## Dev Mode -{{% alert-caution %}} -Dev mode is a BETA feature -{{% /alert-caution %}} +NOTE: Dev mode is a BETA feature Dev mode facilitates faster dev cycles when developing and testing bundles @@ -284,21 +282,24 @@ Dev mode facilitates faster dev cycles when developing and testing bundles uds dev deploy | ``` -The `dev deploy` command performs the following operations +The `dev deploy` command performs the following operations: -- If local bundle: Creates Zarf packages for all local packages in a bundle - - Creates the Zarf tarball in the same directory as the `zarf.yaml` - - Will only create the Zarf tarball if one does not already exist - - Ignores any `kind: ZarfInitConfig` packages in the bundle - - Creates a bundle from the newly created Zarf packages - Deploys the bundle in [YOLO](https://docs.zarf.dev/faq/#what-is-yolo-mode-and-why-would-i-use-it) mode, eliminating the need to do a `zarf init` + - Any `kind: ZarfInitConfig` packages in the bundle will be ignored +- For local bundles: + - For local packages: + - Creates the Zarf tarball if one does not already exist or the `--force-create` flag can be used to force the creation of a new Zarf package + - The Zarf tarball is created in the same directory as the `zarf.yaml` + - The `--flavor` flag can be used to specify what flavor of a package you want to create (example: `--flavor podinfo=upstream` to specify the flavor for the `podinfo` package or `--flavor upstream` to specify the flavor for all the packages in the bundle) + - For remote packages: + - The `--ref` flag can be used to specify what package ref you want to deploy (example: `--ref podinfo=0.2.0`) + - Creates a bundle from the newly created Zarf packages ## Scan -{{% alert-caution %}} -Scan is an ALPHA feature. -Trivy is a prerequisite for scanning container images and filesystem for vulnerabilities. You can find more information and installation instructions at [Trivy's official documentation](https://aquasecurity.github.io/trivy). -{{% /alert-caution %}} +> [!NOTE] +> Scan is an ALPHA feature. +> Trivy is a prerequisite for scanning container images and filesystem for vulnerabilities. You can find more information and installation instructions at [Trivy's official documentation](https://aquasecurity.github.io/trivy). The `scan` command is used to scan a Zarf package for vulnerabilities and generate a report. This command is currently in ALPHA. From 3f87c5f9c64b40b850f9fe33f4f474a5d3714680 Mon Sep 17 00:00:00 2001 From: unclegedd Date: Fri, 7 Jun 2024 14:15:23 -0500 Subject: [PATCH 22/26] small docs --- docs/quickstart-and-usage.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/quickstart-and-usage.md b/docs/quickstart-and-usage.md index 52ab1447..4bbf6ca7 100644 --- a/docs/quickstart-and-usage.md +++ b/docs/quickstart-and-usage.md @@ -87,11 +87,11 @@ Inspect the `uds-bundle.yaml` of a bundle 1. From your local filesystem: `uds inspect uds-bundle-.tar.zst` #### Viewing Images in a Bundle -It is possible derive images from a `uds-bundle.yaml`. This can be useful for situations where you need to know what images will be bundled before you actually create the bundle. This is accomplished with the `--list-images`. For example: +It is possible to derive images from a `uds-bundle.yaml`. This can be useful for situations where you need to know what images will be bundled before you actually create the bundle. This is accomplished with the `--list-images` flag. For example: `uds inspect ./uds-bundle.yaml --list-images` -This command will return a list of images derived from the bundle's packages and taking into account optional and required package components. +This command will return a list of images derived from the bundle's packages, taking into account optional and required package components. #### Viewing SBOMs There are 2 additional flags for the `uds inspect` command you can use to extract and view SBOMs: @@ -143,7 +143,7 @@ When deploying a local bundle, the bundle's architecture will be used for compar It is possible to override the bundle architecture used at validation time by using the `--architecture` / `-a` flag. {{% /alert-note %}} -If, for example, you have a multi-arch remote bundle that you want to deploy from an arm64 machine to an amd64 cluster, the validation with fail because the system arch does not match the cluster arch. However, you can pull the correct bundle version by specificying the arch with the command line architecture flag. +If, for example, you have a multi-arch remote bundle that you want to deploy from an arm64 machine to an amd64 cluster, the validation with fail because the system arch does not match the cluster arch. However, you can pull the correct bundle version by specifying the arch with the command line architecture flag. e.g. `uds deploy -a amd64 --confirm` From 0d449635a84b2348d0164e8ab167f691adf5a364 Mon Sep 17 00:00:00 2001 From: unclegedd Date: Fri, 7 Jun 2024 14:32:34 -0500 Subject: [PATCH 23/26] edits readme --- go.mod | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/go.mod b/go.mod index 1e053ec3..c5676959 100644 --- a/go.mod +++ b/go.mod @@ -1,8 +1,6 @@ module github.com/defenseunicorns/uds-cli -go 1.22.1 - -toolchain go1.22.3 +go 1.22.3 require ( github.com/AlecAivazis/survey/v2 v2.3.7 From 8ed17c9b3f75e78fb7ac05934d64558a97acd847 Mon Sep 17 00:00:00 2001 From: unclegedd Date: Mon, 10 Jun 2024 10:37:54 -0500 Subject: [PATCH 24/26] docs --- README.md | 31 +++++++++------- docs/overrides.md | 1 + docs/quickstart-and-usage.md | 72 +++++++++++++++++++++++++++--------- 3 files changed, 74 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index ab0061f5..36a6f2d2 100644 --- a/README.md +++ b/README.md @@ -94,8 +94,9 @@ There are 2 ways to create Bundles: 1. Inside an OCI registry: `uds create -o ghcr.io/defenseunicorns/dev` 1. Locally on your filesystem: `uds create ` -> [!NOTE] -> The `--insecure` flag is necessary when interacting with a local registry, but not from secure, remote registries such as GHCR. +{{% alert-note %}} +The `--insecure` flag is necessary when interacting with a local registry, but not from secure, remote registries such as GHCR. +{{% /alert-note %}} ### Bundle Deploy @@ -164,8 +165,9 @@ As an example: `uds remove uds-bundle-.tar.zst --packages init,nginx` ### Logs -> [!NOTE] -> Only works with `uds deploy` for now, may work for other operations but isn't guaranteed. +{{% alert-note %}} +Only works with `uds deploy` for now, may work for other operations but isn't guaranteed. +{{% /alert-note %}} The `uds logs` command can be used to view the most recent logs of a bundle operation. Note that depending on your OS temporary directory and file settings, recent logs are purged after a certain amount of time, so this command may return an error if the logs are no longer available. @@ -186,8 +188,9 @@ UDS CLI supports multi-arch bundles. This means you can push bundles with differ When deploying a local bundle, the bundle's architecture will be used for comparison against the cluster architecture to ensure compatibility. If deploying a remote bundle, by default the bundle is pulled based on system architecture, which is then checked against the cluster. -> [!NOTE] -> It is possible to override the bundle architecture used at validation time by using the `--architecture` / `-a` flag. +{{% alert-note %}} +It is possible to override the bundle architecture used at validation time by using the `--architecture` / `-a` flag. +{{% /alert-note %}} If, for example, you have a multi-arch remote bundle that you want to deploy from an arm64 machine to an amd64 cluster, the validation with fail because the system arch does not match the cluster arch. However, you can pull the correct bundle version by specifying the arch with the command line architecture flag. @@ -317,8 +320,9 @@ The naming conventions for deploying duplicate packages are as follows: 1. The duplicate packages must be deployed in different namespaces 1. In order to deploy duplicates of local packages, the `path` field must point to a Zarf package tarball instead of to a folder. -> [!NOTE] -> Today the duplicate packages feature is only supported for packages with Helm charts. This is because Helm charts' [namespaces can be overridden](docs/overrides.md#namespace) at deploy time. +{{% alert-note %}} +Today the duplicate packages feature is only supported for packages with Helm charts. This is because Helm charts' [namespaces can be overridden](docs/overrides.md#namespace) at deploy time. +{{% /alert-note %}} ## Zarf Integration @@ -326,8 +330,9 @@ UDS CLI includes a vendored version of Zarf inside of its binary. To use Zarf, s ## Dev Mode -> [!NOTE] -> Dev mode is a BETA feature +{{% alert-note %}} +Dev mode is a BETA feature +{{% /alert-note %}} Dev mode facilitates faster dev cycles when developing and testing bundles @@ -350,9 +355,9 @@ The `dev deploy` command performs the following operations: ## Scan -> [!NOTE] -> Scan is an ALPHA feature. -> Trivy is a prerequisite for scanning container images and filesystem for vulnerabilities. You can find more information and installation instructions at [Trivy's official documentation](https://aquasecurity.github.io/trivy). +{{% alert-note %}}> Scan is an ALPHA feature. +Trivy is a prerequisite for scanning container images and filesystem for vulnerabilities. You can find more information and installation instructions at [Trivy's official documentation](https://aquasecurity.github.io/trivy). +{{% /alert-note %}} The `scan` command is used to scan a Zarf package for vulnerabilities and generate a report. This command is currently in ALPHA. diff --git a/docs/overrides.md b/docs/overrides.md index 6948ec75..954b266b 100644 --- a/docs/overrides.md +++ b/docs/overrides.md @@ -146,6 +146,7 @@ The `value` is the value to set at the `path`. Values can be simple values such ``` #### Bundle Variables as Values + Bundle and Zarf variables can be used to set override values by using the syntax `${...}`. For example: ```yaml # uds-config.yaml diff --git a/docs/quickstart-and-usage.md b/docs/quickstart-and-usage.md index 4bbf6ca7..4b421330 100644 --- a/docs/quickstart-and-usage.md +++ b/docs/quickstart-and-usage.md @@ -5,16 +5,21 @@ weight: 1 --- ## Install + Recommended installation method is with Brew: + ``` brew tap defenseunicorns/tap && brew install uds ``` + UDS CLI Binaries are also included with each [Github Release](https://github.com/defenseunicorns/uds-cli/releases) ## Contributing + Build instructions and contributing docs are located in [CONTRIBUTING.md](https://github.com/defenseunicorns/uds-cli/blob/main/CONTRIBUTING.md). ## Quickstart + The UDS-CLI's flagship feature is deploying multiple, independent Zarf packages. To create a `UDSBundle` of Zarf packages, create a `uds-bundle.yaml` file like so: ```yaml @@ -34,59 +39,73 @@ packages: repository: ghcr.io/defenseunicorns/uds-cli/podinfo ref: 0.0.1 ``` + The above `UDSBundle` deploys the Zarf init package and podinfo. The packages referenced in `packages` can exist either locally or in an OCI registry. See [here](https://github.com/defenseunicorns/uds-cli/tree/main/src/test/bundles/03-local-and-remote) for an example that deploys both local and remote Zarf packages. More `UDSBundle` examples can be found in the [src/test/bundles](https://github.com/defenseunicorns/uds-cli/tree/main/src/test/bundles) folder. #### Declarative Syntax + The syntax of a `uds-bundle.yaml` is entirely declarative. As a result, the UDS CLI will not prompt users to deploy optional components in a Zarf package. If you want to deploy an optional Zarf component, it must be specified in the `optionalComponents` key of a particular `package`. #### First-class UDS Support + When running `deploy`,`inspect`,`remove`, and `pull` commands, UDS CLI contains shorthand for interacting with the Defense Unicorns org on GHCR. Specifically, unless otherwise specified, paths will automatically be expanded to the Defense Unicorns org on GHCR. For example: + - `uds deploy unicorn-bundle:v0.1.0` is equivalent to `uds deploy ghcr.io/defenseunicorns/packages/uds/bundles/unicorn-bundle:v0.1.0` The bundle matching and expansion is ordered as follows: + 1. Local with a `tar.zst` extension 2. Remote path: `oci://ghcr.io/defenseunicorns/packages/uds/bundles/` 3. Remote path: `oci://ghcr.io/defenseunicorns/packages/delivery/` 4. Remote path: `oci://ghcr.io/defenseunicorns/packages/` -That is to say, if the bundle is not local, UDS CLI will check path 2, path 3, etc for the remote bundle artifact. This behavior can be overriden by specifying the full path to the bundle artifact, for example `uds deploy ghcr.io/defenseunicorns/dev/path/dev-bundle:v0.1.0`. +That is to say, if the bundle is not local, UDS CLI will check path 2, path 3, etc for the remote bundle artifact. This behavior can be overridden by specifying the full path to the bundle artifact, for example `uds deploy ghcr.io/defenseunicorns/dev/path/dev-bundle:v0.1.0`. ### Bundle Create + Pulls the Zarf packages from the registry and bundles them into an OCI artifact. There are 2 ways to create Bundles: + 1. Inside an OCI registry: `uds create -o ghcr.io/defenseunicorns/dev` 1. Locally on your filesystem: `uds create ` -{{% alert-note %}} +{{% alert-note %}} The `--insecure` flag is necessary when interacting with a local registry, but not from secure, remote registries such as GHCR. {{% /alert-note %}} ### Bundle Deploy + Deploys the bundle There are 2 ways to deploy Bundles: + 1. From an OCI registry: `uds deploy ghcr.io/defenseunicorns/dev/:` 1. From your local filesystem: `uds deploy uds-bundle-.tar.zst` #### Specifying Packages using `--packages` + By default all the packages in the bundle are deployed, but you can also deploy only certain packages in the bundle by using the `--packages` flag. As an example: `uds deploy uds-bundle-.tar.zst --packages init,nginx` #### Resuming Bundle Deploys using `--resume` + By default all the packages in the bundle are deployed, regardless of if they have already been deployed, but you can also choose to only deploy packages that have not already been deployed by using the `--resume` flag As an example: `uds deploy uds-bundle-.tar.zst --resume` ### Bundle Inspect + Inspect the `uds-bundle.yaml` of a bundle + 1. From an OCI registry: `uds inspect oci://ghcr.io/defenseunicorns/dev/:` 1. From your local filesystem: `uds inspect uds-bundle-.tar.zst` #### Viewing Images in a Bundle + It is possible to derive images from a `uds-bundle.yaml`. This can be useful for situations where you need to know what images will be bundled before you actually create the bundle. This is accomplished with the `--list-images` flag. For example: `uds inspect ./uds-bundle.yaml --list-images` @@ -94,22 +113,27 @@ It is possible to derive images from a `uds-bundle.yaml`. This can be useful for This command will return a list of images derived from the bundle's packages, taking into account optional and required package components. #### Viewing SBOMs + There are 2 additional flags for the `uds inspect` command you can use to extract and view SBOMs: + - Output the SBOMs as a tar file: `uds inspect ... --sbom` - Output SBOMs into a directory as files: `uds inspect ... --sbom --extract` This functionality will use the `sboms.tar` of the underlying Zarf packages to create new a `bundle-sboms.tar` artifact containing all SBOMs from the Zarf packages in the bundle. ### Bundle Publish + Local bundles can be published to an OCI registry like so: -`uds publish .tar.zst oci:// ` +`uds publish .tar.zst oci://` As an example: `uds publish uds-bundle-example-arm64-0.0.1.tar.zst oci://ghcr.io/github_user` ### Bundle Remove + Removes the bundle There are 2 ways to remove Bundles: + 1. From an OCI registry: `uds remove oci://ghcr.io/defenseunicorns/dev/: --confirm` 1. From your local filesystem: `uds remove uds-bundle-.tar.zst --confirm` @@ -126,7 +150,9 @@ Only works with `uds deploy` for now, may work for other operations but isn't gu The `uds logs` command can be used to view the most recent logs of a bundle operation. Note that depending on your OS temporary directory and file settings, recent logs are purged after a certain amount of time, so this command may return an error if the logs are no longer available. ## Bundle Architecture and Multi-Arch Support + There are several ways to specify the architecture of a bundle according to the following precedence: + 1. Setting `--architecture` or `-a` flag during `uds ...` operations: `uds create --architecture arm64` 2. Setting a `UDS_ARCHITECTURE` environment variable 3. Setting the `options.architecture` key in a `uds-config.yaml` @@ -137,7 +163,8 @@ This means that setting the `--architecture` flag takes precedence over all othe UDS CLI supports multi-arch bundles. This means you can push bundles with different architectures to the same remote OCI repository, at the same tag. For example, you can push both an `amd64` and `arm64` bundle to `ghcr.io//:0.0.1`. ### Architecture Validation -When deploying a local bundle, the bundle's architecture will be used for comparison against the cluster architecture to ensure compatability. If deploying a remote bundle, by default the bundle is pulled based on system architecture, which is then checked against the cluster. + +When deploying a local bundle, the bundle's architecture will be used for comparison against the cluster architecture to ensure compatibility. If deploying a remote bundle, by default the bundle is pulled based on system architecture, which is then checked against the cluster. {{% alert-note %}} It is possible to override the bundle architecture used at validation time by using the `--architecture` / `-a` flag. @@ -148,8 +175,9 @@ If, for example, you have a multi-arch remote bundle that you want to deploy fro e.g. `uds deploy -a amd64 --confirm` -## Configuration +## Variables and Configuration The UDS CLI can be configured with a `uds-config.yaml` file. This file can be placed in the current working directory or specified with an environment variable called `UDS_CONFIG`. The basic structure of the `uds-config.yaml` is as follows: + ```yaml options: log_level: debug @@ -174,11 +202,12 @@ variables: - path: "/" pathType: "Prefix" ``` + The `options` key contains UDS CLI options that are not specific to a particular Zarf package. The `variables` key contains variables that are specific to a particular Zarf package. If you want to share insensitive variables across multiple Zarf packages, you can use the `shared` key, where the key is the variable name and the value is the variable value. -## Sharing Variables -### Importing/Exporting Variables +### Sharing Variables Zarf package variables can be passed between Zarf packages: + ```yaml kind: UDSBundle metadata: @@ -205,13 +234,16 @@ Variables that you want to make available to other packages are in the `export` In the example above, the `OUTPUT` variable is created as part of a Zarf Action in the [output-var](https://github.com/defenseunicorns/uds-cli/tree/main/src/test/packages/no-cluster/output-var) package, and the [receive-var](https://github.com/defenseunicorns/uds-cli/tree/main/src/test/packages/no-cluster/receive-var) package expects a variable called `OUTPUT`. ### Sharing Variables Across Multiple Packages + If a Zarf variable has the same name in multiple packages and you don't want to set it multiple times via the import/export syntax, you can set an environment variable prefixed with `UDS_` and it will be applied to all the Zarf packages in a bundle. For example, if multiple packages require a `DOMAIN` variable, you could set it once with a `UDS_DOMAIN` environment variable and it would be applied to all packages. Note that this can also be done with the `shared` key in the `uds-config.yaml` file. On deploy, you can also set package variables by using the `--set` flag. If the package name isn't included in the key (example: `--set super=true`) the variable will get applied to all of the packages. If the package name is included in the key (example: `--set cool-package.super=true`) the variable will only get applied to that package. ### Variable Precedence and Specificity + In a bundle, variables can come from 4 sources. Those sources and their precedence are shown below in order of least to most specificity: + - Variables declared in a Zarf pkg - Variables `import`'ed from a bundle package's `export` - Variables configured in the `shared` key in a `uds-config.yaml` @@ -221,10 +253,10 @@ In a bundle, variables can come from 4 sources. Those sources and their preceden That is to say, variables set using the `--set` flag take precedence over all other variable sources. - ## Duplicate Packages And Naming -It is possible to deploy multiple instances of the same Zarf package in a bundle. For example, the following `uds-bundle.yaml` deploys 3 instances of the [helm-overrides](https://github.com/defenseunicorns/uds-cli/blob/main/src/test/packages/helm/zarf.yaml) Zarf packags: +It is possible to deploy multiple instances of the same Zarf package in a bundle. For example, the following `uds-bundle.yaml` deploys 3 instances of the [helm-overrides](https://github.com/defenseunicorns/uds-cli/blob/main/src/test/packages/helm/zarf.yaml) Zarf packages: + ```yaml kind: UDSBundle metadata: @@ -261,24 +293,28 @@ packages: ``` The naming conventions for deploying duplicate packages are as follows: + 1. The `name` field of the package in the `uds-bundle.yaml` must be unique -2. The duplicate packages must be deployed in different namespaces -3. In order to deploy duplicates of local packages, the `path` field must point to a Zarf package tarball instead of to a folder. +1. The duplicate packages must be deployed in different namespaces +1. In order to deploy duplicates of local packages, the `path` field must point to a Zarf package tarball instead of to a folder. {{% alert-note %}} Today the duplicate packages feature is only supported for packages with Helm charts. This is because Helm charts' [namespaces can be overridden](https://github.com/defenseunicorns/uds-cli/blob/main/docs/overrides.md) at deploy time. {{% /alert-note %}} ## Zarf Integration + UDS CLI includes a vendored version of Zarf inside of its binary. To use Zarf, simply run `uds zarf `. For example, to create a Zarf package, run `uds zarf create `, or to use the [airgap tooling](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_tools) that Zarf provides, run `uds zarf tools `. ## Dev Mode -NOTE: Dev mode is a BETA feature +{{% alert-note %}} +Dev mode is a BETA feature +{{% /alert-note %}} Dev mode facilitates faster dev cycles when developing and testing bundles -``` +```sh uds dev deploy | ``` @@ -297,10 +333,9 @@ The `dev deploy` command performs the following operations: ## Scan -> [!NOTE] -> Scan is an ALPHA feature. -> Trivy is a prerequisite for scanning container images and filesystem for vulnerabilities. You can find more information and installation instructions at [Trivy's official documentation](https://aquasecurity.github.io/trivy). - +{{% alert-note %}}> Scan is an ALPHA feature. +Trivy is a prerequisite for scanning container images and filesystem for vulnerabilities. You can find more information and installation instructions at [Trivy's official documentation](https://aquasecurity.github.io/trivy). +{{% /alert-note %}} The `scan` command is used to scan a Zarf package for vulnerabilities and generate a report. This command is currently in ALPHA. @@ -313,16 +348,19 @@ uds scan --org --package-name --tag [options ``` ### Required Parameters + - `--org` or `-o`: Organization name (default: `defenseunicorns`) - `--package-name` or `-n`: Name of the package (e.g., `packages/uds/gitlab-runner`) - `--tag` or `-g`: Tag name (e.g., `16.10.0-uds.0-upstream`) - `--output-file` or `-f`: Output file for CSV results ### Optional Parameters + - `--docker-username` or `-u`: Docker username for registry access, accepts CSV values - `--docker-password` or `-p`: Docker password for registry access, accepts CSV values ### Example Usage + ```sh uds scan -o defenseunicorns -n packages/uds/gitlab-runner -g 16.10.0-uds.0-upstream -u docker-username -p docker-password -f gitlab-runner.csv ``` From c3aecc5a5596b86aaa253e5377df95d93e6f39b1 Mon Sep 17 00:00:00 2001 From: unclegedd Date: Mon, 10 Jun 2024 10:40:36 -0500 Subject: [PATCH 25/26] no guide --- docs/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_index.md b/docs/_index.md index a2252ce0..634261dc 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -1,6 +1,6 @@ --- title: Overview -linkTitle: UDS CLI Guide +linkTitle: UDS CLI type: docs menu: main: From 81fe2235e7f548e7697dad89a7c4bd3583422994 Mon Sep 17 00:00:00 2001 From: unclegedd Date: Mon, 10 Jun 2024 10:44:04 -0500 Subject: [PATCH 26/26] fix link --- docs/overrides.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/overrides.md b/docs/overrides.md index 954b266b..240c17b5 100644 --- a/docs/overrides.md +++ b/docs/overrides.md @@ -283,7 +283,7 @@ packages: If a file path is not absolute, it will be set as relative to the `uds-config.yaml` directory. -e.g. the following `uds-config.yaml` is in [`src/test/bundles/07-helm-overrides/variable-files/`](https://github.com/defenseunicorns/uds-cli/blob/uds-cli-docs/src/test/bundles/07-helm-overrides/uds-config.yaml) +e.g. the following `uds-config.yaml` is in [`src/test/bundles/07-helm-overrides/variable-files/`](https://github.com/defenseunicorns/uds-cli/blob/main/src/test/bundles/07-helm-overrides/uds-config.yaml) ```yaml variables: helm-overrides: