1216 - Config File Docs

docs-website/plugins/custom-loaders/index.js

@@ -18,6 +18,33 @@ module.exports = function (context, options) {
                                 filename: 'build/[file].[hash]'
                             }
                         },
+                        {
+                            // Look for all require("*.toml") files
+                            test: /\.toml/,
+                            // Set this as an asset so it is pulled in as-is without compression
+                            type: 'asset/resource',
+                            // Generate a filename to place the example next to the generated index.html file
+                            // (note this adds a fake "build" directory otherwise the examples get placed one directory too high)
+                            // (it also adds a hash since there can be times when the same file is included twice and it needs to be different)
+                            generator: {
+                                filename: 'build/[file].[hash]'
+                            }
+
+                        },
+                        {
+                            // Look for all require("*.ini") files
+                            test: /\.ini/,
+                            // Set this as an asset so it is pulled in as-is without compression
+                            type: 'asset/resource',
+                            // Generate a filename to place the example next to the generated index.html file
+                            // (note this adds a fake "build" directory otherwise the examples get placed one directory too high)
+                            // (it also adds a hash since there can be times when the same file is included twice and it needs to be different)
+                            generator: {
+                                filename: 'build/[file].[hash]'
+                            }
+
+                        }
+
                     ],
                 },
             };

docs-website/src/components/ExampleYAML.js

@@ -2,7 +2,7 @@ import React from "react";
 import { useEffect, useState } from "react";
 import CodeBlock from "@theme/CodeBlock";
 
