diff --git a/docs/enterprise/installing-embedded-air-gap.mdx b/docs/enterprise/installing-embedded-air-gap.mdx index 6da0e3332b..e36c3f2775 100644 --- a/docs/enterprise/installing-embedded-air-gap.mdx +++ b/docs/enterprise/installing-embedded-air-gap.mdx @@ -46,8 +46,6 @@ To install with Embedded Cluster in an air gap environment: * If the **Automatically create airgap builds for newly promoted releases in this channel** setting is enabled on the channel, watch for the build status to complete. * If automatic air gap builds are not enabled, go to the **Release history** page for the channel and build the air gap bundle manually. - For more information, see [Downloading Air Gap Bundles](/vendor/releases-download-airgap-bundles#air-gap-bundle). - :::note Errors in building either the application air gap bundle or the Embedded Cluster infrastructure will be shown if present. ::: diff --git a/docs/enterprise/installing-existing-cluster-airgapped.mdx b/docs/enterprise/installing-existing-cluster-airgapped.mdx index 28fffa842b..bf009f28e6 100644 --- a/docs/enterprise/installing-existing-cluster-airgapped.mdx +++ b/docs/enterprise/installing-existing-cluster-airgapped.mdx @@ -1,8 +1,11 @@ import IntroExisting from "../partials/install/_intro-existing.mdx" import IntroAirGap from "../partials/install/_intro-air-gap.mdx" import PrereqsExistingCluster from "../partials/install/_prereqs-existing-cluster.mdx" -import AirGapBundle from "../partials/install/_airgap-bundle-prereq.mdx" +import BuildAirGapBundle from "../partials/install/_airgap-bundle-build.mdx" +import DownloadAirGapBundle from "../partials/install/_airgap-bundle-download.mdx" +import ViewAirGapBundle from "../partials/install/_airgap-bundle-view-contents.mdx" import LicenseFile from "../partials/install/_license-file-prereq.mdx" +import AirGapLicense from "../partials/install/_airgap-license-download.mdx" import DownloadKotsBundle from "../partials/install/_download-kotsadm-bundle.mdx" import InstallCommandPrompts from "../partials/install/_kots-install-prompts.mdx" import AppNameUI from "../partials/install/_placeholder-app-name-UI.mdx" @@ -17,16 +20,6 @@ import KotsVersionMatch from "../partials/install/_kots-airgap-version-match.mdx -## 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. - -:::note -ECR does not use namespaces. -::: - ## Prerequisites Complete the following prerequisites: @@ -35,15 +28,31 @@ Complete the following prerequisites: * Ensure that there is a compatible Docker image registry available inside the network. For more information about Docker registry compatibility, see [Private Registry Requirements](/enterprise/installing-general-requirements#private-registry-requirements). - + 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. -* + :::note + Amazon Elastic Container Registry (ECR) does not use namespaces. + ::: ## Install {#air-gap} -To install KOTS and an application in an air gap existing cluster: +To install in an air gap cluster with KOTS: + +1. Download the customer license: + + + +1. Go the channel where the target release was promoted to build and download the air gap bundle for the release: + + + +1. + +1. + +1. 1. diff --git a/docs/enterprise/installing-existing-cluster-automation.mdx b/docs/enterprise/installing-existing-cluster-automation.mdx index 1e82acb2ef..37cb379693 100644 --- a/docs/enterprise/installing-existing-cluster-automation.mdx +++ b/docs/enterprise/installing-existing-cluster-automation.mdx @@ -45,19 +45,17 @@ For a tutorial that demonstrates how to install a sample application using the K ## Limitation -Replicated Embedded Cluster does not support headless installations with the KOTS CLI. +[Replicated Embedded Cluster](/vendor/embedded-overview) does not support automated, or _headless_, installations with the KOTS CLI. ## Prerequisite -Create a ConfigValues file to define the configuration settings for the application. For air gap environments, ensure that you can access the ConfigValues file that you create from your installation environment. +Create a ConfigValues YAML file to define the configuration settings for the application. For air gap environments, ensure that you can access the ConfigValues file that you create from your installation environment. + +A ConfigValues file includes the names of the configuration fields for the application along with a user-supplied `value` for each field. The ConfigValues file is specific to the application. For more information, see [Generating a ConfigValues File](/vendor/releases-configvalues). **Example:** - -As shown in the example above, the ConfigValues file includes the names of the configuration fields for the application along with a user-supplied `value` for each field. - -The ConfigValues file is specific to the application. For more information, see [Sharing a ConfigValues File](/vendor/releases-configvalues). ## Install @@ -65,7 +63,7 @@ This section provides the steps for installing an application with the KOTS CLI ### Existing Cluster -To install in an existing cluster: +To install with KOTS in an existing cluster: 1. @@ -114,13 +112,11 @@ To install with kURL on a VM or bare metal server: -### Air Gap Existing Cluster +### Air Gap Existing Cluster -Air gap installations in existing clusters require the application `.airgap` bundle and the KOTS Admin Console `kotsadm.tar.gz` air gap bundle. Additionally, images for the application and the KOTS Admin Console must be pushed to a local private registry. For more information about downloading the necessary air gap bundles, see [Downloading Air Gap Bundles](/vendor/releases-download-airgap-bundles). +To install with KOTS in an air gap existing cluster: -To install in an air gap existing cluster: - -1. Install the KOTS CLI. See [Manually Download and Install](/reference/kots-cli-getting-started#manually-download-and-install) in _Installing the KOTS CLI_. +1. 1. @@ -157,16 +153,12 @@ To install in an air gap existing cluster: -Air gap installations with kURL require the application `.airgap` bundle and the kURL `.tar.gz` air gap bundle. For more information about downloading the necessary air gap bundles, see [Downloading Air Gap Bundles](/vendor/releases-download-airgap-bundles). - To install in an air gap kURL cluster on a VM or bare metal server: 1. Download the kURL `.tar.gz` air gap bundle: - For more information, see [Download the kURL Bundle](/vendor/releases-download-airgap-bundles#installer-bundle) in _Downloading Air Gap Bundles_. - 1. 1. Create the kURL cluster: diff --git a/docs/enterprise/installing-existing-cluster.mdx b/docs/enterprise/installing-existing-cluster.mdx index fbecad560f..93a6f7780c 100644 --- a/docs/enterprise/installing-existing-cluster.mdx +++ b/docs/enterprise/installing-existing-cluster.mdx @@ -1,6 +1,5 @@ import IntroExisting from "../partials/install/_intro-existing.mdx" import PrereqsExistingCluster from "../partials/install/_prereqs-existing-cluster.mdx" -import AirGapBundle from "../partials/install/_airgap-bundle-prereq.mdx" import LicenseFile from "../partials/install/_license-file-prereq.mdx" import InstallCommandPrompts from "../partials/install/_kots-install-prompts.mdx" import AppNameUI from "../partials/install/_placeholder-app-name-UI.mdx" diff --git a/docs/enterprise/installing-kurl-airgap.mdx b/docs/enterprise/installing-kurl-airgap.mdx index edf579e37d..94e6abe027 100644 --- a/docs/enterprise/installing-kurl-airgap.mdx +++ b/docs/enterprise/installing-kurl-airgap.mdx @@ -3,10 +3,14 @@ import IntroEmbedded from "../partials/install/_intro-embedded.mdx" import IntroAirGap from "../partials/install/_intro-air-gap.mdx" import PrereqsEmbeddedCluster from "../partials/install/_prereqs-embedded-cluster.mdx" import HaLoadBalancerPrereq from "../partials/install/_ha-load-balancer-prereq.mdx" -import AirGapBundle from "../partials/install/_airgap-bundle-prereq.mdx" +import AirGapLicense from "../partials/install/_airgap-license-download.mdx" +import BuildAirGapBundle from "../partials/install/_airgap-bundle-build.mdx" +import DownloadAirGapBundle from "../partials/install/_airgap-bundle-download.mdx" +import ViewAirGapBundle from "../partials/install/_airgap-bundle-view-contents.mdx" import LicenseFile from "../partials/install/_license-file-prereq.mdx" import HAStep from "../partials/install/_embedded-ha-step.mdx" import LoginPassword from "../partials/install/_embedded-login-password.mdx" +import DownloadKurlBundle from "../partials/install/_download-kurl-bundle.mdx" import ExtractKurlBundle from "../partials/install/_extract-kurl-bundle.mdx" # Air Gap Installation with kURL @@ -23,21 +27,42 @@ Complete the following prerequisites: - - - - -* Download the `.tar.gz` air gap bundle for the kURL installer. Ensure that you can access the downloaded bundle from the environment where you will install the application. See [Download the kURL Bundle](/vendor/releases-download-airgap-bundles#installer-bundle) in _Downloading Air Gap Bundles_. - ## Install {#air-gap} To install an application with kURL: +1. Download the customer license: + + + +1. Go the channel where the target release was promoted to build and download the air gap bundle for the release: + + + +1. + +1. + +1. Download the `.tar.gz` air gap bundle for the kURL installer, which includes the components needed to run the kURL cluster and install the application with KOTS. kURL air gap bundles can be downloaded from the channel where the given release is promoted: + + * To download the kURL air gap bundle for the Stable channel: + + + + * To download the kURL bundle for channels other than Stable: + + ```bash + replicated channel inspect CHANNEL + ``` + Replace `CHANNEL` with the exact name of the target channel, which can include uppercase letters or special characters, such as `Unstable` or `my-custom-channel`. + + In the output of this command, copy the curl command with the air gap URL. + 1. -1. Run one of the following commands to create the cluster and install KOTS in air gap mode: +1. Run one of the following commands to install in air gap mode: - For a regular installation, run: @@ -68,7 +93,7 @@ To install an application with kURL: 1. Upload your license file. -1. Upload the `.airgap` application air gap bundle. +1. Upload the `.airgap` bundle for the release that you downloaded in an earlier step. 1. On the **Preflight checks** page, the application-specific preflight checks run automatically. Preflight checks are conformance tests that run against the target namespace and cluster to ensure that the environment meets the minimum requirements to support the application. Click **Deploy**. diff --git a/docs/enterprise/updating-app-manager.mdx b/docs/enterprise/updating-app-manager.mdx index 5faad23ad5..76f052ca19 100644 --- a/docs/enterprise/updating-app-manager.mdx +++ b/docs/enterprise/updating-app-manager.mdx @@ -1,6 +1,9 @@ import AdminConsole from "../partials/updating/_admin-console.mdx" import AdminConsoleAirGap from "../partials/updating/_admin-console-air-gap.mdx" import PushKotsImages from "../partials/install/_push-kotsadm-images.mdx" +import BuildAirGapBundle from "../partials/install/_airgap-bundle-build.mdx" +import DownloadAirGapBundle from "../partials/install/_airgap-bundle-download.mdx" +import ViewAirGapBundle from "../partials/install/_airgap-bundle-view-contents.mdx" # Performing Updates in Existing Clusters @@ -43,7 +46,13 @@ Add the `--deploy` flag to automatically deploy this version. To update an application in air gap environments: -1. Get the new `.airgap` bundle for the target application release and ensure that it is available on your local machine. +1. In the [Vendor Portal](https://vendor.replicated.com), go the channel where the target release is promoted to build and download the new `.airgap` bundle: + + + +1. + +1. 1. Run the following command to update the application: @@ -57,7 +66,7 @@ To update an application in air gap environments: ``` Replace: * `APP_SLUG` with the unique slug for the application. See [Get the Application Slug](/vendor/vendor-portal-manage-app#slug) in _Managing Applications_. - * `NEW_AIRGAP_BUNDLE` with the `.airgap` bundle for the target application version. See [Download Air Gap Bundles from the Download Portal](/vendor/releases-download-airgap-bundles#download-portal). + * `NEW_AIRGAP_BUNDLE` with the `.airgap` bundle for the target application version. * `REGISTRY_HOST` with the private registry that contains the Admin Console images. * `REGISTRY_NAMESPACE` with the registry namespace where the images are hosted (Optional). * `RO_USERNAME` and `RO_PASSWORD` with the username and password for an account that has read-only access to the private registry. @@ -107,11 +116,9 @@ To update KOTS in an online existing cluster: To update KOTS in an existing air gap cluster: -1. Download the target version of the following assets from the download portal or from the [Releases](https://github.com/replicatedhq/kots/releases/latest) page in the KOTS GitHub repository: +1. Download the target version of the following assets from the [Releases](https://github.com/replicatedhq/kots/releases/latest) page in the KOTS GitHub repository: * KOTS Admin Console `kotsadm.tar.gz` bundle * KOTS CLI plugin - - For more information, see [Download Air Gap Bundles from the Download Portal](/vendor/releases-download-airgap-bundles#download-portal). Ensure that you can access the downloaded bundles from the environment where the Admin Console is running. diff --git a/docs/enterprise/updating-kurl.mdx b/docs/enterprise/updating-kurl.mdx index bedb40062e..886fe03ed8 100644 --- a/docs/enterprise/updating-kurl.mdx +++ b/docs/enterprise/updating-kurl.mdx @@ -2,6 +2,7 @@ import InstallerRequirements from "../partials/updating/_installerRequirements.m import UpgradePrompt from "../partials/updating/_upgradePrompt.mdx" import AdminConsole from "../partials/updating/_admin-console.mdx" import AdminConsoleAirGap from "../partials/updating/_admin-console-air-gap.mdx" +import DownloadKurlBundle from "../partials/install/_download-kurl-bundle.mdx" # Performing Updates in kURL Clusters @@ -62,14 +63,29 @@ To update the kURL cluster in an air gap environment: 1. Edit the kURL installer spec as desired. For example, update the version of Kubernetes or add, remove, or update add-ons. For more information, see [Creating a kURL Installer](/vendor/packaging-embedded-kubernetes). -1. On each node in the cluster, download the kURL `.tar.gz` air gap bundle for the updated spec. See [Download the kURL Bundle](/vendor/releases-download-airgap-bundles#installer-bundle) in _Downloading Air Gap Bundles_. +1. Repeat the following steps on each node in the cluster to download and extract the kURL `.tar.gz` air gap bundle for the updated spec: - Then, extract the contents: + 1. Download the kURL `.tar.gz` air gap bundle from the channel where the new kURL installer spec is promoted: - ```bash - tar -xvzf FILENAME.tar.gz - ``` - Replace `FILENAME` with the name of the downloaded kURL `.tar.gz` air gap bundle. + * To download the kURL air gap bundle for the Stable channel: + + + + * To download the kURL bundle for channels other than Stable: + + ```bash + replicated channel inspect CHANNEL + ``` + Replace `CHANNEL` with the exact name of the target channel, which can include uppercase letters or special characters, such as `Unstable` or `my-custom-channel`. + + In the output of this command, copy the curl command with the air gap URL. + + 1. Extract the contents of the bundle: + + ```bash + tar -xvzf FILENAME.tar.gz + ``` + Replace `FILENAME` with the name of the downloaded kURL `.tar.gz` air gap bundle. 1. Run the following KURL script to ensure all required images are available: diff --git a/docs/partials/airgap/_airgap-bundle.mdx b/docs/partials/airgap/_airgap-bundle.mdx index c119ceeb60..94eb3b9833 100644 --- a/docs/partials/airgap/_airgap-bundle.mdx +++ b/docs/partials/airgap/_airgap-bundle.mdx @@ -1 +1 @@ -Air gap bundles (`.airgap`) contain the images needed to install and run a single release of your application in _air gap_ environments with no outbound internet access. For more information about how to build and download air gap bundles, see [Downloading Air Gap Bundles](/vendor/releases-download-airgap-bundles). \ No newline at end of file +Air gap bundles (`.airgap`) contain the images needed to install and run a single release of your application in _air gap_ environments with no outbound internet access. \ No newline at end of file diff --git a/docs/partials/install/_airgap-bundle-build.mdx b/docs/partials/install/_airgap-bundle-build.mdx new file mode 100644 index 0000000000..301b6b45b3 --- /dev/null +++ b/docs/partials/install/_airgap-bundle-build.mdx @@ -0,0 +1,10 @@ +* If the **Automatically create airgap builds for newly promoted releases in this channel** setting is enabled on the channel, watch for the build status to complete. +* If automatic air gap builds are not enabled, go to the **Release history** page for the channel and build the air gap bundle manually. + + Release history link on a channel card + + [View a larger version of this image](/images/release-history-link.png) + + ![Build button on the Release history page](/images/release-history-build-airgap-bundle.png) + + [View a larger version of this image](/images/release-history-build-airgap-bundle.png) \ No newline at end of file diff --git a/docs/partials/install/_airgap-bundle-download.mdx b/docs/partials/install/_airgap-bundle-download.mdx new file mode 100644 index 0000000000..50667e86da --- /dev/null +++ b/docs/partials/install/_airgap-bundle-download.mdx @@ -0,0 +1 @@ +After the build completes, download the bundle. Ensure that you can access the downloaded bundle from the environment where you will install the application. \ No newline at end of file diff --git a/docs/partials/install/_airgap-bundle-prereq.mdx b/docs/partials/install/_airgap-bundle-prereq.mdx deleted file mode 100644 index a572f65371..0000000000 --- a/docs/partials/install/_airgap-bundle-prereq.mdx +++ /dev/null @@ -1 +0,0 @@ -* Download the `.airgap` bundle for the application. Ensure that you can access the downloaded bundle from the environment where you will install the application. See [Downloading Air Gap Bundles](/vendor/releases-download-airgap-bundles). \ No newline at end of file diff --git a/docs/partials/install/_airgap-bundle-view-contents.mdx b/docs/partials/install/_airgap-bundle-view-contents.mdx new file mode 100644 index 0000000000..24c32a4966 --- /dev/null +++ b/docs/partials/install/_airgap-bundle-view-contents.mdx @@ -0,0 +1,7 @@ +(Optional) View the contents of the downloaded bundle: + + ```bash + tar -zxvf AIRGAP_BUNDLE + ``` + + Where `AIRGAP_BUNDLE` is the filename for the `.airgap` bundle that you downloaded. \ No newline at end of file diff --git a/docs/partials/install/_airgap-license-download.mdx b/docs/partials/install/_airgap-license-download.mdx new file mode 100644 index 0000000000..fb94608bcb --- /dev/null +++ b/docs/partials/install/_airgap-license-download.mdx @@ -0,0 +1,15 @@ +1. In the [Vendor Portal](https://vendor.replicated.com), go to the **Customers** page. + +1. Click on the name of the target customer and go to the **Manage customer** tab. + +1. Under **License options**, enable the **Airgap Download Enabled** option. Click **Save Changes**. + + ![Airgap Download Enabled option](/images/airgap-download-enabled.png) + + [View a larger version of this image](/images/airgap-download-enabled.png) + +1. At the top of the screen, click **Download license** to download the air gap enabled license. + + ![Download air gap license](/images/download-airgap-license.png) + + [View a larger version of this image](/images/download-airgap-license.png) \ No newline at end of file diff --git a/docs/partials/install/_automation-intro-embedded.mdx b/docs/partials/install/_automation-intro-embedded.mdx index 4df34a73ad..35b2676c75 100644 --- a/docs/partials/install/_automation-intro-embedded.mdx +++ b/docs/partials/install/_automation-intro-embedded.mdx @@ -1 +1 @@ -You can use Replicated kURL to provision a cluster and install an application on a VM or bare metal server. When you use the KOTS CLI to install an application in a kURL cluster, you first run the kURL installation script to provision the cluster and automatically install KOTS in the cluster. Then, you can run the `kots install` command to install the application. \ No newline at end of file +When you use the KOTS CLI to install an application in a kURL cluster, you first run the kURL installation script to provision the cluster and automatically install KOTS in the cluster. Then, you can run the `kots install` command to install the application. \ No newline at end of file diff --git a/docs/partials/install/_download-kotsadm-bundle.mdx b/docs/partials/install/_download-kotsadm-bundle.mdx index 4d3e4bd2f9..136f43f2fc 100644 --- a/docs/partials/install/_download-kotsadm-bundle.mdx +++ b/docs/partials/install/_download-kotsadm-bundle.mdx @@ -1 +1,5 @@ -Download the `kotsadm.tar.gz` air gap bundle from the [Releases](https://github.com/replicatedhq/kots/releases) page in the kots GitHub repository or from the Download Portal. For more information, see [Download the KOTS Admin Console Bundle](/vendor/releases-download-airgap-bundles#download-the-kots-admin-console-bundle) in _Downloading Air Gap Bundles_. The `kotsadm.tar.gz` air gap bundle includes the container images for the KOTS Admin Console. \ No newline at end of file +Download the `kotsadm.tar.gz` air gap bundle from the [Releases](https://github.com/replicatedhq/kots/releases) page in the kots repository in GitHub. Ensure that you can access the downloaded bundle from the environment where you will install the application. + +:::note +The version of the `kotsadm.tar.gz` air gap bundle used must be compatible with the version of the `.airgap` bundle for the given application release. +::: \ No newline at end of file diff --git a/docs/partials/install/_download-kurl-bundle.mdx b/docs/partials/install/_download-kurl-bundle.mdx index 319771495c..d06687ef56 100644 --- a/docs/partials/install/_download-kurl-bundle.mdx +++ b/docs/partials/install/_download-kurl-bundle.mdx @@ -1,4 +1,4 @@ -``` +```bash export REPLICATED_APP=APP_SLUG curl -LS https://k8s.kurl.sh/bundle/$REPLICATED_APP.tar.gz -o $REPLICATED_APP.tar.gz ``` diff --git a/docs/partials/install/_placeholder-airgap-bundle.mdx b/docs/partials/install/_placeholder-airgap-bundle.mdx index f97697501f..148733fdf2 100644 --- a/docs/partials/install/_placeholder-airgap-bundle.mdx +++ b/docs/partials/install/_placeholder-airgap-bundle.mdx @@ -1 +1,3 @@ -* `PATH_TO_AIRGAP_BUNDLE` with the path to the application `.airgap` bundle. For information about downloading the `.airgap` bundle, see [Build and Download the Application Bundle](/vendor/releases-download-airgap-bundles#air-gap-bundle) in _Downloading Air Gap Bundles_. \ No newline at end of file +* `PATH_TO_AIRGAP_BUNDLE` with the path to the `.airgap` bundle for the application release. You can build and download the air gap bundle for a release in the [Vendor Portal](https://vendor.replicated.com) on the **Release history** page for the channel where the release is promoted. + + Alternatively, for information about building and downloading air gap bundles with the Vendor API v3, see [Trigger airgap build for a channel's release](https://replicated-vendor-api.readme.io/reference/channelreleaseairgapbuild) and [Get airgap bundle download URL for the active release on the channel](https://replicated-vendor-api.readme.io/reference/channelreleaseairgapbundleurl) in the Vendor API v3 documentation. \ No newline at end of file diff --git a/docs/partials/install/_placeholders-global.mdx b/docs/partials/install/_placeholders-global.mdx index 6201aa9598..8f69fd029c 100644 --- a/docs/partials/install/_placeholders-global.mdx +++ b/docs/partials/install/_placeholders-global.mdx @@ -2,6 +2,6 @@ * `PASSWORD` with a shared password for accessing the Admin Console. -* `PATH_TO_LICENSE` with the path to your license file. +* `PATH_TO_LICENSE` with the path to your license file. See [Downloading Customer Licenses](/vendor/licenses-download). For information about how to download licenses with the Vendor API v3, see [Download a customer license file as YAML](https://replicated-vendor-api.readme.io/reference/downloadlicense) in the Vendor API v3 documentation. -* `PATH_TO_CONFIGVALUES` with the path to the ConfigValues file. \ No newline at end of file +* `PATH_TO_CONFIGVALUES` with the path to the ConfigValues file. See [Generating a ConfigValues File](/vendor/releases-configvalues). \ No newline at end of file diff --git a/docs/partials/updating/_admin-console-air-gap.mdx b/docs/partials/updating/_admin-console-air-gap.mdx index 9403e6a8a7..74b6baee0b 100644 --- a/docs/partials/updating/_admin-console-air-gap.mdx +++ b/docs/partials/updating/_admin-console-air-gap.mdx @@ -1,6 +1,15 @@ +import BuildAirGapBundle from "../install/_airgap-bundle-build.mdx" +import DownloadAirGapBundle from "../install/_airgap-bundle-download.mdx" +import ViewAirGapBundle from "../install/_airgap-bundle-view-contents.mdx" + To perform an air gap update from the Admin Console: -1. Download the `.airgap` bundle for the new application version. Ensure that you can access the downloaded bundle from the environment where the Admin Console is running. +1. In the [Vendor Portal](https://vendor.replicated.com), go the channel where the target release is promoted to build and download the new `.airgap` bundle: + + + +1. +1. 1. In the Admin Console, go to the **Version History** tab. 1. Click **Upload a new version**. diff --git a/docs/reference/kots-cli-getting-started.md b/docs/reference/kots-cli-getting-started.md index 3a9884330d..c19301ed28 100644 --- a/docs/reference/kots-cli-getting-started.md +++ b/docs/reference/kots-cli-getting-started.md @@ -91,9 +91,7 @@ To manually download and install the KOTS CLI: 1. Download the KOTS CLI release for your operating system. - To download the KOTS CLI release from the download portal, see [Download Air Gap Bundles from the Download Portal](/vendor/releases-download-airgap-bundles#download-portal). - - Alternatively, you can run one of the following commands to download the latest version of the KOTS CLI from the [Releases](https://github.com/replicatedhq/kots/releases/latest) page in the KOTS GitHub repository: + You can run one of the following commands to download the latest version of the KOTS CLI from the [Releases](https://github.com/replicatedhq/kots/releases/latest) page in the KOTS GitHub repository: * **MacOS (AMD and ARM)**: diff --git a/docs/vendor/customer-reporting.md b/docs/vendor/customer-reporting.md index e844893ad2..2b84b6387f 100644 --- a/docs/vendor/customer-reporting.md +++ b/docs/vendor/customer-reporting.md @@ -54,11 +54,10 @@ For more information about how to interpret the time to install metrics, see [Ti ### Download Portal From the **Download portal** section, you can: -* Copy the URL of the download portal for the customer. -* Generate a new password for the download portal. The customer uses this password to log in. -* Access the unique download portal for the customer. +* Manage the password for the Download Portal +* Access the unique Download Portal URL for the customer -You can use the download portal to give your customers access to the files they need to install your application, such as their license file or air gap bundles. For more information, see [Sharing Assets through the Download Portal](releases-share-download-portal). +You can use the Download Portal to give your customers access to the files they need to install your application, such as their license file or air gap bundles. For more information, see [Downloading Assets from the Download Portal](releases-share-download-portal). ### Instances diff --git a/docs/vendor/helm-packaging-airgap-bundles.mdx b/docs/vendor/helm-packaging-airgap-bundles.mdx index b0e055f4f2..b9513046e0 100644 --- a/docs/vendor/helm-packaging-airgap-bundles.mdx +++ b/docs/vendor/helm-packaging-airgap-bundles.mdx @@ -71,7 +71,5 @@ Many applications have images that are included or excluded based on a given con ## Related Topics -* [Downloading Air Gap Bundles](/vendor/releases-download-airgap-bundles) -* [Build and Download the Application Bundle](/vendor/releases-download-airgap-bundles#air-gap-bundle) * [builder](/reference/custom-resource-helmchart-v2#builder) * [Air Gap Installation in Existing Clusters](/enterprise/installing-existing-cluster-airgapped) \ No newline at end of file diff --git a/docs/vendor/kots-faq.mdx b/docs/vendor/kots-faq.mdx index 6f2965abfd..2feef2a6ed 100644 --- a/docs/vendor/kots-faq.mdx +++ b/docs/vendor/kots-faq.mdx @@ -107,7 +107,7 @@ Customer-specific Embedded Cluster installation instructions are provided in the Yes. The Embedded Cluster and KOTS installers support installation in _air gap_ environments with no outbound internet access. -To support air gap installations, vendors can build `.airgap` bundles for their application in the Vendor Portal that contain all the required assets for a specific release of the application. Additionally, Replicated provides bundles that contain the assets for the Replicated installers. For more information how to build and download air gap bundles, see [Downloading Air Gap Bundles](/vendor/releases-download-airgap-bundles). +To support air gap installations, vendors can build air gap bundles for their application in the Vendor Portal that contain all the required assets for a specific release of the application. Additionally, Replicated provides bundles that contain the assets for the Replicated installers. For more information about how to install with Embedded Cluster and KOTS in air gap environments, see [Air Gap Installation with Embedded Cluster](/enterprise/installing-embedded-air-gap) and [Air Gap Installation in Existing Clusters](/enterprise/installing-existing-cluster-airgapped). diff --git a/docs/vendor/licenses-download.md b/docs/vendor/licenses-download.md index d877b9410f..9a7c21f00c 100644 --- a/docs/vendor/licenses-download.md +++ b/docs/vendor/licenses-download.md @@ -1,3 +1,5 @@ +import AirGapLicenseDownload from "../partials/install/_airgap-license-download.mdx" + # Downloading Customer Licenses This topic describes how to download a license file from the Replicated Vendor Portal. @@ -23,18 +25,4 @@ The **Airgap Download Enabled** license option allows KOTS to install an applica To enable the air gap entitlement and download the license: -1. In the [Vendor Portal](https://vendor.replicated.com), go to the **Customers** page. - -1. Click on the name of the target customer and go to the **Manage customer** tab. - -1. Under **License options**, enable the **Airgap Download Enabled** option. Click **Save Changes**. - - ![Airgap Download Enabled option](/images/airgap-download-enabled.png) - - [View a larger version of this image](/images/airgap-download-enabled.png) - -1. At the top of the screen, click **Download license** to download the air gap enabled license. - - ![Download air gap license](/images/download-airgap-license.png) - - [View a larger version of this image](/images/download-airgap-license.png) \ No newline at end of file + \ No newline at end of file diff --git a/docs/vendor/releases-about.mdx b/docs/vendor/releases-about.mdx index bc5be6537e..eb96189192 100644 --- a/docs/vendor/releases-about.mdx +++ b/docs/vendor/releases-about.mdx @@ -51,7 +51,7 @@ The following describes each of the channel settings: For more information about configuring custom domains and assigning default domains, see [Using Custom Domains](custom-domains-using). * The following channel settings apply only to applications that support KOTS: - * **Automatically create airgap builds for newly promoted releases in this channel**: When enabled, the Vendor Portal automatically builds an air gap bundle when a new release is promoted to the channel. When disabled, you can generate an air gap bundle manually for a release on the **Release History** page for the channel. For more information, see [Downloading Air Gap Bundles](releases-download-airgap-bundles). + * **Automatically create airgap builds for newly promoted releases in this channel**: When enabled, the Vendor Portal automatically builds an air gap bundle when a new release is promoted to the channel. When disabled, you can generate an air gap bundle manually for a release on the **Release History** page for the channel. * **Enable semantic versioning**: When enabled, the Vendor Portal verifies that the version label for any releases promoted to the channel uses a valid semantic version. For more information, see [Semantic Versioning](releases-about#semantic-versioning) in _About Releases_. * **Enable new airgap bundle format**: When enabled, air gap bundles built for releases promoted to the channel use a format that supports image digests. This air gap bundle format also ensures that identical image layers are not duplicated, resulting in a smaller air gap bundle size. For more information, see [Using Image Digests in Air Gap Installations](private-images-tags-digests#digests-air-gap) in _Using Image Tags and Digests_. diff --git a/docs/vendor/releases-configvalues.md b/docs/vendor/releases-configvalues.md index 498929ebdf..827a46f04c 100644 --- a/docs/vendor/releases-configvalues.md +++ b/docs/vendor/releases-configvalues.md @@ -6,7 +6,7 @@ import SelectOneExample from "../partials/configValues/_selectOneExample.mdx" import TextExample from "../partials/configValues/_textExample.mdx" import TextAreaExample from "../partials/configValues/_textareaExample.mdx" -# Sharing a ConfigValues File +# Generating a ConfigValues File This topic describes how to view the ConfigValues file for an application installed with Replicated KOTS and prepare the ConfigValues file to be shared with your users. diff --git a/docs/vendor/releases-download-airgap-bundles.mdx b/docs/vendor/releases-download-airgap-bundles.mdx deleted file mode 100644 index 8e1dba5b9c..0000000000 --- a/docs/vendor/releases-download-airgap-bundles.mdx +++ /dev/null @@ -1,150 +0,0 @@ -import DownloadPortal from "../partials/kots/_download-portal-about.mdx" - -# Downloading Air Gap Bundles - -This topic describes how to download air gap bundles for your application, the Replicated KOTS admin console, and the Replicated kURL installer. -## Overview - -_Air gap bundles_ are required to install applications in air gap environments with Replicated KOTS. Air gap bundles include the images needed to install and run applications in an environment that has no outbound internet access. - -Air gap installations with KOTS require an air gap bundle with the application assets, as well as an air gap bundle for the KOTS or kURL installer depending on the installation method. The following describes the contents of each type of air gap bundle: -* **`.airgap`**: Assets for a specific release of the application, such as Kubernetes YAML files and Docker images. -* **`kotsadm.tar.gz`**: Container images for the Replicated KOTS admin console. Required for existing cluster installations in air gap environments. -* **kURL `.tar.gz`**: Open source components to run the cluster, including the container runtime, Kubernetes, the KOTS admin console, the kURL image registry and a number of other [kURL add-ons](https://kurl.sh/add-ons). Required for embedded cluster installations with kURL in air gap environments. - -## Build and Download the Application Bundle {#air-gap-bundle} - -This section describes how to build and download the application `.airgap` bundle from the Vendor Portal. For information about building and downloading `.airgap` bundles with the Vendor API v3, see [Trigger airgap build for a channel's release](https://replicated-vendor-api.readme.io/reference/channelreleaseairgapbuild) and [Get airgap bundle download URL for the active release on the channel](https://replicated-vendor-api.readme.io/reference/channelreleaseairgapbundleurl) in the Vendor API v3 documentation. - -For information about how to download the `.airgap` bundle from the Replicated download portal, see [Download Air Gap Bundles from the Download Portal](#download-portal) below. - -To build and download the `.airgap` bundle for a release: - -1. In the [Vendor Portal](https://vendor.replicated.com), go to **Channels**. On the target channel, click **Release history**. - - Release history link on a channel card - - [View a larger version of this image](/images/release-history-link.png) - -1. On the **Release history** page, click **Build** to build the `.airgap` bundle. - - :::note - By default, the Stable and Beta channels automatically build `.airgap` bundles on new releases. - To edit this functionality on any channel, enable or disable the **Automatically create airgap builds for all releases in this channel** toggle in the channel settings. - ::: - - ![Build button on the Release history page](/images/release-history-build-airgap-bundle.png) - - [View a larger version of this image](/images/release-history-build-airgap-bundle.png) - -1. After the `.airgap` bundle is built, click **Download Bundle**. - -1. (Optional) View the contents of the downloaded bundle: - - ```bash - tar -zxvf AIRGAP_BUNDLE - ``` - Where `AIRGAP_BUNDLE` is the filename for the `.airgap` bundle that you downloaded. - -## Download the KOTS Admin Console Bundle - -Air gap installations in existing clusters require the `kotsadm.tar.gz` air gap bundle, which includes the images for the KOTS admin console. The version of the `kotsadm.tar.gz` air gap bundle used must be compatible with the version of the application `.airgap` bundle. - -The `kotsadm.tar.gz` air gap bundle for each version of KOTS is available for download on the [Releases](https://github.com/replicatedhq/kots/releases) page in the kots repository in GitHub. - -You can also download the `kotsadm.tar.gz` air gap bundle from the Replicated download portal to ensure its compatibility with the application `.airgap` bundle. For more information, see [Download Air Gap Bundles from the Download Portal](#download-portal) below. - -## Download the kURL Bundle {#installer-bundle} - -Air gap installations in embedded clusters created with kURL require the kURL `.tar.gz` air gap bundle, which includes the components needed to run the cluster and install the application with KOTS. - -The kURL bundle is kept separate from the `.airgap` bundle for the following reasons: -* The kURL bundle can get quite large, so this method lets you update your application with a smaller bundle size. -* Whereas air gap bundles for an application often need to be rebuilt with each new release, kURL air gap bundles only need to be built when the underlying cluster components or add-ons must be updated. - -kURL air gap bundles are specific to channels. The kURL air gap bundle used for installation must be downloaded from the same channel where the target release is promoted to ensure its compatibility with the application `.airgap` bundle. - -You can also download the kURL air gap bundle from the Replicated download portal. For more information, see [Download Air Gap Bundles from the Download Portal](#download-portal) below. - -#### Download the kURL Bundle for the Stable Channel - -To download the kURL air gap bundle for the Stable channel: - -```shell -export REPLICATED_APP=APP_SLUG -curl -LS https://k8s.kurl.sh/bundle/$REPLICATED_APP.tar.gz -o $REPLICATED_APP.tar.gz -``` - -Where `APP_SLUG` is the unqiue slug for the application. You can find the slug on the **Application Settings** page in the [Vendor Portal](https://vendor.replicated.com/apps). For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug) in _Managing Applications_. - -#### Download the kURL Bundle for Other Channels - -To download the kURL bundle for channels other than Stable: - -1. Run the following command to get the air gap URL: - - ```shell - replicated channel inspect CHANNEL - ``` - Replace `CHANNEL` with the exact name of the target channel, which can include uppercase letters or special characters, such as `Unstable` or `my-custom-channel`. - - The output shows valid URLs for existing cluster, embedded kURL cluster, and air gap installations. For example: - - ```bash - ID: 2cQZqq44qwTH - NAME: Beta - DESCRIPTION: - RELEASE: - VERSION: - EXISTING: - - curl -fsSL https://kots.io/install | bash - kubectl kots install gitea/beta - - EMBEDDED: - - curl -fsSL https://k8s.kurl.sh/gitea-beta | sudo bash - - AIRGAP: - - curl -fSL -o gitea-beta.tar.gz https://k8s.kurl.sh/bundle/gitea-beta.tar.gz - # ... scp or sneakernet gitea-beta.tar.gz to airgapped machine, then - tar xvf gitea-beta.tar.gz - sudo bash ./install.sh airgap - ``` - -1. In the output of the command, copy the `curl` command with the air gap URL. - -## Download Air Gap Bundles from the Download Portal {#download-portal} - - - -To download air gap bundles from the download portal: - -1. In the [Vendor Portal](https://vendor.replicated.com), on the **Customers** page, click on the name of the target customer. - - :::note - The **Airgap Download Enabled** option must be enabled for the customer on the **Manage customer** page to download air gap bundles from the download portal. - ::: - -1. In the **Download portal** section, click **Generate new password**. Copy the password to your clipboard. - - download portal link - - [View a larger version of this image](/images/download-portal-link.png) - -1. Click **Visit download portal** and log in using the password that you copied. - - The following is an example of the download portal for an air gap customer: - - ![download portal for existing cluster air gap installs](/images/download-portal-existing-cluster.png) - - [View a larger version of this image](/images/download-portal-existing-cluster.png) - -1. On the left side of the screen, select one of the following: - * **Bring my own cluster**: View the air gap bundles for existing cluster installations. - * **Embedded cluster**: View the air gap bundles for embedded cluster installations with kURL. - -1. Under **Select application version**, use the dropdown to select the target application release version. The download portal automatically makes the correct air gap bundles available for download based on the selected application version. - -1. Click the download button to download each air gap bundle. \ No newline at end of file diff --git a/docs/vendor/releases-share-download-portal.md b/docs/vendor/releases-share-download-portal.md index 18aa08a25e..38f26e209a 100644 --- a/docs/vendor/releases-share-download-portal.md +++ b/docs/vendor/releases-share-download-portal.md @@ -1,39 +1,54 @@ import DownloadPortal from "../partials/kots/_download-portal-about.mdx" -# Sharing Assets Through the Download Portal +# Downloading Assets from the Download Portal -This topic describes how to share customer license files, air gap bundles, and other assets with customers through the Replicated download portal. +This topic describes how to download customer license files, air gap bundles, and other assets from the Replicated Download Portal. + +For information about downloading air gap bundles and licenses with the Vendor API v3, see the following pages in the Vendor API v3 documentation: +* [Download a customer license file as YAML](https://replicated-vendor-api.readme.io/reference/downloadlicense) +* [Trigger airgap build for a channel's release](https://replicated-vendor-api.readme.io/reference/channelreleaseairgapbuild) +* [Get airgap bundle download URL for the active release on the channel](https://replicated-vendor-api.readme.io/reference/channelreleaseairgapbundleurl) ## Overview -The most common use case for the download portal is for customers installing into air gap environments who must download both their license file as well as multiple air gap bundles. In this case, the download portal makes it easy for customers to find and download the correct KOTS admin console or kURL air gap bundle based on the selected application version to ensure compatibility. +The most common use case for the Download Portal is for customers installing into air gap environments who need to download both their license file as well as multiple air gap bundles. -The following is an example of the download portal for an air gap customer installing in their own existing cluster: +The following is an example of the Download Portal for an air gap customer installing in their own existing cluster: -![download portal for existing cluster air gap installs](/images/download-portal-existing-cluster.png) +![Download Portal for existing cluster air gap installs](/images/download-portal-existing-cluster.png) [View a larger version of this image](/images/download-portal-existing-cluster.png) -The following is an example of the download portal for an air gap customer installing in an embedded cluster with kURL: +## Limitation + +Installation assets for [Replicated Embedded Cluster](/vendor/embedded-overview) are not available for download in the Download Portal. + +## Download Assets from the Download Portal + +To log in to the Download Portal and download assets: -![download portal for kURL air gap installs](/images/download-portal-kurl.png) +1. In the [Vendor Portal](https://vendor.replicated.com), on the **Customers** page, click on the name of the customer. -[View a larger version of this image](/images/download-portal-kurl.png) +1. (Optional) On the **Manage customer** tab, enable the **Airgap Download Enabled** option. This makes air gap bundles available in the Download Portal. -## Get the Customer-Specific Download Portal URL and Password + ![airgap download enabled license option](/images/airgap-download-enabled.png) -To share installation files with a customer, you can send the customer their unique link and password for the download portal. + [View a larger version of this image](/images/airgap-download-enabled.png) -To get the URL and generate a password for the download portal: +1. On the **Reporting** tab, in the **Download portal** section, click **Manage customer password**. -1. In the [Vendor Portal](https://vendor.replicated.com), on the **Customers** page, click on the name of the target customer. + ![download portal section](/images/download-portal-link.png) -1. In the **Download portal** section, click **Manage customer password**. + [View a larger version of this image](/images/download-portal-link.png) 1. In the pop-up window, enter a password or click **Generate**. + download portal password pop-up + + [View a larger version of this image](/images/download-portal-password-popup.png) + 1. Click **Copy** to copy the password to your clipboard. After the password is saved, it cannot be retrieved again. If you lose the password, you can generate a new one. @@ -47,4 +62,22 @@ and preview your customer's experience. By default, the Download Portal uses the domain `get.replicated.com`. You can optionally use a custom domain for the Download Portal. For more information, see [Using Custom Domains](/vendor/custom-domains-using). ::: -1. Send the URL and password for the Download Portal to your customer. \ No newline at end of file +1. In the Download Portal, on the left side of the screen, select one of the following: + * **Bring my own cluster**: View the downloadable assets for existing cluster installations with KOTS. + * **Embedded cluster**: View the downloadable assets for Replicated kURL installations. + + :::note + Installation assets for [Replicated Embedded Cluster](/vendor/embedded-overview) are not available for download in the Download Portal. + ::: + + The following is an example of the Download Portal for an air gap customer: + + ![download portal for existing cluster air gap installs](/images/download-portal-existing-cluster.png) + + [View a larger version of this image](/images/download-portal-existing-cluster.png) + +1. Under **Select application version**, use the dropdown to select the target application release version. The Download Portal automatically makes the correct air gap bundles available for download based on the selected application version. + +1. Click the download button to download each asset. + +1. To share installation files with a customer, send the customer their unique link and password for the Download Portal. \ No newline at end of file diff --git a/netlify.toml b/netlify.toml index ccaafdccde..37284d52ba 100644 --- a/netlify.toml +++ b/netlify.toml @@ -61,6 +61,10 @@ from = "https://docs.replicated.com/vendor/helm-mapping-example" to = "https://docs.replicated.com/vendor/tutorial-config-setup" +[[redirects]] + from = "https://docs.replicated.com/vendor/releases-download-airgap-bundles" + to = "https://docs.replicated.com/vendor/releases-share-download-portal" + ################################################### # Redirects To the Vendor Section ################################################### diff --git a/sidebars.js b/sidebars.js index 0ff0d94682..1a42c79b8a 100644 --- a/sidebars.js +++ b/sidebars.js @@ -157,6 +157,7 @@ const sidebars = { 'vendor/releases-creating-cli', 'vendor/helm-install-release', 'vendor/releases-sharing-license-install-script', + 'vendor/releases-share-download-portal', 'reference/linter', ], }, @@ -169,6 +170,7 @@ const sidebars = { 'vendor/licenses-adding-custom-fields', 'vendor/licenses-using-builtin-fields', 'vendor/licenses-about-types', + 'vendor/licenses-download', { type: 'category', label: 'Querying License Entitlements', @@ -320,16 +322,6 @@ const sidebars = { 'vendor/operator-defining-additional-namespaces', ], }, - { - type: 'category', - label: 'Downloading and Sharing Assets for KOTS Releases', - items: [ - 'vendor/releases-download-airgap-bundles', - 'vendor/licenses-download', - 'vendor/releases-share-download-portal', - 'vendor/releases-configvalues', - ], - }, ], }, // KOTS ENTERPRISE USER DOCS @@ -360,7 +352,7 @@ const sidebars = { }, { type: 'category', - label: 'Installing in Existing Clusters', + label: 'Installing in Existing Clusters with KOTS', items: [ 'enterprise/installing-existing-cluster', 'enterprise/installing-existing-cluster-airgapped', @@ -375,7 +367,15 @@ const sidebars = { 'enterprise/cluster-management-add-nodes', ], }, - 'enterprise/installing-existing-cluster-automation', + { + type: 'category', + label: 'Installing with the KOTS CLI', + items: [ + 'enterprise/installing-existing-cluster-automation', + 'vendor/releases-configvalues', + ], + }, + 'enterprise/installing-stateful-component-requirements', ], }, diff --git a/static/images/download-portal-link.png b/static/images/download-portal-link.png index d8136a4ac9..a4b91e96ee 100644 Binary files a/static/images/download-portal-link.png and b/static/images/download-portal-link.png differ diff --git a/static/images/download-portal-password-popup.png b/static/images/download-portal-password-popup.png new file mode 100644 index 0000000000..7aa86bf377 Binary files /dev/null and b/static/images/download-portal-password-popup.png differ