From 5c9ea31d64b32740bb0de66ca7ad474edb676124 Mon Sep 17 00:00:00 2001 From: Wayne Starr Date: Tue, 12 Jul 2022 22:17:33 -0500 Subject: [PATCH] generate docs from zarf schema json (#614) --- .github/workflows/zarf-schema-check.yml | 37 + .hooks/jsfh-config.json | 6 + .hooks/verify-zarf-schema.sh | 1 + .hooks/zarf-jsfh-template/base.md | 16 + .hooks/zarf-jsfh-template/breadcrumbs.md | 9 + .hooks/zarf-jsfh-template/content.md | 93 ++ .hooks/zarf-jsfh-template/section_array.md | 23 + .../section_conditional_subschema.md | 24 + .../zarf-jsfh-template/section_description.md | 4 + .hooks/zarf-jsfh-template/section_examples.md | 8 + .hooks/zarf-jsfh-template/section_not.md | 4 + .hooks/zarf-jsfh-template/section_one_of.md | 6 + .../section_properties_details.md | 43 + ...ection_undocumented_required_properties.md | 7 + .hooks/zarf-jsfh-template/tabbed_section.md | 19 + .../2-zarf-packages/1-zarf-packages.md | 11 +- .../2-zarf-packages/2-zarf-components.md | 88 +- docs/4-user-guide/3-zarf-schema.md | 1238 +++++++++++++++++ 18 files changed, 1543 insertions(+), 94 deletions(-) create mode 100644 .github/workflows/zarf-schema-check.yml create mode 100644 .hooks/jsfh-config.json create mode 100644 .hooks/zarf-jsfh-template/base.md create mode 100644 .hooks/zarf-jsfh-template/breadcrumbs.md create mode 100644 .hooks/zarf-jsfh-template/content.md create mode 100644 .hooks/zarf-jsfh-template/section_array.md create mode 100644 .hooks/zarf-jsfh-template/section_conditional_subschema.md create mode 100644 .hooks/zarf-jsfh-template/section_description.md create mode 100644 .hooks/zarf-jsfh-template/section_examples.md create mode 100644 .hooks/zarf-jsfh-template/section_not.md create mode 100644 .hooks/zarf-jsfh-template/section_one_of.md create mode 100644 .hooks/zarf-jsfh-template/section_properties_details.md create mode 100644 .hooks/zarf-jsfh-template/section_undocumented_required_properties.md create mode 100644 .hooks/zarf-jsfh-template/tabbed_section.md create mode 100644 docs/4-user-guide/3-zarf-schema.md diff --git a/.github/workflows/zarf-schema-check.yml b/.github/workflows/zarf-schema-check.yml new file mode 100644 index 0000000000..d13eaf649b --- /dev/null +++ b/.github/workflows/zarf-schema-check.yml @@ -0,0 +1,37 @@ +name: zarf-schema-check +on: + pull_request: + paths: + - "src/types/**" + - "zarf.schema.json" + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - name: "Install GoLang" + uses: actions/setup-go@v3 + with: + go-version: 1.18.x + + - name: "Checkout Repo" + uses: actions/checkout@v3 + + - name: "Setup caching" + uses: actions/cache@v3 + with: + path: | + ~/.cache/go-build + ~/go/pkg/mod + key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }} + restore-keys: | + ${{ runner.os }}-go- + + - name: "Backup Repo Schema Version" + run: 'cp zarf.schema.json zarf.schema.json.bak' + + - name: "Regenerate Schema" + run: 'go run main.go tools config-schema > zarf.schema.json' + + - name: "Compare Schemas" + run: 'cmp -s zarf.schema.json zarf.schema.json.bak' diff --git a/.hooks/jsfh-config.json b/.hooks/jsfh-config.json new file mode 100644 index 0000000000..61cac2ed1b --- /dev/null +++ b/.hooks/jsfh-config.json @@ -0,0 +1,6 @@ +{ + "custom_template_path": ".hooks/zarf-jsfh-template/base.md", + "template_md_options": { "badge_as_image": true, "show_heading_numbers": false }, + "show_toc": false, + "show_breadcrumbs": false +} diff --git a/.hooks/verify-zarf-schema.sh b/.hooks/verify-zarf-schema.sh index bf3a13f1f7..4982675168 100755 --- a/.hooks/verify-zarf-schema.sh +++ b/.hooks/verify-zarf-schema.sh @@ -1,2 +1,3 @@ #!/usr/bin/env sh go run main.go tools config-schema > zarf.schema.json +docker run -it -v $(pwd):/app -w /app --rm python:3.8-alpine /bin/sh -c "pip install json-schema-for-humans && generate-schema-doc --config-file .hooks/jsfh-config.json zarf.schema.json docs/4-user-guide/3-zarf-schema.md" diff --git a/.hooks/zarf-jsfh-template/base.md b/.hooks/zarf-jsfh-template/base.md new file mode 100644 index 0000000000..460220fc03 --- /dev/null +++ b/.hooks/zarf-jsfh-template/base.md @@ -0,0 +1,16 @@ +{% set depth = 0 %} +{{ schema.keywords.get("title").literal | default("Zarf Package Schema") | md_heading(depth) }} +{% set contentBase %} +{% with schema=schema, skip_headers=False, depth=depth %} + {% include "content.md" %} +{% endwith %} +{% endset %} + +{{ md_get_toc() }} + +{{ contentBase }} + +---------------------------------------------------------------------------------------------------------------------------- +{% if config.with_footer -%} +Generated from [zarf.schema.json](https://github.com/defenseunicorns/zarf/blob/master/zarf.schema.json){% if config.footer_show_time %} on {{ get_local_time() }}{% endif %} +{%- endif -%} diff --git a/.hooks/zarf-jsfh-template/breadcrumbs.md b/.hooks/zarf-jsfh-template/breadcrumbs.md new file mode 100644 index 0000000000..099479b487 --- /dev/null +++ b/.hooks/zarf-jsfh-template/breadcrumbs.md @@ -0,0 +1,9 @@ +{% filter md_escape_for_table %} +{%- if config.show_breadcrumbs %} + {%- for node in schema.nodes_from_root -%} + {{ node.name_for_breadcrumbs }}{%- if not loop.last %} > {% endif -%} + {%- endfor -%} +{%- else -%} + {{- schema.name_for_breadcrumbs or schema.property_name -}} +{% endif %} +{% endfilter %} diff --git a/.hooks/zarf-jsfh-template/content.md b/.hooks/zarf-jsfh-template/content.md new file mode 100644 index 0000000000..923dadd8cf --- /dev/null +++ b/.hooks/zarf-jsfh-template/content.md @@ -0,0 +1,93 @@ +{# + content is a template and not a macro in md + because macro parameters are not through context + when rendering a template from the macro and it caused + serious problems when using recursive calls + mandatory context parameters: + schema +#} +{# context parameters default values #} +{% set skip_headers = skip_headers or False %} +{% set depth = depth or 0 %} +{# end context parameters #} + +{% set keys = schema.keywords %} +{%- if not skip_headers %} + +{% if schema.title and schema.title | length > 0 %} +**Title:** {{ schema.title }} +{% endif %} + +{% set description = (schema | get_description) %} +{% include "section_description.md" %} + +{{ schema | md_type_info_table | md_generate_table }} + +{% endif %} + +{% if schema.should_be_a_link(config) %} +{% elif schema.refers_to -%} + {%- with schema=schema.refers_to_merged, skip_headers=True, depth=depth -%} + {% include "content.md" %} + {% endwith %} +{% else %} + + {# Combining: allOf, anyOf, oneOf, not #} + {% if schema.kw_all_of %} + {% with operator="allOf", title="All of(Requirement)", current_node=schema.kw_all_of, skip_required=True %} + {% include "tabbed_section.md" %} + {% endwith %} + {% endif %} + {% if schema.kw_any_of %} + {% with operator="anyOf", title="Any of(Option)", current_node=schema.kw_any_of, skip_required=True %} + {% include "tabbed_section.md" %} + {% endwith %} + {% endif %} + {% if schema.kw_one_of %} + {% with operator="oneOf", title="One of(Option)",current_node=schema.kw_one_of, skip_required=True %} + {% include "tabbed_section.md" %} + {% endwith %} + {% endif %} + {% if schema.kw_not %} + {% include "section_not.md" %} + {% endif %} + + {# Enum and const #} + {% if schema.kw_enum -%} + {% include "section_one_of.md" %} + {%- endif %} + {%- if schema.kw_const -%} + Specific value: `{{ schema.kw_const.raw | python_to_json }}` + {%- endif -%} + + {# Conditional subschema, or if-then-else section #} + {% if schema.has_conditional %} + {% with skip_headers=False, depth=depth+1 %} + {% include "section_conditional_subschema.md" %} + {% endwith %} + {% endif %} + + {# Required properties that are not defined under "properties". They will only be listed #} + {% include "section_undocumented_required_properties.md" %} + + {# Show the requested type(s) #} + {{- schema | md_restrictions_table | md_generate_table -}} + + {# Show array restrictions #} + {% if schema.type_name.startswith("array") %} + {% include "section_array.md" %} + {% endif %} + + {# Display examples #} + {% set examples = schema.examples %} + {% if examples %} + {% include "section_examples.md" %} + {% endif %} + + {# details of Properties, pattern properties, additional properties #} + {% if schema.type_name == "object" %} + {% with skip_required=False %} + {% include "section_properties_details.md" %} + {% endwith %} + {% endif %} +{% endif %} diff --git a/.hooks/zarf-jsfh-template/section_array.md b/.hooks/zarf-jsfh-template/section_array.md new file mode 100644 index 0000000000..5c7367946b --- /dev/null +++ b/.hooks/zarf-jsfh-template/section_array.md @@ -0,0 +1,23 @@ +{{ schema | md_array_restrictions | md_generate_table }} + +{% if schema.array_items_def %} {% filter md_heading(depth+1) %} {% with schema=schema.array_items_def %}{%- include "breadcrumbs.md" %}{% endwith %} {% endfilter %} {% with schema=schema.array_items_def, skip_headers=False, skip_required=True %} {% include "content.md" %} {% endwith %} {% endif %} + +{% if schema.kw_items %} +{{ schema | md_array_items_restrictions | md_generate_table }} + +{% for item in schema.kw_items %} + {% filter md_heading(depth+1, item.html_id) %} + {% with schema=item %}{%- include "breadcrumbs.md" %}{% endwith %} + {% endfilter %} + {% with schema=item, skip_headers=False, skip_required=True %} + {% include "content.md" %} + {% endwith %} +{% endfor %} +{% endif %} + +{% if schema.kw_contains and schema.kw_contains.literal != {} %} +{{ "At least one of the items must be" | md_heading(depth+1) }} +{% with schema=schema.kw_contains, skip_headers=False, skip_required=True %} + {% include "content.md" %} +{% endwith %} +{% endif %} diff --git a/.hooks/zarf-jsfh-template/section_conditional_subschema.md b/.hooks/zarf-jsfh-template/section_conditional_subschema.md new file mode 100644 index 0000000000..fdcc2c4055 --- /dev/null +++ b/.hooks/zarf-jsfh-template/section_conditional_subschema.md @@ -0,0 +1,24 @@ +{% if schema.kw_if %} + {% set first_property = schema.kw_if | get_first_property %} + + {% if schema.kw_then %} + {%- filter md_heading(depth) -%}If ( + {{- first_property.property_name | md_escape_for_table -}} + {{- " = " -}} + {{- first_property.kw_const.literal | python_to_json -}} + ){%- endfilter -%} + {% with schema=schema.kw_then, skip_headers=False, depth=depth %} + {% include "content.md" %} + {% endwith %} + {% endif %} + {% if schema.kw_else %} + {%- filter md_heading(depth) -%}Else (i.e. {{ " " }} + {{- first_property.property_name | md_escape_for_table -}} + {{- " != " -}} + {{- first_property.kw_const.literal | python_to_json -}} + ){%- endfilter -%} + {% with schema=schema.kw_else, skip_headers=False, depth=depth %} + {% include "content.md" %} + {% endwith %} + {% endif %} +{% endif %} diff --git a/.hooks/zarf-jsfh-template/section_description.md b/.hooks/zarf-jsfh-template/section_description.md new file mode 100644 index 0000000000..77cb9bfe9b --- /dev/null +++ b/.hooks/zarf-jsfh-template/section_description.md @@ -0,0 +1,4 @@ +{# Display description #} +{% if description %} +**Description:**{{ " " }}{{ description }} +{% endif %} diff --git a/.hooks/zarf-jsfh-template/section_examples.md b/.hooks/zarf-jsfh-template/section_examples.md new file mode 100644 index 0000000000..ab04436813 --- /dev/null +++ b/.hooks/zarf-jsfh-template/section_examples.md @@ -0,0 +1,8 @@ +**Example{% if examples|length > 1 %}s{% endif %}:**{{ " " }} + +{% for example in examples %} +{% set example_id = schema.html_id ~ "_ex" ~ loop.index %} +```json +{{ example }} +``` +{% endfor %} diff --git a/.hooks/zarf-jsfh-template/section_not.md b/.hooks/zarf-jsfh-template/section_not.md new file mode 100644 index 0000000000..b5be138302 --- /dev/null +++ b/.hooks/zarf-jsfh-template/section_not.md @@ -0,0 +1,4 @@ +{{ "Must **not** be" | md_heading(depth+1) }} +{% with schema=schema.kw_not, skip_headers=False, depth=depth+1, skip_required=True %} + {% include "content.md" %} +{% endwith %} diff --git a/.hooks/zarf-jsfh-template/section_one_of.md b/.hooks/zarf-jsfh-template/section_one_of.md new file mode 100644 index 0000000000..08dde2cc57 --- /dev/null +++ b/.hooks/zarf-jsfh-template/section_one_of.md @@ -0,0 +1,6 @@ +:::note +Must be one of: +{% for enum_choice in schema.kw_enum.array_items %} +* {{ enum_choice.literal | python_to_json }} +{% endfor %} +::: diff --git a/.hooks/zarf-jsfh-template/section_properties_details.md b/.hooks/zarf-jsfh-template/section_properties_details.md new file mode 100644 index 0000000000..9c1085126f --- /dev/null +++ b/.hooks/zarf-jsfh-template/section_properties_details.md @@ -0,0 +1,43 @@ +{% for sub_property in schema.iterate_properties %} + {%- if sub_property.is_additional_properties and not sub_property.is_additional_properties_schema -%} + {% continue %} + {% endif %} + + {% set html_id = sub_property.html_id %} + + {% set description = sub_property | get_description %} +
+{% filter md_heading(depth + 1, html_id, True) -%} + {%- filter replace('\n', '') -%} + {%- if sub_property is deprecated -%}~~{%- endif -%} + {%- if sub_property.is_pattern_property %} Pattern Property{% endif %} {% with schema=sub_property %}{%- include "breadcrumbs.md" %} {% endwith %} + {%- if not skip_required and sub_property.property_name -%} + {{ "*" if sub_property.is_required_property else "" -}} + {%- endif -%} + {%- if sub_property is deprecated -%}~~{%- endif -%} + {%- endfilter %} + {%- endfilter %} + + + +  +
+ + {% with schema=sub_property, skip_headers=False %} + {% if sub_property.is_pattern_property %} +:::note +All properties whose name matches the regular expression +```{{ sub_property.property_name }}``` ([Test](https://regex101.com/?regex={{ sub_property.property_name | urlencode }})) +must respect the following conditions +::: + {% endif %} + {%- if not skip_required and sub_property.property_name -%} + {{ md_badge("Required", "red", show_text=False) if sub_property.is_required_property else "" -}} + {%- endif -%} + {% include "content.md" %} + {% endwith %} + +
+
+ +{% endfor %} diff --git a/.hooks/zarf-jsfh-template/section_undocumented_required_properties.md b/.hooks/zarf-jsfh-template/section_undocumented_required_properties.md new file mode 100644 index 0000000000..0c0a6772c0 --- /dev/null +++ b/.hooks/zarf-jsfh-template/section_undocumented_required_properties.md @@ -0,0 +1,7 @@ +{% set undocumented_required_properties = schema | get_undocumented_required_properties %} +{% if undocumented_required_properties%} +{{ "The following properties are required" | md_heading(depth+1) }} +{% for required_property in undocumented_required_properties %} +* {{ required_property }} +{% endfor %} +{% endif %} diff --git a/.hooks/zarf-jsfh-template/tabbed_section.md b/.hooks/zarf-jsfh-template/tabbed_section.md new file mode 100644 index 0000000000..8dce1feb86 --- /dev/null +++ b/.hooks/zarf-jsfh-template/tabbed_section.md @@ -0,0 +1,19 @@ +
+ +{{ current_node | md_array_items(title) | md_generate_table }} + +{% for node in current_node.array_items %} +
+ + {% filter md_heading(depth+1, node.html_id) -%} + {% if node.is_pattern_property %}Pattern{% endif %} Property `{% with schema=node %}{%- include "breadcrumbs.md" %}{% endwith %}` + {%- endfilter %} + + {% with schema=node, skip_headers=False, depth=depth+1 %} + {% include "content.md" %} + {% endwith %} + +
+{% endfor %} + +
diff --git a/docs/4-user-guide/2-zarf-packages/1-zarf-packages.md b/docs/4-user-guide/2-zarf-packages/1-zarf-packages.md index c5804a4042..3e19a977c9 100644 --- a/docs/4-user-guide/2-zarf-packages/1-zarf-packages.md +++ b/docs/4-user-guide/2-zarf-packages/1-zarf-packages.md @@ -62,16 +62,7 @@ When Zarf is deploying the package, it will use the infrastructure that was crea ## What Makes Up A Package -Zarf packages are split into smaller chunks called 'components'. These components are defined more in the [Zarf Components page](./2-zarf-components.md) but a quick way to understand components are as the actual named capabilities that packages provide. The schema of a zarf.yaml package follows the following format: - -```yaml -kind: # Either ZarfPackageConfig or ZarfInitConfig -metadata: - name: # The name of the package - description: # A description of the package -seed: # Docker registry to seed the cluster with. Only used for init packages -components: # Components definitions are complex and broken down more in the 'Understanding Zarf Components' page -``` +Zarf packages are split into smaller chunks called 'components'. These components are defined more in the [Zarf Components page](./2-zarf-components.md) but a quick way to understand components are as the actual named capabilities that packages provide. The schema of a zarf.yaml package is available here: [ZarfPackage Schema Docs](../3-zarf-schema.md)

diff --git a/docs/4-user-guide/2-zarf-packages/2-zarf-components.md b/docs/4-user-guide/2-zarf-packages/2-zarf-components.md index 2db5bf4122..edc522a0bf 100644 --- a/docs/4-user-guide/2-zarf-packages/2-zarf-components.md +++ b/docs/4-user-guide/2-zarf-packages/2-zarf-components.md @@ -6,12 +6,12 @@ sidebar_position: 2 The actual capabilities that Zarf Packages provided are defined within named components. These components define what dependencies they have and a declaritive definition of how it should be deployed. Each package can have as many components as the package creator wants but a package really isn't anything without at least one component. -Components can define a wide range of resources that it needs when the package it is a part of gets deployed. The schema for the components is listed below but a high level look at the things components can define include: +Components can define a wide range of resources that it needs when the package it is a part of gets deployed. The schema for the components is linked below but a high level look at the things components can define include: * Files to move onto the host * Helm charts to install into the running k8s cluster * Raw Kubernetes manifests to deploy (by getting converted into zarf-generated helm charts and installed) * Container images to push into the registry the init-package created in the k8s cluster - * Git repositories to push into the git server the init-package created in the k8s cluster + * Git repositories to push into the git server the init-package created in the k8s cluster * Data to push into a resource (i.e. a pod) in the k8s cluster * Scripts to run before/after the component is deployed @@ -19,7 +19,7 @@ Components can define a wide range of resources that it needs when the package i ### Deploying a component When deploying a Zarf package, the **components within a package are deployed in the order they are defined in the `zarf.yaml` that the package was created from.** The `zarf.yaml` configuration for each component also defines whether the component is 'required' or not. 'Required' components are always deployed without any additional user interaction whenever the package is deployed while optional components are printed out in an interactive prompt to the user asking if they wish to the deploy the component. - If you already know which components you want to deploy, you can do so without getting prompted by passing the components as a comma separated listed to the `--components` flag during deploy command. (ex. `zarf package deploy ./path/to/package.tar.zst --components=optional-component-1,optional-component-2`) + If you already know which components you want to deploy, you can do so without getting prompted by passing the components as a comma separated listed to the `--components` flag during deploy command. (ex. `zarf package deploy ./path/to/package.tar.zst --components=optional-component-1,optional-component-2`)   @@ -53,84 +53,4 @@ components:   ## What Makes Up A Component -Zarf components can contain any of the following key/value pairs. Technically, none of the keys are required and you can use as many or few that makes sense to get to desired functionality: - - - - -```yaml - - -components: - - name: # A unique identifier for this component. - # The name can only contain alphabetical, numerical, or '-' characters. - - description: # Message given to a user when deciding to enable this component or not - - required: # If required, this component will always be deployed with the package - - only: # Filter components on package create / deploy to control when it is available - localOS: # Only present on package deploy if the OS matches - cluster: - architecture: # Filter on both package deploy & create for matching cluster architecture - distros: # Future use - - secretName: # The secret Zarf will use for the registry; default is 'zarf-registry'> - # The secret lives in the 'zarf' namespace. - - cosignKeyPath: # Path to publickey to use for online resources signed by cosign. - # Signed files should be denoted with sget:// i.e. `sget://defenseunicorns/zarf-injector:0.4.3` - - images: # List of container images the component will use - # These images will be deployed to the Zarf provided docker registry - - repos: # List of git repos the component will use. - # These repos will be pushed into the gitea server. - # This also means the git-server component needs to be deployed during `zarf init`. - # Private repos need to have their credentialis listed in ~/.git-credentials - - - files: # Files to move onto the system that will be doing the `zarf package deploy` command - - source: # URL or path to where the file lives on the machine performing the `zarf package create` command - shasum: # Optional value to verify remote sources - target: # PAth to where the file will be placed on the system performing the `zarf package deploy` command - executable: # Indicates whether or not executable permissions should be set on the file - symlinks: # List of symlinks to create on the system performing the `zarf package deploy` command - - charts: # Helm charts to install during a package deploy - - name: # Name of the component - - url: # URL to where the chart is hosted (git or otherwise) - - version: # Version of the chart to install - - namespace: # Namespace to install the chart into - - gitPath: # Path to the chart on the git repo - - valuesFiles: # List of values files to use for the helm chart - - manifests: # Raw manifests that get converted into zarf-generated helm charts during deploy - - name: # Name of the component - namespace: # Namespace to install the manifest into - # This defaults to 'default' - files: # - kustomizations: # - - dataInjectors: # data packages to push into a running k8s cluster - - source: # TODO - target: # TODO - namespace: # TODO - selector: # TODO - path: # TODO - - import: # References a component in another Zarf package to import - # When 'import' is provided, the only other keys that matter are the 'name', - # 'required', 'description', and 'secretName' keys. - path: # Path to the zarf.yaml file of the component to import - name: # Optional name of the component to import - # If not provided, it defaults to the name of the component being defined - - scripts: # custom commands that run before or after component deployment - showOutput: # Indicates if the output of the scripts should be sent through stdout/stderr - timeoutSeconds: # Amount of time (in seconds) to wait for the script to complete before throwing an error - # The default time is 5 minutes - retry: # Indicates if the script should be retried if it fails - before: # List of scripts to run before the component is deployed - after: # List of scripts to run after the component is deployed -``` \ No newline at end of file +Zarf components can contain different key/value pairs which you can learn more about here under the `components` section: [ZarfComponent Schema Docs](../3-zarf-schema.md#components) diff --git a/docs/4-user-guide/3-zarf-schema.md b/docs/4-user-guide/3-zarf-schema.md new file mode 100644 index 0000000000..ebe1a44971 --- /dev/null +++ b/docs/4-user-guide/3-zarf-schema.md @@ -0,0 +1,1238 @@ +# Zarf Package Schema + +| Type | `object` | +| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/ZarfPackage | + +
+ kind * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +**Description:** The kind of Zarf package + +| Type | `enum (of string)` | +| ----------- | --------------------- | +| **Default** | `"ZarfPackageConfig"` | + +:::note +Must be one of: +* "ZarfInitConfig" +* "ZarfPackageConfig" +::: + +
+
+ +
+ metadata + + +  +
+ +**Description:** Package metadata + +| Type | `object` | +| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/ZarfMetadata | + +
+ name * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +**Description:** Name to identify this Zarf package + +| Type | `string` | +| ---- | -------- | + +| Restrictions | | +| --------------------------------- | --------------------------------------------------------------------------------- | +| **Must match regular expression** | ```^[a-z0-9\-]+$``` [Test](https://regex101.com/?regex=%5E%5Ba-z0-9%5C-%5D%2B%24) | + +
+
+ +
+ description + + +  +
+ +**Description:** Additional information about this package + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ version + + +  +
+ +**Description:** Generic string to track the package version by a package author + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ url + + +  +
+ +**Description:** Link to package information when online + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ image + + +  +
+ +**Description:** An image URL to embed in this package for future Zarf UI listing + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ uncompressed + + +  +
+ +**Description:** Disable compression of this package + +| Type | `boolean` | +| ---- | --------- | + +
+
+ +
+ architecture + + +  +
+ +**Description:** The target cluster architecture of this package + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+
+ +
+ build + + +  +
+ +**Description:** Zarf-generated package build data + +| Type | `object` | +| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/ZarfBuildData | + +
+ terminal * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ user * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ architecture * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ timestamp * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ version * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+
+ +
+ components * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +**Description:** List of components to deploy in this package + +| Type | `array` | +| ---- | ------- | + +| | Array restrictions | +| -------------------- | ------------------ | +| **Min items** | N/A | +| **Max items** | N/A | +| **Items unicity** | False | +| **Additional items** | False | +| **Tuple validation** | See below | + + ## ZarfComponent + +| Type | `object` | +| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/ZarfComponent | + +
+ name + + +  +
+ +**Description:** The name of the component + +| Type | `string` | +| ---- | -------- | + +| Restrictions | | +| --------------------------------- | --------------------------------------------------------------------------------- | +| **Must match regular expression** | ```^[a-z0-9\-]+$``` [Test](https://regex101.com/?regex=%5E%5Ba-z0-9%5C-%5D%2B%24) | + +
+
+ +
+ description + + +  +
+ +**Description:** Message to include during package deploy describing the purpose of this component + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ default + + +  +
+ +**Description:** Determines the default Y/N state for installing this component on package deploy + +| Type | `boolean` | +| ---- | --------- | + +
+
+ +
+ required + + +  +
+ +**Description:** Do not prompt user to install this component + +| Type | `boolean` | +| ---- | --------- | + +
+
+ +
+ only + + +  +
+ +**Description:** Filter when this component is included in package creation or deployment + +| Type | `object` | +| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/ZarfComponentOnlyTarget | + +
+ localOS + + +  +
+ +**Description:** Only deploy component to specified OS + +| Type | `enum (of string)` | +| ---- | ------------------ | + +:::note +Must be one of: +* "linux" +* "darwin" +* "windows" +::: + +
+
+ +
+ cluster + + +  +
+ +**Description:** Only deploy component to specified clusters + +| Type | `object` | +| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/ZarfComponentOnlyCluster | + +
+ architecture + + +  +
+ +**Description:** Only create and deploy to clusters of the given architecture + +| Type | `enum (of string)` | +| ---- | ------------------ | + +:::note +Must be one of: +* "amd64" +* "arm64" +::: + +
+
+ +
+ distros + + +  +
+ +**Description:** Future use + +| Type | `array of string` | +| ---- | ----------------- | + +| | Array restrictions | +| -------------------- | ------------------ | +| **Min items** | N/A | +| **Max items** | N/A | +| **Items unicity** | False | +| **Additional items** | False | +| **Tuple validation** | See below | + + ## distros items + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+
+ +
+
+ +
+ group + + +  +
+ +**Description:** Create a user selector field based on all components in the same group + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ cosignKeyPath + + +  +
+ +**Description:** Specify a path to a public key to validate signed online resources + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ import + + +  +
+ +**Description:** Import a component from another Zarf package + +| Type | `object` | +| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/ZarfComponentImport | + +
+ name + + +  +
+ +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ path * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+
+ +
+ variables + + +  +
+ +**Description:** Dynamic template values for K8s resources + +| Type | `object` | +| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | + +
+ Pattern Property .* + + +  +
+ +:::note +All properties whose name matches the regular expression +```.*``` ([Test](https://regex101.com/?regex=.%2A)) +must respect the following conditions +::: + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+
+ +
+ scripts + + +  +
+ +**Description:** Custom commands to run before or after package deployment + +| Type | `object` | +| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/ZarfComponentScripts | + +
+ showOutput + + +  +
+ +| Type | `boolean` | +| ---- | --------- | + +
+
+ +
+ timeoutSeconds + + +  +
+ +| Type | `integer` | +| ---- | --------- | + +
+
+ +
+ retry + + +  +
+ +| Type | `boolean` | +| ---- | --------- | + +
+
+ +
+ before + + +  +
+ +| Type | `array of string` | +| ---- | ----------------- | + +| | Array restrictions | +| -------------------- | ------------------ | +| **Min items** | N/A | +| **Max items** | N/A | +| **Items unicity** | False | +| **Additional items** | False | +| **Tuple validation** | See below | + + ## before items + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ after + + +  +
+ +| Type | `array of string` | +| ---- | ----------------- | + +| | Array restrictions | +| -------------------- | ------------------ | +| **Min items** | N/A | +| **Max items** | N/A | +| **Items unicity** | False | +| **Additional items** | False | +| **Tuple validation** | See below | + + ## after items + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+
+ +
+ files + + +  +
+ +**Description:** Files to place on disk during package deployment + +| Type | `array` | +| ---- | ------- | + +| | Array restrictions | +| -------------------- | ------------------ | +| **Min items** | N/A | +| **Max items** | N/A | +| **Items unicity** | False | +| **Additional items** | False | +| **Tuple validation** | See below | + + ## ZarfFile + +| Type | `object` | +| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/ZarfFile | + +
+ source * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ shasum + + +  +
+ +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ target * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ executable + + +  +
+ +| Type | `boolean` | +| ---- | --------- | + +
+
+ +
+ symlinks + + +  +
+ +| Type | `array of string` | +| ---- | ----------------- | + +| | Array restrictions | +| -------------------- | ------------------ | +| **Min items** | N/A | +| **Max items** | N/A | +| **Items unicity** | False | +| **Additional items** | False | +| **Tuple validation** | See below | + + ## symlinks items + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+
+ +
+ charts + + +  +
+ +**Description:** Helm charts to install during package deploy + +| Type | `array` | +| ---- | ------- | + +| | Array restrictions | +| -------------------- | ------------------ | +| **Min items** | N/A | +| **Max items** | N/A | +| **Items unicity** | False | +| **Additional items** | False | +| **Tuple validation** | See below | + + ## ZarfChart + +| Type | `object` | +| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/ZarfChart | + +
+ name * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ releaseName + + +  +
+ +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ url * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ version * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ namespace * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ valuesFiles + + +  +
+ +| Type | `array of string` | +| ---- | ----------------- | + +| | Array restrictions | +| -------------------- | ------------------ | +| **Min items** | N/A | +| **Max items** | N/A | +| **Items unicity** | False | +| **Additional items** | False | +| **Tuple validation** | See below | + + ## valuesFiles items + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ gitPath + + +  +
+ +| Type | `string` | +| ---- | -------- | + +
+
+ +
+
+ +
+ manifests + + +  +
+ +| Type | `array` | +| ---- | ------- | + +| | Array restrictions | +| -------------------- | ------------------ | +| **Min items** | N/A | +| **Max items** | N/A | +| **Items unicity** | False | +| **Additional items** | False | +| **Tuple validation** | See below | + + ## ZarfManifest + +| Type | `object` | +| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/ZarfManifest | + +
+ name * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ namespace + + +  +
+ +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ files + + +  +
+ +| Type | `array of string` | +| ---- | ----------------- | + +| | Array restrictions | +| -------------------- | ------------------ | +| **Min items** | N/A | +| **Max items** | N/A | +| **Items unicity** | False | +| **Additional items** | False | +| **Tuple validation** | See below | + + ## files items + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ kustomizeAllowAnyDirectory + + +  +
+ +| Type | `boolean` | +| ---- | --------- | + +
+
+ +
+ kustomizations + + +  +
+ +| Type | `array of string` | +| ---- | ----------------- | + +| | Array restrictions | +| -------------------- | ------------------ | +| **Min items** | N/A | +| **Max items** | N/A | +| **Items unicity** | False | +| **Additional items** | False | +| **Tuple validation** | See below | + + ## kustomizations items + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+
+ +
+ images + + +  +
+ +**Description:** List of OCI images to include in the package + +| Type | `array of string` | +| ---- | ----------------- | + +| | Array restrictions | +| -------------------- | ------------------ | +| **Min items** | N/A | +| **Max items** | N/A | +| **Items unicity** | False | +| **Additional items** | False | +| **Tuple validation** | See below | + + ## images items + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ repos + + +  +
+ +**Description:** List of git repos to include in the package + +| Type | `array of string` | +| ---- | ----------------- | + +| | Array restrictions | +| -------------------- | ------------------ | +| **Min items** | N/A | +| **Max items** | N/A | +| **Items unicity** | False | +| **Additional items** | False | +| **Tuple validation** | See below | + + ## repos items + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ dataInjections + + +  +
+ +**Description:** Datasets to inject into a pod in the target cluster + +| Type | `array` | +| ---- | ------- | + +| | Array restrictions | +| -------------------- | ------------------ | +| **Min items** | N/A | +| **Max items** | N/A | +| **Items unicity** | False | +| **Additional items** | False | +| **Tuple validation** | See below | + + ## ZarfDataInjection + +| Type | `object` | +| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/ZarfDataInjection | + +
+ source * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ target * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `object` | +| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Additional properties** | [![Any type: allowed](https://img.shields.io/badge/Any%20type-allowed-green)](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/ZarfContainerTarget | + +
+ namespace * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ selector * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ container + + +  +
+ +| Type | `string` | +| ---- | -------- | + +
+
+ +
+ path * + + +  +
+ +![Required](https://img.shields.io/badge/Required-red) + +| Type | `string` | +| ---- | -------- | + +
+
+ +
+
+ +
+
+ +
+
+ +
+ seed + + +  +
+ +**Description:** Special image only used for ZarfInitConfig packages when used with the Zarf Injector + +| Type | `string` | +| ---- | -------- | + +
+
+ +---------------------------------------------------------------------------------------------------------------------------- +Generated from [zarf.schema.json](https://github.com/defenseunicorns/zarf/blob/master/zarf.schema.json) on 2022-07-12 at 22:24:30 +0000 \ No newline at end of file