diff --git a/docs/enterprise/installing-existing-cluster-automation.mdx b/docs/enterprise/installing-existing-cluster-automation.mdx index 37cb379693..19f0977b35 100644 --- a/docs/enterprise/installing-existing-cluster-automation.mdx +++ b/docs/enterprise/installing-existing-cluster-automation.mdx @@ -13,55 +13,50 @@ import PushKotsImages from "../partials/install/_push-kotsadm-images.mdx" import KotsVersionMatch from "../partials/install/_kots-airgap-version-match.mdx" import PlaceholderRoCreds from "../partials/install/_placeholder-ro-creds.mdx" -# Installing with the CLI +# Installing from the Command Line -This topic describes how to use the Replicated KOTS CLI to install an application. +This topic describes how to install an application with Replicated KOTS, Replicated Embedded Cluster, or Replicated kURL from the command line. ## Overview -You can use the KOTS CLI to install an application rather than using the KOTS Admin Console UI. In a CLI installation, you provide all the necessary artifacts to configure and install the application with the `kots install` command. For example, rather than uploading your license file in the Admin Console, you provide your license file with the `kots install` command using the `--license-file` flag. Additionally, any preflight checks defined for the application automatically run from the CLI rather than being displayed in the Admin Console. +You can use the command line to install an application with Replicated KOTS, Replicated Embedded Cluster, or Replicated kURL. A common use case for installing from the command line is to automate installation, such as performing headless installations as part of CI/CD pipelines. -The following shows an example of the output from the `kots install` command: +To install from the command line, you provide all the necessary installation assets, such as the license file and the application config values, with the installation command rather than through the Admin Console UI. Any preflight checks defined for the application run automatically during headless installations from the command line rather than being displayed in the Admin Console. -```bash -• Deploying Admin Console - • Creating namespace ✓ - • Waiting for datastore to be ready ✓ -• Waiting for Admin Console to be ready ✓ -• Waiting for installation to complete ✓ -• Waiting for preflight checks to complete ✓ - -• Press Ctrl+C to exit -• Go to http://localhost:8800 to access the Admin Console - -• Go to http://localhost:8888 to access the application -``` +## Prerequisite -One common use case for installing with the CLI is to automate installation, such as installing applications as part of CI/CD pipelines. CLI installations are supported for _online_ environments (with outbound internet access), _air gap_ environments (without outbound internet access), existing clusters, and clusters created with Replicated kURL on a VM or bare metal server. +Create a ConfigValues YAML file to define the configuration values for the application release. You will pass the ConfigValues file with the installation command. For air-gapped environments, ensure that the ConfigValues file can be accessed from the installation environment. -For more information about the advanced options for the `kots install` command, see [install](/reference/kots-cli-install) in the KOTS CLI documentation. +For more information, see [Generating a ConfigValues File](/vendor/releases-configvalues). -For a tutorial that demonstrates how to install a sample application using the KOTS CLI, see [Install with KOTS in an Existing Cluster](/vendor/tutorial-cli-setup). +**Example:** -## Limitation + + +## Install -[Replicated Embedded Cluster](/vendor/embedded-overview) does not support automated, or _headless_, installations with the KOTS CLI. +### Embedded Cluster -## Prerequisite +To install with Embedded Cluster in an online 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. +1. Follow the steps provided in the Vendor Portal to download and untar the Embedded Cluster installation assets. For more information, see [Online Installation with Embedded Cluster](/enterprise/installing-embedded). -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). +1. Run the following command to install: -**Example:** + ```bash + sudo ./APP_SLUG install --license-file PATH_TO_LICENSE \ + --config-values PATH_TO_CONFIGVALUES \ + --admin-console-password ADMIN_CONSOLE_PASSWORD + ``` - - -## Install + Replace: + * `APP_SLUG` with the unique slug for the application. + * `LICENSE_FILE` with the customer license. + * `ADMIN_CONSOLE_PASSWORD` with a password for accessing the Admin Console. + * `PATH_TO_CONFIGVALUES` with the path to the ConfigValues file. See [Generating a ConfigValues File](/vendor/releases-configvalues). -This section provides the steps for installing an application with the KOTS CLI in different types of environments. -### Existing Cluster +### KOTS in an Existing Cluster To install with KOTS in an existing cluster: @@ -83,7 +78,23 @@ To install with KOTS in an existing cluster: -### kURL Cluster + The following shows an example of the output from the kots install command: + + ``` + • Deploying Admin Console + • Creating namespace ✓ + • Waiting for datastore to be ready ✓ + • Waiting for Admin Console to be ready ✓ + • Waiting for installation to complete ✓ + • Waiting for preflight checks to complete ✓ + + • Press Ctrl+C to exit + • Go to http://localhost:8800 to access the Admin Console + + • Go to http://localhost:8888 to access the application + ``` + +### kURL @@ -112,9 +123,33 @@ To install with kURL on a VM or bare metal server: -### Air Gap Existing Cluster +## Air Gap Install + +### Embedded Cluster + +To install with Embedded Cluster in an air-gapped environment: + +1. Follow the steps provided in the Vendor Portal to download and untar the Embedded Cluster air gap installation assets. For more information, see [Air Gap Installation with Embedded Cluster](/enterprise/installing-embedded-air-gap). + +1. Ensure that the Embedded Cluster installation assets are available on the air-gapped machine, then run the following command to install: + + ```bash + sudo ./APP_SLUG install --license-file PATH_TO_LICENSE \ + --config-values PATH_TO_CONFIGVALUES \ + --admin-console-password ADMIN_CONSOLE_PASSWORD \ + --airgap-bundle PATH_TO_AIRGAP_BUNDLE + ``` + + Replace: + * `APP_SLUG` with the unique slug for the application. + * `LICENSE_FILE` with the customer license. + * `PATH_TO_CONFIGVALUES` with the path to the ConfigValues file. See [Generating a ConfigValues File](/vendor/releases-configvalues). + * `ADMIN_CONSOLE_PASSWORD` with a password for accessing the Admin Console. + * `PATH_TO_AIRGAP_BUNDLE` with the path to the Embedded Cluster `.airgap` bundle for the release. + +### KOTS in an Existing Cluster -To install with KOTS in an air gap existing cluster: +To install with KOTS in an air-gapped existing cluster: 1. @@ -149,11 +184,11 @@ To install with KOTS in an air gap existing cluster: -### Air Gap kURL Cluster +### kURL -To install in an air gap kURL cluster on a VM or bare metal server: +To install in an air-gapped kURL cluster: 1. Download the kURL `.tar.gz` air gap bundle: diff --git a/docs/enterprise/installing-overview.md b/docs/enterprise/installing-overview.md index d9eb689df0..8ac20f909a 100644 --- a/docs/enterprise/installing-overview.md +++ b/docs/enterprise/installing-overview.md @@ -48,7 +48,7 @@ For information about image registry requirements, see [Private Registry Require You can automate application installation in online, air gap, existing cluster, and embedded cluster environments using the KOTS CLI. In an automated installation, you provide all the information required to install and deploy the application with the `kots install` command, rather than providing this information in the Replicated Admin Console. -For more information, see [Installing with Automation](/enterprise/installing-existing-cluster-automation). +For more information, see [Installing from the Command Line](/enterprise/installing-existing-cluster-automation). ### KOTS Installations Without Object Storage diff --git a/docs/intro-kots.md b/docs/intro-kots.md index 2dcefb9f66..7610087b03 100644 --- a/docs/intro-kots.md +++ b/docs/intro-kots.md @@ -70,4 +70,4 @@ The kots command-line interface (CLI) is a kubectl plugin. Customers can run com For information about getting started with the KOTS CLI, see [Installing the KOTS CLI](/reference/kots-cli-getting-started). -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 the CLI](/enterprise/installing-existing-cluster-automation). \ No newline at end of file +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, such as in CI/CD pipelines. For information about how to perform headless installations from the command line, see [Installing from the Command Line](/enterprise/installing-existing-cluster-automation). \ No newline at end of file diff --git a/docs/reference/embedded-cluster-install.mdx b/docs/reference/embedded-cluster-install.mdx index e3c08a8b7c..3ece8010f1 100644 --- a/docs/reference/embedded-cluster-install.mdx +++ b/docs/reference/embedded-cluster-install.mdx @@ -44,6 +44,13 @@ sudo ./APP_SLUG install --license LICENSE_FILE [flags]

