Skip to main content

Requirements for Installation

This topic describes the requirements for installing applications with Replicated.

note

This topic does not include any requirements specific to your software vendor. Ensure that you meet any additional requirements for the application defined by your software vendor.

Supported Browsers​

The following table lists the browser requirements for the latest Replicated admin console.

BrowserSupport
Chrome66+
Firefox58+
Opera53+
Edge80+
Safari (Mac OS only)13+
Internet ExplorerUnsupported

Kubernetes Version Compatibility​

Each release of the open source KOTS project maintains compatibility with the current Kubernetes version, and the two most recent versions at the time of its release. This includes support against all patch releases of the corresponding Kubernetes version.

Kubernetes versions 1.22 and earlier are end-of-life (EOL). Kubernetes version 1.23 is nearing EOL. For more information about Kubernetes versions, see Release History in the Kubernetes documentation.

Replicated recommends upgrading to a KOTS version that is compatible with Kubernetes 1.24 and higher.

note

The app manager is based on the open source KOTS project. The app manager version is the same as the KOTS version. For example, KOTS v1.92 is the same as the app manager v1.92.

KOTS VersionsKubernetes Compatibility
v1.71 and laterv1.25, 1.24, v1.23
v1.66 to v1.70v1.23
v1.61 to v1.65v1.23

Existing Cluster Requirements​

To install the app manager in an existing cluster, your environment must meet the following minimum requirements.

Minimum System Requirements​

To install the admin console on an existing cluster, the cluster must meet the following requirements:

  • Admin console minimum requirements: The admin console requires a minimum of 5GB of disk space on the cluster. This includes 4GB for the object store PersistentVolume and 1GB for the rqlite PersistentVolume. The admin console pod requests 100m CPU resources and 100Mi memory. Existing clusters that have LimitRanges specified must support these values. For more information, see Requirements for Admin Console State.

  • Kubernetes version compatibility: The version of Kubernetes running on the cluster must be compatible with the version of KOTS that you use to install the application. This compatibility requirement does not include any specific and additional requirements defined by the software vendor for the application.

    For more information about the versions of Kubernetes that are compatible with each version of KOTS, see Kubernetes Version Compatibility above.

  • OpenShift version compatibility: For Red Hat OpenShift clusters, the version of OpenShift must use a supported Kubernetes version. For more information about supported Kubernetes versions, see Kubernetes Version Compatibility above.

  • Storage class: The cluster must have an existing storage class available. For more information, see Storage Classes in the Kubernetes documentation.

  • Port forwarding: To support port forwarding, Kubernetes clusters require that the SOcket CAT (socat) package is installed on each node.

    If the package is not installed on each node in the cluster, you see the following error message when the installation script attempts to connect to the admin console: unable to do port forwarding: socat not found.

    To check if the package that provides socat is installed, you can run which socat. If the package is installed, the which socat command prints the full path to the socat executable file. For example, usr/bin/socat.

    If the output of the which socat command is socat not found, then you must install the package that provides the socat command. The name of this package can vary depending on the node's operating system.

RBAC Requirements​

The user that runs the installation command must have at least the minimum role-based access control (RBAC) permissions that are required by the app manager. If the user does not have the required RBAC permissions, then an error message displays: Current user has insufficient privileges to install Admin Console.

The required RBAC permissions vary depending on if the user attempts to install the app manager with cluster-scoped access or namespace-scoped access:

Cluster-scoped RBAC Requirements (Default)​

By default, the app manager requires cluster-scoped access. With cluster-scoped access, a Kubernetes ClusterRole and ClusterRoleBinding are created that grant the app manager access to all resources across all namespaces in the cluster.

To install the app manager with cluster-scoped access, the user must meet the following RBAC requirements:

  • The user must be able to create workloads, ClusterRoles, and ClusterRoleBindings.
  • The user must have cluster-admin permissions to create namespaces and assign RBAC roles across the cluster.

Namespace-scoped RBAC Requirements​

The app manager can be installed with namespace-scoped access rather than the default cluster-scoped access. With namespace-scoped access, a Kubernetes Role and RoleBinding are automatically created that grant the app manager permissions only in the namespace where it is installed.

note

Depending on the application, namespace-scoped access for the app manager is required, optional, or not supported. Contact your software vendor for application-specific requirements.

