<detailsclass="tip"><summary>Pre v4.0.0 solution</summary><p>Before we added the <code>--registry-config</code> flag in k3d v4.0.0, you had to bind-mount the file to the correct location: <code>--volume "/home/YOU/my-registries.yaml:/etc/rancher/k3s/registries.yaml"</code></p>
<p>This file is a regular <ahref="https://rancher.com/docs/k3s/latest/en/installation/private-registry/">k3s registries configuration file</a>, and looks like this:</p>
<p>In this example, an image with a name like <code>my.company.registry:5000/nginx:latest</code> would be
<em>pulled</em> from the registry running at <code>http://my.company.registry:5000</code>.</p>
<p>Note well there is an important limitation: <strong>this configuration file will only work with k3s >= v0.10.0</strong>. It will fail silently with previous versions of k3s, but you find in the <ahref="#k3s-old">section below</a> an alternative solution.</p>
<p>This file can also be used for providing additional information necessary for accessing some registries, like <ahref="#authenticated-registries">authentication</a> and <ahref="#secure-registries">certificates</a>.</p>
<h3id="registries-configuration-file-embedded-in-k3ds-simpleconfig">Registries Configuration File embedded in k3d’s SimpleConfig<aclass="headerlink"href="#registries-configuration-file-embedded-in-k3ds-simpleconfig"title="Permanent link">¶</a></h3>
<p>If you’re using a <code>SimpleConfig</code> file to configure your k3d cluster, you may as well embed the registries.yaml in there directly:</p>
<p>Here, the config for the k3d-managed registry, created by the <code>create: true</code> flag will be merged with the config specified under <code>config: |</code>.</p>
<p>When using secure registries, the <ahref="#registries-file"><code>registries.yaml</code> file</a> must include information about the certificates. For example, if you want to use images from the secure registry running at <code>https://my.company.registry</code>, you must first download a CA file valid for that server and store it in some well-known directory like <code>${HOME}/.k3d/my-company-root.pem</code>. </p>
<p>Then you have to mount the CA file in some directory in the nodes in the cluster and include that mounted file in a <code>configs</code> section in the <ahref="#registries-file"><code>registries.yaml</code> file</a>.
For example, if we mount the CA file in <code>/etc/ssl/certs/my-company-root.pem</code>, the <code>registries.yaml</code> will look like:</p>
<h4id="create-a-dedicated-registry-together-with-your-cluster">Create a dedicated registry together with your cluster<aclass="headerlink"href="#create-a-dedicated-registry-together-with-your-cluster"title="Permanent link">¶</a></h4>
<ol>
<li><codeclass="highlight">k3d cluster create mycluster --registry-create</code>: This creates your cluster <code>mycluster</code> together with a registry container called <code>k3d-mycluster-registry</code><ul>
<li>k3d sets everything up in the cluster for containerd to be able to pull images from that registry (using the <code>registries.yaml</code> file)</li>
<li>the port, which the registry is listening on will be mapped to a random port on your host system</li>
</ul>
</li>
<li>Check the k3d command output or <codeclass="highlight">docker ps -f <spanclass="nv">name</span><spanclass="o">=</span>k3d-mycluster-registry</code> to find the exposed port (let’s use <code>12345</code> here)</li>
<li>Pull some image (optional) <codeclass="highlight">docker pull alpine:latest</code>, re-tag it to reference your newly created registry <codeclass="highlight">docker tag alpine:latest k3d-mycluster-registry:12345/testimage:local</code> and push it <codeclass="highlight">docker push k3d-mycluster-registry:12345/testimage:local</code></li>
<li>Use kubectl to create a new pod in your cluster using that image to see, if the cluster can pull from the new registry: <codeclass="highlight">kubectl run --image k3d-mycluster-registry:12345/testimage:local testimage --command -- tail -f /dev/null</code> (creates a container that will not do anything but keep on running)</li>
</ol>
<h4id="create-a-customized-k3d-managed-registry">Create a customized k3d-managed registry<aclass="headerlink"href="#create-a-customized-k3d-managed-registry"title="Permanent link">¶</a></h4>
<li><codeclass="highlight">k3d registry create myregistry.localhost --port <spanclass="m">12345</span></code> creates a new registry called <code>k3d-myregistry.localhost</code> (could be used with automatic resolution of <code>*.localhost</code>, see next section - also, <strong>note the <code>k3d-</code> prefix</strong> that k3d adds to all resources it creates)</li>
<li><codeclass="highlight">k3d cluster create newcluster --registry-use k3d-myregistry.localhost:12345</code> (make sure you use the <strong><code>k3d-</code> prefix</strong> here) creates a new cluster set up to us that registry</li>
<h3id="using-your-own-not-k3d-managed-local-registry">Using your own (not k3d-managed) local registry<aclass="headerlink"href="#using-your-own-not-k3d-managed-local-registry"title="Permanent link">¶</a></h3>
<p><em>We recommend using a k3d-managed registry, as it plays nicely together with k3d clusters, but here’s also a guide to create your own (not k3d-managed) registry, if you need features or customizations, that k3d does not provide:</em></p>
<detailsclass="nonk3dregistry"><summary>Using your own (not k3d-managed) local registry</summary><p>You can start your own local registry it with some <code>docker</code> commands, like:</p>
<p>These commands will start your registry in <code>registry.localhost:5000</code>. In order to push to this registry, you will need to make it accessible as described in the next section.
Once your registry is up and running, we will need to add it to your <code>registries.yaml</code> configuration file.
Finally, you have to connect the registry network to the k3d cluster network: <codeclass="highlight">docker network connect k3d-k3s-default registry.localhost</code>. And then you can <ahref="#testing-your-registry">test your local registry</a>.</p>
<h3id="pushing-to-your-local-registry-address">Pushing to your local registry address<aclass="headerlink"href="#pushing-to-your-local-registry-address"title="Permanent link">¶</a></h3>
<p>As per the guide above, the registry will be available at <code>registry.localhost:5000</code>.</p>
<p>All the nodes in your k3d cluster can resolve this hostname (thanks to the DNS server provided by the Docker daemon) but, in order to be able to push to this registry, this hostname also has to be resolved by your host.</p>
<divclass="admonition info">
<pclass="admonition-title">nss-myhostname to resolve <code>*.localhost</code></p>
<p>Luckily (for Linux users), <ahref="http://man7.org/linux/man-pages/man8/nss-myhostname.8.html">NSS-myhostname</a> ships with many Linux distributions
and should resolve <code>*.localhost</code> automatically to <code>127.0.0.1</code>.<br/>
Otherwise, it’s installable using <code>sudo apt install libnss-myhostname</code>.</p>
<p>If your system does not provide/support tools that can auto-resolve specific names to <code>127.0.0.1</code>, you can manually add an entry in your <code>/etc/hosts</code> (<code>c:\windows\system32\drivers\etc\hosts</code> on Windows) file like this:</p>
<p>We will verify these two things for a local registry (located at <code>k3d-registry.localhost:12345</code>) running in your development machine. Things would be basically the same for checking an external registry, but some additional configuration could be necessary in your local machine when using an authenticated or secure registry (please refer to Docker’s documentation for this).</p>
<p>Then you should check that the pod is running with <code>kubectl get pods -l "app=nginx-test-registry"</code>.</p>
<h2id="configuring-registries-for-k3s-v091">Configuring registries for k3s <= v0.9.1<aclass="headerlink"href="#configuring-registries-for-k3s-v091"title="Permanent link">¶</a></h2>
<p>k3s servers below v0.9.1 do not recognize the <code>registries.yaml</code> file as described in
the in the beginning, so you will need to embed the contents of that file in a <code>containerd</code> configuration file.
You will have to create your own <code>containerd</code> configuration file at some well-known path like <code>${HOME}/.k3d/config.toml.tmpl</code>, like this:</p>
<detailsclass="registriesprev091"><summary>config.toml.tmpl</summary><divclass="highlight"><pre><span></span><code><spanclass="c1"># Original section: no changes</span>
<p>and then mount it at <code>/var/lib/rancher/k3s/agent/etc/containerd/config.toml.tmpl</code> (where <code>containerd</code> in your k3d nodes will load it) when creating the k3d cluster:</p>
<scriptid="__config"type="application/json">{"base":"../../..","features":["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"},"search":"../../../assets/javascripts/workers/search.fe42c31b.min.js","version":null}</script>