The range of IP addresses that can be assigned to Pods and Services, in CIDR notation. **Default:** By default, the CIDR block is `10.244.0.0/16`.

+ + `--config-values` + +

Path to the ConfigValues file for the application. The ConfigValues file can be used to pass the application configuration values from the command line during installation, such as when performing automated installations as part of CI/CD pipelines. For more information about generating the ConfigValues file for a release, see [Generating a ConfigValues File](/vendor/releases-configvalues).

+

Requirement: Embedded Cluster 1.18.0 and later.

+ + `--data-dir` @@ -113,13 +120,13 @@ sudo ./APP_SLUG install --license LICENSE_FILE [flags] ### Air Gap Install ```bash -sudo ./myapp install --license license.yaml --airgap-bundle myapp.airgap +sudo ./my-app install --license license.yaml --airgap-bundle myapp.airgap ``` ### Change the Admin Console and LAM Ports ```bash -sudo ./myapp install --license license.yaml --admin-console-port=20000 --local-artifact-mirror-port=40000 +sudo ./my-app install --license license.yaml --admin-console-port=20000 --local-artifact-mirror-port=40000 ``` ### Change the Data Directory @@ -128,6 +135,14 @@ sudo ./myapp install --license license.yaml --admin-console-port=20000 --local-a sudo ./my-app install --license license.yaml --data-dir /data/embedded-cluster ``` +### Headless (Automated) Install + +```bash +sudo ./my-app install --license license.yaml \ + --config-values configvalues.yaml \ + --admin-console-password password +``` + ### Install Behind a Proxy ```bash @@ -144,7 +159,7 @@ Where: ### Install Behind an MITM Proxy ```bash -sudo ./APP_SLUG install --license license.yaml --private-ca /path/to/private-ca-bundle \ +sudo ./my-app install --license license.yaml --private-ca /path/to/private-ca-bundle \ --http-proxy=http://10.128.0.0:3300 \ --https-proxy=http://10.128.0.0:3300 \ --no-proxy=123.89.46.4,10.96.0.0/16,*.example.com diff --git a/docs/reference/kots-cli-install.mdx b/docs/reference/kots-cli-install.mdx index ed432f6885..0ccec55b6b 100644 --- a/docs/reference/kots-cli-install.mdx +++ b/docs/reference/kots-cli-install.mdx @@ -57,7 +57,7 @@ This command supports all [global flags](kots-cli-global-flags) and also: --config-values string - Path to a manifest file containing configuration values. This manifest must be apiVersion: kots.io/v1beta1 and kind: ConfigValues. For more information, see Installing with the CLI. + Path to a manifest file containing configuration values. This manifest must be apiVersion: kots.io/v1beta1 and kind: ConfigValues. For more information, see Installing from the Command Line. --copy-proxy-env diff --git a/docs/vendor/embedded-overview.mdx b/docs/vendor/embedded-overview.mdx index be21998ca2..884798c940 100644 --- a/docs/vendor/embedded-overview.mdx +++ b/docs/vendor/embedded-overview.mdx @@ -55,7 +55,7 @@ Embedded Cluster has the following limitations: * **Changing node hostnames is not supported**: After a host is added to a Kubernetes cluster, Kubernetes assumes that the hostname and IP address of the host will not change. If you need to change the hostname or IP address of a node, you must first remove the node from the cluster. For more information about the requirements for naming nodes, see [Node name uniqueness](https://kubernetes.io/docs/concepts/architecture/nodes/#node-name-uniqueness) in the Kubernetes documentation. -* **Automated installations not supported**: Users cannot do automated (headless) Embedded Cluster installations because it is not possible to configure the application by passing the [ConfigValues](/vendor/releases-configvalues) file with the installation command. Embedded Cluster installations require that the application is configured from the Admin Console config screen. For more information about automating existing cluster or kURL installations with the KOTS CLI, see [Installing with the CLI](/enterprise/installing-existing-cluster-automation). +* **Automated installations not supported**: Users cannot do automated (headless) Embedded Cluster installations because it is not possible to configure the application by passing the [ConfigValues](/vendor/releases-configvalues) file with the installation command. Embedded Cluster installations require that the application is configured from the Admin Console config screen. For more information about automating existing cluster or kURL installations with the KOTS CLI, see [Installing from the Command Line](/enterprise/installing-existing-cluster-automation). * **Automatic updates not supported**: Configuring automatic updates from the Admin Console so that new versions are automatically deployed is not supported for Embedded Cluster installations. For more information, see [Configuring Automatic Updates](/enterprise/updating-apps). diff --git a/docs/vendor/packaging-rbac.md b/docs/vendor/packaging-rbac.md index 747d32377d..8578edb289 100644 --- a/docs/vendor/packaging-rbac.md +++ b/docs/vendor/packaging-rbac.md @@ -108,7 +108,7 @@ The following limitations apply when using the `requireMinimalRBACPrivileges` or In non-headless installations in air gap environments, KOTS does not have access to the application's `.airgap` package during installation. This means that KOTS does not have the information required to determine whether namespace-scoped access is needed, so it defaults to the more permissive, default cluster-scoped RBAC policy. - For more information about how to do headless installations in air gap environments, see [Air Gap Existing Cluster](/enterprise/installing-existing-cluster-automation#air-gap-existing-cluster) in _Installing with the CLI_. + For more information about how to do headless installations in air gap environments, see [Air Gap Install](/enterprise/installing-existing-cluster-automation#air-gap-install) in _Installing from the Command Line_. * **Changing RBAC permissions for installed instances**: The RBAC permissions for KOTS are set during its initial installation. KOTS runs using the assumed identity and cannot change its own authorization. When you update your application to add or remove the `requireMinimalRBACPrivileges` and `supportMinimalRBACPrivileges` flags in the Application custom resource, the RBAC permissions for KOTS are affected only for new installations. Existing KOTS installations continue to run with their current RBAC permissions. diff --git a/docs/vendor/releases-configvalues.md b/docs/vendor/releases-configvalues.md index 827a46f04c..9a081f540a 100644 --- a/docs/vendor/releases-configvalues.md +++ b/docs/vendor/releases-configvalues.md @@ -8,41 +8,66 @@ import TextAreaExample from "../partials/configValues/_textareaExample.mdx" # 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. +This topic describes how to generate the Replicated KOTS ConfigValues file for an application release. It also includes recommendations for how to prepare a sample ConfigValues file to be shared with your users. -## About ConfigValues Files +## Overview -A ConfigValues file defines the user-supplied configuration values for an application installed with KOTS. Enterprise users can provide a ConfigValues file to configure an application during automated installations with the KOTS CLI. During installation, KOTS reads the values in the ConfigValues file to configure the application. For more information about automated installations with the KOTS CLI, see [Installing with the CLI](/enterprise/installing-existing-cluster-automation). - -ConfigValues files include the configuration fields defined in the Config custom resource for the release, along with the user-supplied and default values for each field. The following is an example of a ConfigValues file: +The KOTS ConfigValues file includes the fields that are defined in the KOTS Config custom resource for an application release, along with the user-supplied and default values for each field. The following is an example of a ConfigValues file: +The ConfigValues file allows you to pass the configuration values for an application from the command line with the install command, rather than through the Admin Console UI. This supports automated or _headless_ installations, such as when installing an application as part of CI/CD pipelines. + +For more information about installing from the command line, see [Installing from the Command Line](/enterprise/installing-existing-cluster-automation). + ## Get the ConfigValues File -When installing an application, KOTS automatically generates a ConfigValues file and saves the file in a directory called `upstream`. After installation, you can view the generated ConfigValues file. +During installation, KOTS automatically generates a ConfigValues file and saves the file in a directory called `upstream`. After installation, you can view the generated ConfigValues file in the Admin Console **View files** tab or from the command line by running the `kubectl kots get config` command. -To get the ConfigValues file for an application: +To get the ConfigValues file from an installed application instance: -1. Install the target release for the application in a development environment. For more information, see [About Installing an Application](/enterprise/installing-overview). +1. Install the target release in a development environment. You can either install the release with Replicated Embedded Cluster or install in an existing cluster with KOTS. For more information, see [Online Installation with Embedded Cluster](/enterprise/installing-embedded) or [Online Installation in Existing Clusters](/enterprise/installing-existing-cluster). -1. View the generated ConfigValues file for the installed instance: +1. Depending on the installer that you used, do one of the following to get the ConfigValues for the installed instance: - ``` - kubectl kots get config --namespace APP_NAMESPACE --decrypt - ``` - Where `APP_NAMESPACE` is the cluster namespace where the application is installed. - - :::note - The `--decrypt` flag decrypts all configuration fields with `type: password`. In the downloaded ConfigValues file, the decrypted value is stored in a `valuePlaintext` field. - ::: + * **For Embedded Cluster installations**: In the Admin Console, go to the **View files** tab. In the filetree, go to **upstream > userdata** and open **config.yaml**, as shown in the image below: + + ![ConfigValues file in the Admin Console View Files tab](/images/admin-console-view-files-configvalues.png) + + [View a larger version of this image](/images/admin-console-view-files-configvalues.png) - The output of the `kots get config` command is the contents of the ConfigValues file. For more information about the `kots get config` command, including additional flags, see [kots get config](/reference/kots-cli-get-config). + * **For KOTS installations in an existing cluster**: Run the `kubectl kots get config` command to view the generated ConfigValues file: + + ``` + kubectl kots get config --namespace APP_NAMESPACE --decrypt + ``` + Where: + * `APP_NAMESPACE` is the cluster namespace where KOTS is running. + * The `--decrypt` flag decrypts all configuration fields with `type: password`. In the downloaded ConfigValues file, the decrypted value is stored in a `valuePlaintext` field. + + The output of the `kots get config` command shows the contents of the ConfigValues file. For more information about the `kots get config` command, including additional flags, see [kots get config](/reference/kots-cli-get-config). + + **Example**: + + ```bash + kubectl kots get config --namespace namespace --decrypt + ``` + ```bash + apiVersion: kots.io/v1beta1 + kind: ConfigValues + metadata: + creationTimestamp: null + spec: + values: + example_item: + value: hello world + ``` + ## Share a Sample ConfigValues File -Replicated recommends that you share an example of an accurate ConfigValues file with your users that they can edit for use in automated installations with the KOTS CLI. +If your users will perform automated or headless installations from the command line, you can share an example of an accurate ConfigValues file that they can edit. -After you get the ConfigValues file for your application using the `kots get config` command, Replicated recommends that you do the following to edit the contents of the ConfigValues file before sharing it with users: +Before sharing a sample ConfigValues with users, Replicated recommends that you edit the sample file in the following ways: * Remove any configuration fields that have `readonly` set to `true`. Users cannot edit read only fields. For more information, see [readonly](/reference/custom-resource-config#readonly) in _Config_. @@ -65,4 +90,4 @@ After you get the ConfigValues file for your application using the `kots get con textarea