To install or upgrade the app manager with namespace-scoped access, the user must have one of the following permission levels in the target namespace:

  • Wildcard permissions (Default): By default, when namespace-scoped access is enabled, the app manager attempts to automatically create the following Role to acquire wildcard (* * *) permissions in the target namespace:

    apiVersion: "rbac.authorization.k8s.io/v1"
    kind: "Role"
    metadata:
    name: "kotsadm-role"
    rules:
    - apiGroups: ["*"]
       resources: ["*"]
       verb: "*"

    To support this default behavior, the user must also have * * * permissions in the target namespace.

  • Minimum App manager RBAC permissions: In some cases, it is not possible to grant the user * * * permissions in the target namespace. For example, an organization might have security policies that prevent this level of permissions.

    If the user installing or upgrading the app manager cannot be granted * * * permissions in the namespace, then they can instead request the minimum RBAC permissions required by the app manager. Using the minimum app manager RBAC permissions also requires manually creating a ServiceAccount, Role, and RoleBinding for the app manager, rather than allowing the app manager to automatically create a Role with * * * permissions.

    To use the minimum app manager RBAC permissions to install or upgrade:

    1. Ensure that the user has the minimum RBAC permissions required by the app manager. The following Role lists the minimum RBAC permissions under rules:

      apiVersion: rbac.authorization.k8s.io/v1
      kind: Role
      metadata:
      labels:
          kots.io/backup: velero
          kots.io/kotsadm: "true"
      name: kotsadm-role
      rules:
        - apiGroups: [""]
          resources: ["configmaps", "persistentvolumeclaims", "pods", "secrets", "services", "limitranges"]
          verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
        - apiGroups: ["apps"]
          resources: ["daemonsets", "deployments", "statefulsets"]
          verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
        - apiGroups: ["batch"]
          resources: ["jobs", "cronjobs"]
          verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
        - apiGroups: ["networking.k8s.io", "extensions"]
          resources: ["ingresses"]
          verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
        - apiGroups: [""]
          resources: ["namespaces", "endpoints", "serviceaccounts"]
          verbs: ["get"]
        - apiGroups: ["authorization.k8s.io"]
          resources: ["selfsubjectaccessreviews", "selfsubjectrulesreviews"]
          verbs: ["create"]
        - apiGroups: ["rbac.authorization.k8s.io"]
          resources: ["roles", "rolebindings"]
          verbs: ["get"]
        - apiGroups: [""]
          resources: ["pods/log", "pods/exec"]
          verbs: ["get", "list", "watch", "create"]
        - apiGroups: ["batch"]
          resources: ["jobs/status"]
          verbs: ["get", "list", "watch"]
      note

      The minimum RBAC requirements can vary slightly depending on the cluster's Kubernetes distribution and the version of the app manager. Reach out to your application vendor if you have the required RBAC permissions listed above and you see an error related to RBAC during installation or upgrade.

    2. Save the following ServiceAccount, Role, and RoleBinding to a single YAML file, such as rbac.yaml:

      apiVersion: v1
      kind: ServiceAccount
      metadata:
      labels:
          kots.io/backup: velero
          kots.io/kotsadm: "true"
      name: kotsadm
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: Role
      metadata:
      labels:
          kots.io/backup: velero
          kots.io/kotsadm: "true"
      name: kotsadm-role
      rules:
        - apiGroups: [""]
          resources: ["configmaps", "persistentvolumeclaims", "pods", "secrets", "services", "limitranges"]
          verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
        - apiGroups: ["apps"]
          resources: ["daemonsets", "deployments", "statefulsets"]
          verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
        - apiGroups: ["batch"]
          resources: ["jobs", "cronjobs"]
          verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
        - apiGroups: ["networking.k8s.io", "extensions"]
          resources: ["ingresses"]
          verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
        - apiGroups: [""]
          resources: ["namespaces", "endpoints", "serviceaccounts"]
          verbs: ["get"]
        - apiGroups: ["authorization.k8s.io"]
          resources: ["selfsubjectaccessreviews", "selfsubjectrulesreviews"]
          verbs: ["create"]
        - apiGroups: ["rbac.authorization.k8s.io"]
          resources: ["roles", "rolebindings"]
          verbs: ["get"]
        - apiGroups: [""]
          resources: ["pods/log", "pods/exec"]
          verbs: ["get", "list", "watch", "create"]
        - apiGroups: ["batch"]
          resources: ["jobs/status"]
          verbs: ["get", "list", "watch"]
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: RoleBinding
      metadata:
      labels:
          kots.io/backup: velero
          kots.io/kotsadm: "true"
      name: kotsadm-rolebinding
      roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: Role
      name: kotsadm-role
      subjects:
      - kind: ServiceAccount
      name: kotsadm

    3. Run the following command to create the RBAC resources for the app manager in the namespace:

      kubectl apply -f RBAC_YAML_FILE -n TARGET_NAMESPACE

      Replace:

      • RBAC_YAML_FILE with the name of the YAML file that you saved in the previous step.
      • TARGET_NAMESPACE with the namespace where the user will install the app manager.
    note

    After manually creating these RBAC resources, the user must include both the --ensure-rbac=false and --skip-rbac-check flags when installing or upgrading. These flags prevent the app manager from checking for or attempting to create a Role with * * * permissions in the namespace. For more information, see Prerequisites in Installing on an Existing Cluster.

