Merge pull request #2830 from replicatedhq/116024

Add EC --config-values flag and update automated install docs

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
+<ConfigValuesExample/>
+
+## 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
+    ```
 
-<ConfigValuesExample/>
-
-## 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:
 
     <PlaceholderNamespaceExisting/>
 
-### 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
 
 <IntroEmbedded/>
 
@@ -112,9 +123,33 @@ To install with kURL on a VM or bare metal server:
 
     <PlaceholderNamespaceEmbedded/>
 
-### 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. <InstallKotsCliAirGap/>
 
@@ -149,11 +184,11 @@ To install with KOTS in an air gap existing cluster:
 
       <PlaceholderRoCreds/>
 
-### Air Gap kURL Cluster
+### kURL
 
 <IntroEmbedded/>
 
-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:
 

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
 

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).
+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).

docs/reference/embedded-cluster-install.mdx

@@ -45,6 +45,13 @@ sudo ./APP_SLUG install --license LICENSE_FILE [flags]
         <p>**Requirement**: Embedded Cluster 1.16.0 or later.</p>
      </td>
   </tr>
+  <tr>
+     <td>`--config-values`</td>
+     <td>
+        <p>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).</p>
+        <p><strong>Requirement:</strong> Embedded Cluster 1.18.0 and later.</p>
+     </td>
+  </tr>
   <tr>
      <td>`--data-dir`</td>
      <td>
@@ -115,13 +122,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
@@ -130,6 +137,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
@@ -146,7 +161,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

docs/reference/kots-cli-install.mdx

@@ -57,7 +57,7 @@ This command supports all [global flags](kots-cli-global-flags) and also:
     <tr>
         <td><code>--config-values</code></td>
         <td>string</td>
-        <td>Path to a manifest file containing configuration values. This manifest must be <code>apiVersion: kots.io/v1beta1</code> and <code>kind: ConfigValues</code>. For more information, see <a href="/enterprise/installing-existing-cluster-automation">Installing with the CLI</a>.</td>
+        <td>Path to a manifest file containing configuration values. This manifest must be <code>apiVersion: kots.io/v1beta1</code> and <code>kind: ConfigValues</code>. For more information, see <a href="/enterprise/installing-existing-cluster-automation">Installing from the Command Line</a>.</td>
     </tr>
     <tr>
         <td><code>--copy-proxy-env</code></td>

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).
 

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.