# Using a Local Docker Registry on Air-Gapped Systems

## Using a Local Docker Registry on Air-Gapped Systems

PMK clusters rely on various docker container images to stand up and run clusters. These images are typically hosted on public registries like:

* Docker Hub (hub.docker.com)
* Quay (quay.io)
* GCR (gcr.io)
* K8S (k8s.gcr.io)

In airgapped environments, these image registries are unreachable. To address this concern, we ship a pre-built tar image along with airctl. This tar file is copied over to the hosts as they are configured, and then the local docker cache is pre-warmed. While this works well in small environments, this scales poorly when provisioning numerous nodes. To address this issue, airctl 5.2≥ supports installing and managing a local registry, that clusters can point to and retrieve images from.

## Using a Local Registry

### Step 1: Configure registry on the DU

You can enable and configure this preference in the local registry by enabling the following option in your airctl config file located at `/opt/pf9/airctl/conf/airctl-config.yaml` on the DU host:

{% tabs %}
{% tab title="None" %}

```none
privateRegistryType: DU
```

{% endtab %}
{% endtabs %}

Once this configuration is set, start and configure the DU using the following command.

{% tabs %}
{% tab title="None" %}

```none
airctl start
```

{% endtab %}
{% endtabs %}

This brings up a registry within the DU that listens on `localhost:5100`, and configures the DU to create clusters pointing to this registry by default.

### Step 2: Push Images to the Local Registry

By default, the registry does not host any images. We push images downloaded from an online repository to this registry using the following command:

{% tabs %}
{% tab title="None" %}

```none
airctl advanced-du push-images --img-tar <path-to-docker-img-tar> --config /opt/pf9/airctl/conf/airctl-config.yaml
```

{% endtab %}
{% endtabs %}

### Step 3: Configure hosts

By default, the *configure hosts* command will still copy the image tars over to the hosts to warm the local cache. Users can skip this step by adding the *--skip-docker-img-import* flag to the configure-hosts command.

{% tabs %}
{% tab title="None" %}

```none
airctl configure-hosts --skip-docker-img-import --config /opt/pf9/airctl/conf/airctl-config.yaml
```

{% endtab %}
{% endtabs %}

The hosts are then configured to pull the container images from the DU using the tunnel created between the host and the DU.

### Step 4: Create Cluster

At this point, you can create the cluster using the normal process. Now, by default, the nodes will be configured to pull container images from the local registry for all images required to stand the cluster up.

{% hint style="warning" %}
**Warning**

⚠️ Application containers are not configured to use the local registry: You will be required to push those images to the registry if you want to serve those images.
{% endhint %}

## Upgrading a DU to Begin Using a Local Registry

Running the DU upgrade with the following fields set in `/opt/pf9/airctl/conf/airctl-config.yaml` will turn on and configure the local registry.

{% tabs %}
{% tab title="None" %}

```none
privateRegistryType
privateRegistryBase
```

{% endtab %}
{% endtabs %}

Alternatively, you can also configure the DU to use the local registry after an upgrade. Set the fields as above and then run the following commands.

{% tabs %}
{% tab title="None" %}

```none
airctl advanced-du update-du --config /opt/pf9/airctl/conf/airctl-config.yaml
airctl advanced-du configure-du --config /opt/pf9/airctl/conf/airctl-config.yaml
```

{% endtab %}
{% endtabs %}

## Upgrading Clusters to Begin Using the Local Registry

Only clusters running kubernetes version 1.20 can run on local registries. By default, once the DU has been upgraded to version 5.3≥ with the *privateRegistry* flags enabled as noted above, the DU is configured to run all clusters in local registry mode. To begin using a local registry, upgrade the cluster to the latest Kubernetes v1.20 available on the DU. Once the upgrade to v1.20 is complete, the cluster will begin running in local registry mode.

## Backup and Restore of Local Registry

**The images stored in the registry will NOT be retained after an upgrade.** The following commands will enable the backup and restore function of the registry image data. To backup, run this command.

{% tabs %}
{% tab title="None" %}

```none
airctl advanced-du backup-images --out registry-backup.tar.gz --config /opt/pf9/airctl/conf/airctl-config.yaml
```

{% endtab %}
{% endtabs %}

To restore the registry image data, run this command.

{% tabs %}
{% tab title="None" %}

```none
airctl advanced-du restore-images --in registry-backup.tar.gz --config /opt/pf9/airctl/conf/airctl-config.yaml
```

{% endtab %}
{% endtabs %}

## Host Configuration

With the introduction of local registries, there are many new flags available to utilize with the `airctl configure-hosts`command. This section below provides a detailed description of these options.

* `--skip-docker-img-import`: By default, the cache of docker images required to stand up the cluster are copied over to the hosts to pre-warm the local docker cache. This option skips that step; the host will now rely on the local registry to serve these images.
* `--skip-docker-install`: By default, *airctl* installs docker as a part of the host configuration. With this option set, *airctl* skips this step and expects the host to come with a version of docker already installed. ***Note**\_\_: Passing this option also skips installation of the docker images.*
* `--skip-image-renaming`: If the *airctl-config.yaml* file has the private registry option enabled, (i.e, has the `privateRegistryType` field set to anything but `none`), the host configuration step will automatically rename images to point to the local registry instead of its upstream versions. Enable this option to continue copying over upstream versions of the images to the hosts. ***Note**\_\_: This option is meaningless if the* *`--skip-docker-img-import`* *option is*
* `--skip-yum-repo-install`: Implement this option to prevent *airctl* from installing the local yum repos for *pf9-hostagent* and other associated packages. Instead, the host is expected to select these packages up from an external yum repo.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.platform9.com/self-managed-cloud-platform/5.7/local-docker-registry-air-gapped.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.