Merge pull request #1989 from replicatedhq/intro-kots

Update about KOTS and kURL

Author: paigecalvert

docs/intro-kots.md

@@ -2,51 +2,76 @@
 displayed_sidebar: kots
 ---
 
-# About KOTS and kURL
+import Kots from "../docs/partials/kots/_kots-definition.mdx"
 
-This topic describes Replicated KOTS and Replicated kURL, used for installing and upgrading applications in a Kubernetes cluster, and the Replicated admin console, used for managing application instances.
+# Introduction to KOTS
+
+This topic provides an introduction to the Replicated KOTS installer, including information about KOTS features, installation options, and user interfaces.
 
 :::note
-You must have the Replicated KOTS entitlement to use the KOTS and kURL installers and features.
+The Replicated KOTS entitlement is required to install applications with KOTS. For more information, see [Pricing](https://www.replicated.com/pricing) on the Replicated website.
 :::
 
-## Replicated KOTS
+## Overview
+
+<Kots/>
 
-Vendors that want to provide a UI-based installation and management experience for applications can leverage KOTS, which provides highly successful installs in diverse environments using a single installer. KOTS is a kubectl plugin that automates installations, making it quick and easy to install with minimal expertise. Applications are deployed securely to on-prem, online, and air gap environments.
+KOTS communicates securely with the Replicated vendor platform to synchronize customer licenses, check for available application updates, send instance data, share customer-generated support bundles, and more.
 
-When KOTS is combined with kURL, kURL provisions an embedded cluster on a virtual machine (VM) or bare metal server for customers that do not have their own Kubernetes cluster. Then KOTS installs the application on the embedded cluster. For more information about kURL, see [kURL](#kurl).
+Installing an application with KOTS provides access to feautures such as:
 
-KOTS also provides the Replicated admin console to make it easy for customers to install, upgrade, and manage their application instance. Customers can also use the kots CLI for installing and manage applications. For more information, see [Admin Console](#admin-console) and [kots CLI](#kots-cli).
+* Support for air gap installations
+* Support for installations on VMs or bare metal servers
+* The KOTS admin console, which provides a user interface where customers can install and manage their application instances
+* Instance telemetry automatically sent to the vendor portal for instances running in customer environments
+* Strict preflight checks that block installation if environment requirements are not met
+* Backup and restore with Replicated snapshots
+* Support for marking releases as required to prevent users from skipping them during upgrades
 
 KOTS is an open source project that is maintained by Replicated. For more information, see the [kots](https://github.com/replicatedhq/kots) repository in GitHub.
 
-## Admin Console
+## About Installing with KOTS
 
-The admin console is a customer-facing user interface that includes built-in functionality allowing users to install, manage, update, configure, monitor, backup and restore, and troubleshoot their application instances. The admin console communicates securely with KOTS to synchronize licenses, check for upgrades, and so on. 
+KOTS can be used to install applications in Kubernetes clusters, including:
+* Existing clusters brought by the user
+* Online or air gapped clusters
+* Embedded clusters provisioned on VMs or bare metal servers with Replicated embedded cluster or Replicated kURL
 
-![Admin Console Dashboard](/images/guides/kots/application.png)
+To install an application with KOTS, users first run an installation script to install KOTS in the target cluster and deploy the KOTS admin console. After KOTS is installed, users can log in to the KOTS admin console to upload their license file, configure the application, run preflight checks, and install and deploy the application.
 
-[View a larger version of this image](/images/guides/kots/application.png)
+The following diagram demonstrates how a single release promoted to the Stable channel in the Replicated vendor platform can be installed using KOTS in an embedded cluster on a VM, in an air gapped cluster, and in an existing internet-connected cluster:
+
+<img alt="Embedded cluster, air gap, and existing cluster app installation workflows" src="/images/kots-installation-overview.png" width="650px"/>
+
+[View a larger version of this image](/images/kots-installation-overview.png)
+
+As shown in the diagram above: 
+* For installations in existing internet-connected clusters, users run a command to install KOTS in their cluster.
+* For embedded cluster installations on VMs or bare metal servers, users run an installation script that both provisions a cluster in their environment and installs KOTS in the cluster.
+* For installations in air gapped clusters, users download air gap bundles for KOTS and the application from the Replicated download portal and then provide the bundles during installation.
 
-<!--
-The admin console features include:
+All users must provide a license file to install with KOTS. After KOTS is installed in the cluster, users can access the KOTS admin console to provide their license file and deploy the application.
 
-- **Config Screen:** Customize the customer-facing Config screen in the admin console to collect required or optional values from your customers that are used to run your application. 
-- **Custom Admin Console:** Customize the admin console with your company's branding, release notes, custom graphs display, application status display, and more.
-- **Backup and Restore:** Enable backup and restore capabilities so that customers can implement full disaster recovery protection for the application and the admin console. 
-- **RBAC:** Use role-based access control (RBAC) for clusters and namespaces. By default, the KOTS installation sets RBAC for the cluster, but you can scope it to namespaces instead. 
--->
+For more information about how to install applications with KOTS, see the [Installing an Application](/enterprise/installing-overview) section.
 
-## kots CLI
+## KOTS User Interfaces
 
-The kots command-line interface (CLI) is a kubectl plugin. Customers can run commands with the kots CLI to install and manage their application instances with KOTS programmatically. For more information, see [Installing the kots CLI](/reference/kots-cli-getting-started).
+This section describes the KOTS interfaces available to users for installing and managing applications.
 
-## kURL
+### KOTS Admin Console
+
+KOTS provides an admin console to make it easy for users to install, manage, update, configure, monitor, backup and restore, and troubleshoot their application instance from a GUI.
+
+The following shows an example of the admin console dashboard for an application:
+
+![Admin Console Dashboard](/images/guides/kots/application.png)
+
+[View a larger version of this image](/images/guides/kots/application.png)
 
-Replicated kURL provisions Kubernetes clusters, which allow customers who do not have an existing cluster to install your application without provisioning a cluster themselves. Clusters created by kURL are called _embedded clusters_. Embedded clusters can be provisioned in online or air gap environments.
+### kots CLI
 
-kURL has a built-in integration with KOTS through its KOTS add-on. With this integration, customers can run a kURL installation script in their virtual machine (VM) or bare metal server, which creates a cluster and then automatically installs KOTS in the cluster. Your application is then deployed with KOTS. 
+The kots command-line interface (CLI) is a kubectl plugin. Customers can run commands with the kots CLI to install and manage their application instances with KOTS programmatically.
 
-For information about how to install applications in embedded clusters, see [Installing with kURL](/enterprise/installing-embedded-cluster). For information about how to create a specification for kURL, see [Creating a Kubernetes Installer](/vendor/packaging-embedded-kubernetes).
+For information about getting started with the kots CLI, see [Installing the kots CLI](/reference/kots-cli-getting-started).
 
-kURL is an open source project that is maintained by Replicated. For more information, see the [kURL repository](https://github.com/replicatedhq/kURL) in GitHub and the [kURL documentation](https://kurl.sh).
+The kots CLI can also be used to install an application without needing to access the admin console. This can be useful for automating installations and upgrades. For information about how to run automated installations with the kots CLI, see [Installing with Automation](/enterprise/installing-existing-cluster-automation).

docs/partials/kots/_kots-definition.mdx

@@ -1 +1 @@
-Replicated KOTS is a kubectl plugin and an in-cluster admin console that provides highly successful installations of Helm charts and Kubernetes applications into customer-controlled environments, including on-prem and air gap environments. KOTS also supports installations onto VMs or bare metal servers through _embedded clusters_, which are clusters built from a customized Kubernetes distribution embedded with an application and provisioned in the customer environment at the time of installation.
+Replicated KOTS is a kubectl plugin and an in-cluster admin console that provides highly successful installations of Helm charts and Kubernetes applications into customer-controlled environments, including on-prem and air gap environments. KOTS also supports installations on VMs or bare metal servers through _embedded clusters_, which are clusters built from a customized Kubernetes distribution embedded with an application and provisioned in the customer environment at the time of installation.

docs/vendor/kurl-about.mdx

@@ -0,0 +1,51 @@
+# Introduction to kURL
+
+This topic provides an introduction to the Replicated kURL installer, including information about kURL specifications and installations.
+
+:::note
+The Replicated KOTS entitlement is required to install applications with KOTS and kURL. For more information, see [Pricing](https://www.replicated.com/pricing) on the Replicated website.
+:::
+
+## Overview
+
+kURL is an open source project maintained by Replicated that software vendors can use to create custom Kubernetes distributions that are embedded with their application. Enterprise customers can then run a kURL installation script on their virtual machine (VM) or bare metal server to provision a cluster and install the application. This allows software vendors to distribute Kubernetes applications to customers that do not have access to a cluster in their environment.
+
+For more information about the kURL open source project, see the [kURL website](https://kurl.sh).
+
+### Kubernetes Installer Specs
+
+To provision a cluster, kURL uses a spec that is defined in a manifest file with `apiVersion: cluster.kurl.sh/v1beta1` and `kind: Installer`. This _Kubernetes installer_ spec can be customized according to the application requirements by including add-ons. kURL provides add-ons for networking, storage, ingress, and more. kURL also provides a KOTS add-on, which installs KOTS in the cluster and deploys the KOTS admin console.
+
+Installer specs can be embedded with an application by promoting the spec to the same channel as the target application release in the Replicated vendor platform. When an installer spec is promoted to a channel, all releases on the channel use the installer for installations with kURL.
+
+For more information about creating Kubernetes installer specs for kURL, see [Creating a Kubernetes Installer](/vendor/packaging-embedded-kubernetes).
+
+### kURL Installations
+
+To install with kURL, users run a kURL installation script on their VM or bare metal server to provision a cluster.
+
+When the KOTS add-on is included in the Kubernetes installer spec, the kURL installation script installs the kots CLI and KOTS admin console in the cluster. After the installation script completes, users can access the admin console at the URL provided in the ouput of the command to configure and deploy the application with KOTS.
+
+The following shows an example of the output of the kURL installation script:
+
+```bash
+        Installation
+          Complete ✔
+
+Kotsadm: http://10.128.0.35:8800
+Login with password (will not be shown again): 3Hy8WYYid
+
+This password has been set for you by default. It is recommended that you change
+this password; this can be done with the following command:
+kubectl kots reset-password default
+```
+
+kURL installations are supported in online (internet-connected) and air gapped environments.
+
+For information about how to install applications with kURL, see [Online Installation with kURL](/enterprise/installing-embedded-cluster).
+
+## About the Open Source kURL Documentation
+
+The open source documentation for the kURL project is available at [kurl.sh](https://kurl.sh/docs/introduction/).
+
+The open source kURL documentation contains additional information including kURL installation options, kURL add-ons, and procedural content such as how to add and manage nodes in kURL clusters. Software vendors can use the open source kURL documentation to find detailed reference information when creating Kubernetes installer specs or testing installation.

sidebars.js

@@ -91,6 +91,7 @@ const sidebars = {
       type: 'category',
       label: 'Replicated kURL',
       items: [
+        'vendor/kurl-about',
         'vendor/packaging-embedded-kubernetes',
         'vendor/packaging-installer-storage',
         'vendor/kurl-nodeport-services',