Kubernetes Installer Cluster Requirements​

To install the app manager on an embedded cluster created by the Replicated Kubernetes installer, your environment must meet the following requirements.

Minimum System Requirements​

  • 4 CPUs or equivalent per machine.
  • 8GB of RAM per machine.
  • 40GB of disk space per machine.
  • TCP ports 2379, 2380, 6443, 6783, 10250, 10251, and 10252 open between cluster nodes.
  • UDP ports 6783 and 6784 open between cluster nodes.
  • Root access is required.
  • (Rook Only) The Rook add-on version 1.4.3 and later requires block storage on each node in the cluster. For more information about how to enable block storage for Rook, see Block Storage in Rook Add-On in the kURL documentation.

Additional System Requirements​

Because the Kubernetes installer is based on the open source kURL project, which is maintained by Replicated, you must meet the additional kURL system requirements when applicable:

  • Supported Operating Systems: For supported operating systems, see Supported Operating Systems in the kURL documentation.

  • kURL Dependencies Directory: kURL installs additional dependencies in the directory /var/lib/kurl and the directory requirements must be met. See kURL Dependencies Directory in the kURL documentation.

  • Networking Requirements: Networking requirements include firewall openings, host firewalls rules, and port availability. See Networking Requirements in the kURL documentation.

  • High Availability Requirements: If you are operating a cluster with high availability, see High Availability Requirements in the kURL documentation.

  • Cloud Disk Performance: For a list of cloud VM instance and disk combinations that are known to provide sufficient performance for etcd and pass the write latency preflight, see Cloud Disk Performance in the kURL documentation.

Private Registry Requirements​

Private registries are required for air gap environments because you push the admin console container images to a private registry during installation. For online environments, it is optional to use private registries.

Private registry settings can be changed at any time. For more information, see Using Private Registries.

Make sure that you use a compatible registry. The app manager has been tested for compatibility with the following registries:

  • Docker Hub

    note

    To avoid the November 20, 2020 Docker Hub rate limits, use the kots docker ensure-secret CLI command. For more information, see Avoiding Docker Hub Rate Limits.

  • Quay

  • Amazon Elastic Container Registry (ECR)

  • Google Container Registry (GCR)

  • Azure Container Registry (ACR)

  • Harbor

  • Sonatype Nexus

Firewall Openings for Online Installations​

The following domains need to be accessible from servers performing online installations. For a list of IP addresses for these services, see replicatedhq/ips in GitHub.

No outbound internet access is required for air gapped installations.

HostExisting Cluster InstallationEmbedded Cluster InstallationDescription
Docker HubRequiredRequiredSome dependencies of KOTS are hosted as public images in Docker Hub.
replicated.appRequiredRequiredUpstream application YAML and metadata is pulled from replicated.app. The current running version of the application (if any) will be sent, in addition to a license ID and an application IDs are sent to replicated.app to authenticate and receive these YAML files. This domain is owned by Replicated, Inc., which is headquartered in Los Angeles, CA.
proxy.replicated.comRequired*Required*Private Docker images are proxied through proxy.replicated.com. The on-prem docker client uses a license ID to authenticate to proxy.replicated.com. This domain is owned by Replicated, Inc which is headquartered in Los Angeles, CA.
registry.replicated.comRequired**Required**Some applications host private images in the Replicated private registry at this domain. The on-prem docker client uses a license ID to authenticate to registry.replicated.com. This domain is owned by Replicated, Inc which is headquartered in Los Angeles, CA.
kots.ioRequiredNot RequiredRequests are made to this domain when you are installing the kots CLI. This domain is owned by Replicated, Inc., which is headquartered in Los Angeles, CA.
github.comRequiredNot RequiredRequests are made to this domain when you are installing the kots CLI.
k8s.kurl.shNot RequiredRequiredKubernetes cluster installation scripts and artifacts are served from kurl.sh. An application identifier is sent in a URL path, and bash scripts and binary executables are served from kurl.sh. This domain is owned by Replicated, Inc., which is headquartered in Los Angeles, CA.
amazonaws.comNot RequiredRequiredtar.gz packages are downloaded from Amazon S3 during embedded cluster installations. For information about dynamically scraping the IP ranges to allowlist for accessing these packages, see AWS IP address ranges in the AWS documentation.

* Required only if the application uses the Replicated proxy service. Contact your application vendor for more information.

** Required only if the application uses the Replicated private registry. Contact your application vendor for more information.