-const FetchExampleYAML = ({ src, component, raw, showLink = true }) => {
+const FetchExampleYAML = ({ src, component, raw, showLink = true, fileName="zarf.yaml" }) => {
   const [content, setContent] = useState(null);
   const linkBaseUrl = `${src}`.replace(/^\/build\/\.\.\//gm,'').replace(/\/zarf\.yaml.+?$/gm,'');
 
@@ -19,6 +19,7 @@ const FetchExampleYAML = ({ src, component, raw, showLink = true }) => {
           setContent(text);
         }
       });
+
   }, []);
 
   if (!content) {
@@ -32,7 +33,7 @@ const FetchExampleYAML = ({ src, component, raw, showLink = true }) => {
     <>
       {showLink && (
         <p>
-          This example's full <code>zarf.yaml</code> can be viewed at{" "}
+          This example's full <code>{fileName}</code> can be viewed at{" "}
           <a href={`/${linkBaseUrl}/#zarf.yaml`}>{linkBaseUrl}</a>
         </p>
       )}

docs-website/src/components/FetchFileCodeBlock.js

@@ -0,0 +1,67 @@
+import React from "react";
+import { useEffect, useState } from "react";
+import CodeBlock from "@theme/CodeBlock";
+
+const FetchFileCodeBlock = ({ src, component, raw, showLink = true, fileFormat, fileName }) => {
+  const [content, setContent] = useState(null);
+
+  const linkBaseUrl = `${src}`.replace(/^\/build\/\.\.\//gm, '').replace(/\/zarf\.yaml.+?$/gm, '');
+
+  const handleDownloadClick = () => {
+    const jsonDataString = JSON.stringify(src, null, 2);
+    const dataUri = 'data:application/json;charset=utf-8,' + encodeURIComponent(jsonDataString);
+
+    const downloadLink = document.createElement('a');
+    downloadLink.href = dataUri;
+    downloadLink.download = fileName;
+    downloadLink.click();
+  };
+
+  useEffect(() => {
+    //  when fileFormat is json then you don't need to fetch, it is [object Object]
+    fileFormat !== "json" ?
+      fetch(src)
+        .then((res) => {
+          return res.text()
+        })
+        .then(async (text) => {
+          if (component) {
+            const lines = text.split("\n");
+            setContent(lines.join("\n"));
+          } else {
+            setContent(text);
+          }
+        }) : setContent(JSON.stringify(src, null, 2))
+  }, []);
+
+  if (!content) {
+    // This is necessary so the bowser does not show [object Object] when fileFormat is json
+    if (fileFormat === "json") {
+      console.log(`Unable to fetch example ${fileFormat} ${fileName}`)
+    } else {
+      console.log(`Unable to fetch example ${fileFormat} ${src}`)
+    }
+
+    return <></>
+  }
+  if (raw) {
+    return <>{content}</>;
+  }
+  return (
+    <>
+      {showLink && (
+        <p>
+          This example's full <code>{fileName}</code> can be viewed at{" "}
+          {fileFormat === "json" ? <a style={{cursor: "pointer"}} onClick={handleDownloadClick}>{fileName}</a> : <a href={`/${linkBaseUrl}/#zarf.yaml`}>{linkBaseUrl}</a>}
+        </p>
+      )}
+      <CodeBlock copy={false} fileFormat={fileFormat}>
+        {content}
+      </CodeBlock>
+    </>
+  );
+
+
+};
+
+export default FetchFileCodeBlock;

docs/2-the-zarf-cli/2-declarative-cli-configuration.md

@@ -0,0 +1,48 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import ExampleYAML from '@site/src/components/ExampleYAML';
+import FetchFileCodeBlock from '@site/src/components/FetchFileCodeBlock';
+
+# Declarative CLI Configuration
+
+## Overview
+
+Users can configure the `zarf init`, `zarf package create`, and `zarf package deploy` command flags, as well as global flags (with the exception of `--confirm`), through a config file to help execute commands more declaratively.
+
+By default, Zarf searches for a config file named `zarf-config.toml` in the current working directory. You can generate a config template for use by Zarf by executing the command `zarf prepare generate-config`, with an optional filename, in any of the supported formats, including `toml`, `json`, `yaml`, `ini` and `props`. For instance, to create a template config file with the `my-cool-env` in the yaml format, you can use the command `zarf prepare generate-config my-cool-env.yaml`.
+
+To use a custom config file, set the `ZARF_CONFIG` environment variable to the path of the desired config file. For example, to use the `my-cool-env.yaml` config file, you can set the `ZARF_CONFIG` environment variable to `my-cool-env.yaml`. The `ZARF_CONFIG` environment variable can be set either in the shell or in the `.env` file in the current working directory. Note that the `ZARF_CONFIG` environment variable takes precedence over the default config file.
+
+Additionally, you can also set any supported config parameter via env variable using the `ZARF_` prefix. For instance, you can set the `zarf init` `--storage-class` flag via the env variable by setting the `ZARF_INIT.STORAGE_CLASS` environment variable. Note that the `ZARF_` environment variable takes precedence over the config file.
+
+While config files set default values, these values can still be overwritten by command line flags. For example, if the config file sets the log level to `info` and the command line flag is set to `debug`, the log level will be set to `debug`. The order of precedence for command line configuration is as follows:
+
+1. Command line flags
+2. Environment variables
+3. Config file
+4. Default values
+
+For additional information, see the [Config File Example](../../examples/config-file/README.md).
+
+## Config File Location
+
+To use a custom config file, set the `ZARF_CONFIG` environment variable to the path of the desired config file. For example, to use the my-cool-env.yaml config file, you can set the `ZARF_CONFIG` environment variable to `my-cool-env.yaml`. The `ZARF_CONFIG` environment variable can be set either in the shell or in the .env file in the current working directory. Note that the ZARF_CONFIG environment variable takes precedence over the default config file.
+
+It will also pickup config files from either your current working directory or `~/.zarf/` if you don't specify a config file.
+
+## Config File Examples
+
+<Tabs queryString="init-file-examples">
+<TabItem value="yaml">
+<ExampleYAML src={require('../../examples/config-file/zarf-config.yaml')} fileName="zarf-config.yaml" />
+</TabItem>
+<TabItem value="toml">
+<FetchFileCodeBlock src={require('../../examples/config-file/zarf-config.toml')} fileFormat="toml" fileName="zarf-config.toml" />
+</TabItem>
+<TabItem value="ini">
+<FetchFileCodeBlock src={require('../../examples/config-file/zarf-config.ini')} fileFormat="ini"   fileName="zarf-config.ini" />
+</TabItem>
+<TabItem value="json">
+<FetchFileCodeBlock src={require('../../examples/config-file/zarf-config.json')} fileFormat="json" fileName="zarf-config.json"  />
+</TabItem>
+</Tabs>

docs/2-the-zarf-cli/index.md

@@ -135,22 +135,3 @@ The `zarf init` command is utilized to configure a K8s cluster in preparation fo
 <!-- TODO: Write some docs (or redirect to other docs) describing when you would be able to do a `zarf package deploy` before a `zarf init` -->
 
 The `zarf package deploy` command is used to deploy an already built tar.zst package onto a machine, typically within a K8s cluster. Generally, it is presumed that the `zarf init` command has already been executed on the target machine. However, there are a few exceptional cases where this assumption does not apply.
-
-## Using a config file to make CLI command flags declarative
-
-Users can configure the `zarf init`, `zarf package create`, and `zarf package deploy` command flags, as well as global flags (with the exception of `--confirm`), through a config file to help execute commands more declaratively.
-
-By default, Zarf searches for a config file named `zarf-config.toml` in the current working directory. You can generate a config template for use by Zarf by executing the command `zarf prepare generate-config`, with an optional filename, in any of the supported formats, including `toml`, `json`, `yaml`, `ini` and `props`. For instance, to create a template config file with the `my-cool-env` in the yaml format, you can use the command `zarf prepare generate-config my-cool-env.yaml`.
-
-To use a custom config file, set the `ZARF_CONFIG` environment variable to the path of the desired config file. For example, to use the `my-cool-env.yaml` config file, you can set the `ZARF_CONFIG` environment variable to `my-cool-env.yaml`. The `ZARF_CONFIG` environment variable can be set either in the shell or in the `.env` file in the current working directory. Note that the `ZARF_CONFIG` environment variable takes precedence over the default config file.
-
-Additionally, you can also set any supported config parameter via env variable using the `ZARF_` prefix. For instance, you can set the `zarf init` `--storage-class` flag via the env variable by setting the `ZARF_INIT.STORAGE_CLASS` environment variable. Note that the `ZARF_` environment variable takes precedence over the config file.
-
-While config files set default values, these values can still be overwritten by command line flags. For example, if the config file sets the log level to `info` and the command line flag is set to `debug`, the log level will be set to `debug`. The order of precedence for command line configuration is as follows:
-
-1. Command line flags
-2. Environment variables
-3. Config file
-4. Default values
-
-For additional information, see the [Config File Example](../../examples/config-file/README.md).

examples/config-file/zarf-config.ini

@@ -4,13 +4,16 @@ log_level=info
 [package.create]
 skip_sbom=false
 
+# set variables for package create
 [package.create.set]
 leopard=spots
 zebra=stripes
 
+
 [package.deploy]
 components=lion
 
+# set variables for package deploy
 [package.deploy.set]
 camel_spider=matte
 scorpion=iridescent

examples/config-file/zarf-config.json

@@ -0,0 +1,20 @@
+{
+    "log_level": "info",
+    "package": {
+        "create": {
+            "skip_sbom": false,
+            "set": {
+                "zebra": "stripes",
+                "leopard": "spots"
+            }
+        },
+        "deploy": {
+            "components": "lion",
+            "set": {
+                "scorpion": "iridescent",
+                "camel_spider": "matte",
+                "tls_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDDvKUzWiZucm6/\n8D2Nx4KVe8t6uHtARpw112f4yGv7xKcOJkbxLbVtor8pj/HS5tRSZq2ziIQl9y98\n8TVAOBezgzPPMDxOqDeyHl5gAtqzpK/eSPmueZIhR88BH2+SMYqa5kxmjn752Rf0\njVeCrVdQ5MD9rqA00oQi/zO+gQQoz6QSuiEQ2pSKYB3gv9oIoJorIU1n4qLYAezn\nTvFwjmKWPPhRdyslpcAi1rVO+mVX3Y2DKU/CfpWNFVVT+H788Srn4yP6iWUymfQU\nvHOXII1erMnES2H9BDffumrRf3m3IpgueQ3vPhB8ftjFZozURj2t/WSeaKsyQSoZ\nWr99DWxpAgMBAAECggEAAW8ARsACSAzOgtlfmgo8Cpw9gUiYnn/l5P8O4+OT5uQp\n1RCytFGBYqwuej9zpffK1k+qNgZp8V0+G8wod6/xfH8Zggr4ZhsVTVirmEhtEaPD\nJf2i1oRNbbD48yknyApU2Y2WQaoJhArzAfeHDI34db83KqR8x+ZC0X7NAjgvr5zS\nb0OfY2tht4oxEWh2m67FzlFgF+cWyszRYyfvHfOFBqLesuCnSfMoOzmbT3SlnxHo\n6GSa1e/kCJVzFJNb74BZTIH0w6Ar/a0QG829VXivqj8lRENU/1xUI2JhNz4RdH7F\n6MeiwQbq4pWjHfh4djuzQFIwOgCnSNRnNuNywOVuAQKBgQDjleEI1XFQawXmHtHu\n6GMhbgptRoSUyutDDdo2MHGvDbxDOIsczIBjxCuYAM47nmGMuWbDJUN+2VQAX32J\nWZagRxWikxnEqv3B7No7tLSQ42rRo/tDBrZPCCuS9u/ZJM4o7MCa/VzTtbicGOCh\nbTIoTeEtT2piIdkrjHFGGlYOLQKBgQDcLNFHrSJCkHfCoz75+zytfYan+2dIxuV/\nMlnrT8XHt33cst4ZwoIQbsE6mv7J4CJqOgUYDvoJpioLV3InUACDxXd+bVY7RwxP\nj25pXzYL++RctVO3IEOCmFkwlq0fNFdrOn8Y/cnRTwd2e60n08rCKgJS8KhEAaO0\nQvVmAHw4rQKBgQDL7hCAnunzuoLFqpZI8tlpKjaTpp3EynO3WSFQb2ZfCvrIbVFS\nU/kz7KN3iDlEeO5GcBeiA7EQaGN6FhbiTXHIWwoK7K8paGMMM1V2LL2kGvQruDm8\n3LXd6Z9KCJXxSKanS0ZnW2KjnnE3Bp+6ZqOMNATzWfckydnUyPrza0PzXQKBgEYS\n1YCUb8Tzqcn+nrp85XDp9INeFh8pfj0fT1L/DpljouEs5Fcaer60ITd/wPuLJCje\n0mQ30AhmJBd7+07bvW4y2LcaIUm4cQiZQ7CxpsfloWaIJ16vHA1iY3B9ZBf8Vp4/\n/dd8XlEJb/ybnB6C35MwP5EaGtOaGfnzHZsbKG35AoGAWm9tpqhuldQ3MCvoAr5Q\nb42JLSKqwpvVjQDiFZPI/0wZTo3WkWm9Rd7CAACheb8S70K1r/JIzsmIcnj0v4xs\nsfd+R35UE+m8MExbDP4lKFParmvi2/UZfb3VFNMmMPTV6AEIBl6N4PmhHMZOsIRs\nH4RxbE+FpmsMAUCpdrzvFkc=\n-----END PRIVATE KEY-----"
+            }
+        }
+    }
+}

examples/config-file/zarf-config.yaml

@@ -9,6 +9,7 @@ package:
       leopard : 'spots'
   deploy:
     components: 'lion'
+    # Set a variable for package deploy
     set:
       scorpion : 'iridescent'
       camel_spider : 'matte'

my-cool-env.yaml

@@ -0,0 +1,49 @@
+architecture: ""
+init:
+    components: ""
+    git:
+        pull_password: ""
+        pull_username: ""
+        push_password: ""
+        push_username: zarf-git-user
+        url: ""
+    registry:
+        nodeport: 0
+        pull_password: ""
+        pull_username: ""
+        push_password: ""
+        push_username: zarf-push
+        secret: ""
+        url: ""
+    storage_class: ""
+insecure: false
+log_level: info
+no_log_file: false
+no_progress: false
+package:
+    create:
+        max_package_size: 0
+        output: ""
+        sbom: false
+        sbom_output: ""
+        set:
+            agent_image: defenseunicorns/zarf/agent
+            agent_image_domain: ghcr.io/
+            agent_image_tag: local
+            injector_version: "2023-07-19"
+            registry_image: library/registry
+            registry_image_domain: ""
+            registry_image_tag: 2.8.2
+        signing_key: ""
+        skip_sbom: false
+    deploy:
+        components: ""
+        public_key: ""
+        set: {}
+        sget: ""
+        shasum: ""
+    oci_concurrency: 3
+    pull:
+        output_directory: ""
+tmp_dir: ""
+zarf_cache: ~/.zarf-cache