<inputclass="md-option"data-md-color-media="(prefers-color-scheme: light)"data-md-color-scheme="default"data-md-color-primary="black"data-md-color-accent="grey"aria-label="Switch to dark mode"type="radio"name="__palette"id="__palette_1">
<labelclass="md-header__button md-icon"title="Switch to dark mode"for="__palette_2"hidden>
<inputclass="md-option"data-md-color-media="(prefers-color-scheme: dark)"data-md-color-scheme="slate"data-md-color-primary="light-blue"data-md-color-accent=""aria-label="Switch to light mode"type="radio"name="__palette"id="__palette_2">
<labelclass="md-header__button md-icon"title="Switch to light mode"for="__palette_1"hidden>
<pclass="admonition-title">Syntax & Semantics</p>
<p>The options defined in the config file are not 100% the same as the CLI flags.<br/>
This concerns naming and style/usage/structure, e.g.</p>
<ul>
<li><code>--api-port</code> is split up into a field named <code>kubeAPI</code> that has 3 different “child fields” (<code>host</code>, <code>hostIP</code> and <code>hostPort</code>)</li>
<li>k3d options are bundled in a scope named <code>options.k3d</code>, where <code>--no-rollback</code> is defined as <code>options.k3d.disableRollback</code></li>
<li>repeatable flags (like <code>--port</code>) are reflected as YAML lists</li>
<p>As of the time of writing this documentation, the config file only <strong>requires</strong> you to define two fields:</p>
<ul>
<li><code>apiVersion</code> to match the version of the config file that you want to use (at this time it would be <code>apiVersion: k3d.io/v1alpha4</code>)</li>
<li><code>kind</code> to define the kind of config file that you want to use (currently we only have the <code>Simple</code> config)</li>
</ul>
<p>So this would be the minimal config file, which configures absolutely nothing:</p>
<p>The configuration options for k3d are continuously evolving and so is the config file (syntax) itself.<br/>
Currently, the config file is still in an Alpha-State, meaning, that it is subject to change anytime (though we try to keep breaking changes low).</p>
<divclass="admonition info">
<pclass="admonition-title">Validation via JSON-Schema</p>
<p>k3d uses a <ahref="https://json-schema.org/">JSON-Schema</a> to describe the expected format and fields of the configuration file.<br/>
This schema is also used to <ahref="https://github.com/xeipuuv/gojsonschema#validation">validate</a> a user-given config file.<br/>
This JSON-Schema can be found in the specific config version sub-directory in the repository (e.g. <ahref="https://github.com/k3d-io/k3d/blob/main/pkg/config/v1alpha4/schema.json">here for <code>v1alpha4</code></a>) and could be used to lookup supported fields or by linters to validate the config file, e.g. in your code editor. </p>
<p>Since the config options and the config file are changing quite a bit, it’s hard to keep track of all the supported config file settings, so here’s an example showing all of them as of the time of writing:</p>
<divclass="highlight"><pre><span></span><code><spanclass="c1"># k3d configuration file, saved as e.g. /home/me/myk3dcluster.yaml</span><spanclass="w"></span>
<spanclass="nt">apiVersion</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">k3d.io/v1alpha4</span><spanclass="w"></span><spanclass="c1"># this will change in the future as we make everything more stable</span><spanclass="w"></span>
<spanclass="nt">kind</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">Simple</span><spanclass="w"></span><spanclass="c1"># internally, we also have a Cluster config, which is not yet available externally</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">name</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">mycluster</span><spanclass="w"></span><spanclass="c1"># name that you want to give to your cluster (will still be prefixed with `k3d-`)</span><spanclass="w"></span>
<spanclass="nt">servers</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">1</span><spanclass="w"></span><spanclass="c1"># same as `--servers 1`</span><spanclass="w"></span>
<spanclass="nt">agents</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">2</span><spanclass="w"></span><spanclass="c1"># same as `--agents 2`</span><spanclass="w"></span>
<spanclass="nt">kubeAPI</span><spanclass="p">:</span><spanclass="w"></span><spanclass="c1"># same as `--api-port myhost.my.domain:6445` (where the name would resolve to 127.0.0.1)</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">host</span><spanclass="p">:</span><spanclass="w"></span><spanclass="s">"myhost.my.domain"</span><spanclass="w"></span><spanclass="c1"># important for the `server` setting in the kubeconfig</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">hostIP</span><spanclass="p">:</span><spanclass="w"></span><spanclass="s">"127.0.0.1"</span><spanclass="w"></span><spanclass="c1"># where the Kubernetes API will be listening on</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">hostPort</span><spanclass="p">:</span><spanclass="w"></span><spanclass="s">"6445"</span><spanclass="w"></span><spanclass="c1"># where the Kubernetes API listening port will be mapped to on your host system</span><spanclass="w"></span>
<spanclass="nt">image</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">rancher/k3s:v1.20.4-k3s1</span><spanclass="w"></span><spanclass="c1"># same as `--image rancher/k3s:v1.20.4-k3s1`</span><spanclass="w"></span>
<spanclass="nt">network</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">my-custom-net</span><spanclass="w"></span><spanclass="c1"># same as `--network my-custom-net`</span><spanclass="w"></span>
<spanclass="nt">subnet</span><spanclass="p">:</span><spanclass="w"></span><spanclass="s">"172.28.0.0/16"</span><spanclass="w"></span><spanclass="c1"># same as `--subnet 172.28.0.0/16`</span><spanclass="w"></span>
<spanclass="nt">token</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">superSecretToken</span><spanclass="w"></span><spanclass="c1"># same as `--token superSecretToken`</span><spanclass="w"></span>
<spanclass="nt">volumes</span><spanclass="p">:</span><spanclass="w"></span><spanclass="c1"># repeatable flags are represented as YAML lists</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="nt">volume</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">/my/host/path:/path/in/node</span><spanclass="w"></span><spanclass="c1"># same as `--volume '/my/host/path:/path/in/node@server:0;agent:*'`</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="nt">port</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">8080:80</span><spanclass="w"></span><spanclass="c1"># same as `--port '8080:80@loadbalancer'`</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="nt">envVar</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">bar=baz</span><spanclass="w"></span><spanclass="c1"># same as `--env 'bar=baz@server:0'`</span><spanclass="w"></span>
<spanclass="nt">registries</span><spanclass="p">:</span><spanclass="w"></span><spanclass="c1"># define how registries should be created or used</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">create</span><spanclass="p">:</span><spanclass="w"></span><spanclass="c1"># creates a default registry to be used with the cluster; same as `--registry-create registry.localhost`</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">k3d-myotherregistry:5000</span><spanclass="w"></span><spanclass="c1"># some other k3d-managed registry; same as `--registry-use 'k3d-myotherregistry:5000'`</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">config</span><spanclass="p">:</span><spanclass="w"></span><spanclass="p p-Indicator">|</span><spanclass="w"></span><spanclass="c1"># define contents of the `registries.yaml` file (or reference a file); same as `--registry-config /path/to/config.yaml`</span><spanclass="w"></span>
<spanclass="nt">hostAliases</span><spanclass="p">:</span><spanclass="w"></span><spanclass="c1"># /etc/hosts style entries to be injected into /etc/hosts in the node containers and in the NodeHosts section in CoreDNS</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">wait</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">true</span><spanclass="w"></span><spanclass="c1"># wait for cluster to be usable before returining; same as `--wait` (default: true)</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">timeout</span><spanclass="p">:</span><spanclass="w"></span><spanclass="s">"60s"</span><spanclass="w"></span><spanclass="c1"># wait timeout before aborting; same as `--timeout 60s`</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">disableLoadbalancer</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">false</span><spanclass="w"></span><spanclass="c1"># same as `--no-lb`</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">disableImageVolume</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">false</span><spanclass="w"></span><spanclass="c1"># same as `--no-image-volume`</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">disableRollback</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">false</span><spanclass="w"></span><spanclass="c1"># same as `--no-Rollback`</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">k3s</span><spanclass="p">:</span><spanclass="w"></span><spanclass="c1"># options passed on to K3s itself</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">extraArgs</span><spanclass="p">:</span><spanclass="w"></span><spanclass="c1"># additional arguments passed to the `k3s server|agent` command; same as `--k3s-arg`</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="nt">label</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">foo=bar</span><spanclass="w"></span><spanclass="c1"># same as `--k3s-node-label 'foo=bar@agent:1'` -> this results in a Kubernetes node label</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">updateDefaultKubeconfig</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">true</span><spanclass="w"></span><spanclass="c1"># add new cluster to your default Kubeconfig; same as `--kubeconfig-update-default` (default: true)</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">switchCurrentContext</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">true</span><spanclass="w"></span><spanclass="c1"># also set current-context to the new cluster's context; same as `--kubeconfig-switch-context` (default: true)</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">runtime</span><spanclass="p">:</span><spanclass="w"></span><spanclass="c1"># runtime (docker) specific options</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="nt">gpuRequest</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">all</span><spanclass="w"></span><spanclass="c1"># same as `--gpus all`</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="nt">label</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">bar=baz</span><spanclass="w"></span><spanclass="c1"># same as `--runtime-label 'bar=baz@agent:1'` -> this results in a runtime (docker) container label</span><spanclass="w"></span>
<li>k3d <ahref="https://pkg.go.dev/os#ExpandEnv">expands environment variables</a> (<code>$VAR</code> or <code>${VAR}</code>) unconditionally in the config file, even before processing it in any way. </li>
</ul>
<h2id="config-file-vs-cli-flags">Config File vs. CLI Flags<aclass="headerlink"href="#config-file-vs-cli-flags"title="Permanent link">¶</a></h2>
<p>k3d uses <ahref="https://github.com/spf13/cobra"><code>Cobra</code></a> and <ahref="https://github.com/spf13/viper"><code>Viper</code></a> for CLI and general config handling respectively.<br/>
This automatically introduces a “config option order of priority” (<ahref="https://github.com/spf13/viper#why-viper">precedence order</a>):</p>
<p>This means, that you can define e.g. a “base configuration file” with settings that you share across different clusters and override only the fields that differ between those clusters in your CLI flags/arguments.<br/>
For example, you use the same config file to create three clusters which only have different names and <code>kubeAPI</code> (<code>--api-port</code>) settings.</p>
<li>SUSE Blog: <ahref="https://www.suse.com/c/introduction-k3d-run-k3s-docker-src/">https://www.suse.com/c/introduction-k3d-run-k3s-docker-src/</a> (Search for <code>The “Configuration as Code” Way</code>)</li>
<scriptid="__config"type="application/json">{"base":"../..","features":["navigation.top","search.suggest","search.highlight","navigation.expand","navigation.tabs"],"translations":{"clipboard.copy":"Copy to clipboard","clipboard.copied":"Copied to clipboard","search.config.lang":"en","search.config.pipeline":"trimmer, stopWordFilter","search.config.separator":"[\\s\\-]+","search.placeholder":"Search","search.result.placeholder":"Type to start searching","search.result.none":"No matching documents","search.result.one":"1 matching document","search.result.other":"# matching documents","search.result.more.one":"1 more on this page","search.result.more.other":"# more on this page","search.result.term.missing":"Missing","select.version.title":"Select version"},"search":"../../assets/javascripts/workers/search.5e67fbfe.min.js","version":{"provider":"mike"}}</script>