Air Gap Installation in Existing Clusters
This topic describes how to use Replicated KOTS to install an application in an existing Kubernetes cluster.
The procedures in this topic apply to installation environments that do not have access to the internet, known as air gap environments.
About Private Registries
Air gapped networks must have a Docker image registry that is available inside the network. KOTS rewrites the application image names in all application manifests to read from the on-premises registry, and it re-tags and pushes the images to the on-premises registry. When authenticating to the registry, credentials with
push permissions are required.
A single application expects to use a single namespace in the Docker image registry. The namespace name can be any valid URL-safe string, supplied at installation time. A registry typically expects the namespace to exist before any images can be pushed into it.
ECR does not use namespaces.
Complete the following prerequisites:
Ensure that your cluster meets the minimum system requirements. See Minimum System Requirements in Installation Requirements.
Ensure that you have at least the minimum RBAC permissions in the cluster required to install KOTS. See RBAC Requirements in Installation Requirements.note
If you manually created RBAC resources for KOTS as described in Namespace-scoped RBAC Requirements, include both the
--skip-rbac-checkflags when you run the
Review the options available with the
kots installcommand before installing. The
kots installcommand includes several optional flags to support different installation use cases. For a list of options, see install in the kots CLI documentation.
- Ensure that there is a compatible Docker image registry available inside the network. For more information about Docker registry compatibility, see Private Registry Requirements.
- Download the
.airgapbundle provided by your software vendor. Ensure that you can access the downloaded bundle from the environment where you will install the application.
- Download the license file provided by your software vendor. Ensure that you can access the downloaded license file from the environment where you will install the application.
- Download the
kotsadm.tar.gzair gap bundle from the kots release page on GitHub. The
kotsadm.tar.gzair gap bundle includes the container images for the Replicated admin console. See Releases in the kots GitHub repository.
This procedure describes how to install KOTS in your existing cluster using the
kotsadm.tar.gz air gap bundle.
KOTS deploys the Replicated admin console, which provides a user interface for installing and managing applications. After you install KOTS, you will use the admin console to install the application in your cluster in the Install and Deploy the Application procedure that follows.
To install KOTS:
Install the Replicated kots CLI plugin. See Install without Root Access in the kots CLI reference section.
Run the following command to confirm that the kots CLI version matches the version of the
kotsadm.tar.gzair gap bundle that you downloaded:
kubectl kots version
Run the following command to extract container images from the
kotsadm.tar.gzbundle and push the images to your private registry:
kubectl kots admin-console push-images ./kotsadm.tar.gz REGISTRY_HOST \
--registry-username RW_USERNAME \
REGISTRY_HOSTwith the hostname for the private registry. For example,
RW_USERNAMEwith the username for an account that has read and write access to the private image registry.
RW_PASSWORDwith the password for the account with read and write access.note
KOTS does not store or reuse these credentials.
Run the following command to install KOTS using the images that you pushed in the previous step:
kubectl kots install APP_NAME \
--kotsadm-registry REGISTRY_HOST \
--kotsadm-namespace REGISTRY_NAMESPACE \
--registry-username RO-USERNAME \
APP_NAMEwith the name of the application. The
APP_NAMEis included in the installation command that your vendor gave you. This is a unique identifier that KOTS will use to refer to the application that you install.
REGISTRY_HOSTwith the hostname for the private registry where you pushed the images. For example,
REGISTRY_NAMESPACEwith the namespace in the private registry where you pushed the images. For example, if you pushed the images to
app-nameis the registry namespace.
RO_USERNAMEwith the username for an account that has read-only access to the private image registry.
RO_PASSWORDwith the password for the read-only account.note
KOTS stores these read-only credentials in a Kubernetes secret in the same namespace where the admin console is installed.
KOTS uses these credentials to pull the images. To allow KOTS to pull images, the credentials are automatically created as an imagePullSecret on all of the admin console Pods.
When prompted by the
Provide the namespace where you want to install both KOTS and the application.
Create a new password for logging in to the admin console.
$ kubectl kots install application-name
Enter the namespace to deploy to: application-name
• Deploying Admin Console
• Creating namespace ✓
• Waiting for datastore to be ready ✓
Enter a new password to be used for the Admin Console: ••••••••
• Waiting for Admin Console to be ready ✓
• Press Ctrl+C to exit
• Go to http://localhost:8800 to access the Admin Console
kots installcommand completes, it creates a port forward to the admin console. The admin console is exposed internally in the cluster and can only be accessed using a port forward.
Continue to Install and Deploy the Application below to log in to the admin console and install the application.
Install and Deploy the Application
After you install KOTS, log in to the admin console to provide your license file and the
.airgap bundle, define your configuration values, run preflight checks, and install and deploy the application.
To install the application using the admin console:
Access the admin console on port 8800:
Existing cluster: If the port forward is active, go to http://localhost:8800 to access the admin console.
If you need to reopen the port forward to the admin console, run the following command:
kubectl kots admin-console -n NAMESPACE
NAMESPACEwith the namespace where KOTS is installed.
Embedded cluster: Go to the address provided in the
Kotsadmfield in the output of the installation command. For example,
(Embedded Cluster Only) On the Bypass Browser TLS warning page, review the information about how to bypass the browser TLS warning, and then click Continue to Setup.
(Embedded Cluster Only) On the HTTPS page, do one of the following:
- To use the self-signed TLS certificate only, enter the hostname (required) if you are using the identity service. If you are not using the identity service, the hostname is optional. Click Skip & continue.
- To use a custom certificate only, enter the hostname (required) if you are using the identity service. If you are not using the identity service, the hostname is optional. Then upload a private key and SSL certificate to secure communication between your browser and the admin console. Click Upload & continue.
Log in to the admin console:
- Existing cluster: Log in with the password that you created during installation.
- Embedded cluster: Log in with the password that was provided in the
Login with password (will not be shown again):field in the output of the installation command.
Upload the license file provided by your application vendor.
(Air Gap Only) Upload the
.airgapair gap bundle provided by your application vendor.
If there are configurations specific to the application, complete the fields on the configuration screen then click Continue. The required and optional configuration fields on this screen are used to build the final deployable Kubernetes manifests for the application.
If the application vendor did not include any configuration options for the application, this screen does not display.
Complete the preflight checks. KOTS automatically runs preflight checks (conformance tests) against the target namespace and cluster to ensure that the environment meets the minimum requirements to support the application.
If there are no preflight check warnings or failures, continue with deployment.
If there are any preflight check warnings and failures:
Resolve the warnings and failures, and click Re-run to run the preflight checks again.
If there are no failures that prevent application deployment, you can choose to dismiss the preflight check warnings to continue.note
Replicated recommends that you address any warnings or failures, rather than dismissing them. Preflight checks help ensure that your environment meets the requirements for application deployment.
If you are installing with minimal role-based access control (RBAC), KOTS recognizes if the preflight checks failed due to insufficient privileges.
When this occurs, a kubectl CLI preflight command displays that lets you manually run the preflight checks. The admin console automatically displays the results of the preflight checks.
After preflight checks are complete, KOTS deploys the admin console and the application, and the admin console dashboard opens:
(Recommended) Change the admin console login password:
- Click the menu in the top right corner of the admin console, then click Change password.
- Enter a new password in the dialog, and click Change Password to save.
Replicated strongly recommends that you change the password from the default provided during installation on an embedded cluster. For more information, see Changing an Admin Console Password.
(Embedded Cluster Only) Add primary and secondary nodes to the cluster. You might add nodes to either meet application requirements defined by the vendor or to support your usage of the application. See Adding Nodes to Embedded Clusters.note
Reach out to your application vendor for information about any node requirements.
(Existing Cluster Only) Configure application and cluster monitoring. This allows you to view graphs on the admin console dashboard with key metrics collected by Prometheus. See Monitoring Applications.