Installing on an Existing Cluster
This topic describes how to use Replicated to install an application on an existing Kubernetes cluster. It includes procedures for installing in online and air gap environments.
Prerequisites
Before installing on an existing cluster, 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 the app manager. See RBAC Requirements in Installation Requirements.
note
If you manually created RBAC resources for the app manager as described in Namespace-scoped RBAC Requirements, include both the
--ensure-rbac=false
and--skip-rbac-check
flags when you run thekots install
command.These flags prevent the app manager from checking for or attempting to create a Role with
* * *
permissions in the namespace. For more information about these flags, see install or admin-console upgrade.Replicated recommends that you review the options available with the
kots install
command before installing. Thekots install
command includes several optional flags to support different installation use cases. For a list of options, see install in the kots CLI documentation.
Install in an Online Environment
You can install an application to an existing Kubernetes cluster that contains nodes that can access the internet. In an online installation, the Replicated app manager pulls container images from the upstream registries directly.
To install on an existing cluster in an online environment:
Run the command that was provided by the application vendor to install the kots CLI, the Replicated admin console, and the application on the cluster:
Install the latest version of the application:
curl https://kots.io/install | bash
kubectl kots install APP_SLUGReplace
APP_SLUG
with the unique slug for the application. The application slug is included in the installation command provided by the vendor.(App manager v1.67.0 and later) Install a specific version of the application: With the app manager v1.67.0 and later, you can install a specific version of the application. Use the
app-version-label
flag and the version label for a particular version of your vendor's application.curl https://kots.io/install | bash
kubectl kots install APP_SLUG --app-version-label=VERSION_LABELReplace:
APP_SLUG
with the unique slug for the application. The application slug is included in the installation command provided by the vendor.VERSION_LABEL
with the label for the version of the application to install. For example,--app-version-label=3.0.1
.
When prompted by the
kots install
command:Provide the namespace where you want to deploy the application and the admin console.
Create a new password for logging in to the admin console.
Example:
$ 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
After the kots install
command installs the admin console and the application on the cluster, it creates a port forward to the admin console. The admin console is exposed internally on the cluster and can only be accessed using a port forward.
Log in to the admin console to complete the application setup, run preflight checks, and deploy. See Completing Application Setup and Deploying.
Install in an Air Gapped Environment
When installing an application with the Replicated app manager from a .airgap
package, the container images and application manifests are provided by the application vendor in an archive that can be used to deliver the artifacts into the cluster.
This feature is only available for licenses that have the air gapped feature enabled.
You can install the admin console using the kots CLI plugin for the kubectl command-line tool. To install the admin console, you use the admin console binary bundle, kotsadm.tar.gz
.
To push images and install:
Install the kots CLI plugin. See Install without Root Access in the kots CLI reference section.
Download
kotsadm.tar.gz
from the kots release page on GitHub. See Releases in the kots GitHub repository.Run the following command to confirm that the asset version matches the kots CLI version:
kubectl kots version
Run the following command to extract admin console container images and push them into a private registry:
kubectl kots admin-console push-images ./kotsadm.tar.gz private.registry.host/app-name \
--registry-username RW_USERNAME \
--registry-password RW_PASSWORDReplace:
RW_USERNAME
with the username for an account that has read and write access to the private image registry.RW_PASSWORD
with the password for the account with read and write access.note
Replicated does not store or reuse these credentials.
Install the admin console using the images that you pushed in the previous step:
kubectl kots install app-name \
--kotsadm-namespace app-name \
--kotsadm-registry private.registry.host \
--registry-username RO-USERNAME \
--registry-password RO-PASSWORDReplace:
RO_USERNAME
with the username for an account that has read-only access to the private image registry.RO_PASSWORD
with the password for the read-only account.
note
Replicated stores these read-only credentials in a Kubernetes secret in the same namespace where the admin console is installed.
Replicated uses these credentials to pull the images. To allow Replicated to pull images, the credentials are automatically created as an imagePullSecret on all of the admin console Pods.
When prompted by the
kots install
command:Provide the namespace where you want to deploy the application and the admin console.
Create a new password for logging in to the admin console.
Example:
$ 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
After the kots install
command installs the admin console and the application on the cluster, it creates a port forward to the admin console. The admin console is exposed internally on the cluster and can only be accessed using a port forward.
Log in to the admin console to complete the application setup, run preflight checks, and deploy. See Completing Application Setup and Deploying.