Plain text in the value field.

- For more information about each configuration field type in the Config custom resource, see [Config](/reference/custom-resource-config). + For more information about each configuration field type in the Config custom resource, see [Config](/reference/custom-resource-config). diff --git a/docs/vendor/replicated-sdk-airgap.mdx b/docs/vendor/replicated-sdk-airgap.mdx index 4ac7708a7b..f077241ef6 100644 --- a/docs/vendor/replicated-sdk-airgap.mdx +++ b/docs/vendor/replicated-sdk-airgap.mdx @@ -39,9 +39,4 @@ Replicated does not provide air gap bundles for applications installed with the ### KOTS -When the SDK is installed by KOTS in an air gap environment, KOTS automatically sets `isAirGap: true` in the SDK Helm chart values to enable air gap mode. No additional configuration is required. - -KOTS automatically enables air gap mode for the SDK when the user follows any of these procedures to do an air gap installation: -* [Air Gap Installation in Existing Clusters](/enterprise/installing-existing-cluster-airgapped) -* [Air Gap Installation with kURL](/enterprise/installing-kurl-airgap) -* [Air Gap Existing Cluster](/enterprise/installing-existing-cluster-automation#air-gap-existing-cluster) or [Air Gap kURL Cluster](/enterprise/installing-existing-cluster-automation#air-gap-kurl-cluster) in _Installing with the CLI_ \ No newline at end of file +When the SDK is installed by KOTS in an air gap environment, KOTS automatically sets `isAirGap: true` in the SDK Helm chart values to enable air gap mode. No additional configuration is required. \ No newline at end of file diff --git a/docs/vendor/replicated-sdk-customizing.md b/docs/vendor/replicated-sdk-customizing.md index 16959c9fda..3b6ab30c80 100644 --- a/docs/vendor/replicated-sdk-customizing.md +++ b/docs/vendor/replicated-sdk-customizing.md @@ -117,7 +117,7 @@ replicated: ``` :::note -If the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` variables are configured with the [kots install](/enterprise/installing-existing-cluster-automation) command, these variables will also be set automatically in the Replicated SDK. +If the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` variables are configured with the [kots install](/reference/kots-cli-install) command, these variables will also be set automatically in the Replicated SDK. ::: **Example**: @@ -152,7 +152,7 @@ To use a CA stored in a ConfigMap: ``` :::note -If the `--private-ca-configmap` flag is used with the [kots install](/enterprise/installing-existing-cluster-automation) command, this value will be populated in the Replicated SDK automatically. +If the `--private-ca-configmap` flag is used with the [kots install](/reference/kots-cli-install) command, this value will be populated in the Replicated SDK automatically. ::: ### Using a Secret diff --git a/sidebars.js b/sidebars.js index 91e2d7718d..ff9716b1ff 100644 --- a/sidebars.js +++ b/sidebars.js @@ -369,7 +369,7 @@ const sidebars = { }, { type: 'category', - label: 'Installing with the KOTS CLI', + label: 'Installing from the Command Line', items: [ 'enterprise/installing-existing-cluster-automation', 'vendor/releases-configvalues', diff --git a/static/images/admin-console-view-files-configvalues.png b/static/images/admin-console-view-files-configvalues.png new file mode 100644 index 0000000000..526f1eca53 Binary files /dev/null and b/static/images/admin-console-view-files-configvalues.png differ