# Change an Admin Console password When you install for the first time with Replicated kURL, the Replicated KOTS Admin Console is secured with a single shared password that is set automatically for all users. Replicated recommends that you change this to a new, unique password for security purposes as this automated password is displayed to the user in plain text. The Admin Console password is salted and one-way hashed using bcrypt. The irreversible hash is stored in a Secret named `kotsadm-password`. The password is not retrievable if lost. If you lose your Admin Console password, reset your password to access the Admin Console. For more information about bcrypt, see [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) on Wikipedia. To change your Admin Console password: 1. Log in to the Admin Console using your current password. 1. In the drop-down in the top right of any page, click **Change password**. 1. In the Change Admin Console Password dialog, edit the fields. - The new password must be at least 6 characters and must not be the same as your current password. - The **New Password** and **Confirm New Password** fields must match each other. 1. Click **Change Password**. If there are any issues with changing the password, an error message displays the specific problem. When the password change succeeds, the current session closes and you are redirected to the Log In page. 1. Log in with the new password. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: --- # Add nodes to kURL clusters :::note Replicated kURL is available only for existing customers. If you are not an existing kURL user, use Replicated Embedded Cluster instead. For more information, see [Use Embedded Cluster](/embedded-cluster/v3/embedded-overview). kURL is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: This topic describes how to add primary and secondary nodes to a Replicated kURL cluster. ## Overview You can generate commands in the Replicated KOTS Admin Console to join additional primary and secondary nodes to kURL clusters. Primary nodes run services that control the cluster. Secondary nodes run services that control the pods that host the application containers. Adding nodes can help manage resources to ensure that the application runs smoothly. For high availability clusters, Kubernetes recommends using at least three primary nodes, and that you use an odd number of nodes to help with leader selection if machine or zone failure occurs. For more information, see [Creating Highly Available Clusters with kubeadm](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/high-availability/) in the Kubernetes documentation. ## Join primary and secondary nodes You can join primary and secondary nodes on the Admin Console **Cluster management** page. To add primary and secondary nodes: 1. (Air Gap Only) For air gapped environments, download and extract the `.tar.gz` bundle on the remote node before running the join command. 1. In the Admin Console, click **Cluster Management > Add a node**. 1. Copy the command that displays in the text box and run it on the node that you are joining to the cluster. ![Join node in Admin Console](/images/join-node.png) [View a larger image](/images/join-node.png) --- # Delete the Admin Console and remove applications This topic describes how to remove installed applications and delete the Replicated KOTS Admin Console. The information in this topic applies to existing cluster installations with KOTS. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Remove an application The Replicated KOTS CLI `kots remove` command removes the reference to an installed application from the Admin Console. When you use `kots remove`, the Admin Console no longer manages the application because the record of that application’s installation is removed. This means that you can no longer manage the application through the Admin Console or through the KOTS CLI. By default, `kots remove` does not delete any of the installed Kubernetes resources for the application from the cluster. To remove both the reference to an application from the Admin Console and remove any resources for the application from the cluster, you can run `kots remove` with the `--undeploy` flag. It can be useful to remove only the reference to an application from the Admin Console if you want to reinstall the application, but you do not want to recreate the namespace or other Kubernetes resources. For example, if you installed an application using an incorrect license file and need to reinstall with the correct license. To remove an application: 1. Run the following command to list the installed applications for a namespace: ``` kubectl kots get apps -n NAMESPACE ``` Replace `NAMESPACE` with the name of the namespace where the Admin Console is installed. In the output of this command, note the slug for the application that you want to remove. 1. Run _one_ of the following commands: * Remove only the reference to the application from the Admin Console: ``` kubectl kots remove APP_SLUG -n NAMESPACE ``` Replace: * `APP_SLUG` with the slug for the application that you want to remove. * `NAMESPACE` with the name of the namespace where the Admin Console is installed. * Remove the reference to the application from the Admin Console and remove its resources from the cluster: ``` kubectl kots remove APP_SLUG -n NAMESPACE --undeploy ``` :::note Optionally, use the `--force` flag to remove the application reference from the Admin Console when the application has already been deployed. The `--force` flag is implied when `--undeploy` is used. For more information, see [remove](/reference/kots-cli-remove) in _KOTS CLI_. ::: ## Delete the Admin Console When you install an application, KOTS creates the Kubernetes resources for the Admin Console itself on the cluster. The Admin Console includes Deployments and Services, Secrets, and other resources such as StatefulSets and PersistentVolumeClaims. By default, KOTS also creates Kubernetes ClusterRole and ClusterRoleBinding resources that grant permissions to the Admin Console on the cluster level. These `kotsadm-role` and `kotsadm-rolebinding` resources are managed outside of the namespace where the Admin Console is installed. Alternatively, when the Admin Console is installed with namespace-scoped access, KOTS creates Role and RoleBinding resources inside the namespace where the Admin Console is installed. In existing cluster installations, if the Admin Console is not installed in the `default` namespace, then you delete the Admin Console by deleting the namespace where it is installed. If you installed the Admin Console with namespace-scoped access, then the Admin Console Role and RoleBinding RBAC resources are also deleted when you delete the namespace. Alternatively, if you installed with the default cluster-scoped access, then you manually delete the Admin Console ClusterRole and ClusterRoleBindings resources from the cluster. For more information, see [supportMinimalRBACPrivileges](/reference/custom-resource-application#supportminimalrbacprivileges) and [requireMinimalRBACPrivileges](/reference/custom-resource-application#requireminimalrbacprivileges) in _Application_. For more information about installing with cluster- or namespace-scoped access, see [RBAC Requirements](/enterprise/installing-general-requirements#rbac-requirements) in _Installation Requirements_. To completely delete the Admin Console from an existing cluster: 1. Run the following command to delete the namespace where the Admin Console is installed: :::important This command deletes everything inside the specified namespace, including the Admin Console Role and RoleBinding resources if you installed with namespace-scoped access. ::: ``` kubectl delete ns NAMESPACE ``` Replace `NAMESPACE` with the name of the namespace where the Admin Console is installed. :::note You cannot delete the `default` namespace. ::: 1. (Cluster-scoped Access Only) If you installed the Admin Console with the default cluster-scoped access, run the following commands to delete the Admin Console ClusterRole and ClusterRoleBinding from the cluster: ``` kubectl delete clusterrole kotsadm-role ``` ``` kubectl delete clusterrolebinding kotsadm-rolebinding ``` 1. (Optional) To uninstall the KOTS CLI, see [Uninstall](https://docs.replicated.com/reference/kots-cli-getting-started#uninstall) in _Installing the KOTS CLI_. --- # Work with the kURL image registry :::note Replicated kURL is available only for existing customers. If you are not an existing kURL user, use Replicated Embedded Cluster instead. For more information, see [Use Embedded Cluster](/embedded-cluster/v3/embedded-overview). kURL is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: This topic describes the Replicated kURL registry for kURL clusters. ## Overview The kURL Registry add-on can be used to host application images. For air gap installations, this kURL registry is automatically used to host all application images. With every application update, new images are pushed to the kURL registry. To keep the registry from running out of storage, images that are no longer used are automatically deleted from the registry. For more information about the kURL Registry add-on, see [Registry Add-On](https://kurl.sh/docs/add-ons/registry) in the kURL documentation. :::note Users can also configure their own private registry for kURL installations instead of using the kURL registry. For more information, see [Configure Local Image Registries](/enterprise/image-registry-settings). ::: ## Trigger garbage collection Every time the application instance is upgraded, image garbage collection automatically deletes images that are no longer used. You can also manually trigger image garbage collection. To manually run garbage collection: ```bash kubectl kots admin-console garbage-collect-images -n NAMESPACE ``` Where `NAMESPACE` is the namespace where the application is installed. For more information, see [admin-console garbage-collect-images](/reference/kots-cli-admin-console-garbage-collect-images/). ## Disable image garbage collection Image garbage collection is enabled by default for kURL clusters that use the kURL registry. To disable image garbage collection: ```bash kubectl patch configmaps kotsadm-confg --type merge -p "{\"data\":{\"enable-image-deletion\":\"false\"}}" ``` To enable garbage collection again: ```bash kubectl patch configmaps kotsadm-confg --type merge -p "{\"data\":{\"enable-image-deletion\":\"true\"}}" ``` ## Restore deleted images Deleted images can be reloaded from air gap bundles using the `admin-console push-images` command. For more information, see [admin-console push-images](/reference/kots-cli-admin-console-push-images/) in the KOTS CLI documentation. The registry address and namespace can be found on the **Registry Settings** page in the Replicated KOTS Admin Console. The registry username and password can be found in the `registry-creds` secret in the default namespace. ## Limitations The kURL registry image garbage collection feature has following limitations: * **Optional components**: Some applications define Kubernetes resources that can be enabled or disabled dynamically. For example, template functions can be used to conditionally deploy a StatefulSet based on configuration from the user. If a resource is disabled and no longer deployed, its images can be included in the garbage collection. To prevent this from happening, include the optional images in the `additionalImages` list of the Application custom resource. For more information, see [`additionalImages`](/reference/custom-resource-application#additionalimages) in _Application_. * **Shared Image Registries**: The image garbage collection process assumes that the registry is not shared with any other instances of Replicated KOTS, nor shared with any external applications. If the built-in kURL registry is used by another external application, disable garbage collection to prevent image loss. * **Customer-Supplied Registries**: Image garbage collection is supported only when used with the built-in kURL registry. If the KOTS instance is configured to use a different registry, disable garbage collection to prevent image loss. For more information about configuring an image registry in the Admin Console, see [Configure Local Image Registries](/enterprise/image-registry-settings). * **Application Rollbacks**: Image garbage collection has no effect when the `allowRollback` field in the Replicated Application custom resource is set to `true`. For more information, see [Application](/reference/custom-resource-application). --- # Avoid Docker Hub rate limits This topic describes how to avoid rate limiting for anonymous and free authenticated use of Docker Hub by providing a Docker Hub username and password to the `kots docker ensure-secret` command. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview On November 20, 2020, rate limits for anonymous and free authenticated use of Docker Hub went into effect. Anonymous and Free Docker Hub users are limited to 100 and 200 container image pull requests per six hours, respectively. Docker Pro and Docker Team accounts continue to have unlimited access to pull container images from Docker Hub. For more information on rate limits, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website. If the application that you are installing or upgrading has public Docker Hub images that are rate limited, then an error occurs when the rate limit is reached. ## Provide Docker Hub credentials To avoid errors caused by reaching the Docker Hub rate limit, a Docker Hub username and password can be passed to the `kots docker ensure-secret` command. The Docker Hub username and password are used only to increase rate limits and do not need access to any private repositories on Docker Hub. Example: ```bash kubectl kots docker ensure-secret --dockerhub-username sentrypro --dockerhub-password password --namespace sentry-pro ``` The `kots docker ensure-secret` command creates an image pull secret that KOTS can use when pulling images. KOTS then creates a new release sequence for the application to apply the image pull secret to all Kubernetes manifests that have images. After running the `kots docker ensure-secret` command, deploy this new release sequence either from the Admin Console or the KOTS CLI. For more information, see [docker ensure-secret](/reference/kots-cli-docker-ensure-secret) in the KOTS CLI documentation. --- # Configure local image registries This topic describes how to configure private registry settings in the Replicated KOTS Admin Console. The information in this topic applies to existing cluster installations with KOTS and installations with Replicated kURL. This topic does _not_ apply to Replicated Embedded Cluster installations. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview Using a private registry lets you create a custom image pipeline. Any proprietary configurations that you make to the application are shared only with the groups that you allow access, such as your team or organization. You also have control over the storage location, logging messages, load balancing requests, and other configuration options. Private registries can be used with online or air gap clusters. ## Requirement The domain of the image registry must support a Docker V2 protocol. KOTS has been tested for compatibility with the following registries: - Docker Hub :::note To avoid the November 20, 2020 Docker Hub rate limits, use the `kots docker ensure-secret` CLI command. For more information, see [Avoiding Docker Hub Rate Limits](image-registry-rate-limits). ::: - Quay - Amazon Elastic Container Registry (ECR) - Google Container Registry (GCR) - Azure Container Registry (ACR) - Harbor - Sonatype Nexus ## Configure local private registries in online clusters In online (internet-connected) installations, you can optionally use a local private image registry. You can also disable the connection or remove the registry settings if needed. To configure private registry settings in an online cluster: 1. In the Admin Console, on the **Registry settings** tab, edit the fields: Registry Settings [View a larger version of this image](/images/registry-settings.png) The following table describes the fields:
Field Description
Hostname Specify a registry domain that uses the Docker V2 protocol.
Username Specify the username for the domain.
Password Specify the password for the domain.
Registry Namespace Specify the registry namespace. The registry namespace is the path between the registry and the image name. For example, `my.registry.com/namespace/image:tag`. For air gap environments, this setting overwrites the registry namespace where images where pushed when KOTS was installed.
Disable Pushing Images to Registry (Optional) Select this option to disable KOTS from pushing images. Make sure that an external process is configured to push images to your registry instead. Your images are still read from your registry when the application is deployed.
1. Click **Test Connection** to test the connection between KOTS and the registry host. 1. Click **Save changes**. ## Change private registries in air gap clusters {#air-gap} You can change the private registry settings at any time in the Admin Console. To change private registry settings in an air gap cluster: 1. In the Admin Console, on the **Registry settings** tab, select the **Disable Pushing Images to Private Registry** checkbox. Click **Save changes**. :::note This is a temporary action that allows you to edit the registry namespace and hostname. If you only want to change the username or password for the registry, you do not have to disable pushing the images. ::: 1. Edit the fields as needed, and click **Save changes**.
Field Description
Hostname Specify a registry domain that uses the Docker V2 protocol.
Username Specify the username for the domain.
Password Specify the password for the domain.
Registry Namespace Specify the registry namespace. For air gap environments, this setting overwrites the registry namespace that you pushed images to when you installed KOTS.
1. Deselect the **Disable Pushing Images to Private Registry** checkbox. This action re-enables KOTS to push images to the registry. 1. Click **Test Connection** to test the connection between KOTS and the private registry host. 1. Click **Save changes**. ## Stop using a registry and remove registry settings To stop using a registry and remove registry settings from the Admin Console: 1. Log in to the Admin Console and go to **Registry Settings**. 1. Click **Stop using registry** to remove the registry settings from the Admin Console. --- # Air gap installation in existing clusters with KOTS This topic describes how to use Replicated KOTS to install an application in an existing Kubernetes cluster in an air-gapped environment. The procedures in this topic apply to installation environments that do not have access to the internet, known as _air gap_ environments. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Prerequisites Complete the following prerequisites: * Ensure that your cluster meets the minimum system requirements. See [Minimum System Requirements](/enterprise/installing-general-requirements#minimum-system-requirements) in _Installation Requirements_. * Ensure that you have at least the minimum RBAC permissions in the cluster required to install KOTS. See [RBAC Requirements](/enterprise/installing-general-requirements#rbac-requirements) in _Installation Requirements_. :::note If you manually created RBAC resources for KOTS as described in [Namespace-scoped RBAC Requirements](/enterprise/installing-general-requirements#namespace-scoped), include both the `--ensure-rbac=false` and `--skip-rbac-check` flags when you run the `kots install` command. These flags prevent KOTS from checking for or attempting to create a Role with `* * *` permissions in the namespace. For more information about these flags, see [install](/reference/kots-cli-install) or [admin-console upgrade](/reference/kots-cli-admin-console-upgrade). ::: * Review the options available with the `kots install` command before installing. The `kots install` command includes several optional flags to support different installation use cases. For a list of options, see [install](/reference/kots-cli-install) in the _KOTS CLI_ documentation. * Ensure that there is a compatible Docker image registry available inside the network. For more information about Docker registry compatibility, see [Compatible Image Registries](/enterprise/installing-general-requirements#registries). 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 in an air gap cluster with KOTS: 1. Download the customer 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) 1. Go the channel where the target release was promoted to build and download the air gap bundle for the release: * 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) 1. 1. 1. 1. :::note The versions of the KOTS CLI and the `kotsadm.tar.gz` bundle must match. You can check the version of the KOTS CLI with `kubectl kots version`. ::: 1. 1. Install the KOTS Admin Console using the images that you pushed in the previous step: ```shell kubectl kots install APP_NAME \ --kotsadm-registry REGISTRY_HOST \ --registry-username RO-USERNAME \ --registry-password RO-PASSWORD ``` Replace: * `APP_NAME` with a name for the application. This is the unique name that KOTS will use to refer to the application that you install. * `REGISTRY_HOST` with the same hostname for the private registry where you pushed the Admin Console images. * `RO_USERNAME` and `RO_PASSWORD` with the username and password for an account that has read-only access to the private registry. :::note KOTS stores these read-only credentials in a Kubernetes secret in the same namespace where the Admin Console is installed. KOTS uses these credentials to pull the images. To allow KOTS to pull images, the credentials are automatically created as an imagePullSecret on all of the Admin Console Pods. ::: 1. 1. Access the Admin Console on port 8800. If the port forward is active, go to [http://localhost:8800](http://localhost:8800) to access the Admin Console. If you need to reopen the port forward to the Admin Console, run the following command: ```shell kubectl kots admin-console -n NAMESPACE ``` Replace `NAMESPACE` with the namespace where KOTS is installed. 1. Log in with the password that you created during installation. 1. Upload your license file. 1. Upload the `.airgap` application air gap bundle. 1. On the config screen, complete the fields for the application configuration options and then click **Continue**. 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**. :::note Replicated recommends that you address any warnings or failures, rather than dismissing them. Preflight checks help ensure that your environment meets the requirements for application deployment. ::: 1. (Minimal RBAC Only) If you are installing with minimal role-based access control (RBAC), KOTS recognizes if the preflight checks failed due to insufficient privileges. When this occurs, a kubectl CLI preflight command displays that lets you manually run the preflight checks. The Admin Console then automatically displays the results of the preflight checks. Click **Deploy**. ![kubectl CLI preflight command](/images/kubectl-preflight-command.png) [View a larger version of this image](/images/kubectl-preflight-command.png) The Admin Console dashboard opens. On the Admin Console dashboard, the application status changes from Missing to Unavailable while the Deployment is being created. When the installation is complete, the status changes to Ready. For example: ![Admin Console dashboard](/images/kotsadm-dashboard-graph.png) [View a larger version of this image](/images/kotsadm-dashboard-graph.png) --- # Install with the KOTS CLI This topic describes how to install an application with Replicated KOTS in an existing cluster using the KOTS CLI. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview You can use the KOTS CLI to install an application with Replicated KOTS. 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. To install with the KOTS CLI, 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 from the CLI rather than being displayed in the Admin Console. 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 ``` ## Prerequisite Create a ConfigValues resource to define the configuration values for the application. The ConfigValues resource 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. For air-gapped environments, ensure that the ConfigValues file can be accessed from the installation environment. The ConfigValues resource includes the fields that are defined in the Replicated Config custom resource for the release, along with the user-supplied and default values for each field, as shown in the example below: ```yaml apiVersion: kots.io/v1beta1 kind: ConfigValues spec: values: config_item_name: default: example_default_value value: example_value boolean_config_item_name: value: "1" password_config_item_name: valuePlaintext: exampleplaintextpassword select_one_config_item_name: default: default_option_name value: selected_option_name ``` #### ConfigValues requirements * Linux operating system * cgroups v2 (required for Kubernetes versions 1.35 and later) * x86-64 architecture * systemd * At least 2GB of memory and 2 CPU cores * The disk on the host must have a maximum P99 write latency of 10 ms. This supports etcd performance and stability. For more information about the disk write latency requirements for etcd, see [Disks](https://etcd.io/docs/latest/op-guide/hardware/#disks) in _Hardware recommendations_ and [What does the etcd warning “failed to send out heartbeat on time” mean?](https://etcd.io/docs/latest/faq/) in the etcd documentation. * The user performing the installation must have root access to the machine, such as with `sudo`. * The data directory used by Embedded Cluster must have 40Gi or more of total space and be less than 80% full. By default, the data directory is `/var/lib/APP_SLUG`, where `APP_SLUG` is the unique slug of the application. The directory can be changed by passing the `--data-dir` flag with the Embedded Cluster `install` command. For more information, see [install](/embedded-cluster/v3/embedded-cluster-install). Note that in addition to the primary data directory, Embedded Cluster creates directories and files in the following locations: - `/etc/cni` - `/etc/k0s` - `/opt/cni` - `/opt/containerd` - `/run/calico` - `/run/containerd` - `/run/k0s` - `/sys/fs/cgroup/kubepods` - `/sys/fs/cgroup/system.slice/containerd.service` - `/sys/fs/cgroup/system.slice/k0scontroller.service` - `/usr/libexec/k0s` - `/var/lib/calico` - `/var/lib/cni` - `/var/lib/containers` - `/var/lib/kubelet` - `/var/log/calico` - `/var/log/containers` - `/var/log/APP_SLUG`, where `APP_SLUG` is the unique slug for the application - `/var/log/pods` - `/usr/local/bin/k0s` * (Online installations only) Access to replicated.app and proxy.replicated.com or your custom domain for each * Embedded Cluster is based on k0s, so all k0s system requirements and external runtime dependencies apply. See [System requirements](https://docs.k0sproject.io/stable/system-requirements/) and [External runtime dependencies](https://docs.k0sproject.io/stable/external-runtime-deps/) in the k0s documentation. For more information, see [ConfigValues](/reference/custom-resource-configvalues). ## Online (internet-connected) installation To install with KOTS in an online existing cluster: 1. 1. Install the application: ```bash kubectl kots install APP_NAME \ --shared-password PASSWORD \ --license-file PATH_TO_LICENSE \ --config-values PATH_TO_CONFIGVALUES \ --namespace NAMESPACE \ --no-port-forward ``` Replace: * `APP_NAME` with a name for the application. This is the unique name that KOTS will use to refer to the application that you install. * `PASSWORD` with a shared password for accessing the Admin Console. * `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. * `NAMESPACE` with the namespace where you want to install both the application and KOTS. ## Air gap installation {#air-gap} To install with KOTS in an air-gapped existing cluster: 1. 1. :::note The versions of the KOTS CLI and the `kotsadm.tar.gz` bundle must match. You can check the version of the KOTS CLI with `kubectl kots version`. ::: 1. 1. Install the application: ```bash kubectl kots install APP_NAME \ --shared-password PASSWORD \ --license-file PATH_TO_LICENSE \ --config-values PATH_TO_CONFIGVALUES \ --airgap-bundle PATH_TO_AIRGAP_BUNDLE \ --namespace NAMESPACE \ --kotsadm-registry REGISTRY_HOST \ --registry-username RO_USERNAME \ --registry-password RO_PASSWORD \ --no-port-forward ``` Replace: * `APP_NAME` with a name for the application. This is the unique name that KOTS will use to refer to the application that you install. * `PASSWORD` with a shared password for accessing the Admin Console. * `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. * `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. * `NAMESPACE` with the namespace where you want to install both the application and KOTS. * `REGISTRY_HOST` with the same hostname for the private registry where you pushed the Admin Console images. * `RO_USERNAME` and `RO_PASSWORD` with the username and password for an account that has read-only access to the private registry. :::note KOTS stores these read-only credentials in a Kubernetes secret in the same namespace where the Admin Console is installed. KOTS uses these credentials to pull the images. To allow KOTS to pull images, the credentials are automatically created as an imagePullSecret on all of the Admin Console Pods. ::: ## (Optional) Access the Admin Console By default, during installation, KOTS automatically opens localhost port 8800 to provide access to the Admin Console. Using the `--no-port-forward` flag with the `kots install` command prevents KOTS from creating a port forward to the Admin Console. After you install with the `--no-port-forward` flag, you can optionally create a port forward so that you can log in to the Admin Console in a browser window. To access the Admin Console: 1. If you installed in a VM where you cannot open a browser window, forward a port on your local machine to `localhost:8800` on the remote VM using the SSH client: ```bash ssh -L LOCAL_PORT:localhost:8800 USERNAME@IP_ADDRESS ``` Replace: * `LOCAL_PORT` with the port on your local machine to forward. For example, `9900` or `8800`. * `USERNAME` with your username for the VM. * `IP_ADDRESS` with the IP address for the VM. **Example**: The following example shows using the SSH client to forward port 8800 on your local machine to `localhost:8800` on the remote VM. ```bash ssh -L 8800:localhost:8800 user@ip-addr ``` 1. Run the following KOTS CLI command to open localhost port 8800, which forwards to the Admin Console service: ```bash kubectl kots admin-console --namespace NAMESPACE ``` Replace `NAMESPACE` with the namespace where the Admin Console was installed. For more information about the `kots admin-console` command, see [admin-console](/reference/kots-cli-admin-console-index) in the _KOTS CLI_ documentation. 1. Open a browser window and go to `https://localhost:8800`. 1. Log in to the Admin Console using the password that you created as part of the `kots install` command. --- # Online installation in existing clusters with KOTS This topic describes how to use Replicated KOTS to install an application in an existing Kubernetes cluster. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Prerequisites Complete the following prerequisites: * Ensure that your cluster meets the minimum system requirements. See [Minimum System Requirements](/enterprise/installing-general-requirements#minimum-system-requirements) in _Installation Requirements_. * Ensure that you have at least the minimum RBAC permissions in the cluster required to install KOTS. See [RBAC Requirements](/enterprise/installing-general-requirements#rbac-requirements) in _Installation Requirements_. :::note If you manually created RBAC resources for KOTS as described in [Namespace-scoped RBAC Requirements](/enterprise/installing-general-requirements#namespace-scoped), include both the `--ensure-rbac=false` and `--skip-rbac-check` flags when you run the `kots install` command. These flags prevent KOTS from checking for or attempting to create a Role with `* * *` permissions in the namespace. For more information about these flags, see [install](/reference/kots-cli-install) or [admin-console upgrade](/reference/kots-cli-admin-console-upgrade). ::: * Review the options available with the `kots install` command before installing. The `kots install` command includes several optional flags to support different installation use cases. For a list of options, see [install](/reference/kots-cli-install) in the _KOTS CLI_ documentation. * Download your license file. Ensure that you can access the downloaded license file from the environment where you will install the application. See [Downloading Customer Licenses](/vendor/licenses-download). ## Install {#online} To install KOTS and the application in an existing cluster: 1. Run one of these commands to install the Replicated KOTS CLI and KOTS. As part of the command, you also specify a name and version for the application that you will install. * **For the latest application version**: ```shell curl https://kots.io/install | bash kubectl kots install APP_NAME ``` * **For a specific application version**: ```shell curl https://kots.io/install | bash kubectl kots install APP_NAME --app-version-label=VERSION_LABEL ``` Replace, where applicable: * `APP_NAME` with the name of the application. The `APP_NAME` is included in the installation command that your vendor gave you. This is a unique identifier that KOTS will use to refer to the application that you install. * `VERSION_LABEL` with the label for the version of the application to install. For example, `--app-version-label=3.0.1`. **Examples:** ```shell curl https://kots.io/install | bash kubectl kots install application-name ``` ```shell curl https://kots.io/install | bash kubectl kots install application-name --app-version-label=3.0.1 ``` 1. 1. Access the Admin Console on port 8800. If the port forward is active, go to [http://localhost:8800](http://localhost:8800) to access the Admin Console. If you need to reopen the port forward to the Admin Console, run the following command: ```shell kubectl kots admin-console -n NAMESPACE ``` Replace `NAMESPACE` with the namespace where KOTS is installed. 1. Log in with the password that you created during installation. 1. Upload your license file. 1. On the config screen, complete the fields for the application configuration options and then click **Continue**. 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**. :::note Replicated recommends that you address any warnings or failures, rather than dismissing them. Preflight checks help ensure that your environment meets the requirements for application deployment. ::: 1. (Minimal RBAC Only) If you are installing with minimal role-based access control (RBAC), KOTS recognizes if the preflight checks failed due to insufficient privileges. When this occurs, a kubectl CLI preflight command displays that lets you manually run the preflight checks. The Admin Console then automatically displays the results of the preflight checks. Click **Deploy**. ![kubectl CLI preflight command](/images/kubectl-preflight-command.png) [View a larger version of this image](/images/kubectl-preflight-command.png) The Admin Console dashboard opens. On the Admin Console dashboard, the application status changes from Missing to Unavailable while the Deployment is being created. When the installation is complete, the status changes to Ready. For example: ![Admin Console dashboard](/images/kotsadm-dashboard-graph.png) [View a larger version of this image](/images/kotsadm-dashboard-graph.png) --- # KOTS installation requirements This topic describes the requirements for installing in a Kubernetes cluster with Replicated KOTS. :::note This topic does not include any requirements specific to the application. Ensure that you meet any additional requirements for the application before installing. ::: :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Supported browsers The following table lists the browser requirements for the Replicated KOTS Admin Console with the latest version of KOTS. | Browser | Support | |----------------------|-------------| | Chrome | 66+ | | Firefox | 58+ | | Opera | 53+ | | Edge | 80+ | | Safari (Mac OS only) | 13+ | | Internet Explorer | Unsupported | ## Kubernetes version compatibility Each release of KOTS maintains compatibility with the current Kubernetes version, and the two most recent versions at the time of its release. This includes support against all patch releases of the corresponding Kubernetes version. Kubernetes versions that are not listed below are end-of-life (EOL) in upstream Kubernetes, and no longer supported by Replicated. For more information about Kubernetes versions, see [Release History](https://kubernetes.io/releases/) in the Kubernetes documentation. Replicated recommends using a version of KOTS that is compatible with a supported Kubernetes version listed in the table below. | KOTS Versions | Kubernetes Compatibility | |------------------------|-----------------------------| | 1.130.5 and later | 1.36, 1.35, 1.34 | | 1.129.4 to 1.130.4 | 1.35, 1.34, 1.33 | | 1.128.3 to 1.129.3 | 1.34, 1.33 | | 1.124.17 to 1.128.3 | 1.33 | ## Minimum system requirements To install KOTS in an existing cluster, your environment must meet the following minimum requirements: * **KOTS Admin Console minimum requirements**: Clusters that have LimitRanges specified must support the following minimum requirements for the Admin Console: * **CPU resources and memory**: The Admin Console pod requests 100m CPU resources and 100Mi memory. * **Disk space**: The Admin Console requires a minimum of 5GB of disk space on the cluster for persistent storage, including: * **4GB for S3-compatible object store**: The Admin Console requires 4GB for an S3-compatible object store to store appplication archives, support bundles, and snapshots that are configured to use a host path and NFS storage destination. By default, KOTS deploys MinIO to satisfy this object storage requirement. During deployment, MinIO is configured with a randomly generated `AccessKeyID` and `SecretAccessKey`, and only exposed as a ClusterIP on the overlay network. :::note You can optionally install KOTS without MinIO by passing `--with-minio=false` with the `kots install` command. This installs KOTS as a StatefulSet using a persistent volume (PV) for storage. For more information, see [Installing KOTS in Existing Clusters Without Object Storage](/enterprise/installing-stateful-component-requirements). ::: * **1GB for rqlite PersistentVolume**: The Admin Console requires 1GB for a rqlite StatefulSet to store version history, application metadata, and other small amounts of data needed to manage the application(s). During deployment, the rqlite component is secured with a randomly generated password, and only exposed as a ClusterIP on the overlay network. * **Supported operating systems**: The following are the supported operating systems for nodes: * Linux AMD64 * Linux ARM64 * **Available StorageClass**: The cluster must have an existing StorageClass available. KOTS creates the required stateful components using the default StorageClass in the cluster. For more information, see [Storage Classes](https://kubernetes.io/docs/concepts/storage/storage-classes/) in the Kubernetes documentation. * **Kubernetes version compatibility**: The version of Kubernetes running on the cluster must be compatible with the version of KOTS that you use to install the application. This compatibility requirement does not include any specific and additional requirements defined by the software vendor for the application. For more information about the versions of Kubernetes that are compatible with each version of KOTS, see [Kubernetes Version Compatibility](#kubernetes-version-compatibility) above. * **OpenShift version compatibility**: For Red Hat OpenShift clusters, the version of OpenShift must use a supported Kubernetes version. For more information about supported Kubernetes versions, see [Kubernetes Version Compatibility](#kubernetes-version-compatibility) above. * **Storage class**: The cluster must have an existing storage class available. For more information, see [Storage Classes](https://kubernetes.io/docs/concepts/storage/storage-classes/) in the Kubernetes documentation. * **Port forwarding**: To support port forwarding, Kubernetes clusters require that the SOcket CAT (socat) package is installed on each node. If the package is not installed on each node in the cluster, you see the following error message when the installation script attempts to connect to the Admin Console: `unable to do port forwarding: socat not found`. To check if the package that provides socat is installed, you can run `which socat`. If the package is installed, the `which socat` command prints the full path to the socat executable file. For example, `usr/bin/socat`. If the output of the `which socat` command is `socat not found`, then you must install the package that provides the socat command. The name of this package can vary depending on the node's operating system. ## RBAC requirements The user that runs the installation command must have at least the minimum role-based access control (RBAC) permissions that are required by KOTS. If the user does not have the required RBAC permissions, then an error message displays: `Current user has insufficient privileges to install Admin Console`. The required RBAC permissions vary depending on if the user attempts to install KOTS with cluster-scoped access or namespace-scoped access: * [Cluster-scoped RBAC Requirements (Default)](#cluster-scoped) * [Namespace-scoped RBAC Requirements](#namespace-scoped) ### Cluster-scoped RBAC requirements (default) {#cluster-scoped} By default, KOTS requires cluster-scoped access. With cluster-scoped access, a Kubernetes ClusterRole and ClusterRoleBinding are created that grant KOTS access to all resources across all namespaces in the cluster. To install KOTS with cluster-scoped access, the user must meet the following RBAC requirements: * The user must be able to create workloads, ClusterRoles, and ClusterRoleBindings. * The user must have cluster-admin permissions to create namespaces and assign RBAC roles across the cluster. ### Namespace-scoped RBAC requirements {#namespace-scoped} KOTS can be installed with namespace-scoped access rather than the default cluster-scoped access. With namespace-scoped access, a Kubernetes Role and RoleBinding are automatically created that grant KOTS permissions only in the namespace where it is installed. :::note Depending on the application, namespace-scoped access for KOTS is required, optional, or not supported. Contact your software vendor for application-specific requirements. ::: To install or upgrade KOTS with namespace-scoped access, the user must have _one_ of the following permission levels in the target namespace: * Wildcard Permissions (Default) * Minimum KOTS RBAC Permissions See the sections below for more information. #### Wildcard permissions (default) By default, when namespace-scoped access is enabled, KOTS attempts to automatically create the following Role to acquire wildcard (`* * *`) permissions in the target namespace: ```yaml apiVersion: "rbac.authorization.k8s.io/v1" kind: "Role" metadata: name: "kotsadm-role" rules: - apiGroups: ["*"] resources: ["*"] verb: "*" ``` To support this default behavior, the user must also have `* * *` permissions in the target namespace. #### Minimum KOTS RBAC permissions In some cases, it is not possible to grant the user `* * *` permissions in the target namespace. For example, an organization might have security policies that prevent this level of permissions. If the user installing or upgrading KOTS cannot be granted `* * *` permissions in the namespace, then they can instead request the minimum RBAC permissions required by KOTS. Using the minimum KOTS RBAC permissions also requires manually creating a ServiceAccount, Role, and RoleBinding for KOTS, rather than allowing KOTS to automatically create a Role with `* * *` permissions. To use the minimum KOTS RBAC permissions to install or upgrade: 1. Ensure that the user has the minimum RBAC permissions required by KOTS. The following lists the minimum RBAC permissions: ```yaml - apiGroups: [""] resources: ["configmaps", "persistentvolumeclaims", "pods", "secrets", "services", "limitranges"] verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] - apiGroups: ["apps"] resources: ["daemonsets", "deployments", "statefulsets"] verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] - apiGroups: ["batch"] resources: ["jobs", "cronjobs"] verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] - apiGroups: ["networking.k8s.io", "extensions"] resources: ["ingresses"] verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] - apiGroups: [""] resources: ["namespaces", "endpoints", "serviceaccounts"] verbs: ["get"] - apiGroups: ["authorization.k8s.io"] resources: ["selfsubjectaccessreviews", "selfsubjectrulesreviews"] verbs: ["create"] - apiGroups: ["rbac.authorization.k8s.io"] resources: ["roles", "rolebindings"] verbs: ["get"] - apiGroups: [""] resources: ["pods/log", "pods/exec"] verbs: ["get", "list", "watch", "create"] - apiGroups: ["batch"] resources: ["jobs/status"] verbs: ["get", "list", "watch"] ``` :::note The minimum RBAC requirements can vary slightly depending on the cluster's Kubernetes distribution and the version of KOTS. Contact your software vendor if you have the required RBAC permissions listed above and you see an error related to RBAC during installation or upgrade. ::: 1. Save the following ServiceAccount, Role, and RoleBinding to a single YAML file, such as `rbac.yaml`: ```yaml apiVersion: v1 kind: ServiceAccount metadata: labels: kots.io/backup: velero kots.io/kotsadm: "true" name: kotsadm --- apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: labels: kots.io/backup: velero kots.io/kotsadm: "true" name: kotsadm-role rules: - apiGroups: [""] resources: ["configmaps", "persistentvolumeclaims", "pods", "secrets", "services", "limitranges"] verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] - apiGroups: ["apps"] resources: ["daemonsets", "deployments", "statefulsets"] verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] - apiGroups: ["batch"] resources: ["jobs", "cronjobs"] verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] - apiGroups: ["networking.k8s.io", "extensions"] resources: ["ingresses"] verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] - apiGroups: [""] resources: ["namespaces", "endpoints", "serviceaccounts"] verbs: ["get"] - apiGroups: ["authorization.k8s.io"] resources: ["selfsubjectaccessreviews", "selfsubjectrulesreviews"] verbs: ["create"] - apiGroups: ["rbac.authorization.k8s.io"] resources: ["roles", "rolebindings"] verbs: ["get"] - apiGroups: [""] resources: ["pods/log", "pods/exec"] verbs: ["get", "list", "watch", "create"] - apiGroups: ["batch"] resources: ["jobs/status"] verbs: ["get", "list", "watch"] --- apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: labels: kots.io/backup: velero kots.io/kotsadm: "true" name: kotsadm-rolebinding roleRef: apiGroup: rbac.authorization.k8s.io kind: Role name: kotsadm-role subjects: - kind: ServiceAccount name: kotsadm ``` 1. If the application contains any Custom Resource Definitions (CRDs), add the CRDs to the Role in the YAML file that you created in the previous step with as many permissions as possible: `["get", "list", "watch", "create", "update", "patch", "delete"]`. :::note Contact your software vendor for information about any CRDs that are included in the application. ::: **Example** ```yaml rules: - apiGroups: ["stable.example.com"] resources: ["crontabs"] verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] ``` 1. Run the following command to create the RBAC resources for KOTS in the namespace: ``` kubectl apply -f RBAC_YAML_FILE -n TARGET_NAMESPACE ``` Replace: * `RBAC_YAML_FILE` with the name of the YAML file with the ServiceAccount, Role, and RoleBinding and that you created. * `TARGET_NAMESPACE` with the namespace where the user will install KOTS. :::note After manually creating these RBAC resources, the user must include both the `--ensure-rbac=false` and `--skip-rbac-check` flags when installing or upgrading. These flags prevent KOTS from checking for or attempting to create a Role with `* * *` permissions in the namespace. For more information, see [Prerequisites](installing-existing-cluster#prerequisites) in _Online Installation in Existing Clusters with KOTS_. ::: ## Compatible image registries {#registries} A private image registry is required for air gap installations with KOTS in existing clusters. You provide the credentials for a compatible private registry during installation. You can also optionally configure a local private image registry for use with installations in online (internet-connected) environments. Private registry settings can be changed at any time. For more information, see [Configuring Local Image Registries](image-registry-settings). KOTS has been tested for compatibility with the following registries: - Docker Hub :::note To avoid the November 20, 2020 Docker Hub rate limits, use the `kots docker ensure-secret` CLI command. For more information, see [Avoiding Docker Hub Rate Limits](image-registry-rate-limits). ::: - Quay - Amazon Elastic Container Registry (ECR) - Google Container Registry (GCR) - Azure Container Registry (ACR) - Harbor - Sonatype Nexus ## Network requirements for online installations ### Firewall openings {#firewall} The domains for the services listed below need to be accessible from servers performing online installations. No outbound internet access is required for air gap installations. For services hosted at domains owned by Replicated, the table includes a link to the list of IP addresses for the domain at [replicatedhq/ips](https://github.com/replicatedhq/ips/blob/main/ip_addresses.json) in GitHub. Note that the IP addresses listed in the `replicatedhq/ips` repository also include IP addresses for some domains that are _not_ required for installation. For any third-party services hosted at domains not owned by Replicated, consult the third-party's documentation for the IP address range for each domain.
Domain Description
Docker Hub

Some dependencies of KOTS are hosted as public images in Docker Hub. The required domains for this service are `index.docker.io`, `cdn.auth0.com`, `*.docker.io`, and `*.docker.com.`
`proxy.replicated.com` *

Private Docker images are proxied through `proxy.replicated.com`. This domain is owned by Replicated, Inc., which is headquartered in Los Angeles, CA.

For the range of IP addresses for `proxy.replicated.com`, see [replicatedhq/ips](https://github.com/replicatedhq/ips/blob/main/ip_addresses.json#L52-L57) in GitHub.
`replicated.app`

Upstream application YAML and metadata is pulled from `replicated.app`. The current running version of the application (if any), as well as a license ID and application ID to authenticate, are all sent to `replicated.app`. This domain is owned by Replicated, Inc., which is headquartered in Los Angeles, CA.

For the range of IP addresses for `replicated.app`, see [replicatedhq/ips](https://github.com/replicatedhq/ips/blob/main/ip_addresses.json#L60-L65) in GitHub.
`registry.replicated.com` **

Some applications host private images in the Replicated registry at this domain. The on-prem docker client uses a license ID to authenticate to `registry.replicated.com`. This domain is owned by Replicated, Inc which is headquartered in Los Angeles, CA.

For the range of IP addresses for `registry.replicated.com`, see [replicatedhq/ips](https://github.com/replicatedhq/ips/blob/main/ip_addresses.json#L20-L25) in GitHub.
`kots.io`

Requests are made to this domain when installing the Replicated KOTS CLI. This domain is owned by Replicated, Inc., which is headquartered in Los Angeles, CA.
`github.com` Requests are made to this domain when installing the Replicated KOTS CLI. For information about retrieving GitHub IP addresses, see [About GitHub's IP addresses](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses) in the GitHub documentation.
* Required only if the application uses the [Replicated proxy registry](/vendor/private-images-about). ** Required only if the application uses the [Replicated registry](/vendor/private-images-replicated). ### IPv4 or IPv4/IPv6 dual-stack only KOTS does not support online installations in single-stack IPv6-only environments. Environments that use IPv4 or dual-stack IPv4/IPv6 networking are supported. --- # Air gap installation with kURL This topic describes how to use Replicated kURL to provision a cluster in a virtual machine (VM) or bare metal server and install an application in the cluster. The procedures in this topic apply to installation environments that do not have access to the internet, known as _air-gapped_ environments. Replicated kURL is an open source project. For more information, see the [kURL documentation](https://kurl.sh/docs/introduction/). :::note Replicated kURL is available only for existing customers. If you are not an existing kURL user, use Replicated Embedded Cluster instead. For more information, see [Use Embedded Cluster](/embedded-cluster/v3/embedded-overview). kURL is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Prerequisites Complete the following prerequisites: * Ensure that your environment meets the minimum system requirements. See [kURL Installation Requirements](/enterprise/installing-kurl-requirements). * Review the advanced installation options available for the kURL installer. See [Advanced Options](https://kurl.sh/docs/install-with-kurl/advanced-options) in the kURL documentation. - If you are installing in high availability (HA) mode, a load balancer is required. You can use the kURL internal load balancer if the [Embedded kURL Cluster Operator (EKCO) Add-On](https://kurl.sh/docs/add-ons/ekco) is included in the kURL Installer spec. Or, you can bring your own external load balancer. An external load balancer might be preferred when clients outside the cluster need access to the cluster's Kubernetes API. To install in HA mode, complete the following prerequisites: - (Optional) If you are going to use the internal EKCO load balancer, you can preconfigure it by passing `| sudo bash -s ha ekco-enable-internal-load-balancer` with the kURL install command. Otherwise, you are prompted for load balancer details during installation. For more information about the EKCO Add-on, see [EKCO Add-On](https://kurl.sh/docs/add-ons/ekco) in the open source kURL documentation. - To use an external load balancer, ensure that the load balancer meets the following requirements: - Must be a TCP forwarding load balancer - Must be configured to distribute traffic to all healthy control plane nodes in its target list - The health check must be a TCP check on port 6443 For more information about how to create a load balancer for kube-apirserver, see [Create load balancer for kube-apiserver](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/high-availability/#create-load-balancer-for-kube-apiserver) in the Kubernetes documentation. You can optionally preconfigure the external loader by passing the `load-balancer-address=HOST:PORT` flag with the kURL install command. Otherwise, you are prompted to provide the load balancer address during installation. ## Install {#air-gap} To install an application with kURL: 1. Download the customer 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) 1. Go the channel where the target release was promoted to build and download the air gap bundle for the release: * 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) 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: ```bash 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. * 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 install in air gap mode: - For a regular installation, run: ```bash cat install.sh | sudo bash -s airgap ``` - For high availability, run: ```bash cat install.sh | sudo bash -s airgap ha ``` 1. 1. 1. Go to the address provided in the `Kotsadm` field in the output of the installation command. For example, `Kotsadm: http://34.171.140.123:8800`. 1. On the Bypass Browser TLS warning page, review the information about how to bypass the browser TLS warning, and then click **Continue to Setup**. 1. On the HTTPS page, do one of the following: - To use the self-signed TLS certificate only, enter the hostname (required) if you are using the identity service. If you are not using the identity service, the hostname is optional. Click **Skip & continue**. - To use a custom certificate only, enter the hostname (required) if you are using the identity service. If you are not using the identity service, the hostname is optional. Then upload a private key and SSL certificate to secure communication between your browser and the Admin Console. Click **Upload & continue**. 1. Log in to the Admin Console with the password that was provided in the `Login with password (will not be shown again):` field in the output of the installation command. 1. Upload your license file. 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**. :::note Replicated recommends that you address any warnings or failures, rather than dismissing them. Preflight checks help ensure that your environment meets the requirements for application deployment. ::: 1. (Minimal RBAC Only) If you are installing with minimal role-based access control (RBAC), KOTS recognizes if the preflight checks failed due to insufficient privileges. When this occurs, a kubectl CLI preflight command displays that lets you manually run the preflight checks. The Admin Console then automatically displays the results of the preflight checks. Click **Deploy**. ![kubectl CLI preflight command](/images/kubectl-preflight-command.png) [View a larger version of this image](/images/kubectl-preflight-command.png) The Admin Console dashboard opens. On the Admin Console dashboard, the application status changes from Missing to Unavailable while the Deployment is being created. When the installation is complete, the status changes to Ready. ![Admin console dashboard showing ready status](/images/gitea-ec-ready.png) [View a larger version of this image](/images/gitea-ec-ready.png) 1. (Recommended) Change the Admin Console login password: 1. Click the menu in the top right corner of the Admin Console, then click **Change password**. 1. Enter a new password in the dialog, and click **Change Password** to save. Replicated strongly recommends that you change the password from the default provided during installation in a kURL cluster. For more information, see [Change an Admin Console Password](auth-changing-passwords). 1. Add primary and secondary nodes to the cluster. You might add nodes to either meet application requirements or to support your usage of the application. See [Adding Nodes to Embedded Clusters](cluster-management-add-nodes). --- # Install with kURL from the command line :::note Replicated kURL is available only for existing customers. If you are not an existing kURL user, use Replicated Embedded Cluster instead. For more information, see [Use Embedded Cluster](/embedded-cluster/v3/embedded-overview). kURL is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: This topic describes how to install an application with Replicated kURL from the command line. ## Overview You can use the command line to install an application with 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. 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. ## Prerequisite Create a ConfigValues YAML file to define the configuration values for the application release. 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. For air-gapped environments, ensure that the ConfigValues file can be accessed from the installation environment. The KOTS ConfigValues file includes the fields that are defined in the Replicated Config custom resource for an application release, along with the user-supplied and default values for each field, as shown in the example below: ```yaml apiVersion: kots.io/v1beta1 kind: ConfigValues spec: values: config_item_name: default: example_default_value value: example_value boolean_config_item_name: value: "1" password_config_item_name: valuePlaintext: exampleplaintextpassword select_one_config_item_name: default: default_option_name value: selected_option_name ``` To get the ConfigValues file from an installed application instance: 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](/embedded-cluster/v3/installing-embedded) or [Online Installation in Existing Clusters](/enterprise/installing-existing-cluster). 1. Depending on the installer that you used, do one of the following to get the ConfigValues for the installed instance: * **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) * **For KOTS installations in an existing cluster**: Run the `kubectl kots get config` command to view the generated ConfigValues file: ```bash 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). ## Online (internet-connected) installation 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. To install with kURL on a VM or bare metal server: 1. Create the kURL cluster: ```bash curl -sSL https://k8s.kurl.sh/APP_NAME | sudo bash ``` 1. Install the application in the cluster: ```bash kubectl kots install APP_NAME \ --shared-password PASSWORD \ --license-file PATH_TO_LICENSE \ --config-values PATH_TO_CONFIGVALUES \ --namespace default \ --no-port-forward ``` Replace: * `APP_NAME` with a name for the application. This is the unique name that KOTS will use to refer to the application that you install. * `PASSWORD` with a shared password for accessing the Admin Console. * `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. * `NAMESPACE` with the namespace where Replicated kURL installed Replicated KOTS when creating the cluster. By default, kURL installs KOTS in the `default` namespace. ## Air gap installation To install in an air-gapped kURL cluster: 1. Download the kURL `.tar.gz` air gap bundle: ```bash 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. 1. 1. Create the kURL cluster: ``` cat install.sh | sudo bash -s airgap ``` 1. Install the application: ```bash kubectl kots install APP_NAME \ --shared-password PASSWORD \ --license-file PATH_TO_LICENSE \ --config-values PATH_TO_CONFIGVALUES \ --airgap-bundle PATH_TO_AIRGAP_BUNDLE \ --namespace default \ --no-port-forward ``` Replace: * `APP_NAME` with a name for the application. This is the unique name that KOTS will use to refer to the application that you install. * `PASSWORD` with a shared password for accessing the Admin Console. * `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. * `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. * `NAMESPACE` with the namespace where Replicated kURL installed Replicated KOTS when creating the cluster. By default, kURL installs KOTS in the `default` namespace. --- # kURL installation requirements This topic lists the installation requirements for Replicated kURL. Ensure that the installation environment meets these requirements before attempting to install. :::note Replicated kURL is available only for existing customers. If you are not an existing kURL user, use Replicated Embedded Cluster instead. For more information, see [Use Embedded Cluster](/embedded-cluster/v3/embedded-overview). kURL is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Minimum system requirements * 4 CPUs or equivalent per machine * 8GB of RAM per machine * 40GB of disk space per machine * TCP ports 2379, 2380, 6443, 6783, and 10250 open between cluster nodes * UDP port 8472 open between cluster nodes :::note If the Kubernetes installer specification uses the deprecated kURL [Weave add-on](https://kurl.sh/docs/add-ons/weave), UDP ports 6783 and 6784 must be open between cluster nodes. Reach out to your software vendor for more information. ::: * Root access is required * (Rook Only) The Rook add-on version 1.4.3 and later requires block storage on each node in the cluster. For more information about how to enable block storage for Rook, see [Block Storage](https://kurl.sh/docs/add-ons/rook/#block-storage) in _Rook Add-On_ in the kURL documentation. ## Additional system requirements You must meet the additional kURL system requirements when applicable: - **Supported Operating Systems**: For supported operating systems, see [Supported Operating Systems](https://kurl.sh/docs/install-with-kurl/system-requirements#supported-operating-systems) in the kURL documentation. - **kURL Dependencies Directory**: kURL installs additional dependencies in the directory /var/lib/kurl and the directory requirements must be met. See [kURL Dependencies Directory](https://kurl.sh/docs/install-with-kurl/system-requirements#kurl-dependencies-directory) in the kURL documentation. - **Networking Requirements**: Networking requirements include firewall openings, host firewalls rules, and port availability. See [Networking Requirements](https://kurl.sh/docs/install-with-kurl/system-requirements#networking-requirements) in the kURL documentation. - **High Availability Requirements**: If you are operating a cluster with high availability, see [High Availability Requirements](https://kurl.sh/docs/install-with-kurl/system-requirements#high-availability-requirements) in the kURL documentation. - **Cloud Disk Performance**: For a list of cloud VM instance and disk combinations that are known to provide sufficient performance for etcd and pass the write latency preflight, see [Cloud Disk Performance](https://kurl.sh/docs/install-with-kurl/system-requirements#cloud-disk-performance) in the kURL documentation. ## Network requirements for online installations ### Firewall openings {#firewall} The domains for the services listed below need to be accessible from servers performing online installations. No outbound internet access is required for air gap installations. For services hosted at domains owned by Replicated, the table includes a link to the list of IP addresses for the domain at [replicatedhq/ips](https://github.com/replicatedhq/ips/blob/main/ip_addresses.json) in GitHub. Note that the IP addresses listed in the `replicatedhq/ips` repository also include IP addresses for some domains that are _not_ required for installation. For any third-party services hosted at domains not owned by Replicated, consult the third-party's documentation for the IP address range for each domain.
Domain Description
Docker Hub

Some dependencies of KOTS are hosted as public images in Docker Hub. The required domains for this service are `index.docker.io`, `cdn.auth0.com`, `*.docker.io`, and `*.docker.com.`
`proxy.replicated.com` *

Private Docker images are proxied through `proxy.replicated.com`. This domain is owned by Replicated, Inc., which is headquartered in Los Angeles, CA.

For the range of IP addresses for `proxy.replicated.com`, see [replicatedhq/ips](https://github.com/replicatedhq/ips/blob/main/ip_addresses.json#L52-L57) in GitHub.
`replicated.app`

Upstream application YAML and metadata is pulled from `replicated.app`. The current running version of the application (if any), as well as a license ID and application ID to authenticate, are all sent to `replicated.app`. This domain is owned by Replicated, Inc., which is headquartered in Los Angeles, CA.

For the range of IP addresses for `replicated.app`, see [replicatedhq/ips](https://github.com/replicatedhq/ips/blob/main/ip_addresses.json#L60-L65) in GitHub.
`registry.replicated.com` **

Some applications host private images in the Replicated registry at this domain. The on-prem docker client uses a license ID to authenticate to `registry.replicated.com`. This domain is owned by Replicated, Inc which is headquartered in Los Angeles, CA.

For the range of IP addresses for `registry.replicated.com`, see [replicatedhq/ips](https://github.com/replicatedhq/ips/blob/main/ip_addresses.json#L20-L25) in GitHub.

`k8s.kurl.sh`

`s3.kurl.sh`

kURL installation scripts and artifacts are served from [kurl.sh](https://kurl.sh). An application identifier is sent in a URL path, and bash scripts and binary executables are served from kurl.sh. This domain is owned by Replicated, Inc., which is headquartered in Los Angeles, CA.

For the range of IP addresses for `k8s.kurl.sh`, see [replicatedhq/ips](https://github.com/replicatedhq/ips/blob/main/ip_addresses.json#L34-L39) in GitHub.

The range of IP addresses for `s3.kurl.sh` are the same as IP addresses for the `kurl.sh` domain. For the range of IP address for `kurl.sh`, see [replicatedhq/ips](https://github.com/replicatedhq/ips/blob/main/ip_addresses.json#L28-L31) in GitHub.
`amazonaws.com` `tar.gz` packages are downloaded from Amazon S3 during installations with kURL. For information about dynamically scraping the IP ranges to allowlist for accessing these packages, see [AWS IP address ranges](https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html#aws-ip-download) in the AWS documentation.
* Required only if the application uses the [Replicated proxy registry](/vendor/private-images-about). ** Required only if the application uses the [Replicated registry](/vendor/private-images-replicated). ### IPv4 or IPv4/IPv6 dual-stack only kURL does not support online installations in single-stack IPv6-only environments. Environments that use IPv4 or dual-stack IPv4/IPv6 networking are supported. --- # Online installation with kURL This topic describes how to use Replicated kURL to provision a cluster in a virtual machine (VM) or bare metal server and install an application in the cluster. Replicated kURL is an open source project. For more information, see the [kURL documentation](https://kurl.sh/docs/introduction/). :::note Replicated kURL is available only for existing customers. If you are not an existing kURL user, use Replicated Embedded Cluster instead. For more information, see [Use Embedded Cluster](/embedded-cluster/v3/embedded-overview). kURL is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Prerequisites Complete the following prerequisites: * Ensure that your environment meets the minimum system requirements. See [kURL Installation Requirements](/enterprise/installing-kurl-requirements). * Review the advanced installation options available for the kURL installer. See [Advanced Options](https://kurl.sh/docs/install-with-kurl/advanced-options) in the kURL documentation. * Download your license file. Ensure that you can access the downloaded license file from the environment where you will install the application. See [Downloading Customer Licenses](/vendor/licenses-download). - If you are installing in high availability (HA) mode, a load balancer is required. You can use the kURL internal load balancer if the [Embedded kURL Cluster Operator (EKCO) Add-On](https://kurl.sh/docs/add-ons/ekco) is included in the kURL Installer spec. Or, you can bring your own external load balancer. An external load balancer might be preferred when clients outside the cluster need access to the cluster's Kubernetes API. To install in HA mode, complete the following prerequisites: - (Optional) If you are going to use the internal EKCO load balancer, you can preconfigure it by passing `| sudo bash -s ha ekco-enable-internal-load-balancer` with the kURL install command. Otherwise, you are prompted for load balancer details during installation. For more information about the EKCO Add-on, see [EKCO Add-On](https://kurl.sh/docs/add-ons/ekco) in the open source kURL documentation. - To use an external load balancer, ensure that the load balancer meets the following requirements: - Must be a TCP forwarding load balancer - Must be configured to distribute traffic to all healthy control plane nodes in its target list - The health check must be a TCP check on port 6443 For more information about how to create a load balancer for kube-apirserver, see [Create load balancer for kube-apiserver](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/high-availability/#create-load-balancer-for-kube-apiserver) in the Kubernetes documentation. You can optionally preconfigure the external loader by passing the `load-balancer-address=HOST:PORT` flag with the kURL install command. Otherwise, you are prompted to provide the load balancer address during installation. ## Install {#install-app} To install an application with kURL: 1. Run one of the following commands to create the cluster with the kURL installer: * For a regular installation, run: ```bash curl -sSL https://k8s.kurl.sh/APP_NAME | sudo bash ``` * For high availability mode: ```bash curl -sSL https://k8s.kurl.sh/APP_NAME | sudo bash -s ha ``` Replace: * `APP_NAME` with the name of the application. The `APP_NAME` is included in the installation command that your vendor gave you. This is a unique identifier that KOTS will use to refer to the application that you install. 1. 1. 1. Go to the address provided in the `Kotsadm` field in the output of the installation command. For example, `Kotsadm: http://34.171.140.123:8800`. 1. On the Bypass Browser TLS warning page, review the information about how to bypass the browser TLS warning, and then click **Continue to Setup**. 1. On the HTTPS page, do one of the following: - To use the self-signed TLS certificate only, enter the hostname (required) if you are using the identity service. If you are not using the identity service, the hostname is optional. Click **Skip & continue**. - To use a custom certificate only, enter the hostname (required) if you are using the identity service. If you are not using the identity service, the hostname is optional. Then upload a private key and SSL certificate to secure communication between your browser and the Admin Console. Click **Upload & continue**. 1. Log in to the Admin Console with the password that was provided in the `Login with password (will not be shown again):` field in the output of the installation command. 1. Upload your license file. 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**. :::note Replicated recommends that you address any warnings or failures, rather than dismissing them. Preflight checks help ensure that your environment meets the requirements for application deployment. ::: 1. (Minimal RBAC Only) If you are installing with minimal role-based access control (RBAC), KOTS recognizes if the preflight checks failed due to insufficient privileges. When this occurs, a kubectl CLI preflight command displays that lets you manually run the preflight checks. The Admin Console then automatically displays the results of the preflight checks. Click **Deploy**. ![kubectl CLI preflight command](/images/kubectl-preflight-command.png) [View a larger version of this image](/images/kubectl-preflight-command.png) The Admin Console dashboard opens. On the Admin Console dashboard, the application status changes from Missing to Unavailable while the Deployment is being created. When the installation is complete, the status changes to Ready. ![Admin console dashboard showing ready status](/images/gitea-ec-ready.png) [View a larger version of this image](/images/gitea-ec-ready.png) 1. (Recommended) Change the Admin Console login password: 1. Click the menu in the top right corner of the Admin Console, then click **Change password**. 1. Enter a new password in the dialog, and click **Change Password** to save. Replicated strongly recommends that you change the password from the default provided during installation in a kURL cluster. For more information, see [Change an Admin Console Password](auth-changing-passwords). 1. Add primary and secondary nodes to the cluster. You might add nodes to either meet application requirements or to support your usage of the application. See [Adding Nodes to Embedded Clusters](cluster-management-add-nodes). --- # Considerations before installing Before you install an application with KOTS in an existing cluster, consider the following installation options. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Online (internet-connected) or air gap installations Most Kubernetes clusters are able to make outbound internet requests. Inbound access is never recommended or required. As such, most cluster operators are able to perform an online installation. If the target cluster does not have outbound internet access, the application can also be delivered through an air gap installation. To install an application in an air-gapped environment, the cluster must have access to an image registry. In this case, KOTS re-tags and pushes all images to the target registry. For information about installing with KOTS in air-gapped environments, see [Air Gap Installation in Existing Clusters with KOTS](installing-existing-cluster-airgapped). ## Hardened environments By default, KOTS Pods and containers are not deployed with a specific security context. For installations into a hardened environment, you can use the `--strict-security-context` flag with the installation command so that KOTS runs with a strict security context for Pods and containers. For more information about the security context enabled by the `--strict-security-context` flag, see [kots install](/reference/kots-cli-install). ## Configuring local image registries During install, KOTS can re-tag and push images to a local image registry. This is useful to enable CVE scans, image policy validation, and other pre-deployment rules. A private image registry is required for air gapped environments, and is optional for online environments. For information about image registry requirements, see [Compatible Image Registries](installing-general-requirements#registries). ## Automated (headless) installation You can automate application installation in online and air-gapped 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 [Install with the KOTS CLI](/enterprise/installing-existing-cluster-automation). ## KOTS installations without object storage The KOTS Admin Console requires persistent storage for state. KOTS deploys MinIO for object storage by default. You can optionally install KOTS without object storage. When installed without object storage, KOTS deploys the Admin Console as a StatefulSet with an attached PersistentVolume (PV) instead of as a deployment. For more information about how to install KOTS without object storage, see [Install KOTS in Existing Clusters Without Object Storage](/enterprise/installing-stateful-component-requirements). --- # Install KOTS in existing clusters without object storage This topic describes how to install Replicated KOTS in existing clusters without the default object storage, including limitations of installing without object storage. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview The Replicated KOTS Admin Console requires persistent storage for state. By default, KOTS deploys an S3-compatible object store to satisfy the Admin Console's persistent storage requirement. The Admin Console stores the following in object storage: * Support bundles * Application archives * Backups taken with Replicated snapshots that are configured to NFS or host path storage destinations For more information about the Admin Console's persistent storage requirements, see [Minimum System Requirements](/enterprise/installing-general-requirements#minimum-system-requirements) in _Installation Requirements_. For existing cluster installations, KOTS deploys MinIO for object storage by default. You can optionally install KOTS without object storage. When installed without object storage, KOTS deploys the Admin Console as a Statefulset with an attached PersistentVolume (PV) instead of as a deployment. In this case, support bundles and application archives are stored in the attached PV instead of in object storage. Additionally, for local snapshots storage, KOTS uses the `local-volume-provider` Velero plugin to store backups on local PVs instead of using object storage. The `local-volume-provider` plugin uses the existing Velero service account credentials to mount volumes directly to the Velero node-agent pods. For more information, see [`local-volume-provider`](https://github.com/replicatedhq/local-volume-provider) in GitHub. ## How to install and upgrade without object storage To install KOTS without object storage in an existing cluster, you can use the `--with-minio=false` flag. #### `kots install --with-minio=false` When `--with-minio=false` is used with the `kots install` command, KOTS does _not_ deploy MinIO. KOTS deploys the Admin Console as a Statefulset with an attached PV instead of as a deployment. For command usage, see [install](/reference/kots-cli-install/). #### `kots admin-console upgrade --with-minio=false` When `--with-minio=false` is used with the `kots admin-console upgrade` command, KOTS upgrades the existing Admin Console instance to the latest version, replaces the running deployment with a StatefulSet, and removes MinIO after a data migration. This results in temporary downtime for the Admin Console, but deployed applications are unaffected. For command usage, see [admin-console upgrade](/reference/kots-cli-admin-console-upgrade/). --- # Access dashboards using port forwarding This topic includes information about how to access Prometheus, Grafana, and Alertmanager in Replicated KOTS existing cluster and Replicated kURL installations. For information about how to configure Prometheus monitoring in existing cluster installations, see [Configure Prometheus Monitoring in Existing Cluster KOTS Installations](monitoring-applications). :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview The Prometheus [expression browser](https://prometheus.io/docs/visualization/browser/), Grafana, and some preconfigured dashboards are included with Kube-Prometheus for advanced visualization. Prometheus Altertmanager is also included for alerting. You can access Prometheus, Grafana, and Alertmanager dashboards using `kubectl port-forward`. :::note You can also expose these pods on NodePorts or behind an ingress controller. This is an advanced use case. For information about exposing the pods on NodePorts, see [NodePorts](https://github.com/prometheus-operator/kube-prometheus/blob/main/docs/customizations/node-ports.md) in the kube-prometheus GitHub repository. For information about exposing the pods behind an ingress controller, see [Expose via Ingress](https://github.com/prometheus-operator/kube-prometheus/blob/main/docs/customizations/exposing-prometheus-alertmanager-grafana-ingress.md) in the kube-prometheus GitHub repository. ::: ## Prerequisite For existing cluster KOTS installations, first install Prometheus in the cluster and configure monitoring. See [Configure Prometheus Monitoring in Existing Cluster KOTS Installations](monitoring-applications) ## Access Prometheus To access the Prometheus dashboard: 1. Run the following command to port forward the Prometheus service: ```bash kubectl --namespace monitoring port-forward svc/prometheus-k8s 9090 ``` 1. Access the dashboard at http://localhost:9090. ## Access Grafana Users can access the Grafana dashboard by logging in using a default username and password. For information about configuring Grafana, see the [Grafana documentation](https://grafana.com/docs/). For information about constructing Prometheus queries, see [Querying Prometheus](https://prometheus.io/docs/prometheus/latest/querying/basics/) in the Prometheus documentation. To access the Grafana dashboard: 1. Run the following command to port forward the Grafana service: ```bash kubectl --namespace monitoring port-forward deployment/grafana 3000 ``` 1. Access the dashboard at http://localhost:3000. 1. Log in to Grafana: * **Existing cluster**: Use the default Grafana username and password: `admin:admin`. * **kURL cluster**: The Grafana password is randomly generated by kURL and is displayed on the command line after kURL provisions the cluster. To log in, use this password generated by kURL and the username `admin`. To retrieve the password, run the following kubectl command: ``` kubectl get secret -n monitoring grafana-admin -o jsonpath="{.data.admin-password}" | base64 -d ``` ## Access Alertmanager Alerting with Prometheus has two phases: * Phase 1: Alerting rules in Prometheus servers send alerts to an Alertmanager. * Phase 2: The Alertmanager then manages those alerts, including silencing, inhibition, aggregation, and sending out notifications through methods such as email, on-call notification systems, and chat platforms. For more information about configuring Alertmanager, see [Configuration](https://prometheus.io/docs/alerting/configuration/) in the Prometheus documentation. To access the Alertmanager dashboard: 1. Run the following command to port forward the Alertmanager service: ``` kubectl --namespace monitoring port-forward svc/prometheus-alertmanager 9093 ``` 1. Access the dashboard at http://localhost:9093. --- # Configure Prometheus monitoring in existing cluster KOTS installations This topic describes how to monitor applications and clusters with Prometheus in existing cluster installations with Replicated KOTS. For information about how to access Prometheus, Grafana, and Alertmanager, see [Access Dashboards Using Port Forwarding](/enterprise/monitoring-access-dashboards). For information about consuming Prometheus metrics externally in kURL installations, see [Consume Prometheus Metrics Externally](monitoring-external-prometheus). :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview The KOTS Admin Console can use the open source systems monitoring tool Prometheus to collect metrics on an application and the cluster where the application is installed. Prometheus components include the main Prometheus server, which scrapes and stores time series data, an Alertmanager for alerting on metrics, and Grafana for visualizing metrics. For more information about Prometheus, see [What is Prometheus?](https://prometheus.io/docs/introduction/overview/) in the Prometheus documentation. The Admin Console exposes graphs with key metrics collected by Prometheus in the **Monitoring** section of the dashboard. By default, the Admin Console displays the following graphs: * Cluster disk usage * Pod CPU usage * Pod memory usage In addition to these default graphs, application developers can also expose business and application level metrics and alerts on the dashboard. The following screenshot shows an example of the **Monitoring** section on the Admin Console dashboard with the Disk Usage, CPU Usage, and Memory Usage default graphs: Graphs on the Admin Console dashboard [View a larger version of this image](/images/kotsadm-dashboard-graph.png) ## Configure Prometheus monitoring For existing cluster installations with KOTS, users can install Prometheus in the cluster and then connect the Admin Console to the Prometheus endpoint to enable monitoring. ### Step 1: Install Prometheus in the cluster {#configure-existing} Replicated recommends that you use CoreOS's Kube-Prometheus distribution for installing and configuring highly available Prometheus on an existing cluster. For more information, see the [kube-prometheus](https://github.com/coreos/kube-prometheus) GitHub repository. This repository collects Kubernetes manifests, Grafana dashboards, and Prometheus rules combined with documentation and scripts to provide easy to operate end-to-end Kubernetes cluster monitoring with Prometheus using the Prometheus Operator. To install Prometheus using the recommended Kube-Prometheus distribution: 1. Clone the [kube-prometheus](https://github.com/coreos/kube-prometheus) repository to the device where there is access to the cluster. 1. Use `kubectl` to create the resources on the cluster: ```bash # Create the namespace and CRDs, and then wait for them to be available before creating the remaining resources kubectl create -f manifests/setup until kubectl get servicemonitors --all-namespaces ; do date; sleep 1; echo ""; done kubectl create -f manifests/ ``` For advanced and cluster-specific configuration, you can customize Kube-Prometheus by compiling the manifests using jsonnet. For more information, see the [jsonnet website](https://jsonnet.org/). For more information about advanced Kube-Prometheus configuration options, see [Customize Kube-Prometheus](https://github.com/coreos/kube-prometheus#customizing-kube-prometheus) in the kube-prometheus GitHub repository. ### Step 2: Connect to a Prometheus endpoint To view graphs on the Admin Console dashboard, provide the address of a Prometheus instance installed in the cluster. To connect the Admin Console to a Prometheus endpoint: 1. On the Admin Console dashboard, under Monitoring, click **Configure Prometheus Address**. 1. Enter the address for the Prometheus endpoint in the text box and click **Save**. ![Configure Prometheus](/images/kotsadm-dashboard-configureprometheus.png) Graphs appear on the dashboard shortly after saving the address. --- # Consume Prometheus metrics externally :::note Replicated kURL is available only for existing customers. If you are not an existing kURL user, use Replicated Embedded Cluster instead. For more information, see [Use Embedded Cluster](/embedded-cluster/v3/embedded-overview). kURL is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: This topic describes how to consume Prometheus metrics in Replicated kURL clusters from a monitoring service that is outside the cluster. For information about how to access Prometheus, Grafana, and Alertmanager, see [Accessing Dashboards Using Port Forwarding](/enterprise/monitoring-access-dashboards). ## Overview The KOTS Admin Console can use the open source systems monitoring tool Prometheus to collect metrics on an application and the cluster where the application is installed. Prometheus components include the main Prometheus server, which scrapes and stores time series data, an Alertmanager for alerting on metrics, and Grafana for visualizing metrics. For more information about Prometheus, see [What is Prometheus?](https://prometheus.io/docs/introduction/overview/) in the Prometheus documentation. The Admin Console exposes graphs with key metrics collected by Prometheus in the **Monitoring** section of the dashboard. By default, the Admin Console displays the following graphs: * Cluster disk usage * Pod CPU usage * Pod memory usage In addition to these default graphs, application developers can also expose business and application level metrics and alerts on the dashboard. The following screenshot shows an example of the **Monitoring** section on the Admin Console dashboard with the Disk Usage, CPU Usage, and Memory Usage default graphs: Graphs on the Admin Console dashboard [View a larger version of this image](/images/kotsadm-dashboard-graph.png) For kURL installations, if the [kURL Prometheus add-on](https://kurl.sh/docs/add-ons/prometheus) is included in the kURL installer spec, then the Prometheus monitoring system is installed alongside the application. No additional configuration is required to collect metrics and view any default and custom graphs on the Admin Console dashboard. Prometheus is deployed in kURL clusters as a NodePort service named `prometheus-k8s` in the `monitoring` namespace. The `prometheus-k8s` service is exposed on the IP address for each node in the cluster at port 30900. You can run the following command to view the `prometheus-k8s` service in your cluster: ``` kubectl get services -l app=kube-prometheus-stack-prometheus -n monitoring ``` The output of the command includes details about the Prometheus service, including the type of service and the ports where the service is exposed. For example: ``` NAME TYPE CLUSTER_IP EXTERNAL_IP PORT(S) AGE prometheus-k8s NodePort 10.96.2.229 9090:30900/TCP 5hr ``` As shown in the example above, port 9090 on the `prometheus-k8s` service maps to port 30900 on each of the nodes. For more information about NodePort services, see [Type NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport) in _Services_ in the Kubernetes documentation. ## Prerequisite Before you can consume Prometheus metrics in kURL clusters externally, ensure that firewall rules on all nodes in the cluster allow inbound TCP traffic on port 30900. ## Consume metrics from external services You can connect to the `prometheus-k8s` service on port 30900 from any node in the cluster to access Prometheus metrics emitted by kURL clusters. To consume Prometheus metrics from an external service: 1. Get the external IP address for one of the nodes in the cluster. You will use this IP address in the next step to access the `prometheus-k8s` service. You can find the IP address for a node in the output of the following command: ``` kubectl describe node NODE_NAME ``` Where `NODE_NAME` is the name of a node in the cluster. :::note Depending on the node's network configuration, there might be different IP addresses for accessing the node from an external or internal network. For example, the IP address 10.128.0.35 might be assigned to the node in the internal network, whereas the IP address used to access the node from external or public networks is 34.28.178.93. Consult your infrastructure team to assist you in determining which IP address to use. ::: 1. In a browser, go to `http://NODE_IP_ADDRESS:30900` to verify that you can connect to the `prometheus-k8s` NodePort service. Replace `NODE_IP_ADDRESS` with the external IP address that you copied in the first step. For example, `http://34.28.178.93:30900`. If the connection is successful, the Prometheus UI displays in the browser. 1. From your external monitoring solution, add Prometheus as an HTTP data source using the same URL from the previous step: `http://NODE_IP_ADDRESS:30900`. --- # Validate SBOM signatures This topic describes the process to perform the validation of software bill of material (SBOM) signatures for Replicated KOTS, Replicated kURL, and Troubleshoot releases. ## About Software Bills of Materials A _software bill of materials_ (SBOM) is an inventory of all components used to create a software package. SBOMs have emerged as critical building blocks in software security and software supply chain risk management. When you install software, validating an SBOM signature can help you understand exactly what the software package is installing. This information can help you ensure that the files are compatible with your licensing policies and help determine whether there is exposure to CVEs. For information about validating the Replicated SDK, including SLSA provenance, image signatures, and SBOM attestations, see [Validate provenance of releases for the Replicated SDK](/vendor/replicated-sdk-slsa-validating). ## Prerequisite Before you perform these tasks, you must install cosign. For more information, see the [sigstore repository](https://github.com/sigstore/cosign) in GitHub. ## Validate a KOTS SBOM signature Each KOTS release includes a signed SBOM for KOTS Go dependencies. To validate a KOTS SBOM signature: 1. Go to the [KOTS GitHub repository](https://github.com/replicatedhq/kots/releases) and download the specific KOTS release that you want to validate. 1. Extract the tar.gz file. **Example:** ``` tar -zxvf kots_darwin_all.tar.gz ``` A KOTS binary and SBOM folder are created. 1. Run the following cosign command to validate the signatures: ``` cosign verify-blob --key sbom/key.pub --signature sbom/kots-sbom.tgz.sig sbom/kots-sbom.tgz ``` ## Validate a kURL SBOM signature If a kURL installer is used, then signed SBOMs for kURL Go and Javascript dependencies are combined into a TAR file and are included with the release. To validate a kURL SBOM signature: 1. Go to the [kURL GitHub repository](https://github.com/replicatedhq/kURL/releases) and download the specific kURL release files that you want to validate. There are three assets related to the SBOM: - `kurl-sbom.tgz` contains SBOMs for Go and Javascript dependencies - `kurl-sbom.tgz.sig` is the digital signature for `kurl-sbom.tgz` - `key.pub` is the public key from the key pair used to `sign kurl-sbom.tgz` 2. Run the following cosign command to validate the signatures: ``` cosign verify-blob --key key.pub --signature kurl-sbom.tgz.sig kurl-sbom.tgz ``` ## Validate a Troubleshoot SBOM signature A signed SBOM for Troubleshoot dependencies is included in each release. To validate an Troubleshoot SBOM signature: 1. Go to the [Troubleshoot GitHub repository](https://github.com/replicatedhq/troubleshoot/releases) and download the specific Troubleshoot release files that you want to validate. There are three assets related to the SBOM: - `troubleshoot-sbom.tgz` contains a software bill of materials for Troubleshoot. - `troubleshoot-sbom.tgz.sig` is the digital signature for `troubleshoot-sbom.tgz` - `key.pub` is the public key from the key pair used to sign `troubleshoot-sbom.tgz` 2. Run the following cosign command to validate the signatures: ``` $ cosign verify-blob --key key.pub --signature troubleshoot-sbom.tgz.sig troubleshoot-sbom.tgz ``` --- # How to set up backup storage This topic describes the process of setting up backup storage for the Replicated snapshots feature. ## Configuring backup storage for embedded clusters You must configure a backup storage destination before you can create backups. This procedure describes how to configure backup storage for snapshots for _embedded clusters_ created by Replicated kURL. To configure snapshots for embedded clusters: 1. On the Snapshots tab in the Admin Console, click **Check for Velero** to see whether kURL already installed Velero in the embedded cluster. 1. If Velero was installed, update the default internal storage settings in the Admin Console because internal storage is insufficient for full backups. See [Update Settings in the Admin Console](snapshots-updating-with-admin-console). 1. If Velero was not installed: 1. Install the Velero CLI. See [Install the Velero CLI](snapshots-velero-cli-installing). 1. Install Velero and configure a storage destination using one of the following procedures. - [Configure a Host Path Storage Destination](snapshots-configuring-hostpath) - [Configure an NFS Storage Destination](snapshots-configuring-nfs) - [Configure Other Storage Destinations](snapshots-storage-destinations) 1. Optionally increase the default memory for the node-agent Pod. See [Configure Namespace Access and Memory Limit](snapshots-velero-installing-config). ## Configuring backup storage for existing clusters You must configure a backup storage destination before you can create backups. Follow this process to install Velero and configure the snapshots feature: 1. Install the Velero CLI. See [Install the Velero CLI](snapshots-velero-cli-installing). 1. Install Velero and configure a storage destination using one of the following procedures. - [Configure a Host Path Storage Destination](snapshots-configuring-hostpath) - [Configure an NFS Storage Destination](snapshots-configuring-nfs) - [Configure Other Storage Destinations](snapshots-storage-destinations) 1. Enable access to the Velero namespace if you are using RBAC and optionally increase the default memory for the node-agent Pod. See [Configure Namespace Access and Memory Limit](snapshots-velero-installing-config). ## Next step After you configure a storage destination, you can create a backup. See [Create and Schedule Backups](snapshots-creating). ## Additional resources * [Restore Full Backups](snapshots-restoring-full) * [Troubleshoot Snapshots](snapshots-troubleshooting-backup-restore) --- # Configure a host path storage destination This topic describes how to install Velero and configure a host path as your storage destination for backups. :::note If Velero is already installed, you can update your storage destination in the Replicated Admin Console. For embedded clusters with the Velero add-on, you must update the default internal storage settings in the Admin Console because internal storage is insufficient for full backups. For more information about updating storage, see [Updating Settings in the Admin Console](snapshots-updating-with-admin-console). ::: :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: :::important The local-volume-provider (LVP) plugin supports only Restic. Velero 1.17 and later do not support LVP. KOTS uses LVP only when you disable MinIO or explicitly install the LVP plugin. If you use LVP for HostPath storage, migrate to a Kopia-compatible destination before upgrading to Velero 1.17 or later. Existing LVP backups from Velero 1.16 and earlier are not restorable on Velero 1.17 or later. For more information, see [Upgrade Velero for snapshots](snapshots-velero-upgrading). ::: ## Requirements * The host path must be a dedicated directory. Do not use a partition used by a service like Docker or Kubernetes for ephemeral storage. * The host path must exist and be writable by the user:group 1001:1001 on all nodes in the cluster. For example, in a Linux environment you might run `sudo chown -R 1001:1001 /backups` to change the user:group permissions. If you use a mounted directory for the storage destination, such as one that is created with the Common Internet File System (CIFS) or Server Message Block (SMB) protocols, ensure that you configure the user:group 1001:1001 permissions on all nodes in the cluster and from the server side as well. You cannot change the permissions of a mounted network shared filesystem from the client side. To reassign the user:group to 1001:1001 for a directory that is already mounted, you must remount the directory. For example, for a CIFS mounted directory, specify the `uid=1001,gid=1001` mount options in the CIFS mount command. ## Prerequisites Complete the following items before you perform this task: * Review the limitations and considerations. See [Limitations and Considerations](/vendor/snapshots-overview#limitations-and-considerations) in _About Backup and Restore_. * Install the velero CLI. See [Install the Velero CLI](snapshots-velero-cli-installing). ## Install Velero and configure host path storage in online environments To install Velero and configure host path storage in online environments: 1. 1. 1. Run the following command to configure the host path storage destination: ``` kubectl kots velero configure-hostpath --namespace NAME --hostpath /PATH ``` Replace: - `NAME` with the namespace where the Replicated KOTS Admin Console is installed and running - `PATH` with the path to the directory where the backups will be stored For more information about required storage destination flags, see [`velero`](/reference/kots-cli-velero-index) in _Reference_. ## Install Velero and configure host path storage in air-gapped environments To install Velero and configure host path storage in air-gapped environments: 1. 1. :::note It is typical for the velero and node-agent Pods to be in the `ErrImagePull` or `ImagePullBackOff` state after you run the `velero install` command because Velero does not support passing registry credentials during installation. In Replicated KOTS v1.94.0 and later, this situation resolves itself after you complete the instructions to configure the storage destination. If you are on an earlier version of KOTS, Replicated recommends that you upgrade to KOTS v1.94.0 or later. Otherwise, you must patch the Velero deployment manually and add the image pull secret to access the registry. ::: 1. 1. Run the following command to configure the host path storage destination: ``` kubectl kots velero configure-hostpath \ --namespace NAME \ --hostpath /PATH \ --kotsadm-registry REGISTRY_HOSTNAME[/REGISTRY_NAMESPACE] \ --registry-username REGISTRY_USERNAME \ --registry-password REGISTRY_PASSWORD ``` Replace: - `NAME` with the namespace where the Admin Console is installed and running - `PATH` with the path to the directory where the backups will be stored - `REGISTRY_HOSTNAME` with the registry endpoint where the images are hosted - `REGISTRY_NAMESPACE` with the registry namespace where the images are hosted (Optional) - `REGISTRY_USERNAME` with the username to use to authenticate with the registry - `REGISTRY_PASSWORD` with the password to use to authenticate with the registry For more information about required storage destination flags, see [`velero`](/reference/kots-cli-velero-index) in _Reference_. ## Configure host path storage in the Admin Console Alternatively, when the Admin Console and application are already installed, you can start in the Admin Console to install Velero and configure a host path storage destination. To install Velero and configure host path storage for existing clusters: 1. From the Admin Console, click **Snapshots > Settings and Schedule**. 1. Click **Add a new storage destination**. The Add a new destination dialog opens and shows instructions for setting up Velero with different providers. 1. Click **Host Path**. ![Snapshot Provider Host Path](/images/snapshot-provider-hostpath.png) 1. In the Configure Host Path dialog, enter the path to the directory where the backups will be stored. Click **Get instructions**. ![Snapshot Provider Host Path Fields](/images/snapshot-provider-hostpath-field.png) A dialog opens with instructions on how to set up Velero with the specified host path configuration. 1. Follow the steps in the dialog to install Velero and configure the storage destination. ![Snapshot Provider File System Instructions](/images/snapshot-provider-hostpath-instructions.png) 1. Return to the Admin Console and either click **Check for Velero** or refresh the page to verify that the Velero installation is detected. ## Next steps * (Existing Clusters Only) Configure Velero namespace access if you are using minimal RBAC. See [Configure Namespace Access and Memory Limit](snapshots-velero-installing-config). * (Optional) Increase the default memory limits. See [Configure Namespace Access and Memory Limit](snapshots-velero-installing-config). * Create or schedule backups. See [Create and Schedule Backups](snapshots-creating). ## Additional resources * [Troubleshoot Snapshots](/enterprise/snapshots-troubleshooting-backup-restore) --- # Configure an NFS storage destination This topic describes how to install Velero and configure a Network File System (NFS) as your storage destination for backups. :::note If Velero is already installed, you can update your storage destination in the Replicated Admin Console. For embedded clusters with the Velero add-on, you must update the default internal storage settings in the Admin Console because internal storage is insufficient for full backups. For more information about updating storage, see [Updating Settings in the Admin Console](snapshots-updating-with-admin-console). ::: :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: :::important The local-volume-provider (LVP) plugin supports only Restic. Velero 1.17 and later do not support LVP. KOTS uses LVP only when you disable MinIO or explicitly install the LVP plugin. If you use LVP for NFS storage, migrate to a Kopia-compatible destination before upgrading to Velero 1.17 or later. Existing LVP backups from Velero 1.16 and earlier are not restorable on Velero 1.17 or later. For more information, see [Upgrade Velero for snapshots](snapshots-velero-upgrading). ::: ## Requirements Configuring an NFS server as a snapshots storage destination has the following requirements: * The NFS server must be configured to allow access from all of the nodes in the cluster. * The NFS directory must be writable by the user:group 1001:1001. * Ensure that you configure the user:group 1001:1001 permissions for the directory on the NFS server. * All of the nodes in the cluster must have the necessary NFS client packages installed to be able to communicate with the NFS server. For example, the `nfs-common` package is a common package used on Ubuntu. * Any firewalls must be properly configured to allow traffic between the NFS server and clients (cluster nodes). ## Prerequisites Complete the following items before you perform this task: * Review the limitations and considerations. See [Limitations and Considerations](/vendor/snapshots-overview#limitations-and-considerations) in _About Backup and Restore_. * Install the velero CLI. See [Install the Velero CLI](snapshots-velero-cli-installing). ## Install Velero and configure NFS storage in online environments To install Velero and configure NFS storage in an online environment: 1. 1. 1. Run the following command to configure the NFS storage destination: ``` kubectl kots velero configure-nfs --namespace NAME --nfs-path PATH --nfs-server HOST ``` Replace: - `NAME` with the namespace where the Replicated KOTS Admin Console is installed and running - `PATH` with the path that is exported by the NFS server - `HOST` with the hostname or IP address of the NFS server For more information about required storage destination flags, see [`velero`](/reference/kots-cli-velero-index) in _Reference_. ## Install Velero and configure NFS storage in air-gapped environments To install Velero and configure NFS storage in air-gapped environments: 1. 1. :::note It is typical for the velero and node-agent Pods to be in the `ErrImagePull` or `ImagePullBackOff` state after you run the `velero install` command because Velero does not support passing registry credentials during installation. In Replicated KOTS v1.94.0 and later, this situation resolves itself after you complete the instructions to configure the storage destination. If you are on an earlier version of KOTS, Replicated recommends that you upgrade to KOTS v1.94.0 or later. Otherwise, you must patch the Velero deployment manually and add the image pull secret to access the registry. ::: 1. 1. Run the following command to configure the NFS storage destination: ``` kubectl kots velero configure-nfs \ --namespace NAME \ --nfs-server HOST \ --nfs-path PATH \ --kotsadm-registry REGISTRY_HOSTNAME[/REGISTRY_NAMESPACE] \ --registry-username REGISTRY_USERNAME \ --registry-password REGISTRY_PASSWORD ``` Replace: - `NAME` with the namespace where the Admin Console is installed and running - `HOST` with the hostname or IP address of the NFS server - `PATH` with the path that is exported by the NFS server - `REGISTRY_HOSTNAME` with the registry endpoint where the images are hosted - `REGISTRY_NAMESPACE` with the registry namespace where the images are hosted (Optional) - `REGISTRY_USERNAME` with the username to use to authenticate with the registry - `REGISTRY_PASSWORD` with the password to use to authenticate with the registry For more information about required storage destination flags, see [`velero`](/reference/kots-cli-velero-index) in _Reference_. ## Configure NFS storage in the Admin Console Alternatively, when the Admin Console and application are already installed, you can start in the Admin Console to install Velero and configure an NFS storage destination. To install Velero and configure NFS storage for existing clusters: 1. From the Admin Console, click **Snapshots > Settings and Schedule**. 1. Click **Add a new storage destination**. The Add a new destination dialog opens and shows instructions for setting up Velero with different providers. 1. Click **NFS**. ![Snapshot Provider NFS](/images/snapshot-provider-nfs.png) 1. In the Configure NFS dialog, enter the NFS server hostname or IP Address, and the path that is exported by the NFS server. Click **Get instructions**. ![Snapshot Provider NFS Fields](/images/snapshot-provider-nfs-fields.png) A dialog opens with instructions on how to set up Velero with the specified NFS configuration. 1. Follow the steps in the dialog to install Velero and configure the storage destination. ![Snapshot Provider File System Instructions](/images/snapshot-provider-nfs-instructions.png) 1. Return to the Admin Console and either click **Check for Velero** or refresh the page to verify that the Velero installation is detected. ## Next steps * (Existing Clusters Only) Configure Velero namespace access if you are using minimal RBAC. See [Configure Namespace Access and Memory Limit](snapshots-velero-installing-config). * (Optional) Increase the default memory limits. See [Configure Namespace Access and Memory Limit](snapshots-velero-installing-config). * Create or schedule backups. See [Create and Schedule Backups](snapshots-creating). ## Additional resources * [Troubleshoot Snapshots](snapshots-troubleshooting-backup-restore) --- # Create and schedule backups This topic describes how to use the Replicated snapshots feature to create backups. It also includes information about how to use the Replicated KOTS Admin Console create a schedule for automatic backups. For information about restoring, see [Restore from Backups](snapshots-restoring-full). :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Prerequisites - Before you can create backups, you must configure a storage destination: - [Configure a Host Path Storage Destination](snapshots-configuring-hostpath) - [Configure an NFS Storage Destination](snapshots-configuring-nfs) - [Configure Other Storage Destinations](snapshots-storage-destinations) - If you have multiple applications in the Admin Console, make sure that each application has its own Backup custom resource file so that they can be included in the full backup. Use the **View file** tab to check for the Backup custom resources (`kind: Backup`, `apiVersion: velero.io/v1`). If any Backup custom resource files are missing, contact your vendor. ## Create a full backup (recommended) {#full} Full backups, or _instance snapshots_, back up the Admin Console and all application data, including application volumes and manifest files. If you manage multiple applications with the Admin Console, data from all applications that support backups is included in a full backup. From a full backup, you can: * Restore application and Admin Console data * Restore only application data * Restore only Admin Console data You can create a full backup with the following methods: * [Create a Backup with the CLI](#cli-backup) * [Create a Backup in the Admin Console](#admin-console-backup) ### Create a backup with the CLI {#cli-backup} To create a full backup with the Replicated KOTS CLI, run the following command: ``` kubectl kots backup --namespace NAMESPACE ``` Replace `NAMESPACE` with the namespace where the Admin Console is installed. For more information, see [backup](/reference/kots-cli-backup-index) in _KOTS CLI_. ### Create a backup in the Admin Console {#admin-console-backup} To create a full backup in the Admin Console: 1. To check if backups are supported for an application, go to the **View files** page, open the `upstream` folder, and confirm that the application includes a manifest file with `kind: Backup` and `apiVersion: velero.io/v1`. This manifest also shows which pod volumes are being backed up. 1. Go to **Snapshots > Full Snapshots (Instance)**. 1. Click **Start a snapshot**. When the backup is complete, it appears in the list of backups on the page, as shown in the following image: ![Full snapshot page with one completed snapshot](/images/snapshot-instance-list.png) ## Create a partial backup {#partial} Partial backups, or _application snapshots_, back up application volumes and application manifests only. Partial backups do not back up Admin Console data. :::note Replicated recommends that you create full backups instead of partial backups because partial backups are not suitable for disaster recovery. See [Create a Full Backup](#full) above. ::: To create a partial backup in the Admin Console: 1. Go to **Snapshots > Partial Snapshots (Application)**. 1. If you manage multiple applications in the Admin Console, use the dropdown to select the application that you want to back up. 1. Click **Start a snapshot**. When the snapshot is complete, it appears in the list of snapshots on the page as shown in the following image: ![Partial snapshot page with one completed snapshot](/images/snapshot-application-list.png) ## Schedule automatic backups You can use the Admin Console to schedule full or partial backups. This is useful for automatically creating regular backups of Admin Console and application data. To schedule automatic backups in the Admin Console: 1. Go to **Snapshots > Settings & Schedule**. 1. Under **Automatic snapshots**, select **Full snapshots (Instance)** or **Partial snapshots (Application)** depending on the type of backup that you want to schedule. ![Snapshot Settings and Schedule page](/images/snapshot-schedule.png) 1. (Partial Backups Only) If you manage multiple applications in the Admin Console, use the dropdown to select the application that you want to back up. 1. Select **Enable automatic scheduled snapshots**. 1. Configure the automatic backup schedule for the type of snapshots that you selected: * For **Schedule**, select Hourly, Daily, Weekly, or Custom. * For **Cron Expression**, enter a cron expression to create a custom automatic backup schedule. For information about supported cron expressions, see [Cron Expressions](/reference/cron-expressions). 1. (Optional) For **Retention Policy**, edit the amount of time that backup data is saved. By default, backup data is saved for 30 days. The retention policy applies to all backups, including both automatically- and manually-created backups. Changing the retention policy affects only backups created after the time of the change. ## Additional resources [Troubleshoot Snapshots](snapshots-troubleshooting-backup-restore) --- # Restore from backups This topic describes how to restore from full or partial backups using Replicated snapshots. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview Snapshots supports the following types of restores: * Restore both the application and the KOTS Admin Console (also referred to as a _full_ restore) * Restore the KOTS Admin Console only * Restore the application only (also referred to as a _partial_ restore) You can do any type of restore from a full backup using the KOTS CLI. You can also restore an application from a full or partial backup using the Admin Console. ## Limitations The following limitations apply to restoring from backups using snapshots: * * * * For a full list of limitations and considerations related to the snapshots feature, see [Limitations and Considerations](/vendor/snapshots-overview#limitations-and-considerations) in _About Backup and Restore_. ## Restore from a full backup using the CLI {#full-cli} You can use the KOTS CLI to restore both the Admin Console and the application, the Admin Console only, or the application only. If you need to restore the Admin Console, you must use the KOTS CLI because the Admin Console gets recreated and is disconnected during the restore process. :::note Only full backups can be restored using the KOTS CLI. To restore an application from a partial backup, use the Admin Console. See [Restore the Application Only Using the Admin Console](/enterprise/snapshots-restoring-full#admin-console). ::: To restore using the CLI, see the corresponding procedure for your environment: - [Existing Clusters](#existing) - [Online kURL Clusters](#online) - [Air Gap kURL Clusters](#air-gapped) ### Existing clusters {#existing} :::note If you are restoring to a healthy online cluster, you can skip reinstalling Velero and continue to running the `get backups` and `restore` commands in the last two steps. ::: To restore a full backup in an existing cluster: 1. (Air Gap Only) For air-gapped environments, do the following to prepare the necessary Velero images so that you can install Velero in the target cluster: 1. Download the following images to your local machine, tag them, then upload them to your local image registry: * The Velero image. See [Preparing the Velero Image](https://velero.io/docs/v1.16/on-premises/#preparing-the-velero-image). * The `velero/velero-plugin-for-aws:$PLUGIN_VERSION` plugin image. See [Preparing plugin images](https://velero.io/docs/v1.16/on-premises/#preparing-plugin-images). * The restore helper image. The restore helper is required for File System Backups. See [Preparing the restore helper image](https://velero.io/docs/v1.16/on-premises/#preparing-the-restore-helper-image-optional). 1. Create a ConfigMap in the Velero namespace to specify the location of the Velero restore helper image on your local registry. For more information about the requirements for this ConfigMap, see [Customize Restore Helper Container](https://velero.io/docs/v1.16/file-system-backup/#customize-restore-helper-container). 1. (New or Unhealthy Clusters Only) In the cluster where you will do the restore, install a version of Velero that is compatible with the version that was used to make the snapshot backup. The Velero installation command varies depending on the storage destination for the backup: * **Host Path:** See [Configuring a Host Path Storage Destination](snapshots-configuring-hostpath) * **NFS:** See [Configuring an NFS Storage Destination](snapshots-configuring-nfs) or for the configuration steps and how to set up Velero. * **AWS, GCP, Azure, or other S3:** See [Configuring Other Storage Destinations](snapshots-storage-destinations). :::note For air-gapped environments, be sure to point to the location of each image on your local image registry with the `velero install` command. For more information, see [Installing Velero](https://velero.io/docs/v1.16/on-premises/#installing-velero). ::: 1. 1. ### Online kURL clusters {#online} :::note If you are restoring to a healthy cluster, you can skip the installation and configuration steps and continue to running the `get backups` and `restore` commands in the last two steps. ::: To restore a full backup in a kURL cluster: 1. (New or Unhealthy Clusters Only) Provision a cluster with kURL and install the target application in the cluster. See [Online Installation with kURL](installing-kurl). 1. (New or Unhealthy Clusters Only) In the new kURL cluster, configure a storage destination that holds the backup you want to use: * **Host Path:** See [Configuring a Host Path Storage Destination](snapshots-configuring-hostpath) * **NFS:** See [Configuring an NFS Storage Destination](snapshots-configuring-nfs) or for the configuration steps and how to set up Velero. * **AWS, GCP, Azure, or other S3:** See [Configuring Other Storage Destinations](snapshots-storage-destinations). 1. 1. ### Air gap kURL clusters {#air-gapped} To restore a full backup in an air gap kURL cluster: 1. Run the following command to install a new cluster and provide kURL with the correct registry IP address. kURL must be able to assign the same IP address to the embedded private image registry in the new cluster. ```bash cat install.sh | sudo bash -s airgap kurl-registry-ip=IP ``` Replace `IP` with the registry IP address. 1. Use the KOTS CLI to configure Velero to use a storage destination. The storage backend used for backups must be accessible from the new cluster. * **Host Path:** See [Configuring a Host Path Storage Destination](snapshots-configuring-hostpath) * **NFS:** See [Configuring an NFS Storage Destination](snapshots-configuring-nfs) or for the configuration steps and how to set up Velero. * **S3-Compatible:** See [Configure S3-Compatible Storage for Air Gapped Environments](snapshots-storage-destinations#configure-s3-compatible-storage-for-air-gapped-environments) in _Configuring Other Storage Destinations_. 1. 1. ## Restore the application only using the Admin Console {#admin-console} You can restore an application from a full or partial backup using the Admin Console. ### Prerequisite for air-gapped environments For existing cluster installations in air-gapped environments, ensure that Velero is installed on the cluster before proceeding with the restore. To prepare the necessary Velero images and install Velero in air-gapped environments: 1. Download the following images to your local machine, tag them, then upload them to your local image registry: * The Velero image. See [Preparing the Velero Image](https://velero.io/docs/v1.16/on-premises/#preparing-the-velero-image). * The `velero/velero-plugin-for-aws:$PLUGIN_VERSION` plugin image. See [Preparing plugin images](https://velero.io/docs/v1.16/on-premises/#preparing-plugin-images). * The restore helper image. The restore helper is required for File System Backups. See [Preparing the restore helper image](https://velero.io/docs/v1.16/on-premises/#preparing-the-restore-helper-image-optional). 1. Create a ConfigMap in the Velero namespace to specify the location of the Velero restore helper image on your local registry. For more information about the requirements for this ConfigMap, see [Customize Restore Helper Container](https://velero.io/docs/v1.16/file-system-backup/#customize-restore-helper-container). 1. In the cluster where you will do the restore, install a version of Velero that is compatible with the version that was used to make the snapshot backup. The Velero installation command varies depending on the storage destination for the backup: * **Host Path:** See [Configuring a Host Path Storage Destination](snapshots-configuring-hostpath) * **NFS:** See [Configuring an NFS Storage Destination](snapshots-configuring-nfs) or for the configuration steps and how to set up Velero. * **AWS, GCP, Azure, or other S3:** See [Configuring Other Storage Destinations](snapshots-storage-destinations). :::note For air-gapped environments, be sure to point to the location of each image on your local image registry with the `velero install` command. For more information, see [Installing Velero](https://velero.io/docs/v1.16/on-premises/#installing-velero). ::: ### Restore an application from a full backup To restore an application from a full backup: 1. Select **Full Snapshots (Instance)** from the Snapshots tab. ![Full Snapshot tab](/images/full-snapshot-tab.png) [View a larger version of this image](/images/full-snapshot-tab.png) 1. Click the **Restore from this backup** icon (the circular blue arrows) for the backup that you want to restore. 1. In the **Restore from backup** dialog, select **Partial restore**. ![Restore Full Snapshot dialog](/images/restore-backup-dialog.png) [View a larger version of this image](/images/restore-backup-dialog.png) :::note You can also get the CLI commands for full restores or Admin Console only restores from this dialog. ::: 1. At the bottom of the dialog, enter the application slug provided by your software vendor. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug) in _Managing Applications_. 1. Click **Confirm and restore**. ### Restore an application from a partial backup To restore an application from a partial backup: 1. Select **Partial Snapshots (Application)** from the Snapshots tab. ![Partial Snapshot tab](/images/partial-snapshot-tab.png) [View a larger version of this image](/images/partial-snapshot-tab.png) 1. Click the **Restore from this backup** icon (the circular blue arrows) for the backup that you want to restore. The **Restore from Partial backup (Application)** dialog opens. 1. Under **Type your application slug to continue**, enter the application slug provided by your software vendor. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug) in _Managing Applications_. ![Restore Partial Snapshot dialog](/images/restore-partial-dialog.png) [View a larger version of this image](/images/restore-partial-dialog.png) 1. Click **Confirm and restore**. ## Additional resources [Troubleshooting Snapshots](snapshots-troubleshooting-backup-restore) --- # Configure other storage destinations This topic describes installing Velero and configuring storage for Amazon Web Service (AWS), Google Cloud Provider (GCP), Microsoft Azure, and S3-compatible providers. To configure host path or NFS as a storage destination, see [Configure a Host Path Storage Destination](snapshots-configuring-hostpath) and [Configure an NFS Storage Destination](snapshots-configuring-nfs). :::note If Velero is already installed, you can update your storage destination in the Replicated Admin Console. For embedded clusters with the Velero add-on, you must update the default internal storage settings in the Admin Console because internal storage is insufficient for full backups. For more information about updating storage, see [Updating Settings in the Admin Console](snapshots-updating-with-admin-console). ::: :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Prerequisites Complete the following items before you install Velero and configure a storage destination: * Review the limitations and considerations. See [Limitations and Considerations](/vendor/snapshots-overview#limitations-and-considerations) in _About Backup and Restore_. * Install the velero CLI. See [Install the Velero CLI](snapshots-velero-cli-installing). ## Configure AWS storage for online environments In this procedure, you install Velero and configure an AWS storage destination in online environments. Snapshots does not support Amazon Simple Storage Service (Amazon S3) buckets that have a bucket policy requiring the server-side encryption header. If you want to require server-side encryption for objects, you can enable default encryption on the bucket instead. For more information about Amazon S3, see the [Amazon S3](https://docs.aws.amazon.com/s3/?icmpid=docs_homepage_featuredsvcs) documentation. To install Velero and configure an AWS storage destination: 1. Follow the instructions for [installing Velero on AWS](https://github.com/vmware-tanzu/velero-plugin-for-aws#setup) in the velero-plugin-for-aws repository in GitHub. 1. Run the `velero install` command with these additional flags: * **Velero 1.17 and later**: Use the `--use-node-agent` and `--use-volume-snapshots=false` flags. * **Velero 1.11 to 1.16**: Use the `--use-node-agent`, `--uploader-type=restic`, and `--use-volume-snapshots=false` flags. **Example:** ``` velero install \ --provider aws \ --plugins velero/velero-plugin-for-aws:v1.14.2 \ --bucket $BUCKET \ --backup-location-config region=$REGION \ --secret-file CREDS_FILE \ --use-node-agent \ --use-volume-snapshots=false ``` ## Configure GCP storage for online environments In this procedure, you install Velero and configure a GCP storage destination in online environments. To install Velero and configure a GCP storage destination: 1. Follow the instructions for installing Velero on GCP in the [velero-plugin-for-gcp](https://github.com/vmware-tanzu/velero-plugin-for-gcp#setup) repository in GitHub. 1. Run the `velero install` command with these additional flags: * **Velero 1.17 and later**: Use the `--use-node-agent` and `--use-volume-snapshots=false` flags. * **Velero 1.11 to 1.16**: Use the `--use-node-agent`, `--uploader-type=restic`, and `--use-volume-snapshots=false` flags. **Example:** ``` velero install \ --provider gcp \ --plugins velero/velero-plugin-for-gcp:v1.14.2 \ --bucket $BUCKET \ --secret-file ./CREDS_FILE \ --use-node-agent \ --use-volume-snapshots=false ``` ## Configure Azure storage for online environments In this procedure, you install Velero and configure an Azure storage destination in online environments. To install Velero and configure an Azure storage destination: 1. Follow the instructions for [Install Velero on Azure](https://github.com/vmware-tanzu/velero-plugin-for-microsoft-azure#setup) in the Velero documentation. 1. Run the `velero install` command with these additional flags: * **Velero 1.17 and later**: Use the `--use-node-agent` and `--use-volume-snapshots=false` flags. * **Velero 1.11 to 1.16**: Use the `--use-node-agent`, `--uploader-type=restic`, and `--use-volume-snapshots=false` flags. **Example:** ``` velero install \ --provider azure \ --plugins velero/velero-plugin-for-microsoft-azure:v1.14.2 \ --bucket $BLOB_CONTAINER \ --secret-file ./CREDS_FILE \ --backup-location-config resourceGroup=$AZURE_BACKUP_RESOURCE_GROUP,storageAccount=$AZURE_STORAGE_ACCOUNT_ID[,subscriptionId=$AZURE_BACKUP_SUBSCRIPTION_ID] \ --snapshot-location-config apiTimeout=[,resourceGroup=$AZURE_BACKUP_RESOURCE_GROUP,subscriptionId=$AZURE_BACKUP_SUBSCRIPTION_ID] \ --use-node-agent \ --use-volume-snapshots=false ``` ## Configure s3-compatible storage for online environments Replicated supports the following S3-compatible object stores for storing backups with Velero: - Ceph RADOS v12.2.7 - MinIO Run the following command to install Velero and configure an S3-compatible storage destination in an online environment. For more information about required storage destination flags, see [`velero`](/reference/kots-cli-velero-index) in _Reference_. ``` kubectl kots velero configure-other-s3 \ --namespace NAME \ --endpoint ENDPOINT \ --region REGION \ --bucket BUCKET \ --access-key-id ACCESS_KEY_ID \ --secret-access-key SECRET_ACCESS_KEY ``` Replace: - NAME with the name of the namespace where the Replicated KOTS Admin Console is installed and running - ENDPOINT with the s3 endpoint - REGION with the region where the bucket exists - BUCKET with the name of the object storage bucket where backups should be stored - ACCESS_KEY_ID with the access key id to use for accessing the bucket - SECRET_ACCESS_KEY with the secret access key to use for accessing the bucket **Example:** ``` kubectl kots velero configure-other-s3 \ --namespace default \ --endpoint http://minio \ --region minio \ --bucket kots-snaps \ --access-key-id XXXXXXXJTJB7M2XZUV7D \ --secret-access-key mysecretkey ``` If no Velero installation is detected, instructions are displayed to install Velero and configure the storage destination. ## Configure s3-compatible storage for air-gapped environments > Introduced in Replicated KOTS v1.94.0 The following S3-compatible object stores are supported for storing backups with Velero: - Ceph RADOS v12.2.7 - MinIO Run the following command to install Velero and configure an S3-compatible storage destination in an air-gapped environment. For more information about required storage destination flags, see [`velero`](/reference/kots-cli-velero-index) in _Reference_. ```bash kubectl kots velero configure-other-s3 \ --namespace NAME \ --endpoint ENDPOINT \ --region REGION \ --bucket BUCKET \ --access-key-id ACCESS_KEY_ID \ --secret-access-key SECRET_ACCESS_KEY \ --kotsadm-registry REGISTRY_HOSTNAME[/REGISTRY_NAMESPACE] \ --registry-username REGISTRY_USERNAME \ --registry-password REGISTRY_PASSWORD ``` Replace: - `NAME` with the name of the namespace where the Admin Console is installed and running - `ENDPOINT` with the s3 endpoint - `REGION` with the region where the bucket exists - `BUCKET` with the name of the object storage bucket where backups should be stored - `ACCESS_KEY_ID` with the access key id to use for accessing the bucket - `SECRET_ACCESS_KEY` with the secret access key to use for accessing the bucket - `REGISTRY_HOSTNAME` with the registry endpoint where the images are hosted - `REGISTRY_NAMESPACE` with the registry namespace where the images are hosted (Optional) - `REGISTRY_USERNAME` with the username to use to authenticate with the registry - `REGISTRY_PASSWORD` with the password to use to authenticate with the registry If no Velero installation is detected, instructions are displayed to install Velero and configure the storage destination. :::note It is typical for the velero and node-agent Pods to be in the `ErrImagePull` or `ImagePullBackOff` state after you run the `velero install` command because Velero does not support passing registry credentials during installation. In Replicated KOTS v1.94.0 and later, this situation resolves itself after you complete the instructions to configure the storage destination. If you are on an earlier version of KOTS, Replicated recommends that you upgrade to KOTS v1.94.0 or later. Otherwise, you must patch the Velero deployment manually and add the image pull secret to access the registry. ::: ## Next steps * (Existing Clusters Only) Configure Velero namespace access if you are using minimal RBAC. See [Configure Namespace Access and Memory Limit](snapshots-velero-installing-config). * (Optional) Increase the default memory limits. See [Configure Namespace Access and Memory Limit](snapshots-velero-installing-config). * Create or schedule backups. See [Create and Schedule Backups](snapshots-creating). ## Additional resources * [Troubleshoot Snapshots](snapshots-troubleshooting-backup-restore) --- # Troubleshoot snapshots When a snapshot fails, KOTS automatically collects and stores a support bundle. This bundle contains all logs and system state at the time of the failure. It is a good place to view the logs. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Velero is crashing If Velero is crashing and not starting, some common causes are: ### Invalid cloud credentials #### Symptom You see the following error message from Velero when trying to configure a snapshot. ```shell time="2020-04-10T14:22:24Z" level=info msg="Checking existence of namespace" logSource="pkg/cmd/server/server.go:337" namespace=velero time="2020-04-10T14:22:24Z" level=info msg="Namespace exists" logSource="pkg/cmd/server/server.go:343" namespace=velero time="2020-04-10T14:22:27Z" level=info msg="Checking existence of Velero custom resource definitions" logSource="pkg/cmd/server/server.go:372" time="2020-04-10T14:22:31Z" level=info msg="All Velero custom resource definitions exist" logSource="pkg/cmd/server/server.go:406" time="2020-04-10T14:22:31Z" level=info msg="Checking that all backup storage locations are valid" logSource="pkg/cmd/server/server.go:413" An error occurred: some backup storage locations are invalid: backup store for location "default" is invalid: rpc error: code = Unknown desc = NoSuchBucket: The specified bucket does not exist status code: 404, request id: BEFAE2B9B05A2DCF, host id: YdlejsorQrn667ziO6Xr6gzwKJJ3jpZzZBMwwMIMpWj18Phfii6Za+dQ4AgfzRcxavQXYcgxRJI= ``` #### Cause If the cloud access credentials are invalid or do not have access to the location in the configuration, Velero will crashloop. The support bundle includes the Velero logs, and the message looks like this. #### Solution Replicated recommends that you validate the access key / secret or service account json. ### Invalid top-level directories #### Symptom You see the following error message when Velero is starting: ```shell time="2020-04-10T14:12:42Z" level=info msg="Checking existence of namespace" logSource="pkg/cmd/server/server.go:337" namespace=velero time="2020-04-10T14:12:42Z" level=info msg="Namespace exists" logSource="pkg/cmd/server/server.go:343" namespace=velero time="2020-04-10T14:12:44Z" level=info msg="Checking existence of Velero custom resource definitions" logSource="pkg/cmd/server/server.go:372" time="2020-04-10T14:12:44Z" level=info msg="All Velero custom resource definitions exist" logSource="pkg/cmd/server/server.go:406" time="2020-04-10T14:12:44Z" level=info msg="Checking that all backup storage locations are valid" logSource="pkg/cmd/server/server.go:413" An error occurred: some backup storage locations are invalid: backup store for location "default" is invalid: Backup store contains invalid top-level directories: [other-directory] ``` #### Cause Velero displays this error message when it attempts to start and uses a reconfigured or re-used bucket. When configuring Velero to use a bucket, the bucket cannot contain other data, or Velero will crash. #### Solution Configure Velero to use a bucket that does not contain other data. ## Node agent is crashing If the node-agent Pod is crashing and not starting, some common causes are: ### Metrics server is failing to start #### Symptom You see the following error in the node-agent logs. ```shell time="2023-11-16T21:29:44Z" level=info msg="Starting metric server for node agent at address []" logSource="pkg/cmd/cli/nodeagent/server.go:229" time="2023-11-16T21:29:44Z" level=fatal msg="Failed to start metric server for node agent at []: listen tcp :80: bind: permission denied" logSource="pkg/cmd/cli/nodeagent/server.go:236" ``` #### Cause This issue occurs in Velero 1.12.0 and 1.12.1. Velero does not set the port correctly when starting the metrics server. The metrics server fails to start with a `permission denied` error. The error occurs in environments that do not run MinIO and have Host Path, Network File System (NFS), or internal storage destinations configured. When the metrics server fails to start, the node-agent Pod crashes. For more information about this issue, see [the GitHub issue details](https://github.com/vmware-tanzu/velero/issues/6792). #### Solution Replicated recommends that you either upgrade to Velero 1.12.2 or later, or downgrade to a version earlier than 1.12.0. ## Snapshot creation is failing ### Timeout error when creating a snapshot #### Symptom You see a backup error that includes a timeout message when attempting to create a snapshot. For example: ```bash Error backing up item timed out after 12h0m0s ``` #### Cause This error message appears when the node-agent Pod operation reaches the timeout limit. The default timeout is 240 minutes. For Velero 1.16 and earlier, Velero integrates with Restic to provide a solution for backing up and restoring Kubernetes volumes. For more information, see [File System Backup](https://velero.io/docs/v1.10/file-system-backup/) in the Velero documentation. For Velero 1.17 and later, Velero uses Kopia for file-system backups by default. #### Solution Use the kubectl Kubernetes command-line tool to patch the Velero deployment to increase the timeout: **Velero 1.17 and later**: ```bash kubectl patch deployment velero -n velero --type json -p '[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--fs-backup-timeout=TIMEOUT_LIMIT"}]' ``` **Velero 1.16 and earlier**: ```bash kubectl patch deployment velero -n velero --type json -p '[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--restic-timeout=TIMEOUT_LIMIT"}]' ``` Replace `TIMEOUT_LIMIT` with a length of time for the node-agent Pod operation timeout in hours, minutes, and seconds. Use the format `0h0m0s`. For example, `48h30m0s`. :::note The timeout value reverts back to the default value if you rerun the `velero install` command. ::: ### Memory limit reached on the node-agent pod #### Symptom The Linux kernel Out Of Memory (OOM) killer kills the node-agent Pod, or snapshots fail with errors similar to: ``` pod volume backup failed: ... signal: killed ``` #### Cause Velero sets default limits for the velero Pod and the node-agent Pod during installation. For Velero 1.16 and earlier, a known Restic issue causes high memory usage. This high memory usage can cause failures during snapshot creation when the Pod reaches the memory limit. For Velero 1.17 and later, Velero uses Kopia for file-system backups by default. Large volumes with Kopia can also require a higher memory limit. For more information about the Restic issue, see the [Restic backup — OOM-killed on raspberry pi after backing up another computer to same repo](https://github.com/restic/restic/issues/1988) issue in the Restic GitHub repository. #### Solution Increase the default memory limit for the node-agent Pod if your application is particularly large. For more information about configuring Velero resource requests and limits, see [Customize resource requests and limits](https://velero.io/docs/v1.17/customize-installation/#customize-resource-requests-and-limits) in the Velero documentation. For example, the following kubectl command increases the memory limit for the node-agent DaemonSet from the default of 1Gi to 2Gi: ``` kubectl -n velero patch daemonset node-agent -p '{"spec":{"template":{"spec":{"containers":[{"name":"node-agent","resources":{"limits":{"memory":"2Gi"}}}]}}}}' ``` Alternatively, you can lower the memory garbage collection target percentage on the node-agent DaemonSet. This can help the node-agent Pod avoid reaching the memory limit during snapshot creation. Run the following kubectl command: ``` kubectl -n velero set env daemonset/node-agent GOGC=1 ``` ### Velero cannot read at least one source file #### Symptom You see the following error in Velero logs: ``` Error backing up item...Warning: at least one source file could not be read ``` #### Cause For Velero 1.16 and earlier, there are file changes between Restic's initial scan of the volume and during the backup to the Restic store. #### Solution To resolve this issue, do one of the following: * Use [hooks](/vendor/snapshots-hooks) to export data to an [EmptyDir](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir) volume and include that in the backup instead of the primary PVC volume. See [Configure Backup and Restore Hooks for Snapshots](/vendor/snapshots-hooks). * Freeze the file system to ensure all pending disk I/O operations have completed prior to taking a snapshot. For more information, see [Hook Example with fsfreeze](https://velero.io/docs/main/backup-hooks/#hook-example-with-fsfreeze) in the Velero documentation. ## Kopia file-system backup issues (Velero 1.17 and later) ### Data mover pods do not start or complete #### Cause For Velero 1.17 and later, Kopia spawns data mover pods from the node-agent. If a backup or restore stays in progress, the data mover pods might not start or complete. #### Solution Check the node-agent logs for errors that prevent data mover pods from starting. Verify that the cluster can pull the data mover pod image and that any pod security policies or security context constraints allow the pod to start. ### BackupRepository is not available #### Cause For Velero 1.17 and later, Kopia uses `BackupRepository` custom resources (CRs) to manage repositories. A backup or restore can fail if the `BackupRepository` CR is not available or is in a failed state. #### Solution Check the status of the `BackupRepository` CRs: ```bash kubectl get backuprepositories -n velero ``` Describe any CR that is not in a Ready state to view the error: ```bash kubectl describe backuprepository BACKUP_REPOSITORY_NAME -n velero ``` Common errors include invalid credentials, network connectivity issues, or problems with the underlying storage. After you resolve the issue, Velero retries the backup repository operations. ### Read-only root filesystem errors #### Cause For Velero 1.17 and later, Kopia needs writable directories for cache and configuration. The default paths are `/home/cnb/udmrepo` and `/home/cnb/.cache`. If `ReadOnlyRootFilesystem` applies to the Velero or node-agent pods, Kopia cannot write to these directories and the backup or restore fails. #### Solution Add `emptyDir` volumes for `/home/cnb/udmrepo` and `/home/cnb/.cache` to the Velero deployment and the node-agent daemon set. Mount the volumes at the required paths so Kopia can write cache and configuration data. ### LVP storage location is unavailable after upgrade #### Cause The Local Volume Provider (LVP) is not compatible with Kopia. If you upgrade to Velero 1.17 or later and the existing storage location uses LVP, snapshots fail because Kopia cannot write to LVP storage. :::important LVP backups created on Velero 1.16 and earlier are not restorable on Velero 1.17 and later. Before you upgrade, migrate to a Kopia-compatible storage destination. For more information, see [Upgrade Velero for snapshots](snapshots-velero-upgrading). ::: #### Solution Before you upgrade to Velero 1.17 or later, migrate from LVP to a Kopia-compatible destination. Replicated recommends one of the following options: * Reinstall KOTS with `--with-minio=true`. * Reconfigure the storage location to use an external S3-compatible object store, such as Amazon S3, Google Cloud Storage, Azure Blob Storage, or another S3-compatible provider. Install the target Velero plugin before you reconfigure the storage location. For more information, see [Upgrade Velero for snapshots](snapshots-velero-upgrading). ## Snapshot restore is failing ### Service NodePort is already allocated #### Symptom In the Replicated KOTS Admin Console, you see an **Application failed to restore** error. The error indicates that the port number for a static NodePort is already in use. For example: ![Snapshot Troubleshoot Service NodePort](/images/snapshot-troubleshoot-service-nodeport.png) [View a larger version of this image](/images/snapshot-troubleshoot-service-nodeport.png) #### Cause A known issue in Kubernetes versions earlier than version 1.19 can cause static NodePort services to collide in multi-primary high availability setups. This collision occurs when recreating the services. For more information about this known issue, see https://github.com/kubernetes/kubernetes/issues/85894. #### Solution Kubernetes version 1.19 fixes this issue. To resolve this issue, upgrade to Kubernetes version 1.19 or later. For more information about the fix, see https://github.com/kubernetes/kubernetes/pull/89937. ### Partial snapshot restore finishes with warnings #### Symptom In the Admin Console, when the partial snapshot restore completes, you see warnings indicating that Velero did not restore Endpoint resources: ![Snapshot Troubleshoot Restore Warnings](/images/snapshot-troubleshoot-restore-warnings.png) #### Cause Velero changed the resource restore priority in 1.10.3 and 1.11.0, which leads to this warning when restoring Endpoint resources. For more information about this issue, see [the issue details](https://github.com/vmware-tanzu/velero/issues/6280) in GitHub. #### Solution These warnings do not necessarily mean that the restore itself failed. The endpoints likely exist because Kubernetes creates them when the restore process restores the related Service resources. However, to prevent encountering these warnings, use Velero version 1.11.1 or later. --- # Deleted snapshots do not reclaim disk space on host path storage This topic describes why deleted snapshots might not reclaim disk space on embedded kURL clusters. It also explains how to reclaim the space manually. The issue applies to clusters that use Host Path storage with the Velero Restic uploader. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Symptom On an embedded kURL cluster that uses Host Path storage with the Velero Restic uploader, disk space is not reclaimed after you delete snapshots. You can delete snapshots from the Admin Console or with the KOTS CLI. The disk continues to fill even though only the retained backups appear in `velero get backup`. ## Cause Velero's repository maintenance job runs a `restic prune` operation. The prune removes data that is no longer referenced from the Restic repository. This frees the disk space that deleted or expired snapshots used. On Velero versions earlier than 1.17.0, the repository maintenance job does not inherit the Velero Pod security context. The job runs as a different user than the node-agent Pod that created the Restic repository files on the Host Path store. The Restic files belong to UID 1001 with mode 0700. The maintenance job receives a `permission denied` error when it tries to read the repository. The prune operation then fails. Because the prune fails, data from deleted or expired snapshots is never reclaimed. The backup disk grows without bound. For example, the maintenance Pod logs show an error similar to the following: ``` restic prune --repo=.../restic/default ... Fatal: unable to open repository at .../restic/default: ReadDir: open .../restic/default/keys: permission denied ``` Velero 1.17.0 and later include the upstream fix. The fix copies the security context from the origin Pod to the maintenance job. The automated prune operation can then read the repository files and reclaim disk space. For more information, see [Copy security context from origin pod](https://github.com/vmware-tanzu/velero/pull/8943) in the Velero repository. ## Solution The solution depends on the Velero version. ### Velero 1.17.0 and later Upgrade to Velero 1.17.0 or later. The automated Restic repository maintenance job can then read the repository files and reclaim disk space. After the upgrade, you can adjust the maintenance frequency with the `--default-repo-maintain-frequency` Velero server flag. For example: ```bash kubectl patch deployment velero -n velero --type json -p '[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--default-repo-maintain-frequency=48h0m0s"}]' ``` Replace `48h0m0s` with the desired frequency. Velero uses the default value if you do not set the flag. :::note The `--default-restic-prune-frequency` flag was the previous name for this flag. Velero removed `--default-restic-prune-frequency` in version 1.10.0. It renamed the flag to `--default-repo-maintain-frequency`. On Velero 1.10.0 and later, `--default-restic-prune-frequency` is not a recognized flag and has no effect. For more information, see the [Velero 1.10 breaking changes](https://github.com/vmware-tanzu/velero/blob/main/changelogs/CHANGELOG-1.10.md#breaking-changes). ::: For more information about file-system backups, see [File System Backup](https://velero.io/docs/v1.17/file-system-backup/) in the Velero documentation. ### Velero 1.16.x and earlier On Velero versions earlier than 1.17.0, the automated prune fails regardless of the maintenance frequency. Tuning the frequency does not help. To reclaim disk space until you can upgrade to Velero 1.17.0 or later, run `restic prune` manually from inside the Velero Pod. The Velero Pod runs as the correct user (UID 1001), so the prune operation can read the repository files. Run the following commands to prune both the `default` and `kurl` Restic repositories: ```bash PREFIX=$(kubectl -n velero get bsl default -o jsonpath='{.spec.config.resticRepoPrefix}') kubectl -n velero get secret velero-repo-credentials -o jsonpath='{.data.repository-password}' | base64 -d \ | kubectl -n velero exec -i deploy/velero -c velero -- \ restic -r "$PREFIX/default" --cache-dir=/scratch/.cache/restic --password-file=/dev/stdin prune kubectl -n velero get secret velero-repo-credentials -o jsonpath='{.data.repository-password}' | base64 -d \ | kubectl -n velero exec -i deploy/velero -c velero -- \ restic -r "$PREFIX/kurl" --cache-dir=/scratch/.cache/restic --password-file=/dev/stdin prune ``` For more information about upgrading Velero, see [Upgrade Velero for snapshots](/enterprise/snapshots-velero-upgrading). ## Additional resources - [Velero Version Compatibility](/vendor/snapshots-overview#velero-version-compatibility) - [Troubleshoot Snapshots](/enterprise/snapshots-troubleshooting-backup-restore) - [Upgrade Velero for snapshots](/enterprise/snapshots-velero-upgrading) - [Configure a Host Path Storage Destination](/enterprise/snapshots-configuring-hostpath) --- # Update storage settings This topic describes how to update existing storage destination settings using the Replicated Admin Console. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Prerequisite If you are changing from one provider to another provider, make sure that you meet the prerequisites for the storage destination. For information about prerequisites, see: - [Configure a Host Path Storage Destination](snapshots-configuring-hostpath) - [Configure an NFS Storage Destination](snapshots-configuring-nfs) - [Configure Other Storage Destinations](snapshots-storage-destinations) ## Update storage settings You can update storage destination settings for online and air gapped environments at any time using the Admin Console. Additionally, if Velero was automatically installed by Replicated kURL, then Replicated recommends that you change the default internal storage because it is not sufficient for disaster recovery. To update storage destination settings: 1. In the Admin Console, select **Snapshots** > **Settings and Schedule**. 1. Under storage, you can edit the existing settings or click **Add a new storage destination** and select a storage destination type. ![Snapshot Destination Dropdown Host Path](/images/snapshot-destination-dropdown-hostpath.png) The configuration fields that display depend on the type of storage destination. See the following storage destination sections for field descriptions: - [AWS](#aws-fields) - [GCP](#gcp-fields) - [Azure](#azure-fields) - [S3-compatible](#s3-compatible-fields) - [NFS](#nfs-fields) - [Host Path](#host-path-fields) 1. Click **Update storage settings**. The update can take several minutes. ### AWS fields When configuring the Admin Console to store backups on Amazon Web Services (AWS), the following fields are available: | Name | Description | |------------------------------|-----------------------------------------------------------------------------------------------------------------| | Region | The AWS region that the S3 bucket is available in | | Bucket | The name of the S3 bucket to use | | Path (Optional) | The path in the bucket to store all backups in | | Access Key ID (Optional) | The AWS IAM Access Key ID that can read from and write to the bucket | | Secret Access Key (Optional) | The AWS IAM Secret Access Key that is associated with the Access Key ID | | Use Instance Role | When enabled, instead of providing an Access Key ID and Secret Access Key, Velero will use an instance IAM role | | Add a CA Certificate | (Optional) Upload a third-party issued (proxy) CA certificate used for trusting the authenticity of the snapshot storage endpoint. Only one file can be uploaded. However, it is possible to concatenate multiple certificates into one file. **Formats:** PEM, CER, CRT, CA, and KEY | ### GCP fields When configuring the Admin Console to store backups on Google Cloud Provide (GCP), the following fields are available: | Name | Description | |-----------------|-----------------------------------------------------------------------------------------------------------| | Bucket | The name of the GCP storage bucket to use | | Path (Optional) | The path in the bucket to store all backups in | | Service Account | The GCP IAM Service Account JSON file that has permissions to read from and write to the storage location | | Add a CA Certificate | (Optional) Upload a third-party issued (proxy) CA certificate used for trusting the authenticity of the snapshot storage endpoint. Only one file can be uploaded. However, it is possible to concatenate multiple certificates into one file. **Formats:** PEM, CER, CRT, CA, and KEY | ### Azure fields When configuring the Admin Console to store backups on Microsoft Azure, the following fields are available: | Name | Description | |----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| | Bucket | The name of the Azure Blob Storage Container to use | | Path (Optional) | The path in the Blob Storage Container to store all backups in | | Resource Group | The Resource Group name of the target Blob Storage Container | | Storage Account | The Storage Account Name of the target Blob Storage Container | | Subscription ID | The Subscription ID associated with the target Blob Storage Container (required only for access via Service Principle or AAD Pod Identity) | | Tenant ID | The Tenant ID associated with the Azure account of the target Blob Storage container (required only for access via Service Principle) | | Client ID | The Client ID of a Service Principle with access to the target Container (required only for access via Service Principle) | | Client Secret | The Client Secret of a Service Principle with access to the target Container (required only for access via Service Principle) | | Cloud Name | The Azure cloud for the target storage (options: AzurePublicCloud, AzureUSGovernmentCloud, AzureChinaCloud, AzureGermanCloud) | | Add a CA Certificate | (Optional) Upload a third-party issued (proxy) CA certificate used for trusting the authenticity of the snapshot storage endpoint. Only one file can be uploaded. However, it is possible to concatenate multiple certificates into one file. **Formats:** PEM, CER, CRT, CA, and KEY | Only connections with Service Principles are supported at this time. For more information about authentication methods and setting up Azure, see [Velero plugins for Microsoft Azure](https://github.com/vmware-tanzu/velero-plugin-for-microsoft-azure) in the velero-plugin-for-microsoft-azure GitHub repository. ### S3-compatible fields Replicated supports the following S3-compatible object stores for storing backups with Velero: * Ceph RADOS v12.2.7. For more information, see the [Ceph](https://docs.ceph.com/en/quincy/) documentation. * MinIO. For more information, see the [MinIO](https://docs.min.io/docs/minio-quickstart-guide.html) documentation. When configuring the Admin Console to store backups on S3-compatible storage, the following fields are available: | Name | Description | |------------------------------|-----------------------------------------------------------------------------------------------------------------| | Region | The AWS region that the S3 bucket is available in | | Endpoint | The endpoint to use to connect to the bucket | | Bucket | The name of the S3 bucket to use | | Path (Optional) | The path in the bucket to store all backups in | | Access Key ID (Optional) | The AWS IAM Access Key ID that can read from and write to the bucket | | Secret Access Key (Optional) | The AWS IAM Secret Access Key that is associated with the Access Key ID | | Use Instance Role | When enabled, instead of providing an Access Key ID and Secret Access Key, Velero will use an instance IAM role | | Add a CA Certificate | (Optional) Upload a third-party issued (proxy) CA certificate used for trusting the authenticity of the snapshot storage endpoint. Only one file can be uploaded. However, it is possible to concatenate multiple certificates into one file. **Formats:** PEM, CER, CRT, CA, and KEY | ### NFS fields When configuring the Admin Console to store backups on network file system (NFS) storage, the following fields are available: | Name | Description | |--------|----------------------------------------------| | Server | The hostname or IP address of the NFS server | | Path | The path that is exported by the NFS server | ### Host path fields When configuring the Admin Console to store backups on host path storage, the following fields are available: **Host path**: Enter the path to the directory on the node. Although the path can be local, Replicated recommends that you use an external host path. --- # Install the Velero CLI You install the Velero CLI before installing Velero and configuring a storage destination for backups. :::note For embedded clusters created with Replicated kURL, check whether the kURL Installer spec included the Velero add-on. If so, the kURL installer automatically installed Velero with default internal storage. Replicated recommends that you change the default internal storage because it is insufficient for disaster recovery. See [Updating Storage Settings in the Admin Console](snapshots-updating-with-admin-console). ::: :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: :::note Velero 1.17 and later uses Kopia as the default file-system backup uploader. For more information, see [Velero Version Compatibility](/vendor/snapshots-overview#velero-version-compatibility). ::: ## Install the Velero CLI in an online cluster To install the Velero CLI in an online cluster: 1. Do one of the following: - (Embedded kURL cluster) Run an SSH command to access and authenticate to your cluster node. - (Existing cluster) Open a terminal in the environment that you manage the cluster from, which can be a local machine that has kubectl installed. 1. Check for the latest supported release of the Velero CLI for **Linux AMD64** in the Velero GitHub repo at https://github.com/vmware-tanzu/velero/releases. Although Replicated supports earlier versions of Velero, Replicated recommends using the latest supported version. For more information about supported versions, see [Velero Version Compatibility](/vendor/snapshots-overview#velero-version-compatibility). Note the version number for the next step. 1. Run the following command to download the latest supported Velero CLI version for the **Linux AMD64** operating system to the cluster: ``` curl -LO https://github.com/vmware-tanzu/velero/releases/download/VERSION/velero-VERSION-linux-amd64.tar.gz ``` Replace VERSION with the version number using the format `vx.x.x` **Example:** ``` curl -LO https://github.com/vmware-tanzu/velero/releases/download/v1.18.2/velero-v1.18.2-linux-amd64.tar.gz ``` 1. Run the following command to extract the TAR file: ``` tar zxvf velero-VERSION-linuxamd64.tar.gz ``` Replace VERSION with the version number using the format `vx.x.x`. 1. Run the following command to install the Velero CLI: ``` sudo mv velero-VERSION-linux-amd64/velero /usr/local/bin/velero ``` Replace VERSION with the version number using the format `vx.x.x`. 1. Run `velero version` to test that the Velero CLI installation worked correctly. You might get an error message stating that there are no matches for the server version. This is acceptable, as long as you get a confirmation for the client version. After the Velero installation, you also see the server version. ## Install the Velero CLI in an air-gapped cluster To install the Velero CLI in an air-gapped cluster: 1. From a computer with internet access, check for the latest supported release of the Velero CLI for **Linux AMD64** in the Velero GitHub repo at https://github.com/vmware-tanzu/velero/releases. Although Replicated supports earlier versions of Velero, Replicated recommends using the latest supported version. See [Velero Version Compatibility](/vendor/snapshots-overview#velero-version-compatibility). Note the version number for the next step. 1. Run the following command to download the latest supported Velero CLI version for the **Linux AMD64** operating system to the cluster: ``` curl -LO https://github.com/vmware-tanzu/velero/releases/download/VERSION/velero-VERSION-linux-amd64.tar.gz ``` Replace VERSION with the version number using the format `vx.x.x` **Example:** ``` curl -LO https://github.com/vmware-tanzu/velero/releases/download/v1.18.2/velero-v1.18.2-linux-amd64.tar.gz ``` 1. Copy the TAR file to the air-gapped node. 1. Run the following command to extract the TAR file: ``` tar zxvf velero-VERSION-linuxamd64.tar.gz ``` Replace VERSION with the version number using the format `vx.x.x`. 1. Run the following command to install the Velero CLI: ``` sudo mv velero-VERSION-linux-amd64/velero /usr/local/bin/velero ``` Replace VERSION with the version number using the format `vx.x.x`. 1. Run `velero version` to test that the Velero CLI installation worked correctly. You might get an error message stating that there are no matches for the server version. This is acceptable, as long as you get a confirmation for the client version. After the Velero installation, you should see the server version also. ## Next step Install Velero and configure a storage destination using one of the following procedures: - [Configuring a Host Path Storage Destination](snapshots-configuring-hostpath) - [Configuring an NFS Storage Destination](snapshots-configuring-nfs) - [Configuring Other Storage Destinations](snapshots-storage-destinations) --- # Configure namespace access and memory limit This topic describes how to configure namespace access and the memory limit for Velero. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview The Replicated KOTS Admin Console requires access to the namespace where Velero runs. If your Admin Console is running with minimal role-based-access-control (RBAC) privileges, you must enable the Admin Console to access Velero. Additionally, if the application uses a large amount of memory, you can configure the default memory limit to help ensure that Velero runs successfully with snapshots. ## Configure namespace access This section applies only to _existing cluster_ installations (online and air gap) where the Admin Console is running with minimal role-based-access-control (RBAC) privileges. Run the following command to enable the Admin Console to access the Velero namespace: ``` kubectl kots velero ensure-permissions --namespace ADMIN_CONSOLE_NAMESPACE --velero-namespace VELERO_NAMESPACE ``` Replace: * `ADMIN_CONSOLE_NAMESPACE` with the namespace on the cluster where the Admin Console is running. * `VELERO_NAMESPACE` with the namespace on the cluster where Velero runs. For more information, see [`velero ensure-permissions`](/reference/kots-cli-velero-ensure-permissions/) in the KOTS CLI documentation. For more information about RBAC privileges for the Admin Console, see [Kubernetes RBAC](/vendor/packaging-rbac). ## Configure memory limit This section applies to all online and air gap installations. Velero sets default limits for the velero Pod and the node-agent Pod during installation. There is a known issue with the file-system backup uploader. High memory usage from this issue can cause failures during backup creation when the Pod reaches the memory limit. Increase the default memory limit for the node-agent Pod if your application is particularly large. For more information about configuring Velero resource requests and limits, see [Customize resource requests and limits](https://velero.io/docs/v1.17/customize-installation/#customize-resource-requests-and-limits) in the Velero documentation. For example, the following kubectl command increases the memory limit for the node-agent DaemonSet from the default of 1Gi to 2Gi: ``` kubectl -n velero patch daemonset node-agent -p '{"spec":{"template":{"spec":{"containers":[{"name":"node-agent","resources":{"limits":{"memory":"2Gi"}}}]}}}}' ``` Alternatively, you can lower the memory garbage collection target percentage on the node-agent DaemonSet. This can help the node-agent Pod avoid reaching the memory limit during snapshot creation. Run the following kubectl command: ``` kubectl -n velero set env daemonset/node-agent GOGC=1 ``` ## Additional resources * [Troubleshooting Snapshots](snapshots-troubleshooting-backup-restore) --- # Upgrade Velero for snapshots This topic describes how to upgrade Velero for Replicated snapshots. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview Velero 1.17 and later uses Kopia as the default uploader for file-system backups. If you upgrade from Velero 1.16 or earlier, verify that your storage destination is compatible with Kopia before you upgrade. Some storage destinations, such as the Local Volume Provider (LVP), are not compatible with Kopia. Migrate these destinations before the upgrade. For more information about snapshot troubleshooting, see [Troubleshoot Snapshots](snapshots-troubleshooting-backup-restore). ## Before you upgrade Complete the following prerequisites before you upgrade Velero: 1. Check the current storage destination type. If the storage location uses LVP, migrate to a Kopia-compatible destination before you upgrade. For more information, see [Migrate from Local Volume Provider (LVP) to a Kopia-compatible destination](#migrate-from-local-volume-provider-lvp-to-a-kopia-compatible-destination). 1. Take a snapshot of the application before you upgrade. This snapshot lets you restore the application if the upgrade fails. 1. Install the Velero plugin for the target storage destination, if needed. For example, verify that the plugin image is available in the registry for air-gapped environments. For more information, see [Configure Other Storage Destinations](snapshots-storage-destinations). ## Migrate from local volume provider (LVP) to a Kopia-compatible destination LVP is not compatible with Kopia. If the storage location uses LVP, migrate to a Kopia-compatible destination before you upgrade to Velero 1.17 or later. :::important LVP backups created on Velero 1.16 and earlier are not restorable on Velero 1.17 and later. Replicated recommends that you migrate to a Kopia-compatible destination before you upgrade. ::: In-place reconfiguration from LVP to a filesystem-based Minio deployment is not supported. The `minio-enabled-snapshots=false` setting persists, so reconfiguring to filesystem Minio in the Admin Console does not enable a Kopia-compatible object store. Replicated recommends one of the following options: * Reinstall KOTS with `--with-minio=true`. This installs a Minio object store that is compatible with Kopia. * Reconfigure the storage location to use an external S3-compatible object store, such as Amazon S3, Google Cloud Storage, Azure Blob Storage, or another S3-compatible provider. Install the target Velero plugin before you reconfigure the storage location. For more information, see [Configure Other Storage Destinations](snapshots-storage-destinations). For more information about LVP storage issues after upgrade, see [LVP storage location is unavailable after upgrade](snapshots-troubleshooting-backup-restore#lvp-storage-location-is-unavailable-after-upgrade) in _Troubleshoot Snapshots_. ## Upgrade one version at a time Replicated recommends that you upgrade Velero one version at a time. For example, if you are running Velero 1.15, upgrade to Velero 1.16 first, verify that snapshots work, and then upgrade to Velero 1.17. Upgrading incrementally reduces the risk of incompatible custom resources or storage locations. To upgrade Velero, follow the upgrade instructions for the target Velero version in the [Velero documentation](https://velero.io/docs/). KOTS does not provide an Admin Console button or a KOTS CLI command to upgrade Velero. The cluster administrator performs the upgrade manually. ## Verify the upgrade After you upgrade Velero, verify that the upgrade is successful: 1. Run `velero version` to confirm the expected Velero version. 1. Check the status of the `BackupStorageLocation`: ```bash velero backup-location get ``` The BackupStorageLocation must be in an `Available` state before you create backups. If it is not available, describe the BackupStorageLocation to view the error: ```bash kubectl describe backupstoragelocation -n velero ``` 1. Check the status of the `BackupRepository` CRs: ```bash kubectl get backuprepositories -n velero ``` All `BackupRepository` CRs must be in a `Ready` state before you create backups. If a CR is not ready, describe the CR to view the error: ```bash kubectl describe backuprepository -n velero ``` 1. Create a test backup and verify that it completes successfully. For more information, see [Create and Schedule Backups](snapshots-creating). ## Restore existing Restic backups Velero 1.17 and 1.18 can restore Restic backups created on Velero 1.16 and earlier. To restore an existing Restic backup, use the same storage location and credentials that you used to create the backup. ## Additional resources * [Troubleshoot Snapshots](snapshots-troubleshooting-backup-restore) * [Configure Other Storage Destinations](snapshots-storage-destinations) * [Configure a Host Path Storage Destination](snapshots-configuring-hostpath) * [Configure an NFS Storage Destination](snapshots-configuring-nfs) * [Configure Namespace Access and Memory Limit](snapshots-velero-installing-config) * [Create and Schedule Backups](snapshots-creating) * [Update storage settings](snapshots-updating-with-admin-console) --- # Understand application status details in the Admin Console This topic describes how to view the status of an application on the Replicated KOTS Admin Console dashboard. It also describes how Replicated KOTS collects and aggregates the application status. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## View status details The application status displays on the dashboard of the Admin Console. Viewing the status details can be helpful for troubleshooting. To view the status details, click **Details** next to the status on the dashboard. ![Status Details](/images/kotsadm-dashboard-appstatus.png) ## About application status To display application status on the Admin Console dashboard, KOTS aggregates the status of specific Kubernetes resources for the application. The following resource types are supported for displaying application status: * Deployment * StatefulSet * Service * Ingress * PersistentVolumeClaims (PVC) * DaemonSet Applications can specify one or more of the supported Kubernetes workloads listed above. KOTS watches all specified workloads for state changes. For more information about how to interpret the application status displayed on the Admin Console dashboard, see [Resource Statuses](#resource-statuses) and [Aggregate Application Status](#aggregate-application-status) below. ### Resource statuses Possible application statuses are Ready, Updating, Degraded, Unavailable, and Missing. The following table lists the supported Kubernetes resources and the conditions that contribute to each status:
Deployment StatefulSet Service Ingress PVC DaemonSet
Ready Ready replicas equals desired replicas Ready replicas equals desired replicas All desired endpoints are ready, any load balancers have been assigned All desired backend service endpoints are ready, any load balancers have been assigned Claim is bound Ready daemon pods equals desired scheduled daemon pods
Updating The deployed replicas are from a different revision The deployed replicas are from a different revision N/A N/A N/A The deployed daemon pods are from a different revision
Degraded At least 1 replica is ready, but more are desired At least 1 replica is ready, but more are desired At least one endpoint is ready, but more are desired At least one backend service endpoint is ready, but more are desired N/A At least one daemon pod is ready, but more are desired
Unavailable No replicas are ready No replicas are ready No endpoints are ready, no load balancer has been assigned No backend service endpoints are ready, no load balancer has been assigned Claim is pending or lost No daemon pods are ready
Missing Missing is an initial deployment status indicating that informers have not reported their status because the application has just been deployed and the underlying resource has not been created yet. After the resource is created, the status changes. However, if a resource changes from another status to Missing, then the resource was either deleted or the informers failed to report a status.
### Aggregate application status When you provide more than one Kubernetes resource, Replicated aggregates all resource statuses to display a single application status. Replicated uses the least available resource status to represent the aggregate application status. For example, if at least one resource has an Unavailable status, then the aggregate application status is Unavailable. The following table describes the resource statuses that define each aggregate application status:
Resource Statuses Aggregate Application Status
No status available for any resource Missing
One or more resources Unavailable Unavailable
One or more resources Degraded Degraded
One or more resources Updating Updating
All resources Ready Ready
--- # Generate support bundles from the Admin Console This topic describes how to generate support bundles from the KOTS Admin Console. ## Generate a bundle from the Admin Console The Replicated KOTS Admin Console includes a **Troubleshoot** page where you can generate a support bundle and review remediation suggestions for troubleshooting. You can also download the support bundle from the Admin Console. To generate a support bundle in the KOTS Admin Console: 1. Log in to the Admin Console and go to the **Troubleshoot** tab. 1. Click **Analyze** to start analyzing the application. Or, copy the command provided to generate a bundle from the CLI. The analysis executes the support bundle plugin. After the analysis completes, the bundle is available on the **Troubleshoot** tab in the Admin Console. If any known issues are detected, they are highlighted with possible remediation suggestions. :::note No data leaves the cluster. Data is never sent across the internet or to anyone else. ::: 1. (Optional) If enabled for your online installation, you might also see a **Send bundle to vendor** button available. Clicking this button will send the support bundle directly to your vendor. Replicated recommendeds following up with your vendor to let them know the bundle has been provided. Send bundle to vendor screen [View a larger version of this image](/images/send-bundle-to-vendor.png) 1. (Optional) Click **Download bundle** to download the support bundle. You can send the bundle to your vendor for assistance. --- # Perform updates in existing clusters This topic describes how to perform updates in existing cluster installations with Replicated KOTS. It includes information about how to update applications and the version of KOTS running in the cluster. It also includes information about how the Admin Console determines version precendence. See [How the Admin Console Determines Version Precendence](/enterprise/updating-app-manager#how-the-admin-console-determines-version-precedence). :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Update an application You can perform an application update using the KOTS Admin Console or the KOTS CLI. You can also set up automatic updates. See [Configure Automatic Updates](/enterprise/updating-apps). ### Using the Admin Console #### Online environments To perform an update from the Admin Console: 1. In the Admin Console, go to the **Version History** tab. 1. Click **Check for updates**. A new upstream version displays in the list of available versions. New Version Available [View a larger version of this image](/images/new-version-available.png) 1. (Optional) When there are multiple versions of an application, you can compare the changes between them by clicking **Diff releases** in the right corner. You can review changes between any two arbitrary releases by clicking the icon in the header of the release column. Select the two versions to compare, and click **Diff releases** to show the relative changes between the two releases. Diff Releases [View a larger version of this image](/images/diff-releases.png) New Changes [View a larger version of this image](/images/new-changes.png) 1. (Optional) Click the **View preflight checks** icon to view or re-run the preflight checks. Preflight checks [View a larger version of this image](/images/preflight-checks.png) 1. Return to the **Version History** tab and click **Deploy** next to the target version. #### Air gap environments 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. 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: * 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) 1. 1. 1. In the Admin Console, go to the **Version History** tab. 1. Click **Upload a new version**. A new upstream version displays in the list of available versions. ![New Version Available](/images/new-version-available.png) 1. (Optional) When there are multiple versions of an application, you can compare the changes between them by clicking **Diff releases** in the right corner. You can review changes between any two arbitrary releases by clicking the icon in the header of the release column. Select the two versions to compare, and click **Diff releases** to show the relative changes between the two releases. ![Diff Releases](/images/diff-releases.png) ![New Changes](/images/new-changes.png) 1. (Optional) Click the **View preflight checks** icon to view or re-run the preflight checks. ![Preflight Checks](/images/preflight-checks.png) 1. Return to the **Version History** tab and click **Deploy** next to the target version. ### Using the KOTS CLI You can use the KOTS CLI [upstream upgrade](/reference/kots-cli-upstream-upgrade) command to update an application in existing cluster installations. #### Online environments To update an application in online environments: ```bash kubectl kots upstream upgrade APP_SLUG -n ADMIN_CONSOLE_NAMESPACE ``` Where: * `APP_SLUG` is the unique slug for the application. See [Get the Application Slug](/vendor/vendor-portal-manage-app#slug) in _Managing Applications_. * `ADMIN_CONSOLE_NAMESPACE` is the namespace where the Admin Console is running. :::note Add the `--deploy` flag to automatically deploy this version. ::: #### Air gap environments To update an application in air gap environments: 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: * 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) 1. 1. 1. Run the following command to update the application: ```bash kubectl kots upstream upgrade APP_SLUG \ --airgap-bundle NEW_AIRGAP_BUNDLE \ --kotsadm-registry REGISTRY_HOST[/REGISTRY_NAMESPACE] \ --registry-username RO_USERNAME \ --registry-password RO_PASSWORD \ -n ADMIN_CONSOLE_NAMESPACE ``` 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. * `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. * `ADMIN_CONSOLE_NAMESPACE` with the namespace where the Admin Console is running. :::note Add the `--deploy` flag to automatically deploy this version. ::: ## Update KOTS This section describes how to update the version of Replicated KOTS running in your cluster. For information about the latest versions of KOTS, see [KOTS Release Notes](/release-notes/rn-app-manager). :::note Downgrading KOTS to a version earlier than what is currently deployed is not supported. ::: ### Online environments To update KOTS in an online existing cluster: 1. Run _one_ of the following commands to update the KOTS CLI to the target version of KOTS: - **Install or update to the latest version**: ``` curl https://kots.io/install | bash ``` - **Install or update to a specific version**: ``` curl https://kots.io/install/VERSION | bash ``` Where `VERSION` is the target KOTS version. For more KOTS CLI installation options, including information about how to install or update without root access, see [Install the KOTS CLI](/reference/kots-cli-getting-started). 1. Run the following command to update the KOTS Admin Console to the same version as the KOTS CLI: ```bash kubectl kots admin-console upgrade -n NAMESPACE ``` Replace `NAMESPACE` with the namespace in your cluster where KOTS is installed. ### Air gap environments To update KOTS in an existing air gap cluster: 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 Ensure that you can access the downloaded bundles from the environment where the Admin Console is running. 1. Install or update the KOTS CLI to the version that you downloaded. See [Manually Download and Install](/reference/kots-cli-getting-started#manually-download-and-install) in _Installing the KOTS CLI_. 1. 1. Run the following command using registry read-only credentials to update the KOTS Admin Console: ``` kubectl kots admin-console upgrade \ --kotsadm-registry REGISTRY_HOST \ --registry-username RO_USERNAME \ --registry-password RO_PASSWORD \ -n NAMESPACE ``` Replace: * `REGISTRY_HOST` with the same private registry from the previous step. * `RO_USERNAME` with the username for credentials with read-only permissions to the registry. * `RO_PASSWORD` with the password associated with the username. * `NAMESPACE` with the namespace on your cluster where KOTS is installed. For help information, run `kubectl kots admin-console upgrade -h`. ## How the Admin Console determines version precedence The Admin Console uses version precedence to determine which versions are available for upgrade. Version precedence also determines the order in which versions are displayed on the **Version history** page, as shown in the example below: ![Admin console version history page](/images/new-version-available.png) [View a larger version of this image](/images/new-version-available.png) The Admin Console uses the following logic to determine version precendence: * For channels _without_ semantic versioning (SemVer) enabled, the Admin Console sequences releases by their promotion dates and times. For example, if you promote a release with version label abc at 10:00am, and then promote a release with version label xyz at 10:15am, then version xyz has higher precedence (abc < xyz). * For channels _with_ SemVer enabled, the Admin Console sequences releases by their semantic version. For information about how precedence is determined in SemVer, see [11. Precedence refers to how versions are compared to each other when ordered](https://semver.org/#spec-item-11) in the Semantic Versioning 2.0.0 documentation. The following shows an example of version precendence in SemVer when pre-release fields are used: - 2.13.0 - 2.12.1 - 2.12.0 - 2.12.0-2 - 2.12.0-1 - 2.11.0 :::note Build metadata in the semantic version string is ignored when determining version precedence. For example, the Admin Console interprets 2.12.0, 2.12.0+1, and 2.12.0+2 as the same version. Instead of using build metadata in your semantic version labels, Replicated recommends that you increment the patch version. Or, use pre-release identifiers. For example, 1.0.0-alpha or 1.0.0-1. ::: * For channels with SemVer enabled where there are one or more releases that do _not_ use SemVer, the Admin Console determines precedence based on the semantic version when possible. The release(s) with non-semantic versions stay in the order of their promotion dates. For example, assume that you promote these releases in the following order to a channel without SemVer enabled: - 1.0.0 promoted at 10:00 AM - abc promoted at 10:15 AM - 0.1.0 promoted at 10:30 AM - xyz promoted at 10:45 AM - 2.0.0 promoted at 11:00 AM Then, you enable SemVer on that channel. The Admin Console assigns precedence as follows: 0.1.0 < 1.0.0 < abc < xyz < 2.0.0. --- # Configure automatic updates This topic describes how to configure automatic updates for applications installed in online (internet-connected) environments. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview For applications installed in an online environment, the Replicated KOTS Admin Console automatically checks for new versions once every four hours by default. After the Admin Console checks for updates, it downloads any new versions of the application and displays them on the **Version History** tab. You can edit this default cadence to customize how often the Admin Console checks for and downloads new versions. You can also configure the Admin Console to automatically deploy new versions of the application after it downloads them. The Admin Console only deploys new versions automatically if preflight checks pass. By default, the Admin Console does not automatically deploy any version of an application. ## Limitations Automatic updates have the following limitations: * Automatic updates are not supported for [Replicated Embedded Cluster](/embedded-cluster/v3/embedded-overview) installations. * Automatic updates are not supported for applications installed in air gap environments with no outbound internet access. * Automatically deploying new versions is not supported when KOTS is installed with minimal RBAC. This is because all preflight checks must pass for the new version to be automatically deployed, and preflight checks that require cluster-scoped access will fail in minimal RBAC environments. ## Set up automatic updates To configure automatic updates: 1. In the Admin Console, go to the **Version History** tab and click **Configure automatic updates**. The **Configure automatic updates** dialog opens. 1. Under **Automatically check for updates**, use the default or select a cadence (Hourly, Daily, Weekly, Never, Custom) from the dropdown list. To turn off automatic updates, select **Never**. To define a custom cadence, select **Custom**, then enter a cron expression in the text field. For more information about cron expressions, see [Cron Expressions](/reference/cron-expressions). Configured automatic update checks use the local server time. ![Configure automatic updates](/images/automatic-updates-config.png) 1. Under **Automatically deploy new versions**, select an option. The available options depend on whether semantic versioning is enabled for the channel. * **For channels that use semantic versioning**: (v1.58.0 and later) Select an option in the dropdown to specify the versions that the Admin Console automatically deploys. For example, to automatically deploy only new patch and minor versions, select **Automatically deploy new patch and minor versions**. * **For channels that do not use semantic versioning**: (v1.67.0 and later) Optionally select **Enable automatic deployment**. When this checkbox is enabled, the Admin Console automatically deploys each new version of the application that it downloads. --- # About kURL cluster updates :::note Replicated kURL is available only for existing customers. If you are not an existing kURL user, use Replicated Embedded Cluster instead. For more information, see [Use Embedded Cluster](/embedded-cluster/v3/embedded-overview). kURL is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: This topic provides an overview of Replicated kURL cluster updates. For information about how to perform updates in kURL clusters, see [Perform Updates in kURL Clusters](updating-kurl). ## Overview The Replicated kURL installer spec specifies the kURL add-ons and the Kubernetes version that are deployed in kURL clusters. You can run the kURL installation script to apply the latest installer spec and update the cluster. ## About Kubernetes updates {#kubernetes} The version of Kubernetes running in a kURL cluster can be upgraded by one or more minor versions. The Kubernetes upgrade process in kURL clusters steps through one minor version at a time. For example, upgrades from Kubernetes 1.19.x to 1.26.x install versions 1.20.x, 1.21x, 1.22.x, 1.23.x, 1.24.x, and 1.25.x before installing 1.26.x. The installation script automatically detects when the Kubernetes version in your cluster must be updated. When a Kubernetes upgrade is required, the script first prints a prompt: `Drain local node and apply upgrade?`. When you confirm the prompt, it drains and upgrades the local primary node where the script is running. Then, if there are any remote primary nodes to upgrade, the script drains each sequentially and prints a command that you must run on the node to upgrade. For example, the command that that script prints might look like the following: `curl -sSL https://kurl.sh/myapp/upgrade.sh | sudo bash -s hostname-check=master-node-2 kubernetes-version=v1.24.3`. The script polls the status of each remote node until it detects that the Kubernetes upgrade is complete. Then, it uncordons the node and proceeds to cordon and drain the next node. This process ensures that only one node is cordoned at a time. After upgrading all primary nodes, the script performs the same operation sequentially on all remote secondary nodes. ### Air gap multi-version Kubernetes updates {#kubernetes-multi} To upgrade Kubernetes by more than one minor version in air gapped kURL clusters, you must provide a package that includes the assets required for the upgrade. When you run the installation script to upgrade, the script searches for the package in the `/var/lib/kurl/assets/` directory. The script then lists any required assets that are missing, prints a command to download the missing assets as a `.tar.gz` package, and prompts you to provide an absolute path to the package in your local directory. For example: ``` ⚙ Upgrading Kubernetes from 1.23.17 to 1.26.3 This involves upgrading from 1.23 to 1.24, 1.24 to 1.25, and 1.25 to 1.26. This may take some time. ⚙ Downloading assets required for Kubernetes 1.23.17 to 1.26.3 upgrade The following packages are not available locally, and are required: kubernetes-1.24.12.tar.gz kubernetes-1.25.8.tar.gz You can download them with the following command: curl -LO https://kurl.sh/bundle/version/v2023.04.24-0/19d41b7/packages/kubernetes-1.24.12,kubernetes-1.25.8.tar.gz Please provide the path to the file on the server. Absolute path to file: ``` ## About add-ons and KOTS updates {#add-ons} If the application vendor updated any add-ons in the kURL installer spec since the last time that you ran the installation script in your cluster, the script automatically updates the add-ons after updating Kubernetes (if required). For a complete list of add-ons that can be included in the kURL installer spec, including the KOTS add-on, see [Add-ons](https://kurl.sh/docs/add-ons/antrea) in the kURL documentation. ### containerd and docker add-on updates The installation script upgrades the version of the Containerd or Docker container runtime if required by the installer spec. For example, if your cluster uses Containerd version 1.6.4 and the spec is updated to use 1.6.18, then Containerd is updated to 1.6.18 in your cluster when you run the installation script. The installation script also supports migrating from Docker to Containerd as Docker is not supported in Kubernetes versions 1.24 and later. If the install script detects a change from Docker to Containerd, it installs Containerd, loads the images found in Docker, and removes Docker. For information about the container runtime add-ons, see [Containerd Add-On](https://kurl.sh/docs/add-ons/containerd) and [Docker Add-On](https://kurl.sh/docs/add-ons/docker) in the kURL documentation. ### KOTS updates (KOTS add-on) The version of KOTS that is installed in a kURL cluster is set by the [KOTS add-on](https://kurl.sh/docs/add-ons/kotsadm), which is defined in the kURL installer spec. For example, if the version of KOTS running in your cluster is 1.109.0, and the KOTS add-on in the kURL installer spec is updated to 1.109.12, then the KOTS version in your cluster is updated to 1.109.12 when you update the cluster. --- # Perform updates in kURL clusters :::note Replicated kURL is available only for existing customers. If you are not an existing kURL user, use Replicated Embedded Cluster instead. For more information, see [Use Embedded Cluster](/embedded-cluster/v3/embedded-overview). kURL is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: This topic describes how to perform updates in Replicated kURL installations. It includes procedures for updating an application, as well as for updating the versions of Kubernetes, Replicated KOTS, and add-ons in a kURL cluster. For more information about managing nodes in kURL clusters, including how to safely reset, reboot, and remove nodes when performing maintenance tasks, see [Manage Nodes](https://kurl.sh/docs/install-with-kurl/managing-nodes) in the open source kURL documentation. ## Update an application For kURL installations, you can update an application from the Admin Console. You can also set up automatic updates. See [Configure Automatic Updates](/enterprise/updating-apps). ### Online environments To perform an update from the Admin Console: 1. In the Admin Console, go to the **Version History** tab. 1. Click **Check for updates**. A new upstream version displays in the list of available versions. New Version Available [View a larger version of this image](/images/new-version-available.png) 1. (Optional) When there are multiple versions of an application, you can compare the changes between them by clicking **Diff releases** in the right corner. You can review changes between any two arbitrary releases by clicking the icon in the header of the release column. Select the two versions to compare, and click **Diff releases** to show the relative changes between the two releases. Diff Releases [View a larger version of this image](/images/diff-releases.png) New Changes [View a larger version of this image](/images/new-changes.png) 1. (Optional) Click the **View preflight checks** icon to view or re-run the preflight checks. Preflight checks [View a larger version of this image](/images/preflight-checks.png) 1. Return to the **Version History** tab and click **Deploy** next to the target version. ### Air gap environments 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. 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**. A new upstream version displays in the list of available versions. ![New Version Available](/images/new-version-available.png) 1. (Optional) When there are multiple versions of an application, you can compare the changes between them by clicking **Diff releases** in the right corner. You can review changes between any two arbitrary releases by clicking the icon in the header of the release column. Select the two versions to compare, and click **Diff releases** to show the relative changes between the two releases. ![Diff Releases](/images/diff-releases.png) ![New Changes](/images/new-changes.png) 1. (Optional) Click the **View preflight checks** icon to view or re-run the preflight checks. ![Preflight Checks](/images/preflight-checks.png) 1. Return to the **Version History** tab and click **Deploy** next to the target version. ## Update the kURL cluster After updating the kURL installer spec, you can rerun the kURL installation script to update a kURL cluster. For more information about kURL cluster udpates, see [About kURL Cluster Updates](/enterprise/updating-kurl-about). For more information about managing nodes in kURL clusters, including how to safely reset, reboot, and remove nodes when performing maintenance tasks, see [Manage Nodes](https://kurl.sh/docs/install-with-kurl/managing-nodes) in the open source kURL documentation. :::important The Kubernetes scheduler automatically reschedules Pods to other nodes during maintenance. Any deployments or StatefulSets with a single replica experience downtime while being rescheduled. ::: ### Online environments To update the kURL cluster in an online 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 [Create a kURL Installer](/vendor/packaging-embedded-kubernetes). 1. Run the kURL installation script on any primary node in the cluster: ```bash curl -sSL https://k8s.kurl.sh/APP_SLUG | sudo bash -s ADVANCED_OPTIONS ``` Replace: * `APP_SLUG` with the unique slug for the application. * `ADVANCED_OPTIONS` optionally with any flags listed in [Advanced Options](https://kurl.sh/docs/install-with-kurl/advanced-options) in the kURL documentation. To use no advanced installation options, remove `-s ADVANCED_OPTIONS` from the command. See the following recommendations for advanced options: * **installer-spec-file**: If you used the `installer-spec-file` flag to pass a `patch.yaml` file when you installed, you must pass the same `patch.yaml` file when you upgrade. This prevents the installer from overwriting any configuration from your `patch.yaml` file and making changes to the add-ons in your cluster. For example: `installer-spec-file="./patch.yaml"`. * **app-version-label**: By default, the script also upgrades your application to the latest version when you run the installation script. You can specify a target application version with the `app-version-label` flag. To avoid upgrading your application version, set the `app-version-label` flag to the currently installed application version. For example: `app-version-label=1.5.0`. 1. ### Air gap environments For air gap installations, you must load images on each node in the cluster before you can run the installation script to update Kubernetes and any add-ons. This is because upgraded components might have Pods scheduled on any node in the cluster. 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 [Create a kURL Installer](/vendor/packaging-embedded-kubernetes). 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: 1. Download the kURL `.tar.gz` air gap bundle from the channel where the new kURL installer spec is promoted: * To download the kURL air gap bundle for the Stable channel: ```bash 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. * 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: ```bash cat tasks.sh | sudo bash -s load-images ``` :::note The kURL installation script that you will run in the next step also performs a check for required images and prompts you to run the `load-images` command if any images are missing. ::: 1. Run the kURL installation script on any primary node in the cluster with the `airgap` option: ```bash cat install.sh | sudo bash -s airgap OTHER_ADVANCED_OPTIONS ``` Replace `OTHER_ADVANCED_OPTIONS` optionally with any flags listed in [Advanced Options](https://kurl.sh/docs/install-with-kurl/advanced-options) in the kURL documentation. See the following recommendations for advanced options: * **installer-spec-file**: If you used the `installer-spec-file` flag to pass a `patch.yaml` file when you installed, you must pass the same `patch.yaml` file when you upgrade. This prevents the installer from overwriting any configuration from your `patch.yaml` file and making changes to the add-ons in your cluster. For example: `installer-spec-file="./patch.yaml"`. * **app-version-label**: By default, the script also upgrades your application to the latest version when you run the installation script. You can specify a target application version with the `app-version-label` flag. To avoid upgrading your application version, set the `app-version-label` flag to the currently installed application version. For example: `app-version-label=1.5.0`. 1. :::note If Kubernetes must be upgraded by more than one minor version, the script automatically searches for the required Kubernetes assets in the `/var/lib/kurl/assets/` directory. If the assets are not available, the script prints a command to download the assets as a `tar.gz` package. Download and provide the absolute path to the package when prompted to continue with the upgrade. ::: --- # Update licenses in the Admin Console This topic describes how to update a license from the KOTS Admin Console. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Update online licenses To update licenses in online environments: 1. In the Admin Console, go to the **License** tab. 1. Click **Sync license** to get the latest updates. ![Online License](/images/online-license-tab.png) [View a larger version of this image](/images/online-license-tab.png) :::note If no changes are detected, a **License is already up to date** message appears. ::: When the license is updated, KOTS makes a new version available that includes the license changes: ![License updated successfully](/images/kots-license-update-message.png) [View a larger version of this image](/images/kots-license-update-message.png) 1. In the dialog, click **Go to new version** to navigate to the **Version history** page. 1. On the **Version history** page, next to the new version labeled **License Change**, click **Deploy** then **Yes, deploy**. ![Deploy license change](/images/kots-deploy-license-change.png) [View a larger version of this image](/images/kots-deploy-license-change.png) The version with the license change is then displayed as the currently deployed version, as shown below: ![Currently deployed version](/images/kots-license-change-currently-deployed.png) [View a larger version of this image](/images/kots-license-change-currently-deployed.png) ## Update air gap licenses To update licenses in air gap environments: 1. Download the new license. Ensure that it is available on the machine where you can access a browser. 1. In the Admin Console, go to the **License** tab. 1. Click **Upload license** and select the new license. ![Airgap License](/images/airgap-license-tab.png) [View a larger version of this image](/images/airgap-license-tab.png) :::note If no changes are detected, a **License is already up to date** message appears. ::: When the license is updated, KOTS makes a new version available that includes the license changes: ![License updated successfully](/images/kots-airgap-license-update-message.png) [View a larger version of this image](/images/kots-airgap-license-update-message.png) 1. In the dialog, click **Go to new version** to navigate to the **Version history** page. 1. On the **Version history** page, next to the new version labeled **License Change**, click **Deploy** then **Yes, deploy**. ![Deploy license change](/images/kots-deploy-license-change.png) [View a larger version of this image](/images/kots-deploy-license-change.png) The version with the license change is then displayed as the currently deployed version, as shown below: ![Currently deployed version](/images/kots-license-change-currently-deployed.png) [View a larger version of this image](/images/kots-license-change-currently-deployed.png) ## Upgrade from a community license If you have a community license, you can change your license by uploading a new one. This allows you to upgrade from a community version of the software without having to reinstall the Admin Console and the application. To change a community license to another license: 1. Download the new license. 1. In the **License** tab of the Admin Console, click **Change license**. 1. In the dialog, upload the new license file. --- # Patch with Kustomize This topic describes how to use Kustomize to patch an application before deploying. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview Replicated KOTS uses Kustomize to let you make patches to an application outside of the options available in the KOTS Admin Console **Config** page. _Kustomizations_ are the Kustomize configuration objects, defined in `kustomization.yaml` files, that describe how to transform or generate other Kubernetes objects. These kustomizations overlay the application resource files and can persist after release updates. For example, you can kustomize the number of replicas that you want to continually use in your environment or specify what `nodeSelectors` to use for a deployment. For more information, see the [Kustomize website](https://kustomize.io). ## Limitation For Helm charts deployed with version `kots.io/v1beta2` of the Replicated HelmChart custom resource, editing the downstream Kustomization files to make changes to the application before deploying is not supported. This is because KOTS does not use Kustomize when installing Helm charts with the `kots.io/v1beta2` HelmChart custom resource. For more information, see [About Distributing Helm Charts with KOTS](/vendor/helm-native-about). ## About the directory structure You can patch an application with Kustomize from the **View files** page in the Admin Console. The **View files** page shows the Kubernetes manifest files for the application. The following images shows an example of the file directory on the View files page: ![Kustomize Directory Structure](/images/kustomize-dir-structure.png) [View a larger version of this image](/images/kustomize-dir-structure.png) For more information about each of the sections in the file directory, see the following sections: - [Upstream](#upstream) - [Base](#base) - [Overlays](#overlays) - [Rendered](#rendered) - [skippedFiles](#skippedfiles) ### Upstream The following table describes the `upstream` directory and whether custom changes persist after an update:
Directory Changes Persist? Description
upstream No, except for the userdata subdirectory

The upstream directory exactly mirrors the content pushed to a release.

Contains the template functions, preflight checks, support bundle, config options, license, and so on.

Contains a userdata subdirectory that includes user data files such as the license file and the config file.
### Base The following table describes the `base` directory and whether custom changes persist after an update:
Directory Changes Persist? Description
base No

After KOTS processes and renders the upstream, it puts those files in the base directory.

Only the deployable application files, such as files deployable with kubectl apply, are placed here.

Any non-deployable manifests, such as template functions, preflight checks, and configuration options, are removed.
### Overlays The `overlays` directory contains the following subdirectories that apply specific kustomizations to the `base` directory when deploying a version to the cluster. The following table describes the subdirectories and specifies whether the custom changes made in each subdirectory persist after an update.
Subdirectory Changes Persist? Description
midstream No Contains KOTS-specific kustomizations, such as:
  • Backup labels, such as those used to configure Velero.
  • Image pull secret definitions and patches to inject the imagePullSecret field into relevant manifests (such as deployments, stateful sets, and jobs).
downstream Yes

Contains user-defined kustomizations that are applied to the midstream directory and deployed to the cluster.

Only one downstream subdirectory is supported. It is automatically created and named this-cluster when the Admin Console is installed.

To add kustomizations, see Patch an Application.
midstream/charts No

Appears only when the useHelmInstall property in the HelmChart custom resource is set to true.

Contains a subdirectory for each Helm chart. Each Helm chart has its own kustomizations because each chart is rendered and deployed separately from other charts and manifests.

The subcharts of each Helm chart also have their own kustomizations and are rendered separately. However, these subcharts are included and deployed as part of the parent chart.
downstream/charts Yes

Appears only when the useHelmInstall property in the HelmChart custom resource is set to true.

Contains a subdirectory for each Helm chart. Each Helm chart has its own kustomizations because each chart is rendered and deployed separately from other charts and manifests.

The subcharts of each Helm chart also have their own kustomizations and are rendered separately. However, these subcharts are included and deployed as part of the parent chart.
### Rendered The following table describes the `rendered` directory and whether custom changes persist after an update:
Directory Changes Persist? Description
rendered No

Contains the final rendered application manifests that are deployed to the cluster.

The rendered files are created when KOTS processes the base by applying the corresponding overlays and the user-defined kustomizations. KOTS puts the rendered files in the rendered directory.
rendered/charts No

Appears only when the useHelmInstall property in the HelmChart custom resource is set to true.

Contains a subdirectory for each rendered Helm chart. Each Helm chart is deployed separately from other charts and manifests.

The rendered subcharts of each Helm chart are included and deployed as part of the parent chart.
### skippedFiles The `skippedFiles` directory lists files that KOTS is not able to process or render, such as invalid YAML files. The `_index.yaml` file contains metadata and details about the errors, such as which files they were found in and sometimes the line number of the error. ## Patch an application To patch the application with Kustomize so that your changes persist between updates, edit the files in the `overlays/downstream/this-cluster` directory. The Admin Console overwrites the `upstream` and `base` directories each time you upgrade the application to a later version. To patch an application: 1. On the View Files tab in the Admin Console, click **Need to edit these files? Click here to learn how**. ![edit-patches-kots-app](/images/edit-patches-kots-app.png) 1. To download the application bundle locally: ```shell kubectl kots download --namespace APP_NAMESPACE --slug APP_SLUG ``` Replace: * `APP_NAMESPACE` with the namespace on the cluster where the application is deployed. * `APP_SLUG` with the unique slug for the application. You can copy these values from the dialog that appears when you click **Need to edit these files? Click here to learn how**. 1. Create a Kubernetes manifest YAML file and make any desired edits. You only need to add the fields and values that you want to change because this patch file overwrites the corresponding values in the `base` directory. For example, the following `Deployment` patch manifest file shows an edit only to the number of replicas. None of the other values in the `base/deployment.yaml` file will be overwritten. ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: example-nginx spec: replicas: 2 ``` 1. Add the filename that you created in the previous step to the `patches` field in the `kustomization.yaml` file, located in `/overlays/downstream/this-cluster`. The `downstream/this-cluster` subdirectory is where custom changes (patches) persist when releases are updated. These changes are in turn applied to the `midstream` directory. For more information, see [overlays](#overlays). **Example:** ```yaml apiVersion: kustomize.config.k8s.io/v1beta1 bases: - ../../midstream kind: Kustomization patches: - path: ./FILENAME.yaml ``` 1. Upload your changes to the cluster: ```shell kubectl kots upload --namespace APP_NAMESPACE --slug APP_SLUG ~/APP-SLUG ``` 1. On the Version History tab in the Admin Console, click **Diff** to see the new version of the application with the diff of the changes that you uploaded. ![kustomize-view-history-diff](/images/kustomize-view-history-diff.png) [View a larger version of this image](/images/kustomize-view-history-diff.png) 1. Click **Deploy** to apply the changes. ![kustomize-view-history-deploy](/images/kustomize-view-history-deploy.png) 1. Verify your changes. For example, running the following command shows that there are two NGINX pods running after deploying two replicas in the example YAML above: ```shell kubectl get po | grep example-nginx ``` **Example output:** ```shell example-nginx-f5c49fdf6-bf584 1/1 Running 0 1h example-nginx-t6ght74jr-58fhr 1/1 Running 0 1m ``` --- # Update TLS certificates in kURL clusters :::note Replicated kURL is available only for existing customers. If you are not an existing kURL user, use Replicated Embedded Cluster instead. For more information, see [Use Embedded Cluster](/embedded-cluster/v3/embedded-overview). kURL is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: This topic describes how to upload custom TLS certificates for Replicated kURL clusters. ## Overview For kURL clusters, the default Replicated KOTS self-signed certificate automatically renews 30 days before the expiration date. If you have uploaded a custom TLS certificate instead, then no renewal is attempted, even if the certificate is expired. In this case, you must manually upload a new custom certificate. For information about TLS renewal for registry and Kubernetes control plane with Replicated kURL, see [TLS Certificates](https://kurl.sh/docs/install-with-kurl/setup-tls-certs) in the kURL documentation. ## Update custom TLS certificates If you are using a custom TLS certificate in a kURL cluster, you manually upload a new certificate when the previous one expires. :::important Adding the `acceptAnonymousUploads` annotation temporarily creates a vulnerability for an attacker to maliciously upload TLS certificates. After TLS certificates have been uploaded, the vulnerability is closed again. Replicated recommends that you complete this upload process quickly to minimize the vulnerability risk. ::: To upload a new custom TLS certificate: 1. Run the following annotation command to restore the ability to upload new TLS certificates: ```bash kubectl -n default annotate secret kotsadm-tls acceptAnonymousUploads=1 --overwrite ``` 1. Run the following command to get the name of the kurl-proxy server: ```bash kubectl get pods -A | grep kurl-proxy | awk '{print $2}' ``` 1. Run the following command to delete the kurl-proxy pod. The pod automatically restarts after the command runs. ```bash kubectl delete pods PROXY_SERVER ``` Replace PROXY_SERVER with the name of the kurl-proxy server that you got in the previous step. 1. After the pod has restarted, direct your browser to `http://:8800/tls` and go through the upload process in the user interface. --- # Introduction to KOTS This topic provides an introduction to the Replicated KOTS installer, including information about KOTS features, installation options, and user interfaces. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview Replicated KOTS is a kubectl plugin and an in-cluster Admin Console that provides highly successful installations of Helm charts and Kubernetes applications into customer-controlled environments, including on-prem and air gap environments. KOTS communicates securely with the Replicated Vendor Portal to synchronize customer licenses, check for available application updates, send instance data, share customer-generated support bundles, and more. Installing an application with KOTS provides access to features such as: * Support for air gap installations in environments with limited or no outbound internet access * Support for installations on VMs or bare metal servers, when using Replicated Embedded Cluster or Replicated kURL * The KOTS Admin Console, which provides a user interface where customers can install and manage their application instances * Instance telemetry automatically sent to the Vendor Portal for instances running in customer environments * Strict preflight checks that block installation if environment requirements are not met * Backup and restore with Replicated snapshots * Support for marking releases as required to prevent users from skipping them during upgrades KOTS is an open source project that is maintained by Replicated. For more information, see the [kots](https://github.com/replicatedhq/kots) repository in GitHub. ## About installing with KOTS KOTS can be used to install Kubernetes applications and Helm charts in the following environments: * Clusters provisioned on VMs or bare metal servers with Replicated Embedded Cluster or Replicated kURL * Existing clusters brought by the user * Online (internet-connected) or air-gapped (disconnected) environments To install an application with KOTS, users first run an installation script that installs KOTS in the target cluster and deploys the KOTS Admin Console. After KOTS is installed, users can log in to the KOTS Admin Console to upload their license file, configure the application, run preflight checks, and install and deploy the application. The following diagram demonstrates how a single release promoted to the Stable channel in the Vendor Portal can be installed with KOTS in an embedded cluster on a VM, in an existing air-gapped cluster, and in an existing internet-connected cluster: Embedded cluster, air gap, and existing cluster app installation workflows [View a larger version of this image](/images/kots-installation-overview.png) As shown in the diagram above: * For installations in existing online (internet-connected) clusters, users run a command to install KOTS in their cluster. * For installations on VMs or bare metal servers, users run an Embedded Cluster or kURL installation script that both provisions a cluster in their environment and installs KOTS in the cluster. * For installations in air-gapped clusters, users download air gap bundles for KOTS and the application from the Replicated Download Portal and then provide the bundles during installation. All users must have a valid license file to install with KOTS. After KOTS is installed in the cluster, users can access the KOTS Admin Console to provide their license and deploy the application. For more information about how to install applications with KOTS, see the [Installing an Application](/enterprise/installing-overview) section. ## KOTS user interfaces This section describes the KOTS interfaces available to users for installing and managing applications. ### KOTS Admin Console KOTS provides an Admin Console to make it easy for users to install, manage, update, configure, monitor, backup and restore, and troubleshoot their application instance from a GUI. The following shows an example of the Admin Console dashboard for an application: ![Admin Console Dashboard](/images/guides/kots/application.png) [View a larger version of this image](/images/guides/kots/application.png) For applications installed with Replicated Embedded Cluster in a VM or bare metal server, the Admin Console also includes a **Cluster Management** tab where users can add and manage nodes in the embedded cluster, as shown below: ![Admin console dashboard with Cluster Management tab](/images/gitea-ec-ready.png) [View a larger version of this image](/images/gitea-ec-ready.png) ### KOTS CLI The KOTS command-line interface (CLI) is a kubectl plugin. Customers can run commands with the KOTS CLI to install and manage their application instances with KOTS programmatically. For information about 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, such as in CI/CD pipelines. For information about how to perform headless installations from the command line, see [Install with the KOTS CLI](/enterprise/installing-existing-cluster-automation). --- --- pagination_prev: null --- # About the Replicated Platform This topic provides an introduction to the Replicated Platform, including a platform overview and a list of key features. It also describes the Commercial Software Distribution Lifecycle and how Replicated features support each phase of the lifecycle. ## Platform overview Replicated is a commercial software distribution platform. ISVs can use Replicated Platform features to distribute modern commercial software into complex, customer-controlled environments, including on-prem and air gap. The Replicated Platform features support ISVs during each phase of the Commercial Software Distribution Lifecycle. For more information, see [Commercial Software Distribution Lifecycle](#csdl) on this page. The following diagram shows how the Replicated Platform supports the full application lifecycle, from distribution and installation with Embedded Cluster to post-installation support: ![replicated platform features workflow](/images/replicated-platform.png) [View a larger version of this image](/images/replicated-platform.png) The diagram shows how software vendors use CI/CD pipelines to test releases in environments provisioned by [Replicated Compatibility Matrix (CMX)](/vendor/testing-about). Vendors then promote releases to a customer-facing or internal channel in the [Vendor Portal](/vendor/releases-about). Customers can install application releases that vendors promote to the channel to which they subscribe. To install, the customer logs in to the [Replicated Enterprise Portal](/vendor/enterprise-portal-about) to download their license, which grants proxy access to the application images through the [Replicated proxy registry](/vendor/private-images-about). They also download the installation assets for the [Replicated Embedded Cluster](/vendor/embedded-overview) installer. Customers can access the Enterprise Portal at any time to get installation and update instructions, upload [support bundles](/vendor/preflight-support-bundle-about#support-bundles), view security information from the [Security Center](/vendor/security-center-about), and more. During installation, Embedded Cluster runs [preflight checks](/vendor/preflight-support-bundle-about) on the host to verify that the environment meets the installation requirements. Then, it creates a Kubernetes cluster in the VM and deploys a UI. From the UI, the customer enters application-specific configurations, runs application preflight checks, optionally joins nodes to the cluster, and deploys the application. Embedded Cluster also deploys the [Replicated SDK](/vendor/replicated-sdk-overview) in the cluster, if the vendor included the SDK as a dependency of their application. The SDK's in-cluster API sends [instance data](/vendor/instance-insights-event-data) and custom metrics from the customer environment to the Vendor Portal. Vendors can configure [event notifications](/vendor/event-notifications) to email or webhook destinations. These notifications alert vendors to key events: customer support bundle uploads, instances unhealthy for an extended period, or trial licenses about to expire. ## Replicated Platform features The following describes the key features of the Replicated Platform. ### Helm CLI installations Replicated distributes your application as Helm charts through the Replicated proxy registry. Customers with existing Kubernetes clusters install your application using the Helm CLI, authenticating with their unique license ID. For more information, see [About installation options](/vendor/concepts-installers). ### Embedded Cluster Replicated Embedded Cluster is a Kubernetes installer based on the open source Kubernetes distribution k0s. With Embedded Cluster, users install and manage both the cluster and the application together as a single appliance on a VM or bare metal server. For more information, see [Embedded Cluster overview](/embedded-cluster/v3/embedded-overview). ### Preflight checks and support bundles Preflight checks and support bundles are provided by the Troubleshoot open source project, which is maintained by Replicated. Troubleshoot is a kubectl plugin that provides diagnostic tools for Kubernetes applications. For more information, see the open source [Troubleshoot](https://troubleshoot.sh/docs/collect/) documentation. Preflight checks and support bundles analyze data from customer environments to provide insights that help users to avoid or troubleshoot common issues with an application: * **Preflight checks** run before an application is installed to check that the customer environment meets the application requirements. * **Support bundles** collect troubleshooting data from customer environments to help users diagnose problems with application deployments. For more information, see [About preflight checks and support bundles](/vendor/preflight-support-bundle-about). ### Proxy registry The Replicated proxy registry grants proxy access to an application's images using the customer's unique license. This means that customers can get access to application images during installation without the vendor needing to provide registry credentials. For more information, see [About the Replicated proxy registry](/vendor/private-images-about). ### Replicated SDK The Replicated SDK is a Helm chart that you can install as a small service alongside your application. It provides an in-cluster API that communicates with the Vendor Portal. For example, the SDK API can return details about the customer's license or report telemetry on the application instance back to the Vendor Portal. For more information, see [About the Replicated SDK](/vendor/replicated-sdk-overview). ### Vendor Portal The Replicated Vendor Portal is the web-based interface for configuring Replicated features, managing application releases, viewing customer insights and reporting, and managing teams. You can also interact with the Vendor Portal programmatically using the following developer tools: * **Replicated CLI**: Use the Replicated CLI to complete tasks programmatically, including all tasks for packaging and managing applications, and managing artifacts such as teams, license files, and so on. For more information, see [Installing the Replicated CLI](/reference/replicated-cli-installing). * **Vendor API v3**: Use the Vendor API to complete tasks programmatically, including all tasks for packaging and managing applications, and managing artifacts such as teams and license files. For more information, see [Using the Vendor API v3](/reference/vendor-api-using). ### Enterprise Portal The Enterprise Portal is a customizable, web-based portal where customers can view install and update instructions, upload support bundles, view instance insights, and more. For more information, see [About the Enteprise Portal](/vendor/enterprise-portal-about). The following shows an example of the Enterprise Portal dashboard: ![Enterprise Portal dashboard](/images/enterprise-portal-dashboard.png) [View a larger version of this image](/images/enterprise-portal-dashboard.png) ### Compatibility matrix Use Replicated Compatibility Matrix (CMX) to create VMs or Kubernetes clusters within minutes. Interact with CMX through the Vendor Portal or the Replicated CLI to integrate CMX into your existing CI/CD workflows and programmatically create test environments. For more information, see [About CMX](/vendor/testing-about). The following shows the CMX page for creating a cluster: Create a cluster page [View a larger version of this image](/images/create-a-cluster.png) ## Commercial software distribution lifecycle {#csdl} Replicated Platform features support ISVs in each phase of the Commercial Software Distribution Lifecycle, shown in the following diagram: ![software distribution lifecycle wheel](/images/software-dev-lifecycle.png) [View a larger version of this image](/images/software-dev-lifecycle.png) Commercial software distribution is the business process that ISVs use to enable enterprise customers to self-host a private application instance in their own environment. Replicated developed the Commercial Software Distribution Lifecycle to represent the stages essential for delivering software securely and reliably to customer-controlled environments. Replicated based this lifecycle on the DevOps lifecycle and the Software Development Lifecycle (SDLC), but it focuses on what ISVs must do to distribute third-party commercial software to tens, hundreds, or thousands of enterprise customers. For more information about to download a copy of The Commercial Software Distribution Handbook, see [The Commercial Software Distribution Handbook](https://www.replicated.com/the-commercial-software-distribution-handbook). The following describes the phases of the software distribution lifecycle: * **[Develop](#develop)**: Application design and architecture decisions align with customer needs, and development teams can quickly iterate on new features. * **[Test](#test)**: Run automated tests in several customer-representative environments as part of continuous integration and continuous delivery (CI/CD) workflows. * **[License](#license)**: Customize licenses for each customer and issue, manage, and update them as needed. * **[Release](#release)**: Use channels to share releases with external and internal users, publish release artifacts securely, and use consistent versioning. * **[Install](#install)**: Provide unique installation options depending on customers' preferences and experience levels. * **[Report](#report)**: Make more informed prioritization decisions by collecting usage and performance metadata for application instances running in customer environments. * **[Support](#support)**: Diagnose and resolve support issues quickly. For more information about the Replicated features that support each phase, see the following sections. ### Develop The Replicated SDK exposes an in-cluster API that you can develop against to quickly integrate and test core functionality with an application. For example, use the in-cluster API to send custom metrics to the Replicated Vendor Portal after installing the SDK alongside your application. For more information about using the Replicated SDK, see [About the Replicated SDK](/vendor/replicated-sdk-overview). ### Test Use CMX to quickly provision ephemeral VMs and Kubernetes clusters. When integrated into CI/CD workflows, CMX automatically creates a variety of customer-representative environments for testing code changes. For more information, see [About CMX](/vendor/testing-about). ### License Create customers in the Replicated Vendor Portal to handle licensing for your application in both online and air gap environments. For example: * License free trials and different tiers of product plans * Create and manage custom license entitlements * Verify license entitlements both before installation and during runtime * Measure and report usage For more information about working with customers and custom license fields, see [About customers](/vendor/licenses-about). ### Release Release channels in the Replicated Vendor Portal allow ISVs to make different application versions available to different customers, without needing to maintain separate code bases. For example, use a "Beta" channel to share beta releases with only a subset of customers. For more information about working with channels, see [About channels and releases](/vendor/releases-about). Additionally, the Replicated proxy registry grants proxy access to private application images using the customers' license. This ensures customers have appropriate access to images based on their assigned channel. For more information about using the proxy registry, see [About the Replicated proxy registry](/vendor/private-images-about). ### Install Applications distributed with the Replicated Platform can support different installation methods from the same application release, helping you to meet your customers where they are. Customers new to Kubernetes, or who prefer a dedicated cluster, can install on a VM or bare metal server with the Embedded Cluster installer. For more information, see [Embedded Cluster overview](/embedded-cluster/v2/embedded-overview). Customers familiar with Kubernetes and Helm can install in their own existing cluster using the Helm CLI. For more information, see [Installing with Helm](/vendor/install-with-helm). Customers in environments with limited or no outbound internet access can securely push images to their own internal registry, then install using the Helm CLI or a Replicated installer. Additionally, the Enterprise Portal provides a customizable, web-based portal where customers can view install and update instructions, upload support bundles, view instance insights, and more. For more information, see [About the Enteprise Portal](/vendor/enterprise-portal-about). ### Report When installed alongside an application, the Replicated SDK automatically sends instance data from the customer environment to the Replicated Vendor Portal. This instance data includes health and status indicators, adoption metrics, and performance metrics. For more information, see [About instance and event data](/vendor/instance-insights-event-data). ISVs can also set up notifications to get alerted of important instance issues or performance trends. For more information, see [About Event Notifications](/vendor/event-notifications). ### Support Support teams can use Replicated features to more quickly diagnose and resolve application issues. For example: - Customize and generate support bundles, which collect and analyze redacted information from the customer's cluster, environment, and application instance. See [About preflight checks and support bundles](/vendor/preflight-support-bundle-about). - Provision customer-representative environments with CMX to recreate and diagnose issues. See [About CMX](/vendor/testing-about). - Get insights into an instance's status by accessing telemetry data, which covers the health of the application, the current application version, and details about the infrastructure and cluster where the application is running. For more information, see [Customer reporting](/vendor/customer-reporting). For more information, see [Customer reporting](/vendor/customer-reporting). --- --- slug: / pagination_next: null title: Home hide_table_of_contents: true hide_title: true ---

Welcome to Replicated Docs

Learn how to use the Replicated Platform to secure and distribute your software to enterprise customers

Did You Know

Add custom license fields

Custom license fields allow you to define application-specific entitlements and add other types of metadata to customer licenses.

Learn more →

Browse product documentation

Vendor Platform

Teams and Accounts

Manage team members, RBAC, API tokens, and more

Applications

Manage your application in the Vendor Portal

Channels and Releases

Create and promote application versions

Customers and Licenses

Manage customer records and license entitlements

Custom Domains

Alias Replicated domains

Insights and Telemetry

Get telemetry and event data from customer instances

Replicated CLI

Use the CLI to manage applications, releases, and more

Vendor API

Integrate Vendor Platform functionality into your workflows

Embedded Cluster

Overview

Distribute a Kubernetes cluster and your application together as a single appliance

Embedded Cluster Config

Embedded Cluster Config resource

Online Installation with Embedded Cluster

Install with internet access using Embedded Cluster

Air Gap Installation with Embedded Cluster

Install in environments without internet access

Perform Updates with Embedded Cluster

Update an application and the cluster infrastructure

Helm CLI Installations

Overview

An introduction to Helm CLI installations for applications distributed with Replicated

Install with the Helm CLI

Install your application using Helm CLI

Install and Update with the Helm CLI in Air Gap Environments

Use Helm in environments without internet access

Enterprise Portal

Overview

Give customers access to releases and instance data

Customize the Enterprise Portal

Configure branding and appearance for customers

Manage Customer Access to the Enterprise Portal

Invite and manage customer portal users

Use the Enterprise Portal

Access and use the Enterprise Portal

Self-Service Sign-ups

Enable self-service access to trial or community licenses for customers

Compatibility Matrix

Overview

Test your application across customer-representative environments

CMX Pricing

Learn about pricing for CMX clusters and VMs

Test in Air Gap Environments

Simulate networks with no outbound internet access

Use CMX VMs

Create and manage virtual machines for testing

Use CMX Clusters

Create and manage Kubernetes clusters for testing

Test in CMX with CI/CD

Automate testing workflows with continuous integration

Replicated Proxy Registry

Overview

Grant proxy access to private images

Add and Manage External Registries

Connect external image registries

Use the Proxy Registry with Embedded Cluster

Proxy images for Embedded Cluster installations

Use the Proxy Registry with Helm CLI Installations

Proxy images for Helm CLI installations

Connect to a Public Registry

Pull images from public registries

Replicated SDK

Overview

In-cluster service and API to integrate key Replicated functionality into your application

Install the Replicated SDK

Install alongside an application or as a standalone component

Development Mode

Develop against the SDK API to test changes locally

Replicated SDK API

API reference for Replicated SDK endpoints

Customize the Replicated SDK

Customize RBAC, set environment variables, add tolerations, and more

Troubleshoot

Overview

Learn about troubleshooting tools for customer environments

Define Preflight Checks

Verify that customer environments meet application requirements

Add and Customize Support Bundles

Configure support bundles for troubleshooting

Generate Support Bundles

Collect support bundles in customer environments

Inspect Support Bundles

Analyze support bundles to troubleshoot issues

Submit a Support Request

Contact Replicated support for assistance

--- # Cron expressions This topic describes the supported cron expressions that you can use to schedule automatic application update checks and automatic backups in the Replicated Admin Console. The information in this topic applies to applications installed with a Replicated installer (Embedded Cluster, KOTS, kURL). For more information, see [Configure Automatic Updates](/enterprise/updating-apps) and [Schedule Automatic Backups](/enterprise/snapshots-creating#schedule-automatic-backups) in _Creating and Scheduling Backups_. ## Syntax ``` ``` ## Fields The following table lists the required cron fields and supported values:
Required Field Allowed Values Allowed Special Characters
Minute 0 through 59 , - *
Hour 0 through 23 , - *
Day-of-month 1 through 31 , - * ?
Month 1 through 12 or JAN through DEC , - *
Day-of-week 1 through 7 or SUN through SAT , - * ?
## Special characters Replicated uses an external cron Go library. For more information about it's usage, see [cron](https://pkg.go.dev/github.com/robfig/cron/v3). The following table describes the supported special characters:
Special Character Description
Comma (,) Specifies a list or multiple values, which can be consecutive or not. For example, 1,2,4 in the Day-of-week field signifies every Monday, Tuesday, and Thursday.
Dash (-) Specifies a contiguous range. For example, 4-6 in the Month field signifies April through June.
Asterisk (*) Specifies that all of the values for the field are used. For example, using * in the Month field means that all of the months are included in the schedule.
Question mark (?) Specifies that one or another value can be used. For example, enter 5 for Day-of-the-month and ? for Day-of-the-week to check for updates on the 5th day of the month, regardless of which day of the week it is.
## Predefined schedules You can use one of the following predefined schedule values instead of a cron expression:
Schedule Value Description Equivalent Cron Expression
@yearly (or @annually) Runs once a year, at midnight on January 1. 0 0 1 1 *
@monthly Runs once a month, at midnight on the first of the month. 0 0 1 * *
@weekly Run once a week, at midnight on Saturday. 0 0 * * 0
@daily (or @midnight) Runs once a day, at midnight. 0 0 * * *
@hourly Runs once an hour, at the beginning of the hour. 0 * * * *
@never

Disables the schedule completely. Only used by KOTS.

This value can be useful when you are calling the API directly or are editing the KOTS configuration manually.

 0 * * * *
@default

Selects the default schedule option (every 4 hours). Begins when the Admin Console starts up.

This value can be useful when you are calling the API directly or are editing the KOTS configuration manually.

 0 * * * *
## Intervals You can also schedule the job to operate at fixed intervals, starting at the time the job is added or when cron is run: ``` @every DURATION ``` Replace `DURATION` with a string that is accepted by time.ParseDuration, with the exception of seconds. Seconds are not supported by KOTS. For more information about duration strings, see [time.ParseDuration](http://golang.org/pkg/time/#ParseDuration) in the Go Time documentation. As with standard cron expressions, the interval does not include the job runtime. For example, if a job is scheduled to run every 10 minutes, and the job takes 4 minutes to run, there are 6 minutes of idle time between each run. ## Examples The following examples show valid cron expressions to schedule checking for updates: - At 11:30 AM every day: ``` 30 11 * * * ``` - After 1 hour and 45 minutes, and then every interval following that: ``` @every 1h45m ``` --- # About custom resources You can include custom resources in your releases to control the experience for installations with a Replicated installer, add support air gap installations, and configure functionality like preflight checks, support bundles, and disaster recovery. Custom resources are consumed by Replicated installers, the Replicated Admin Console, or by other kubectl plugins. Custom resources are packaged as part of the application, but are _not_ deployed to the cluster. ## Custom resources The following custom resources can be used in releases distributed with Replicated:
API Group/Version Kind Description
app.k8s.io/v1beta1 [SIG Application](https://github.com/kubernetes-sigs/application#kubernetes-applications) Defines metadata about the application
embeddedcluster.replicated.com/v1beta1 [Config](/embedded-cluster/v3/embedded-config) Defines a Replicated Embedded Cluster distribution
cluster.kurl.sh/v1beta1 [Installer](https://kurl.sh/docs/create-installer/) Defines a Replicated kURL distribution
kots.io/v1beta1 [Application](custom-resource-application) Adds metadata to the user-facing UI for installations with a Replicated installer
kots.io/v1beta1 [Config](custom-resource-config) Defines a user-facing configuration screen for installations with a Replicated installer
kots.io/v1beta2 [HelmChart](custom-resource-helmchart-v2) Identifies an instantiation of a Helm chart
kots.io/v1beta1 [LintConfig](custom-resource-lintconfig) Customizes the default rule levels for the release linter
troubleshoot.sh/v1beta2 [Preflight](custom-resource-preflight) Defines collectors and analyzers for preflight checks
troubleshoot.sh/v1beta2 [Redactor](https://troubleshoot.sh/docs/redact/) Defines custom redactors for support bundles and preflight checks
troubleshoot.sh/v1beta2 [Support Bundle](custom-resource-preflight) Defines collectors and analyzers for support bundles
velero.io/v1 [Backup](https://velero.io/docs/v1.17/api-types/backup/) Defines a Velero backup request
--- # Application The Application custom resource lets you add your company or application branding to the customer-facing UI, including a custom title and icon. Depending on which Replicated installer the customer uses, this UI is either the Embedded Cluster v3 install and upgrade wizard or the Replicated Admin Console. For Embedded Cluster v2, KOTS existing cluster, and kURL installations, the Application custom resource also lets you configure other aspects of the Admin Console user experience. This includes setting a minimum required KOTS version, adding custom graphs with Prometheus to the dashboard, and more. ## Example The following is an example manifest file for the Application custom resource: ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: title: Your Application icon: https://support.io/img/logo.png releaseNotes: "" allowRollback: true targetKotsVersion: "1.130.2" minKotsVersion: "1.124.5" requireMinimalRBACPrivileges: true additionalImages: - jenkins/jenkins:lts excludedImages: - auto additionalNamespaces: - "*" ports: - serviceName: web servicePort: 9000 localPort: 9000 applicationUrl: "http://web" statusInformers: - deployment/my-web-svc - deployment/my-worker graphs: - title: User Signups query: 'sum(user_signup_events_total)' ``` ## Spec ### `title` The title to use in the customer-facing UI. Typically, this is the application name. #### Limitation The `title` property doesn't support Go templating. #### Example ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: outline-app spec: title: Outline ``` The following shows an example of how the title appears in the Embedded Cluster v3 install wizard: install wizard login screen [View a larger version of this image](/images/embedded-cluster-v3-install-wizard-login.png) ### `icon` A file with the icon to use in the customer-facing UI. Typically, this is the application's logo. The icon can be a remote URL or a Base64 encoded image. Air gap installations require Base64 encoded images. #### Limitation The `icon` property doesn't support Go templating. #### Examples ##### Remote URL ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: icon: https://support.io/img/logo.png ``` ##### Base64-encoded image ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: icon: data:image/svg+xml;base64,PHNy4xMDwM...# based64-encoded image ``` ### `releaseNotes` The release notes for this application version. You can also set the release notes from the Vendor Portal or Replicated CLI when you promote a release. For more information, see [Managing releases with the Vendor Portal](/vendor/releases-creating-releases) or [Managing releases with the CLI](/vendor/releases-creating-cli). For Embedded Cluster v2, KOTS existing cluster, and kURL installations, customers can access release notes from the Admin Console. For Embedded Cluster v3, you can optionally include these release notes in your application using the Replicated [ReleaseNotes](/reference/template-functions-license-context#releasenotes) template function. #### Limitation The `releaseNotes` property doesn't support Go templating. #### Example ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: releaseNotes: Fixes a bug and adds a new feature. ``` ### `allowRollback` Enable this flag to create a **Rollback** button on the Admin Console **Version History** page. By default, `allowRollback` is false. If your application does not introduce backwards-incompatible versions, such as through database migrations, you can use `allowRollback`. This flag lets end users roll back to previous versions from the Admin Console. Rollback does not revert any state. Rather, it recovers the YAML manifests applied to the cluster. #### Limitations * The `allowRollback` property doesn't support Go templating. * Embedded Cluster v3 doesn't support the `allowRollback` property. * Embedded Cluster v2 supports rolling back the application version only. It doesn't support rolling back the Embedded Cluster version. Users can roll back to an earlier application version only when the Embedded Cluster version stays the same. For example, after upgrading to 1.1.0, users can roll back to version 1.0.0 only if both 1.0.0 and 1.1.0 use the same Embedded Cluster version. #### Example ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: allowRollback: true ``` ### `additionalNamespaces` An array of additional namespaces as strings that the installer creates in the cluster. One common use case for `additionalNamespaces` is Operators, which often need to be able to manage resources in multiple namespaces in the cluster. For Embedded Cluster v3 installations, Embedded Cluster ensures that the private CA ConfigMap exists in each additional namespace. This allows Embedded Cluster to manage resources in the namespace. For more information about the ConfigMap, see [PrivatCACert](/reference/template-functions-static-context#privatecacert). For Embedded Cluster v2, KOTS existing cluster, and kURL installations, KOTS creates a Role and RoleBinding in each namespace. This ensures that the Admin Console has full access to manage resources in the namespace. KOTS also ensures that the application pull secret exists in each namespace, and that this secret has access to pull application images. #### Limitations * The `additionalNamespaces` property doesn't support Go templating. * If the current user account does not have access to create the additional namespaces, the installer will show an error and fail. #### Examples ##### Array of multiple additional namespaces ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: my-operator spec: additionalNamespaces: - namespace1 - namespace2 ``` ##### Dynamically-created namespaces For dynamically-created namespaces, specify `"*"`. ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: additionalNamespaces: - "*" ``` ### `additionalImages` An array of strings that reference images to include in air gap bundles and push to the local registry during installation. One common use case for `additionalImages` is Operators, which might need to include additional images that are not referenced until runtime. For more information about setting `additionalImages` for Embedded Cluster v2, KOTS existing cluster, or kURL installations, see [Defining Additional Images](/vendor/operator-defining-additional-images). #### Limitations * The `additionalImages` property doesn't support Go templating. * Supported for Embedded Cluster v2, KOTS existing cluster, and kURL installations only. Embedded Cluster v3 doesn't support the `additionalImages` property. #### Example ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: my-app spec: additionalImages: - elasticsearch:7.6.0 - quay.io/orgname/private-image:v1.2.3 - registry.replicated.com/my-operator/my-private-image:abd123f ``` ### `excludedImages` An array of strings that reference images to exclude from air gap bundles. #### Limitations * The `excludedImages` property doesn't support Go templating. * Supported for Embedded Cluster v2, KOTS existing cluster, and kURL installations only. Embedded Cluster v3 doesn't support the `excludedImages` property. #### Example ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: excludedImages: - auto # This image does not exist but is imported by the Istio Gateway chart ``` ### `requireMinimalRBACPrivileges` When true, `requireMinimalRBACPrivileges` requires minimal role-based access control (RBAC) for KOTS. When set to `true`, KOTS creates a namespace-scoped Role and RoleBinding instead of the default cluster-scoped ClusterRole and ClusterRoleBinding. By default, `requireMinimalRBACPrivileges` is false. For additional requirements and limitations related to using namespace-scoped RBAC, see [About Namespace-scoped RBAC](/vendor/packaging-rbac#min-rbac) in _Configuring KOTS RBAC_. #### Limitations * The `requireMinimalRBACPrivileges` property doesn't support Go templating. * Supported for KOTS existing cluster installations only. Embedded Cluster doesn't support the `requireMinimalRBACPrivileges` property. #### Example ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: requireMinimalRBACPrivileges: true ``` ### `supportMinimalRBACPrivileges` Allows your end customers to enable minimal role-based access control (RBAC). When set to `true`, KOTS supports creating a namespace-scoped Role and RoleBinding instead of the default cluster-scoped ClusterRole and ClusterRoleBinding. By default, `supportMinimalRBACPrivileges` is false. KOTS uses minimal RBAC only when you pass the `--use-minimal-rbac` flag with the `kots install` command. For additional requirements and limitations related to using namespace-scoped RBAC, see [About Namespace-scoped RBAC](/vendor/packaging-rbac#min-rbac) in _Configuring KOTS RBAC_. #### Limitations * The `supportMinimalRBACPrivileges` property doesn't support Go templating. * Supported for KOTS existing cluster installations only. Embedded Cluster doesn't support the `supportMinimalRBACPrivileges` property. #### Example ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: supportMinimalRBACPrivileges: true ``` ### `ports` Extra ports, in addition to the `8800` Admin Console port, that are port-forwarded when running the `kubectl kots admin-console` command. With ports specified, KOTS can establish port forwarding to simplify connections to the deployed application. When the application starts and the service is ready, the KOTS CLI prints the URL to access the port-forwarded service. For more information, see [Port Forwarding Services with KOTS](/vendor/admin-console-port-forward). #### About port forwarding in VM-based installations For installations on VMs or bare metal servers with Embedded Cluster v2 or kURL, KOTS does not automatically create port forwards. This is because KOTS cannot verify that the ports are secure and authenticated. Instead, Embedded Cluster v2 or kURL creates a NodePort service. This makes the Admin Console accessible on a port on the node (port `8800` for kURL or port `30000` for Embedded Cluster v2). You can expose additional ports on the node for Embedded Cluster v2 or kURL installations by creating NodePort services. For more information, see [Exposing Services Using NodePorts](/vendor/kurl-nodeport-services). #### Properties | Property | Description | | --- | --- | | `ports.serviceName` | The name of the service that receives the traffic. | | `ports.servicePort` | The `containerPort` of the Pod where the service is running. Ensure that you use the `containerPort` and not the `servicePort`. The `containerPort` and `servicePort` are often the same port, though it is possible that they are different. | | `ports.localPort` | The port to map on the local workstation. | | `ports.applicationUrl` | Optional. When set to the same URL as the one in the `descriptor.links.url` field of the Kubernetes SIG Application custom resource, KOTS adds a link on the Admin Console dashboard where users can access the given service. This process automatically links to the hostname in the browser where users access the Admin Console and appends the specified `localPort`. If not set, KOTS links the URL defined in the `descriptor.links.url` field of the Kubernetes SIG Application on the Admin Console dashboard. | #### Limitations * `ports` supports Go templates in the `ports.serviceName` and `ports.applicationUrl` fields only. Using Go templates in the `ports.localPort` or `ports.servicePort` fields results in an installation error similar to the following: `json: cannot unmarshal string into Go struct field ApplicationPort.spec.ports.servicePort of type int`. * Supported only for Embedded Cluster v2, KOTS existing cluster, and kURL installations. Embedded Cluster v3 doesn't support the `ports` property or port-forwarding services with KOTS. #### Example ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: ports: - serviceName: web servicePort: 9000 localPort: 9000 applicationUrl: "http://web" ``` ### `statusInformers` Resources to watch and report application status back to the user. When you include `statusInformers`, the dashboard can indicate when the application deployment is complete and the application is ready for use. `statusInformers` use the format `[namespace/]type/name`, where namespace is optional. For more information about including `statusInformers`, see [Enable and understand application status](/vendor/insights-app-status). :::note For Embedded Cluster v3 installations, you can define custom status informers using the Replicated SDK instead of listing them in the Application custom resource `statusInformers` field. For more information, see [Enable application status insights](/vendor/insights-app-status#enable-application-status-insights). ::: #### Examples ##### Plain text ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: statusInformers: - deployment/my-web-svc - deployment/my-worker ``` ##### Go templating The following example shows excluding a specific status informer based on a user-supplied value from the Admin Console Configuration screen: ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: statusInformers: - deployment/my-web-svc - '{{repl if ConfigOptionEquals "option" "value"}}deployment/my-worker{{repl else}}{{repl end}}' ``` ### `graphs` For installations with KOTS in existing cluster, `graphs` defines custom graphs to include on the Admin Console dashboard. For more information about how to create custom graphs, see [Adding Custom Graphs](/vendor/admin-console-prometheus-monitoring). The `graphs` key has the following fields: * `graphs.title`: The graph title. * `graphs.query`: The Prometheus query. * `graphs.legend`: The legend to use for the query line. You can use Prometheus templating in the `legend` fields with each element returned from the Prometheus query. The template escape sequence is `{{}}`. Use `{{ value }}`. For more information, see [Template Reference](https://prometheus.io/docs/prometheus/latest/configuration/template_reference/) in the Prometheus documentation. * `graphs.queries`: A list of queries containing a `query` and `legend`. * `graphs.yAxisFormat`: The format of the Y axis labels with support for all Grafana units. For more information, see [Visualizations](https://grafana.com/docs/features/panels/graph/#left-y-right-y) in the Grafana documentation. * `graphs.yAxisTemplate`: Y axis labels template. #### Limitation Embedded Cluster doesn't support the `graphs` property. #### Example ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: graphs: - title: User Signups query: 'sum(user_signup_events_total)' ``` ### `proxyRegistryDomain` (Deprecated) :::important `proxyRegistryDomain` is deprecated. For information about how to use a custom domain for the Replicated proxy registry, see [Use Custom Domains](/vendor/custom-domains-using). ::: The custom domain used for proxy.replicated.com. For more information, see [Using Custom Domains](/vendor/custom-domains-using). #### Limitation The `proxyRegistryDomain` property doesn't support Go templating. #### Example ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: proxyRegistryDomain: "proxy.yourcompany.com" ``` ### `replicatedRegistryDomain` (Deprecated) :::important `replicatedRegistryDomain` is deprecated. For information about how to use a custom domain for the Replicated registry, see [Use Custom Domains](/vendor/custom-domains-using). ::: The custom domain used for registry.replicated.com. For more information, see [Using Custom Domains](/vendor/custom-domains-using). #### Limitation The `replicatedRegistryDomain` property doesn't support Go templating. #### Example ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: replicatedRegistryDomain: "registry.yourcompany.com" ``` ### `targetKotsVersion` For KOTS existing cluster installations, `targetKotsVersion` specifies the version of KOTS to use. For more information, see [Setting Minimum and Target Versions for KOTS](/vendor/packaging-kots-versions). #### Limitations * The `targetKotsVersion` property doesn't support Go templating. * Supported for KOTS existing cluster installations only. Embedded Cluster doesn't support the `targetKotsVersion` property. To avoid installation failures, do not use `targetKotsVersion` in releases that support installation with Embedded Cluster. For more information, see [Setting Minimum and Target Versions for KOTS](/vendor/packaging-kots-versions). #### Example ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: targetKotsVersion: "1.130.2" ``` ### `minKotsVersion` For KOTS existing cluster installations, `minKotsVersion` sets the minimum KOTS version required to deploy the given release. KOTS blocks an installation or update if the deployed KOTS version is earlier than the `minKotsVersion`. For more information, see [Setting Minimum and Target Versions for KOTS](/vendor/packaging-kots-versions). #### Limitations * The `minKotsVersion` property doesn't support Go templating. * Supported for KOTS existing cluster installations only. Embedded Cluster doesn't support the `minKotsVersion` property. To avoid installation failures, do not use `minKotsVersion` in releases that support installation with Embedded Cluster. For more information, see [Setting Minimum and Target Versions for KOTS](/vendor/packaging-kots-versions). #### Example ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: your-application spec: minKotsVersion: "1.124.5" ``` --- # Velero Backup resource for snapshots This topic provides information about the supported fields in the Velero Backup resource for the Replicated KOTS snapshots feature. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview The Velero Backup custom resource enables the KOTS snapshots backup and restore feature. The backend of this feature uses the Velero open source project to back up Kubernetes manifests and persistent volumes. ## Example The following shows an example of the Velero Backup resource: ```yaml apiVersion: velero.io/v1 kind: Backup metadata: name: backup annotations: # `pvc-volume` will be the only volume included in the backup backup.velero.io/backup-volumes: pvc-volume spec: includedNamespaces: - '*' excludedNamespaces: - some-namespace orderedResources: pods: mysql/mysql-cluster-replica-0,mysql/mysql-cluster-replica-1 persistentvolumes: pvc-12345,pvc-67890 ttl: 720h hooks: resources: - name: my-hook includedNamespaces: - '*' excludedNamespaces: - some-namespace includedResources: - pods excludedResources: [] labelSelector: matchLabels: app: velero component: server pre: - exec: container: my-container command: - /bin/uname - -a onError: Fail timeout: 10s post: [] ``` ## Supported fields for full backups with snapshots {#fields} For partial backups with the snapshots feature, you can use all of the fields that Velero supports. See [Backups](https://velero.io/docs/v1.10/api-types/backup/) in the Velero documentation. However, not all fields are supported for full backups. The table below lists the fields that are supported for full backups with snapshots:
Field Name Description
includedNamespaces (Optional) Specifies an array of namespaces to include in the backup. If unspecified, all namespaces are included.
excludedNamespaces (Optional) Specifies an array of namespaces to exclude from the backup.
orderedResources (Optional) Specifies the order of the resources to collect during the backup process. This is a map that uses a key as the plural resource. Each resource name has the format NAMESPACE/OBJECTNAME. The object names are a comma delimited list. For cluster resources, use OBJECTNAME only.
ttl Specifies the amount of time before this backup is eligible for garbage collection. Default:720h (equivalent to 30 days). This value is configurable only by the customer.
hooks (Optional) Specifies the actions to perform at different times during a backup. The only supported hook is executing a command in a container in a pod (uses the pod exec API). Supports pre and post hooks.
hooks.resources (Optional) Specifies an array of hooks that are applied to specific resources.
hooks.resources.name Specifies the name of the hook. This value displays in the backup log.
hooks.resources.includedNamespaces (Optional) Specifies an array of namespaces that this hook applies to. If unspecified, the hook is applied to all namespaces.
hooks.resources.excludedNamespaces (Optional) Specifies an array of namespaces to which this hook does not apply.
hooks.resources.includedResources Specifies an array of pod resources to which this hook applies.
hooks.resources.excludedResources (Optional) Specifies an array of resources to which this hook does not apply.
hooks.resources.labelSelector (Optional) Specifies that this hook only applies to objects that match this label selector.
hooks.resources.pre Specifies an array of exec hooks to run before executing custom actions.
hooks.resources.post Specifies an array of exec hooks to run after executing custom actions. Supports the same arrays and fields as pre hooks.
hooks.resources.[post/pre].exec Specifies the type of the hook. exec is the only supported type.
hooks.resources.[post/pre].exec.container (Optional) Specifies the name of the container where the specified command will be executed. If unspecified, the first container in the pod is used.
hooks.resources.[post/pre].exec.command Specifies the command to execute. The format is an array.
hooks.resources.[post/pre].exec.onError (Optional) Specifies how to handle an error that might occur when executing the command. Valid values: Fail and Continue Default: Fail
hooks.resources.[post/pre].exec.timeout (Optional) Specifies how many seconds to wait for the command to finish executing before the action times out. Default: 30s
## Limitations {#limitations} - The following top-level Velero fields, or children of `spec`, are not supported in full backups: - `snapshotVolumes` - `volumeSnapshotLocations` - `labelSelector` - `includedResources` - `excludedResources` :::note Some of these fields are supported for hook arrays, as described in the previous field definition table. See [Supported Fields for Full Backups with Snapshots](#fields) above. ::: - All resources are included in the backup by default. However, resources can be excluded by adding `velero.io/exclude-from-backup=true` to the manifest files that you want to exclude. For more information, see [Configure Snapshots](/vendor/snapshots-configuring-backups). --- # Config The Replicated Config custom resource defines the application-specific configuration fields that you want to expose to your end customers. For example, if you let your customers bring their own external database, you could expose config fields for the database host, port, username, and password. During application installation or upgrade, your end customers provide values for each config field either through the UI or with the [ConfigValues](/reference/custom-resource-configvalues) custom resource (for headless installations). ## Example ```yaml apiVersion: kots.io/v1beta1 kind: Config metadata: name: outline-wiki-config spec: groups: - name: general title: General items: - name: hostname title: Hostname help_text: | The hostname customers will use to access Outline (e.g. outline.example.com). type: text required: true - name: database title: Database items: - name: postgres_type title: PostgreSQL type: select_one default: embedded_postgres items: - name: embedded_postgres title: Embedded PostgreSQL - name: external_postgres title: External PostgreSQL - name: embedded_postgres_password title: Embedded PostgreSQL Password type: password value: 'repl{{ RandomString 32 }}' when: 'repl{{ ConfigOptionEquals "postgres_type" "embedded_postgres" }}' help_text: | Auto-generated on first install. Leave as-is unless you need a specific password. - name: external_postgres_host title: Host type: text when: 'repl{{ ConfigOptionEquals "postgres_type" "external_postgres" }}' required: true - name: external_postgres_port title: Port type: text default: "5432" when: 'repl{{ ConfigOptionEquals "postgres_type" "external_postgres" }}' - name: external_postgres_database title: Database Name type: text default: outline when: 'repl{{ ConfigOptionEquals "postgres_type" "external_postgres" }}' - name: external_postgres_username title: Username type: text default: outline when: 'repl{{ ConfigOptionEquals "postgres_type" "external_postgres" }}' - name: external_postgres_password title: Password type: password when: 'repl{{ ConfigOptionEquals "postgres_type" "external_postgres" }}' required: true ``` The following images show how this Config custom resource renders in the Embedded Cluster v3 installation wizard: ![Config screen example](/images/config-screen-example.png) [View a larger version of this image](/images/config-screen-example.png) ![Config screen example](/images/config-screen-example-embedded-postgres.png) [View a larger version of this image](/images/config-screen-example-embedded-postgres.png) ## Use config values in your Helm chart {#use-config-values} After defining config fields, you map the user-supplied values to your Helm chart using the [HelmChart v2 custom resource](/reference/custom-resource-helmchart-v2). In the HelmChart CR's `values` key, use the `ConfigOption` template function to reference config field values by name. ### Example: Map config values to Helm chart values Given the Config example on this page, the following HelmChart CR maps the database configuration to Helm values: ```yaml apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: my-app spec: chart: name: my-app chartVersion: 1.0.0 values: postgresql: type: 'repl{{ ConfigOption "postgres_type" }}' host: 'repl{{ ConfigOption "external_postgres_host" }}' port: 'repl{{ ConfigOption "external_postgres_port" }}' database: 'repl{{ ConfigOption "external_postgres_database" }}' username: 'repl{{ ConfigOption "external_postgres_username" }}' password: 'repl{{ ConfigOption "external_postgres_password" }}' embeddedPassword: 'repl{{ ConfigOption "embedded_postgres_password" }}' hostname: 'repl{{ ConfigOption "hostname" }}' ``` The template functions are evaluated at install and upgrade time. The resulting values are passed to your Helm chart as if they were set in `values.yaml`. ### Common patterns The following are common patterns for using config values: - **Conditional Helm values**: Use `ConfigOptionEquals` to set values based on a selection: ```yaml values: postgresql: enabled: 'repl{{ ConfigOptionEquals "postgres_type" "embedded_postgres" }}' ``` - **Generated secrets**: Config fields with a `value` using `RandomString` generate a value on first install and persist it across upgrades: ```yaml # In the Config CR - name: session_secret title: Session Secret type: password hidden: true value: 'repl{{ RandomString 32 }}' ``` - **Boolean fields**: Use `ConfigOptionEquals` to convert a bool field to a Helm value: ```yaml values: features: enableFeatureX: 'repl{{ ConfigOptionEquals "enable_feature_x" "1" }}' ``` For more information about template functions for config values, see [Config Context](/reference/template-functions-config-context). ## Group properties Groups have a `name`, `title`, `description` and an array of `items`. ### `description` Descriptive help text for the group that displays on the config screen. Supports markdown formatting. To provide help text for individual items on the Config page, use the item `help_text` property. See [help_text](#help_text). ```yaml spec: groups: - name: example_group title: First Group # Provide a description of the input fields in the group description: Select whether or not to enable HTTP. items: - name: http_enabled title: HTTP Enabled type: bool default: "0" ``` ### `name` A unique identifier for the group. ```yaml spec: groups: # The name must be unique - name: example_group title: First Group items: - name: http_enabled title: HTTP Enabled type: bool default: "0" ``` ### `title` The title of the group that displays on the config screen. ```yaml spec: groups: - name: example_group # First Group is the heading that appears on the Config page title: First Group items: - name: http_enabled title: HTTP Enabled type: bool default: "0" ``` ### `when` The `when` property denotes groups that display on the config screen only when a condition evaluates to true. When the condition evaluates to false, the group does not display. This lets you conditionally show or hide fields so your end customers only see the options that are relevant to them. You can use Go template functions to create conditional statements. Replicated provides a set of Go template functions that you can use to evaluate conditions like the user's environment, their license entitlements, and their previous configuration choices. For more information, see [About Replicated Template Functions](/reference/template-functions-about). :::note `when` is a property of both groups and items. See [Item Properties > `when`](/reference/custom-resource-config#when-item). ::: #### Requirements and limitations * The `when` property accepts the following types of values: * Booleans * Strings that match "true", "True", "false", or "False" * For the `when` property to evaluate to true, the values compared in the conditional statement must match exactly without quotes #### Example ```yaml apiVersion: kots.io/v1beta1 kind: Config metadata: name: outline-wiki-config spec: groups: - name: database title: Database items: - name: postgres_type title: PostgreSQL type: select_one default: embedded_postgres items: - name: embedded_postgres title: Embedded PostgreSQL - name: external_postgres title: External PostgreSQL - name: embedded_postgres_password title: Embedded PostgreSQL Password type: password value: 'repl{{ RandomString 32 }}' when: 'repl{{ ConfigOptionEquals "postgres_type" "embedded_postgres" }}' help_text: | Auto-generated on first install. Leave as-is unless you need a specific password. - name: external_postgres_host title: Host type: text when: 'repl{{ ConfigOptionEquals "postgres_type" "external_postgres" }}' required: true - name: external_postgres_port title: Port type: text default: "5432" when: 'repl{{ ConfigOptionEquals "postgres_type" "external_postgres" }}' - name: external_postgres_database title: Database Name type: text default: outline when: 'repl{{ ConfigOptionEquals "postgres_type" "external_postgres" }}' - name: external_postgres_username title: Username type: text default: outline when: 'repl{{ ConfigOptionEquals "postgres_type" "external_postgres" }}' - name: external_postgres_password title: Password type: password when: 'repl{{ ConfigOptionEquals "postgres_type" "external_postgres" }}' required: true ``` ### `items` Each group contains an array of items that map to input fields on the config screen. All items have `name`, `title`, and `type` properties and belong to a single group. For more information, see [Item Properties](#item-properties) and [Item Types](#item-types). :::note If all items in a group hide because their `when` conditions evaluate to false, the group also hides, including its `title` and `description`. To ensure the group remains visible and shows messaging to the user, include a `label` item in the group without a `when` condition. ::: ## Item types The section describes each of the item types: - `bool` - `dropdown` - `file` - `heading` - `label` - `password` - `radio` - `select_one` (Deprecated) - `text` - `textarea` ### `bool` The `bool` input type should use a "0" or "1" to set the value ```yaml - name: group_title title: Group Title items: - name: http_enabled title: HTTP Enabled type: bool default: "0" ``` Boolean selector on the configuration screen [View a larger version of this image](/images/config-screen-bool.png) ### `dropdown` > Introduced in KOTS v1.114.0 The `dropdown` item type includes one or more nested items that display in a dropdown on the config screen. Dropdowns are especially useful for displaying long lists of options. You can also use the [`radio`](#radio) item type to display radio buttons for items with shorter lists of options. To set a default value for `dropdown` items, set the `default` field to the name of the target nested item. ```yaml spec: groups: - name: example_settings title: My Example Config items: - name: version title: Version default: version_latest type: dropdown items: - name: version_latest title: latest - name: version_123 title: 1.2.3 - name: version_124 title: 1.2.4 - name: version_125 title: 1.2.5 ``` Dropdown item type on config screen [View a larger version of this image](/images/config-screen-dropdown.png) Dropdown item type expanded [View a larger version of this image](/images/config-screen-dropdown-open.png) ### `file` A `file` is a special type of form field that renders an [``](https://www.w3schools.com/tags/tag_input.asp) HTML element. The form field captures only the file contents, not the filename. See the [`ConfigOptionData`](template-functions-config-context#configoptiondata) template function for examples on how to use the file contents in your application. ```yaml - name: certs title: TLS Configuration items: - name: tls_private_key_file title: Private Key type: file - name: tls_certificate_file title: Certificate type: file ``` File input field on the configuration screen [View a larger version of this image](/images/config-screen-file.png) ### `heading` The `heading` type allows you to display a group heading as a sub-element within a group. This is useful when you would like to use a config group to group items together, but still separate the items visually. ```yaml - name: ldap_settings title: LDAP Server Settings items: ... - name: ldap_schema type: heading title: LDAP schema ... ``` Heading on the configuration screen [View a larger versio of this image](/images/config-screen-heading.png) ### `label` The `label` type allows you to display an input label. ```yaml - name: email title: Email items: - name: email-address title: Email Address type: text - name: description type: label title: "Note: The system will send you an email every hour." ``` Email address label on the configuration screen [View a larger version of this image](/images/config-screen-label.png) ### `password` The `password` type is a text field that hides the character input. ```yaml - name: password_text title: Password Text type: password value: '{{repl RandomString 10}}' ``` Password text field on the configuration screen [View a larger version of this image](/images/config-screen-password.png) ### `radio` > Introduced in KOTS v1.114.0 The `radio` item type includes one or more nested items that display as radio buttons on the config screen. Radio buttons are especially useful for displaying short lists of options. You can also use the [`dropdown`](#dropdown) item type for items with longer lists of options. To set a default value for `radio` items, set the `default` field to the name of the target nested item. ```yaml spec: groups: - name: example_settings title: My Example Config items: - name: authentication_type title: Authentication Type default: authentication_type_anonymous type: radio items: - name: authentication_type_anonymous title: Anonymous - name: authentication_type_password title: Password ``` ### `select_one` (Deprecated) :::important The `select_one` item type is deprecated. Use [`radio`](#radio) instead. ::: `select_one` items must contain nested items. The nested items display as radio buttons on the config screen. Use the `name` field of a `select_one` item with Replicated template functions in the Config context (such as ConfigOption or ConfigOptionEquals) to return the user-selected option. For example, if the user selects the **Password** option for the `select_one` item in the following example, then the template function `'{{repl ConfigOption "authentication_type"}}'` returns `authentication_type_password`. For more information about working with template functions in the Config context, see [Config Context](/reference/template-functions-config-context). ```yaml spec: groups: - name: example_settings title: My Example Config description: Configuration to serve as an example for creating your own. items: - name: authentication_type title: Authentication Type default: authentication_type_anonymous type: select_one items: - name: authentication_type_anonymous title: Anonymous - name: authentication_type_password title: Password ``` Select one field on the configuration screen ### `text` A `text` input field allows users to enter a string value. Optionally, all additional properties are available for this input type. ```yaml - name: example_text_input title: Example Text Input type: text ``` Text field on the configuration screen :::important Do not store secrets or passwords in `text` items because they are not encrypted or masked and can be accessed. Instead, use [`password`](#password) items. ::: ### `textarea` A `textarea` items creates a multi-line text input for when users have to enter a sizeable amount of text. ```yaml - name: custom_key title: Set your secret key for your app description: Paste in your Custom Key items: - name: key title: Key type: textarea - name: hostname title: Hostname type: text ``` Text area field on the configuration screen ## Item properties Items have a `name`, `title`, `type`, and other optional properties. ### `affix` Affix items `left` or `right` to display them on the same line on the config screen. Specify the `affix` field to all of the items in a particular group to preserve the line spacing and prevent the appearance of crowded text. #### Example ```yaml groups: - name: example_settings title: My Example Config description: Configuration to serve as an example for creating your own. items: - name: username title: Username type: text required: true affix: left - name: password title: Password type: password required: true affix: right ``` ### `default` Defines the default value for the config item. If the user does not provide a value for the item, the `default` value takes effect. If the `default` value is not associated with a `password` type config item, then it appears as placeholder text on the config screen. The installer reevaluates Go template functions in the `default` property each time the user changes their configuration settings. #### Example ```yaml - name: custom_key title: Set your secret key for your app description: Paste in your Custom Key items: - name: key title: Key type: text value: "" default: change me ``` Default change me value displayed under the config field [View a larger version of this image](/images/config-default.png) ### `help_text` Displays a helpful message under the `title` for the config item on the config screen. The property supports markdown syntax. For more information, see [Basic writing and formatting syntax](https://guides.github.com/features/mastering-markdown/) in the GitHub Docs. #### Example ```yaml - name: http_settings title: HTTP Settings items: - name: http_enabled title: HTTP Enabled help_text: Check to enable the HTTP listener type: bool ``` Config field with help text underneath [View a larger version of this image](/images/config-help-text.png) ### `hidden` Hidden items are not visible on the config screen. When you assign a template function that generates a value to a `value` property, you can use the `readonly` and `hidden` properties to define whether or not the generated value is ephemeral or persistent between changes to the configuration settings for the application. For more information, see [RandomString](template-functions-static-context#randomstring) in _Static Context_. #### Limitation The `hidden` property doesn't support Go templating. #### Example ```yaml - name: secret_key title: Secret Key type: password hidden: true value: "{{repl RandomString 40}}" ``` ### `name` (Required) A unique identifier for the config item. Item names must be unique both within the group and across all groups. The item `name` is not displayed on the config screen. Use the item `name` with Replicated template functions in the Config context (such as ConfigOption or ConfigOptionEquals) to return the value of the item. For more information, see [Config Context](/reference/template-functions-config-context). #### Example ```yaml - name: http_settings title: HTTP Settings items: - name: http_enabled title: HTTP Enabled type: bool ``` ### `readonly` Readonly items display on the config screen and users cannot edit their value. When you assign a template function that generates a value to a `value` property, you can use the `readonly` and `hidden` properties to define whether or not the generated value is ephemeral or persistent between changes to the configuration settings for the application. For more information, see [RandomString](template-functions-static-context#randomstring) in _Static Context_. #### Limitation The `readonly` property doesn't support Go templating. #### Example ```yaml - name: key title: Key type: text value: "" default: change me - name: unique_key title: Unique Key type: text value: "{{repl RandomString 20}}" readonly: true ``` Default change me value displayed under the config field [View a larger version of this image](/images/config-readonly.png) ### `recommended` Displays a Recommended tag for the config item on the config screen. #### Limitations * The `recommended` property doesn't support Go templating. * Embedded Cluster v3 doesn't support the `recommended` property #### Example ```yaml - name: recommended_field title: My recommended field type: bool default: "0" recommended: true ``` config field with green recommended tag [View a larger version of this image](/images/config-recommended-item.png) ### `required` Displays a Required tag for the config item on the config screen. A required item prevents the application from starting until it has a value. #### Limitation The `required` property doesn't support Go templating. #### Example ```yaml - name: custom_key title: Set your secret key for your app description: Paste in your Custom Key items: - name: key title: Key type: text value: "" default: change me required: true ``` config field with yellow required tag [View a larger version of this image](/images/config-required-item.png) ### `title` (Required) The title of the config item that displays on the config screen. #### Example ```yaml - name: http_settings title: HTTP Settings items: - name: http_enabled title: HTTP Enabled help_text: Check to enable the HTTP listener type: bool ``` Config field with help text underneath [View a larger version of this image](/images/config-help-text.png) ### `type` (Required) Each item has a `type` property that defines the type of user input accepted by the field. The `type` property supports the following values: For information about each type, see [Item Types](#item-types). #### Limitation The `type` property doesn't support Go templating. #### Example ```yaml - name: group_title title: Group Title items: - name: http_enabled title: HTTP Enabled type: bool default: "0" ``` field named HTTP Enabled with disabled checkbox [View a larger version of this image](/images/config-screen-bool.png) ### `value` Defines the value of the config item. Data that you add to `value` appears as the HTML input value for the config item on the config screen. If the config item is not readonly, then the data that you add to `value` is overwritten by any user input for the item. If the item is readonly, then the data that you add to `value` cannot be overwritten. When you assign a template function that generates a value to a `value` property, you can use the `readonly` and `hidden` properties to define whether or not the generated value is ephemeral or persistent between changes to the configuration settings for the application. For more information, see [RandomString](template-functions-static-context#randomstring) in _Static Context_. #### Example ```yaml - name: custom_key title: Set your secret key for your app description: Paste in your Custom Key items: - name: key title: Key type: text value: "{{repl RandomString 20}}" ``` config field with random string as HTML input [View a larger version of this image](/images/config-value-randomstring.png) ### `when` {#when-item} The `when` property denotes items that display on the config screen only when a condition evaluates to true. When the condition evaluates to false, the item does not display. This lets you conditionally show or hide fields so your end customers only see the options that are relevant to them. You can use Go template functions to create conditional statements. Replicated provides a set of Go template functions that you can use to evaluate conditions like the user's environment, their license entitlements, and their previous configuration choices. For more information, see [About Replicated Template Functions](/reference/template-functions-about). :::note `when` is a property of both groups and items. See [Group Properties > `when`](/reference/custom-resource-config#when) above. ::: #### Requirements * The `when` property accepts the following types of values: * Booleans * Strings that match "true", "True", "false", or "False" * For the `when` property to evaluate to true, the values compared in the conditional statement must match exactly without quotes - Do not apply `when` to items nested under a `radio`, `dropdown`, or `select_one` item. To conditionally show or hide `radio`, `dropdown`, or `select_one` items, apply the `when` property to the item itself. #### Example Display the `database_host` and `database_password` items only when the user selects `external` for the `db_type` item: ```yaml - name: database_settings_group title: Database Settings items: - name: db_type title: Database Type type: radio default: external items: - name: external title: External - name: embedded title: Embedded DB - name: database_host title: Database Hostname type: text when: repl{{ (ConfigOptionEquals "db_type" "external")}} - name: database_password title: Database Password type: password when: repl{{ (ConfigOptionEquals "db_type" "external")}} ``` External option selected and conditional fields displayed [View a larger version of this image](/images/config-when-enabled.png) Embedded DB option selected and no additional fields displayed [View a larger version of this image](/images/config-when-disabled.png) ### `validation` Use the `validation` property to validate an item's value and specify custom validation rules that determine whether the value is valid. You can use regex to validate whether an item's value matches the provided regular expression `pattern`. The regex pattern should be of the [RE2 regular expression](https://github.com/google/re2/wiki/Syntax) type and can validate the `text`, `textarea`, `password`, and `file` field types. Based on specified validation rules, the item is validated and a validation message is returned if the validation rule is not satisfied. A default message is returned if there is an empty validation message. The validation rules are as follows: - An item is validated only when its value is not empty. - Items of types `text`, `textarea`, `password`, and `file` are validated, but `repeatable` items are not validated. - If an item is marked as `hidden` or if its `when` condition is set to `false`, the item is not validated. - If a group `when` condition is set to `false`, the items in the group are not validated. #### Limitation The `validation` property doesn't support Go templating. #### Example Validates and returns if `password` value is not matching the regex. The `jwt_token` file content is only validated if the file is uploaded since it is optional. ``` - name: smtp-settings title: SMTP Settings - name: smtp_password title: SMTP Password type: password required: true validation: regex: pattern: ^(?:[\w@#$%^&+=!*()_\-{}[\]:;"'<>,.?\/|]){8,16}$ message: The password must be between 8 and 16 characters long and can contain a combination of uppercase letters, lowercase letters, digits, and special characters. - name: jwt_token title: JWT token type: file validation: regex: pattern: ^[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]*$ message: Upload a file with valid JWT token. ``` Password validation error [View a larger version of this image](/images/regex_password_validation_error.png) File validation error only when uploaded [View a larger version of this image](/images/regex_file_validation_error.png) ## Repeatable Items A repeatable config item copies a YAML array entry or YAML document for as many values as are provided. Any number of values can be added to a repeatable item to generate additional copies. To make an item repeatable, set `repeatable` to true: ```yaml - name: ports_group items: - name: serviceport title: Service Port type: text repeatable: true ``` Repeatable items do not use the `default` or `value` fields, but instead a `valuesByGroup` field. `valuesByGroup` must have an entry for the parent Config Group name, with all of the default `key:value` pairs nested in the group. The repeatable item requires at least one default entry: ```yaml valuesByGroup: ports_group: port-default-1: "80" ``` ### Limitations * Repeatable items work only for text, textarea, and file types. * Repeatable item names must only consist of lower case alphanumeric characters. * Repeatable items are only supported for Kubernetes manifests, not Helm charts. ### Template targets Repeatable items require that you provide at least one `template`. The `template` defines a YAML target in the manifest to duplicate for each repeatable item. Required fields for a template target are `apiVersion`, `kind`, and `name`. `namespace` is an optional template target field to match a YAML document's `metadata.namespace` property when the same filename appears in multiple namespaces. The installer duplicates the entire YAML node at the target, including nested fields. The `yamlPath` field of the `template` must denote index position for arrays using square brackets. For example, `spec.ports[0]` selects the first port entry for duplication. The installer appends all duplicate YAML to the final array in the `yamlPath`. `yamlPath` must end with an array. **Example:** ```yaml templates: - apiVersion: v1 kind: Service name: my-service namespace: my-app yamlPath: 'spec.ports[0]' ``` If the `yamlPath` field is not present, the installer replaces the entire YAML document matching the `template` with a copy for each repeatable item entry. The `metadata.name` field of the new document reflects the repeatable item `key`. ### Templating Use the delimiters `repl[[ .itemName ]]` or `[[repl .itemName ]]` for repeat items. Place these delimiters anywhere inside the `yamlPath` target node: ```yaml - port: repl{{ ConfigOption "[[repl .serviceport ]]" | ParseInt }} name: '[[repl .serviceport ]]' ``` This repeatable templating is not compatible with sprig templating functions. Use it to insert repeatable `keys` into the manifest. You can nest repeatable templating inside Replicated config templating. ### Ordering The installer processes repeatable templates before config template rendering. The installer processes repeatable items in order of the template targets in the Config Spec file. Effectively, this ordering is from the top of the Config Spec, by Config Group, by Config Item, and then by template target. ```yaml - name: ports_group items: - name: serviceport title: Service Port type: text repeatable: true templates: - apiVersion: v1 #processed first kind: Service name: my-service namespace: my-app yamlPath: 'spec.ports[0]' - apiVersion: v1 #processed second kind: Service name: my-service namespace: my-app {other item properties ...} - name: other_ports title: Other Service Port type: text repeatable: true templates: - apiVersion: v1 #processed third kind: Service name: my-other-service namespace: my-app {other item properties ...} - name: deployments items: - name: deployment-name title: Deployment Names type: text repeatable: true templates: - apiVersion: apps/v1 #processed fourth kind: Deployment name: my-deployment namespace: my-app {other item properties ...} ``` ### Repeatable examples In these examples, the release includes the default service port "80". When you add port 443 as an additional port on the config screen, The installer stores it in the ConfigValues file. #### Repeatable item example for a yamlPath **Config custom resource manifest file:** ```yaml - name: ports_group items: - name: serviceport title: Service Port type: text repeatable: true templates: - apiVersion: v1 kind: Service name: my-service namespace: my-app yamlPath: spec.ports[0] valuesByGroup: ports_group: port-default-1: "80" ``` **Config values:** ```yaml apiVersion: kots.io/v1beta1 kind: ConfigValues metadata: name: example_app spec: values: port-default-1: repeatableItem: serviceport value: "80" serviceport-8jdn2bgd: repeatableItem: serviceport value: "443" ``` **Template manifest:** ```yaml apiVersion: v1 kind: Service metadata: name: my-service namespace: my-app spec: type: NodePort ports: - port: repl{{ ConfigOption "[[repl .serviceport ]]" | ParseInt }} name: '[[repl .serviceport ]]' selector: app: repeat_example component: my-deployment ``` **After repeatable config processing:** **Note**: This phase is internal to configuration rendering for KOTS. This example is only provided to further explain the templating process.* ```yaml apiVersion: v1 kind: Service metadata: name: my-service namespace: my-app spec: type: NodePort ports: - port: repl{{ ConfigOption "port-default-1" | ParseInt }} name: 'port-default-1' - port: repl{{ ConfigOption "serviceport-8jdn2bgd" | ParseInt }} name: 'serviceport-8jdn2bgd' selector: app: repeat_example component: my-deployment ``` **Resulting manifest:** ```yaml apiVersion: v1 kind: Service metadata: name: my-service namespace: my-app spec: type: NodePort ports: - port: 80 name: port-default-1 - port: 443 name: serviceport-8jdn2bgd selector: app: repeat_example component: my-deployment ``` #### Repeatable Item Example for an Entire Document **Config spec:** ```yaml - name: ports_group items: - name: serviceport title: Service Port type: text repeatable: true templates: - apiVersion: v1 kind: Service name: my-service namespace: my-app valuesByGroup: ports_group: port-default-1: "80" ``` **Config values:** ```yaml apiVersion: kots.io/v1beta1 kind: ConfigValues metadata: name: example_app spec: values: port-default-1: repeatableItem: serviceport value: "80" serviceport-8jdn2bgd: repeatableItem: serviceport value: "443" ``` **Template manifest:** ```yaml apiVersion: v1 kind: Service metadata: name: my-service namespace: my-app spec: type: NodePort ports: - port: repl{{ ConfigOption "[[repl .serviceport ]]" | ParseInt }} selector: app: repeat_example component: repl[[ .serviceport ]] ``` **After repeatable config processing:** **Note**: This phase is internal to configuration rendering for KOTS. This example is only provided to further explain the templating process.* ```yaml apiVersion: v1 kind: Service metadata: name: port-default-1 namespace: my-app spec: type: NodePort ports: - port: repl{{ ConfigOption "port-default-1" | ParseInt }} selector: app: repeat_example component: port-default-1 --- apiVersion: v1 kind: Service metadata: name: serviceport-8jdn2bgd namespace: my-app spec: type: NodePort ports: - port: repl{{ ConfigOption "serviceport-8jdn2bgd" | ParseInt }} selector: app: repeat_example component: serviceport-8jdn2bgd ``` **Resulting manifest:** ```yaml apiVersion: v1 kind: Service metadata: name: port-default-1 namespace: my-app spec: type: NodePort ports: - port: 80 selector: app: repeat_example component: port-default-1 --- apiVersion: v1 kind: Service metadata: name: serviceport-8jdn2bgd namespace: my-app spec: type: NodePort ports: - port: 443 selector: app: repeat_example component: serviceport-8jdn2bgd ``` --- # ConfigValues This topic describes the Replicated ConfigValues resource. Use ConfigValues to set application configuration values during automated or headless installations from the command line. ## Overview The ConfigValues resource lists the values and defaults for each application configuration item defined in the Replicated [Config](custom-resource-config) resource in the release. In automated or headless installations, end users set configuration values from the command line rather than through the UI. They provide a ConfigValues resource with the install command. The following image shows how application configuration items defined a Config resource map to a ConfigValues resource: ![Config fields mapped from Config resource to ConfigValues resource](/images/configvalues-diagram.png) [View a larger version of this image](/images/configvalues-diagram.png) As shown in the preceding image, the `values` key in the ConfigValues resource lists each item from the Config resource by its `name`. For each item, the ConfigValues resource lists the user-supplied value and the default defined in the Config resource (if applicable). ## Example ```yaml apiVersion: kots.io/v1beta1 kind: ConfigValues spec: values: config_item_name: default: example_default_value value: example_value boolean_config_item_name: value: "1" password_config_item_name: valuePlaintext: exampleplaintextpassword select_one_config_item_name: default: default_option_name value: selected_option_name ``` ## Requirements * Linux operating system * cgroups v2 (required for Kubernetes versions 1.35 and later) * x86-64 architecture * systemd * At least 2GB of memory and 2 CPU cores * The disk on the host must have a maximum P99 write latency of 10 ms. This supports etcd performance and stability. For more information about the disk write latency requirements for etcd, see [Disks](https://etcd.io/docs/latest/op-guide/hardware/#disks) in _Hardware recommendations_ and [What does the etcd warning “failed to send out heartbeat on time” mean?](https://etcd.io/docs/latest/faq/) in the etcd documentation. * The user performing the installation must have root access to the machine, such as with `sudo`. * The data directory used by Embedded Cluster must have 40Gi or more of total space and be less than 80% full. By default, the data directory is `/var/lib/APP_SLUG`, where `APP_SLUG` is the unique slug of the application. The directory can be changed by passing the `--data-dir` flag with the Embedded Cluster `install` command. For more information, see [install](/embedded-cluster/v3/embedded-cluster-install). Note that in addition to the primary data directory, Embedded Cluster creates directories and files in the following locations: - `/etc/cni` - `/etc/k0s` - `/opt/cni` - `/opt/containerd` - `/run/calico` - `/run/containerd` - `/run/k0s` - `/sys/fs/cgroup/kubepods` - `/sys/fs/cgroup/system.slice/containerd.service` - `/sys/fs/cgroup/system.slice/k0scontroller.service` - `/usr/libexec/k0s` - `/var/lib/calico` - `/var/lib/cni` - `/var/lib/containers` - `/var/lib/kubelet` - `/var/log/calico` - `/var/log/containers` - `/var/log/APP_SLUG`, where `APP_SLUG` is the unique slug for the application - `/var/log/pods` - `/usr/local/bin/k0s` * (Online installations only) Access to replicated.app and proxy.replicated.com or your custom domain for each * Embedded Cluster is based on k0s, so all k0s system requirements and external runtime dependencies apply. See [System requirements](https://docs.k0sproject.io/stable/system-requirements/) and [External runtime dependencies](https://docs.k0sproject.io/stable/external-runtime-deps/) in the k0s documentation. ## Limitation Replicated template functions are not supported in the ConfigValues resource. To use a template function for a config item's value, add it to the `default` or `value` property in the [Config](custom-resource-config) resource instead. For more information about working with Replicated template functions, see [About Replicated Template Functions](/reference/template-functions-about). ## ConfigValues spec ### values.[item_name].default The item's default value, as defined in the [Config](custom-resource-config) custom resource in the release. #### Example ```yaml apiVersion: kots.io/v1beta1 kind: ConfigValues spec: values: certificate_source: default: generate_internal deploy_postgres: default: "1" value: "0" service_type: default: cluster_ip value: node_port node_port_port: default: "443" value: "3000" ``` ### values.[item_name].value The user-supplied value for the application configuration item. #### Example ```yaml apiVersion: kots.io/v1beta1 kind: ConfigValues spec: values: slack_clientid: value: T057KR02S slackernews_domain: value: hello.ingress.replicatedcluster.com slackernews_admin_user_emails: value: mandy@nitflex.com, jeff@nitflex.com, anil@nitflex.com service_type: value: node_port node_port_port: value: "443" ``` :::note For KOTS or Embedded Cluster v2 installations, the `value` property in the auto-generated ConfigValues might also contain one of the following: * A value rendered by a Replicated template function. For example, a [`hidden`](/reference/custom-resource-config#hidden) item defined in the Config resource could use the Replicated [RandomString](/reference/template-functions-static-context#randomstring) template function to set the value with `value: repl{{ RandomString 40}}`. In this case, the template function generates the value for the item in the ConfigValues, not the user. For more information about using Replicated template functions, see [About Replicated Template Functions](/reference/template-functions-about). * An encrypted empty string. For any `password` configuration items without a user-supplied value, the Admin Console sets the value to an empty string. In the ConfigValues generated for the installation, this empty string is automatically encrypted. * An empty mapping (`{}`). For configuration items without a user-supplied `value` or a `default`, KOTS sets the value to `{}`. ::: ### values.[item_name].valuePlaintext {#valueplaintext} A plain text value. For any configuration items of type [`password`](/reference/custom-resource-config#password), provide the password in plain text in the `valuePlaintext` property rather than in the `value` property. During installation, the installer encrypts the values set in `valuePlaintext`. In the ConfigValues resource automatically generated as part of installation, the installer saves these encrypted values in `value` properties. The following image shows how the installer encrypts a `valuePlaintext` value and adds it to a `value` property during installation: ![valuesPlaintext field in ConfigValues](/images/configvalues-plaintext.png) [View a larger version of this image](/images/configvalues-plaintext.png) #### Example ```yaml apiVersion: kots.io/v1beta1 kind: ConfigValues spec: values: slack_bot_token: valuePlaintext: examplebottoken slack_clientsecret: valuePlaintext: exampleclientsecret slack_user_token: valuePlaintext: exampleusertoken ``` ## (KOTS and Embedded Cluster v2 Only) Download the ConfigValues for an installation {#download} This section applies only to installations with KOTS in an existing cluster or with Embedded Cluster v2. To get the ConfigValues file from an installed application instance: 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](/embedded-cluster/v3/installing-embedded) or [Online Installation in Existing Clusters](/enterprise/installing-existing-cluster). 1. Depending on the installer that you used, do one of the following to get the ConfigValues for the installed instance: * **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) * **For KOTS installations in an existing cluster**: Run the `kubectl kots get config` command to view the generated ConfigValues file: ```bash 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). --- # HelmChart v2 This topic describes the Replicated HelmChart v2 custom resource. ## Overview Each Helm chart `.tgz` archive in a release requires a unique HelmChart custom resource. The HelmChart custom resource provides the Replicated installer with the instructions needed to process and deploy the given Helm chart. The HelmChart custom resource also generates a list of required images for the chart, which is necessary for the following use cases: * Air gap installations with the Helm CLI or with a Replicated installer * Online installations with a Replicated installer where the user will push images to a local image registry * Online or air gap installations that use the [Security Center (Alpha)](/vendor/security-center-about) to scan and report on Helm chart images ## Example The following is an example manifest file for the HelmChart v2 custom resource: ```yaml apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: # chart identifies a matching chart from a .tgz chart: name: samplechart chartVersion: 3.1.7 releaseName: samplechart-release-1 exclude: "repl{{ ConfigOptionEquals 'include_chart' 'include_chart_no'}}" # weight determines the order that charts are applied, with lower weights first. weight: 42 # helmUpgradeFlags specifies additional flags to pass to the `helm upgrade` command. helmUpgradeFlags: - --skip-crds - --no-hooks - --timeout - 1200s - --history-max=15 # values are used in the customer environment as a pre-render step # these values are supplied to helm template values: postgresql: enabled: repl{{ ConfigOptionEquals 'postgres_type' 'embedded_postgres'}} optionalValues: - when: "repl{{ ConfigOptionEquals 'postgres_type' 'external_postgres'}}" recursiveMerge: false values: postgresql: postgresqlDatabase: "repl{{ if ConfigOptionEquals 'postgres_type' 'external_postgres'}}repl{{ ConfigOption 'external_postgres_database'}}repl{{ end}}" postgresqlUsername: "repl{{ if ConfigOptionEquals 'postgres_type' 'external_postgres'}}repl{{ ConfigOption 'external_postgres_username'}}repl{{ end}}" postgresqlHost: "repl{{ if ConfigOptionEquals 'postgres_type' 'external_postgres'}}repl{{ ConfigOption 'external_postgres_host'}}repl{{ end}}" postgresqlPassword: "repl{{ if ConfigOptionEquals 'postgres_type' 'external_postgres'}}repl{{ ConfigOption 'external_postgres_password'}}repl{{ end}}" postgresqlPort: "repl{{ if ConfigOptionEquals 'postgres_type' 'external_postgres'}}repl{{ ConfigOption 'external_postgres_port'}}repl{{ end}}" # namespace allows for a chart to be installed in an alternate namespace to # the default namespace: samplechart-namespace # builder values render the chart with all images and manifests. # builder is used to create `.airgap` packages and to support end users # who use private registries builder: postgresql: enabled: true ``` ## Properties ### chart The `chart` key allows for a mapping between the data in this definition and the chart archive itself. You can create multiple HelmChart resources that all reference a single chart archive. `chart` has the following properties: | Property | Description | | --- | --- | | `chart.name` | The name of the chart. This value must exactly match the `name` field from a `Chart.yaml` in a `.tgz` chart archive that is also included in the release. If the names do not match, then the installation can error or fail. | | `chart.chartVersion` | The version of the chart. This value must match the `version` field from a `Chart.yaml` in a `.tgz` chart archive that is also included in the release. | #### Example ```yaml apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: chart: name: samplechart chartVersion: 3.1.7 ``` ### releaseName Specifies the release name to use when installing this instance of the Helm chart. Defaults to the chart name. The release name must be unique across all charts deployed in the namespace. To deploy multiple instances of the same Helm chart in a release, add a separate HelmChart custom resource with a unique release name for each instance. Must be a valid Helm release name that matches regex `^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$` and is no longer than 53 characters. #### Example ```yaml apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: releaseName: samplechart-release-1 ``` ### weight For installations with a Replicated installer, `weight` specifies the installation order of the Helm charts in the release. Charts are installed by weight in ascending order with lower weights first. `weight` also determines the uninstall order, where charts are uninstalled by weight in descending order with higher weights first. For installations with the Helm CLI, the Replicated Enterprise Portal uses the `weight` property to order the list of charts in the installation and update instructions. For more information, see [View Install and Update Instructions](/vendor/enterprise-portal-use#view-install-and-update-instructions) in _Access and Use the Enterprise Portal_. **Supported values:** Positive or negative integers. **Default:** `0` #### Example ```yaml apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: weight: 42 ``` ### helmUpgradeFlags Specifies additional flags to pass to the `helm upgrade` command. The Replicated installer runs `helm upgrade` for _all_ deployments, not just upgrades, by specifying the `--install` flag. The Replicated installer passes these flags in addition to the flags it passes by default. The values specified in this field take precedence if the installer already passes the same flag. Template functions can parse the `helmUpgradeFlags` attribute. For more information, see [About Replicated template functions](/reference/template-functions-about). For non-boolean flags that require an additional argument, such as `--timeout 1200s`, you must use an equal sign (`=`) or specify the additional argument separately in the array. :::note KOTS passes `--wait` to Helm by default, which means Helm waits for all non-hook resources to reach a Ready state before running post-install or post-upgrade hooks. If a non-hook resource depends on a resource created by a hook (for example, a Deployment with an init container that waits for a database custom resource created by a post-install hook), this creates a circular deadlock. To avoid this, add `--wait=false` and `--wait-for-jobs=false` to `helmUpgradeFlags`. These flags are appended after the defaults and override them. ::: #### Examples ```yaml helmUpgradeFlags: - --timeout - 1200s - --history-max=15 ``` Disable the default `--wait` behavior to prevent deadlocks with post-install hooks: ```yaml helmUpgradeFlags: - --wait=false - --wait-for-jobs=false ``` ### exclude When the installer processes your release, it excludes any Helm chart if the output of the `exclude` field is `true`. Template functions can parse the `exclude` attribute. See [About Replicated template functions](template-functions-about). #### Example ```yaml apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: exclude: '{{repl ConfigOptionEquals "postgres_type" "external_postgres" }}' ``` ### values Use the `values` key to set or delete values in the corresponding Helm chart's `values.yaml` file. Any values that you include in the `values` key must match values in the Helm chart `values.yaml`. For example, `spec.values.images.pullSecret` in the HelmChart custom resource matches `images.pullSecret` in the Helm chart `values.yaml`. During installation or upgrade with a Replicated installer, the installer merges `values` with the Helm chart `values.yaml` in the chart archive. Only include values in the `values` key that you want to set or delete. #### Examples ##### Set static values ```yaml # Helm chart values.yaml replicatedOnlyValue: enabled: false ``` ```yaml # HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart spec: values: replicatedOnlyValue: enabled: true ``` ##### Set values with Replicated Config template functions Using Replicated template functions in the [Config](/reference/template-functions-config-context) context allows you to set Helm values based on user-supplied values from the Admin Console configuration page. The following Helm chart `values.yaml` file contains `postgresql.enabled`, which is set to `false`: ```yaml # Helm chart values.yaml postgresql: enabled: false ``` The following HelmChart custom resource contains a mapping to `postgresql.enabled` in its `values` key: ```yaml # HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: values: postgresql: enabled: repl{{ ConfigOptionEquals `postgres_type` `embedded_postgres`}} ``` The `values.postgresql.enabled` field in the HelmChart custom resource above uses the Replicated [ConfigOptionEquals](/reference/template-functions-config-context#configoptionequals) template function to evaluate the user's selection for a `postgres_type` configuration option. During installation or upgrade, the template function is rendered to true or false based on the user's selction. Then, the Replicated installer sets the matching `postgresql.enabled` value in the Helm chart `values.yaml` file accordingly. ##### Set values with Replicated License template functions Using Replicated template functions in the [License](/reference/template-functions-license-context) context allows you to set Helm values based on the unique license file used for installation or upgrade. For example, the following HelmChart custom resource uses the Replicated [LiencseFieldValue](/reference/template-functions-license-context#licensefieldvalue) template function to evaluate if the license has the boolean `newFeatureEntitlement` field set to `true`: ```yaml # HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: values: newFeature: enabled: repl{{ LicenseFieldValue "newFeatureEntitlement" }} ``` During installation or upgrade, the LicenseFieldValue template function is rendered based on the user's license. Then, the Replicated installer sets the matching `newFeature.enabled` value in the Helm chart `values.yaml` file accordingly. ##### Delete a default value key A common use case for deleting default value keys is when you include a community Helm chart as a dependency. Because you cannot control how the community chart is built and structured, you might want to change some of the default behavior. For more information about using a `null` value to delete a key, see [Deleting a Default Key](https://helm.sh/docs/chart_template_guide/values_files/#deleting-a-default-key) in the Helm documentation. ```yaml # HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart spec: values: exampleKey: "null" ``` ### optionalValues Use the `optionalValues` key to set values in the Helm chart `values.yaml` file when a conditional statement evaluates to true. For example, a customer including an optional application component might need Helm chart values related to that component. `optionalValues` includes the following properties: | Property | Description | | --- | --- | | `optionalValues.when` | Defines a conditional statement that must evaluate to true for the Helm chart to apply the values in `optionalValues.values`. The Replicated installer defers evaluation of the conditional in `optionalValues.when` until render time in the customer environment. | | `optionalValues.recursiveMerge` | The `optionalValues.recursiveMerge` boolean defines how the Replicated installer merges `values` and `optionalValues`. When `optionalValues.recursiveMerge` is false, the top level keys in `optionalValues` override the top level keys in `values`. When `optionalValues.recursiveMerge` is true, the installer includes all keys from `values` and `optionalValues`. In the case of a conflict where there is a matching key in `optionalValues` and `values`, the Replicated installer uses the value of the key from `optionalValues`. By default, `optionalValues.recursiveMerge` is false. For an example, see [Recursive merge](#recursive-merge) on this page.| | `optionalValues.values` | Array of key value pairs to set in the Helm chart when the specified condition is true. Supports static values and Replicated template functions. | #### Examples ##### Set optional values with Replicated template functions ```yaml # Replicated HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: outline spec: chart: name: outline chartVersion: 0.7.3 releaseName: outline namespace: outline spec: optionalValues: - when: "repl{{ ConfigOptionEquals 'postgres_type' 'external_postgres' }}" recursiveMerge: true values: externalPostgresql: host: "repl{{ ConfigOption 'external_postgres_host' }}" port: "repl{{ ConfigOption 'external_postgres_port' }}" database: "repl{{ ConfigOption 'external_postgres_database' }}" username: "repl{{ ConfigOption 'external_postgres_username' }}" password: "repl{{ ConfigOption 'external_postgres_password' }}" - when: "repl{{ ConfigOptionEquals 'redis_type' 'external_redis' }}" recursiveMerge: true values: externalRedis: host: "repl{{ ConfigOption 'external_redis_host' }}" port: "repl{{ ConfigOption 'external_redis_port' }}" password: "repl{{ ConfigOption 'external_redis_password' }}" ``` ##### Recursive merge The following HelmChart custom resource has both `values` and `optionalValues`: ```yaml # HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart spec: values: favorite: drink: hot: tea cold: soda dessert: ice cream day: saturday optionalValues: - when: '{{repl ConfigOptionEquals "example_config_option" "1" }}' recursiveMerge: false values: example_config_option: enabled: true favorite: drink: cold: lemonade ``` The associated Helm chart `values.yaml` file defines these key value pairs: ```yaml # Helm chart values.yaml favorite: drink: hot: coffee cold: soda dessert: pie ``` The associated Helm chart has the following `templates/configmap.yaml` file: ```yaml # templates/configmap.yaml apiVersion: v1 kind: ConfigMap data: favorite_day: {{ .Values.favorite.day }} favorite_dessert: {{ .Values.favorite.dessert }} favorite_drink_cold: {{ .Values.favorite.drink.cold }} favorite_drink_hot: {{ .Values.favorite.drink.hot }} ``` When `recursiveMerge` is `false`, the ConfigMap for the deployed application includes the following key value pairs: ```yaml # templates/configmap.yaml apiVersion: v1 kind: ConfigMap data: favorite_day: null favorite_dessert: pie favorite_drink_cold: lemonade favorite_drink_hot: coffee ``` When `recursiveMerge` is `true`, the ConfigMap for the deployed application includes the following key value pairs: ```yaml # templates/configmap.yaml apiVersion: v1 kind: ConfigMap data: favorite_day: saturday favorite_dessert: ice cream favorite_drink_cold: lemonade favorite_drink_hot: tea ``` ### namespace The `namespace` key specifies an alternative namespace to install the Helm chart. By default, for Embedded Cluster v2 and KOTS existing cluster installations, KOTS installs the chart in the same namespace as the Admin Console. For Embedded Cluster v3 installations, Embedded Cluster installs the chart in a namespace named `` by default. Template functions can parse the `namespace` attribute. For more information about template functions, see [About Replicated template functions](/reference/template-functions-about). For Embedded Cluster v2 and KOTS existing cluster installations, if you specify a namespace in the HelmChart `namespace` field, you must also include the same namespace in the [additionalNamespaces](custom-resource-application#additionalnamespaces) field of the Application custom resource. ### builder The `builder` key contains the minimum Helm values required so that the output of `helm template` exposes all container images needed to install the chart in an air-gapped environment. The Replicated Vendor Portal uses the Helm values in the `builder` key to run `helm template` on the chart. It then parses the output to generate a list of required images. The Vendor Portal then uses this list of images to do the following: * Create the Helm CLI air gap installation instructions that are automatically made available to customers in the [Enterprise Portal](/vendor/enterprise-portal-about) or Download Portal. * Build the `.airgap` bundle for a release to support air gap installations with a Replicated installer (Embedded Cluster, KOTS, kURL). * Determine which images to scan and report on in the [Security Center (Alpha)](/vendor/security-center-about). You must configure the `builder` key to support the following installation types: * Air gap installations with a Replicated installer (Embedded Cluster, KOTS, kURL) * Air gap installations with the Helm CLI * Online installations with KOTS or kURL where the user will push images to their own local image registry #### Requirements The `builder` key has the following requirements and recommendations: * Replicated recommends that you include only the minimum Helm values in the `builder` key required to template the Helm chart with the correct image tags. * Use only static, or _hardcoded_, values in the `builder` key. You can't use template functions in the `builder` key because values in the `builder` key are not rendered in a customer environment. * Any `required` Helm values that need to be set to render the chart templates must have a value in the `builder` key. For more information about the Helm `required` function, see [Using the 'required' function](https://helm.sh/docs/howto/charts_tips_and_tricks/#using-the-required-function) in the Helm documentation. * Specify `kubeVersion` in the root Helm chart. The Vendor Portal renders Helm charts with the minimum Kubernetes minor version that satisfies the `kubeVersion` in the root Helm chart. For example, if the chart specifies `kubeVersion: >=1.24.1`, then it's rendered with Kubernetes 1.25.0. If this fails or if a `kubeVersion` is not specified in the root Helm chart, then the Vendor Portal attempts to render the chart with each supported minor version of Kubernetes up to the latest version. #### Example Many applications include or exclude images based on a given condition. For example, a Helm chart might include a conditional PostgreSQL Deployment, as shown in the following Helm template: ```yaml {{- if .Values.postgresql.enabled }} apiVersion: apps/v1 kind: Deployment metadata: name: postgresql labels: app: postgresql spec: selector: matchLabels: app: postgresql template: metadata: labels: app: postgresql spec: containers: - name: postgresql image: "postgres:10.17" ports: - name: postgresql containerPort: 80 # ... {{- end }} ``` To include the `postgresql` image in the air gap bundle, add `postgresql.enabled` to the `builder` key of the HelmChart custom resource and set it to `true`: ```yaml apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: chart: name: samplechart chartVersion: 3.1.7 values: postgresql: enabled: repl{{ ConfigOptionEquals "postgres_type" "embedded_postgres"}} builder: postgresql: enabled: true ``` --- # HelmChart v1 (Deprecated) :::important The HelmChart custom resource `apiVersion: kots.io/v1beta1` is deprecated. For installations with Replicated KOTS v1.99.0 and later, use the HelmChart custom resource with `apiVersion: kots.io/v1beta2` instead. See [HelmChart v2](/reference/custom-resource-helmchart-v2). ::: Each Helm chart `.tgz` archive in a release requires a unique HelmChart custom resource. The HelmChart custom resource provides the Replicated installer with the instructions needed to process and deploy the given Helm chart. The HelmChart custom resource also generates a list of required images for the chart, which is necessary for the following use cases: * Air gap installations with the Helm CLI or with a Replicated installer * Online installations with a Replicated installer where the user will push images to a local image registry * Online or air gap installations that use the [Security Center (Alpha)](/vendor/security-center-about) to scan and report on Helm chart images For more information, see [About Distributing Helm Charts with KOTS](/vendor/helm-native-about). ## Example The following is an example manifest file for the HelmChart v1 custom resource: ```yaml apiVersion: kots.io/v1beta1 kind: HelmChart metadata: name: samplechart spec: # chart identifies a matching chart from a .tgz chart: name: samplechart chartVersion: 3.1.7 releaseName: samplechart-release-1 exclude: "repl{{ ConfigOptionEquals `include_chart` `include_chart_no`}}" # helmVersion identifies the Helm Version used to render the chart. Default is v3. helmVersion: v3 # useHelmInstall identifies the kots.io/v1beta1 installation method useHelmInstall: true # weight determines the order that charts with "useHelmInstall: true" are applied, with lower weights first. weight: 42 # helmUpgradeFlags specifies additional flags to pass to the `helm upgrade` command. helmUpgradeFlags: - --skip-crds - --no-hooks - --timeout - 1200s - --history-max=15 # values are used in the customer environment, as a pre-render step # these values will be supplied to helm template values: postgresql: enabled: repl{{ ConfigOptionEquals `postgres_type` `embedded_postgres`}} optionalValues: - when: "repl{{ ConfigOptionEquals `postgres_type` `external_postgres`}}" recursiveMerge: false values: postgresql: postgresqlDatabase: "repl{{ if ConfigOptionEquals `postgres_type` `external_postgres`}}repl{{ ConfigOption `external_postgres_database`}}repl{{ end}}" postgresqlUsername: "repl{{ if ConfigOptionEquals `postgres_type` `external_postgres`}}repl{{ ConfigOption `external_postgres_username`}}repl{{ end}}" postgresqlHost: "repl{{ if ConfigOptionEquals `postgres_type` `external_postgres`}}repl{{ ConfigOption `external_postgres_host`}}repl{{ end}}" postgresqlPassword: "repl{{ if ConfigOptionEquals `postgres_type` `external_postgres`}}repl{{ ConfigOption `external_postgres_password`}}repl{{ end}}" postgresqlPort: "repl{{ if ConfigOptionEquals `postgres_type` `external_postgres`}}repl{{ ConfigOption `external_postgres_port`}}repl{{ end}}" # namespace allows for a chart to be installed in an alternate namespace to # the default namespace: samplechart-namespace # builder values provide a way to render the chart with all images # and manifests. this is used in Replicated to create `.airgap` packages builder: postgresql: enabled: true ``` ## Properties ### chart The `chart` key allows for a mapping between the data in this definition and the chart archive itself. You can create multiple HelmChart resources that all reference a single chart archive. | Property | Description | | --- | --- | | `chart.name` | The name of the chart. This value must exactly match the `name` field from a `Chart.yaml` in a `.tgz` chart archive that is also included in the release. If the names do not match, then the installation can error or fail. | | `chart.chartVersion` | The version of the chart. This value must match the `version` field from a `Chart.yaml` in a `.tgz` chart archive that is also included in the release. | | `chart.releaseName` | | ### helmVersion Identifies the Helm Version used to render the chart. Acceptable values are `v2` or `v3`. `v3` is the default when no value is specified. :::note Support for Helm v2, including security patches, ended on November 13, 2020. If you specified `helmVersion: v2` in any HelmChart custom resources, update your references to v3. By default, KOTS uses Helm v3 to process all Helm charts. ::: ### useHelmInstall Identifies the method that KOTS uses to install the Helm chart: * `useHelmInstall: true`: KOTS uses Kustomize to modify the chart then repackages the resulting manifests to install. This was previously referred to as the _native Helm_ installation method. * `useHelmInstall: false`: KOTS renders the Helm templates and deploys them as standard Kubernetes manifests using `kubectl apply`. This was previously referred to as the _Replicated Helm_ installation method. :::note You cannot migrate Helm charts in existing installations from the `useHelmInstall: false` installation method to a different method. If a user previously installed the Helm chart using `apiVersion: kots.io/v1beta1` and `useHelmInstall: false`, the installer won't attempt to use a different installation method. Instead, it displays the following error: `Deployment method for chart has changed`. To change the installation method from `useHelmInstall: false` to a different method, the user must reinstall your application in a new environment. ::: For more information about how KOTS deploys Helm charts when `useHelmInstall` is `true` or `false`, see [About Distributing Helm Charts with KOTS](/vendor/helm-native-about). ### weight The `weight` field is _not_ supported for HelmChart custom resources with `useHelmInstall: false`. For installations with a Replicated installer, `weight` specifies the installation order of the Helm charts in the release. Charts are installed by weight in ascending order with lower weights first. `weight` also determines the uninstall order, where charts are uninstalled by weight in descending order with higher weights first. For installations with the Helm CLI, the Replicated Enterprise Portal uses the `weight` property to order the list of charts in the installation and update instructions. For more information, see [View Install and Update Instructions](/vendor/enterprise-portal-use#view-install-and-update-instructions) in _Access and Use the Enterprise Portal_. **Supported values:** Positive or negative integers. **Default:** `0` ### helmUpgradeFlags The `helmUpgradeFlags` field is _not_ supported for HelmChart custom resources with `useHelmInstall: false`. Specifies additional flags to pass to the `helm upgrade` command. The Replicated installer runs `helm upgrade` for _all_ deployments, not just upgrades, by specifying the `--install` flag. The Replicated installer passes these flags in addition to the flags it passes by default. The values specified in this field take precedence if the installer already passes the same flag. Template functions can parse the `helmUpgradeFlags` attribute. For more information, see [About Replicated template functions](/reference/template-functions-about). For non-boolean flags that require an additional argument, such as `--timeout 1200s`, you must use an equal sign (`=`) or specify the additional argument separately in the array. :::note KOTS passes `--wait` to Helm by default, which means Helm waits for all non-hook resources to reach a Ready state before running post-install or post-upgrade hooks. If a non-hook resource depends on a resource created by a hook (for example, a Deployment with an init container that waits for a database custom resource created by a post-install hook), this creates a circular deadlock. To avoid this, add `--wait=false` and `--wait-for-jobs=false` to `helmUpgradeFlags`. These flags are appended after the defaults and override them. ::: #### Examples ```yaml helmUpgradeFlags: - --timeout - 1200s - --history-max=15 ``` Disable the default `--wait` behavior to prevent deadlocks with post-install hooks: ```yaml helmUpgradeFlags: - --wait=false - --wait-for-jobs=false ``` ### values Use the `values` key to set or delete values in the corresponding Helm chart's `values.yaml` file. Any values that you include in the `values` key must match values in the Helm chart `values.yaml`. For example, `spec.values.images.pullSecret` in the HelmChart custom resource matches `images.pullSecret` in the Helm chart `values.yaml`. During installation or upgrade with a Replicated installer, the installer merges `values` with the Helm chart `values.yaml` in the chart archive. Only include values in the `values` key that you want to set or delete. #### Example ```yaml # HelmChart custom resource apiVersion: kots.io/v1beta1 kind: HelmChart metadata: name: samplechart spec: values: postgresql: enabled: repl{{ ConfigOptionEquals `postgres_type` `embedded_postgres`}} ``` ### exclude When the installer processes your release, it excludes any Helm chart if the output of the `exclude` field is `true`. Template functions can parse the `exclude` attribute. See [About Replicated template functions](template-functions-about). ### optionalValues Use the `optionalValues` key to set values in the Helm chart `values.yaml` file when a conditional statement evaluates to true. For example, a customer including an optional application component might need Helm chart values related to that component. `optionalValues` includes the following properties: | Property | Description | | --- | --- | | `optionalValues.when` | Defines a conditional statement that must evaluate to true for the Helm chart to apply the values in `optionalValues.values`. The Replicated installer defers evaluation of the conditional in `optionalValues.when` until render time in the customer environment. | | `optionalValues.recursiveMerge` | The `optionalValues.recursiveMerge` boolean defines how the Replicated installer merges `values` and `optionalValues`. When `optionalValues.recursiveMerge` is false, the top level keys in `optionalValues` override the top level keys in `values`. When `optionalValues.recursiveMerge` is true, the installer includes all keys from `values` and `optionalValues`. In the case of a conflict where there is a matching key in `optionalValues` and `values`, the Replicated installer uses the value of the key from `optionalValues`. By default, `optionalValues.recursiveMerge` is false. For an example, see [Recursive merge](#recursive-merge) on this page.| | `optionalValues.values` | Array of key value pairs to set in the Helm chart when the specified condition is true. Supports static values and Replicated template functions. | #### Examples ##### Set optional values with Replicated template functions ```yaml # HelmChart custom resource apiVersion: kots.io/v1beta1 kind: HelmChart spec: optionalValues: - when: "repl{{ ConfigOptionEquals `mariadb_type` `external`}}" recursiveMerge: false values: externalDatabase: host: "repl{{ ConfigOption `external_db_host`}}" user: "repl{{ ConfigOption `external_db_user`}}" password: "repl{{ ConfigOption `external_db_password`}}" database: "repl{{ ConfigOption `external_db_database`}}" port: "repl{{ ConfigOption `external_ db_port`}}" ``` During installation, the Replicated installer renders the template functions and sets the `externalDatabase` values in the HelmChart `values.yaml` file _only_ when the user selects the `external` option for `mariadb_type`. ##### Recursive merge The following HelmChart custom resource has both `values` and `optionalValues`: ```yaml # HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart spec: values: favorite: drink: hot: tea cold: soda dessert: ice cream day: saturday optionalValues: - when: '{{repl ConfigOptionEquals "example_config_option" "1" }}' recursiveMerge: false values: example_config_option: enabled: true favorite: drink: cold: lemonade ``` The associated Helm chart `values.yaml` file defines these key value pairs: ```yaml # Helm chart values.yaml favorite: drink: hot: coffee cold: soda dessert: pie ``` The associated Helm chart has the following `templates/configmap.yaml` file: ```yaml # templates/configmap.yaml apiVersion: v1 kind: ConfigMap data: favorite_day: {{ .Values.favorite.day }} favorite_dessert: {{ .Values.favorite.dessert }} favorite_drink_cold: {{ .Values.favorite.drink.cold }} favorite_drink_hot: {{ .Values.favorite.drink.hot }} ``` When `recursiveMerge` is `false`, the ConfigMap for the deployed application includes the following key value pairs: ```yaml # templates/configmap.yaml apiVersion: v1 kind: ConfigMap data: favorite_day: null favorite_dessert: pie favorite_drink_cold: lemonade favorite_drink_hot: coffee ``` When `recursiveMerge` is `true`, the ConfigMap for the deployed application includes the following key value pairs: ```yaml # templates/configmap.yaml apiVersion: v1 kind: ConfigMap data: favorite_day: saturday favorite_dessert: ice cream favorite_drink_cold: lemonade favorite_drink_hot: tea ``` ### namespace The `namespace` key specifies an alternative namespace to install the Helm chart. By default, for Embedded Cluster v2 and KOTS existing cluster installations, KOTS installs the chart in the same namespace as the Admin Console. For Embedded Cluster v3 installations, Embedded Cluster installs the chart in a namespace named `` by default. Template functions can parse the `namespace` attribute. For more information about template functions, see [About Replicated template functions](/reference/template-functions-about). For Embedded Cluster v2 and KOTS existing cluster installations, if you specify a namespace in the HelmChart `namespace` field, you must also include the same namespace in the [additionalNamespaces](custom-resource-application#additionalnamespaces) field of the Application custom resource. ### builder The `builder` key contains the minimum Helm values required so that the output of `helm template` exposes all container images needed to install the chart in an air-gapped environment. The Replicated Vendor Portal uses the Helm values in the `builder` key to run `helm template` on the chart. It then parses the output to generate a list of required images. The Vendor Portal then uses this list of images to do the following: * Create the Helm CLI air gap installation instructions that are automatically made available to customers in the [Enterprise Portal](/vendor/enterprise-portal-about) or Download Portal. * Build the `.airgap` bundle for a release to support air gap installations with a Replicated installer (Embedded Cluster, KOTS, kURL). * Determine which images to scan and report on in the [Security Center (Alpha)](/vendor/security-center-about). You must configure the `builder` key to support the following installation types: * Air gap installations with a Replicated installer (Embedded Cluster, KOTS, kURL) * Air gap installations with the Helm CLI * Online installations with KOTS or kURL where the user will push images to their own local image registry #### Requirements The `builder` key has the following requirements and recommendations: * Replicated recommends that you include only the minimum Helm values in the `builder` key required to template the Helm chart with the correct image tags. * Use only static, or _hardcoded_, values in the `builder` key. You can't use template functions in the `builder` key because values in the `builder` key are not rendered in a customer environment. * Any `required` Helm values that need to be set to render the chart templates must have a value in the `builder` key. For more information about the Helm `required` function, see [Using the 'required' function](https://helm.sh/docs/howto/charts_tips_and_tricks/#using-the-required-function) in the Helm documentation. * Specify `kubeVersion` in the root Helm chart. The Vendor Portal renders Helm charts with the minimum Kubernetes minor version that satisfies the `kubeVersion` in the root Helm chart. For example, if the chart specifies `kubeVersion: >=1.24.1`, then it's rendered with Kubernetes 1.25.0. If this fails or if a `kubeVersion` is not specified in the root Helm chart, then the Vendor Portal attempts to render the chart with each supported minor version of Kubernetes up to the latest version. #### Example Many applications include or exclude images based on a given condition. For example, a Helm chart might include a conditional PostgreSQL Deployment, as shown in the following Helm template: ```yaml {{- if .Values.postgresql.enabled }} apiVersion: apps/v1 kind: Deployment metadata: name: postgresql labels: app: postgresql spec: selector: matchLabels: app: postgresql template: metadata: labels: app: postgresql spec: containers: - name: postgresql image: "postgres:10.17" ports: - name: postgresql containerPort: 80 # ... {{- end }} ``` To include the `postgresql` image in the air gap bundle, add `postgresql.enabled` to the `builder` key of the HelmChart custom resource and set it to `true`: ```yaml apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: chart: name: samplechart chartVersion: 3.1.7 values: postgresql: enabled: repl{{ ConfigOptionEquals "postgres_type" "embedded_postgres"}} builder: postgresql: enabled: true ``` --- # LintConfig The linter checks the manifest files in Replicated KOTS releases to ensure that there are no YAML syntax errors, that all required manifest files are present in the release to support installation with KOTS, and more. The linter runs automatically against releases that you create in the Replicated vendor portal, and displays any error or warning messages in the vendor portal UI. The linter rules have default levels that can be overwritten. You can configure custom levels by adding a LintConfig manifest file (`kind: LintConfig`) to the release. Specify the rule name and level you want the rule to have. Rules that are not included in the LintConfig manifest file keep their default level. For information about linter rules and their default levels, see [Linter Rules](/reference/linter). The supported levels are:
Level Description
error The rule is enabled and shows as an error.
warn The rule is enabled and shows as a warning.
info The rule is enabled and shows an informational message.
off The rule is disabled.
## Example The following example manifest file overwrites the level for the application-icon to `off` to disable the rule. Additionally, the level for the application-statusInformers rule is changed to `error`, so instead of the default warning, it displays an error if the application is missing status informers. ```yaml apiVersion: kots.io/v1beta1 kind: LintConfig metadata: name: default-lint-config spec: rules: - name: application-icon level: "off" - name: application-statusInformers level: "error" ``` --- # Preflight and SupportBundle You can define preflight checks and support bundle specifications for Replicated KOTS and Helm installations. Preflight collectors and analyzers provide cluster operators with clear feedback for any missing requirements or incompatibilities in the target environment before an application is deployed. Preflight checks are not automatically included in releases, so you must define them if you want to include them with a release. Support bundles collect and analyze troubleshooting data from a cluster and help diagnose problems with application deployments. For KOTS, default support bundles are automatically included with releases, and can be customized. For Helm installations, support bundles are not pre-enabled and must be defined if you want to use them. Collectors and analyzers are configured in Preflight and Support Bundle custom resources. :::note Built-in redactors run by default for preflight checks and support bundles to protect sensitive information. ::: ## Defining custom resources To define preflight checks or customize the default support bundle settings, add the corresponding custom resource YAML to your release. Then add custom collector and analyzer specifications to the custom resource. For more information about these troubleshoot features and how to configure them, see [About Preflight Checks and Support Bundles](/vendor/preflight-support-bundle-about). The following sections show basic Preflight and Support Bundle custom resource definitions. ### Preflight The Preflight custom resource uses `kind: Preflight`: ```yaml apiVersion: troubleshoot.sh/v1beta2 kind: Preflight metadata: name: sample spec: collectors: [] analyzers: [] ``` ### SupportBundle The SupportBundle custom resource uses `kind: SupportBundle`: ```yaml apiVersion: troubleshoot.sh/v1beta2 kind: SupportBundle metadata: name: sample spec: collectors: [] analyzers: [] ``` ## Global fields Global fields, also known as shared properties, are fields that are supported on all collectors or all analyzers. The following sections list the global fields for [collectors](#collector-global-fields) and [analyzers](#analyzer-global-fields) respectively. Additionally, each collector and analyzer has its own fields. For more information about collector- and analyzer-specific fields, see the [Troubleshoot documentation](https://troubleshoot.sh/docs/). ### Collector global fields The following fields are supported on all optional collectors for preflights and support bundles. For a list of collectors, see [All Collectors](https://troubleshoot.sh/docs/collect/all/) in the Troubleshoot documentation.
Field Name Description
collectorName (Optional) A collector can specify the collectorName field. In some collectors, this field controls the path where result files are stored in the support bundle.
exclude (Optional) (KOTS Only) Based on the runtime available configuration, a conditional can be specified in the exclude field. This is useful for deployment techniques that allow templating for Replicated KOTS and the optional KOTS Helm component. When this value is true, the collector is not included.
### KOTS collector example This is an example of collector definition for a KOTS support bundle: ```yaml apiVersion: troubleshoot.sh/v1beta2 kind: SupportBundle metadata: name: sample spec: collectors: - collectd: collectorName: "collectd" image: busybox:1 namespace: default hostPath: "/var/lib/collectd/rrd" imagePullPolicy: IfNotPresent imagePullSecret: name: my-temporary-secret data: .dockerconfigjson: ewoJICJhdXRocyI6IHsKzCQksHR0cHM6Ly9pbmRleC5kb2NrZXIuaW8vdjEvIjoge30KCX0sCgkiSHR0cEhlYWRlcnMiOiB7CgkJIlVzZXItQWdlbnQiOiAiRG9ja2VyLUNsaWVudC8xOS4wMy4xMiAoZGFyd2luKSIKCX0sCgkiY3JlZHNTdG9yZSI6ICJkZXNrdG9wIiwKCSJleHBlcmltZW50YWwiOiAiZGlzYWJsZWQiLAoJInN0YWNrT3JjaGVzdHJhdG9yIjogInN3YXJtIgp9 type: kubernetes.io/dockerconfigjson ``` ### Analyzer global fields The following fields are supported on all optional analyzers for preflights and support bundles. For a list of analyzers, see [Analyzing Data](https://troubleshoot.sh/docs/analyze/) in the Troubleshoot documentation.
Field Name Description
collectorName (Optional) An analyzer can specify the collectorName field.
exclude (Optional) (KOTS Only) A condition based on the runtime available configuration can be specified in the exclude field. This is useful for deployment techniques that allow templating for KOTS and the optional KOTS Helm component. When this value is true, the analyzer is not included.
strict (Optional) (KOTS Only) An analyzer can be set to strict: true so that fail outcomes for that analyzer prevent the release from being deployed by KOTS until the vendor-specified requirements are met. When exclude: true is also specified, exclude overrides strict and the analyzer is not executed.
### KOTS analyzer example This is an example of an KOTS analyzer definition with a strict preflight check and `exclude` set for installations that do not use Replicated kURL. In this case, the strict preflight is enforced on an embedded cluster but not on an existing cluster or air gap cluster. ```yaml apiVersion: troubleshoot.sh/v1beta2 kind: Preflight metadata: name: check-kubernetes-version spec: analyzers: - clusterVersion: exclude: 'repl{{ (not IsKurl) }}' strict: true outcomes: - fail: when: "< 1.16.0" message: The application requires Kubernetes 1.16.0 or later uri: https://kubernetes.io - warn: when: "< 1.17.0" message: Your cluster meets the minimum version of Kubernetes, but we recommend you update to 1.17.0 or later. uri: https://kubernetes.io - pass: message: Your cluster meets the recommended and required versions of Kubernetes. ``` --- # Redactor (KOTS Only) This topic describes how to define redactors with the Redactor custom resource. :::note Custom redactors defined with the Redactor resource apply only to installations with Replicated KOTS. ::: ## Overview Preflight checks and support bundles include built-in redactors. These built-in redactors use regular expressions to identify and hide potentially sensitive data before it is analyzed. For example, the built-in redactors hide values that match common patterns for data sources, passwords, and user IDs that can be found in standard database connection strings. They also hide environment variables with names that begin with words like token, password, or user. To view the complete list of regex patterns for the built-in redactors, see [`redact.go`](https://github.com/replicatedhq/troubleshoot/blob/main/pkg/redact/redact.go#L204) in the open-source Troubleshoot GitHub repo. For Replicated KOTS installations, you can also add custom redactors to support bundles using the Redactor custom resource manifest file. For example, you can redact API keys or account numbers, depending on your customer needs. For more information about redactors, see [Redacting Data](https://troubleshoot.sh/docs/redact/) in the Troubleshoot documentation. ## Defining Custom Redactors You can add custom redactors for KOTS installations using the following basic Redactor custom resource manifest file (`kind: Redactor`): ```yaml apiVersion: troubleshoot.sh/v1beta2 kind: Redactor metadata: name: sample spec: redactors: [] ``` ## Objects and Fields A redactor supports two objects: `fileSelector` and `removals`. These objects specify the files the redactor applies to and how the redactions occur. For more information and examples of these fields, see [KOTS Redactor Example](#example) below and [Redactors](https://troubleshoot.sh/docs/redact/redactors/) in the Troubleshoot documentation. ### fileSelector The `fileSelector` object determines which files the redactor is applied to. If this object is omitted from the manifest file, the redactor is applied to all files. This object supports the following optional fields:
Field Name Description
file (Optional) Specifies a single file for redaction.
files (Optional) Specifies multiple files for redaction.
Globbing is used to match files. For example, /my/test/glob/* matches /my/test/glob/file, but does not match /my/test/glob/subdir/file. ### removals The `removals` object is required and defines the redactions that occur. This object supports the following fields. At least one of these fields must be specified:
Field Name Description
regex (Optional) Allows a regular expression to be applied for removal and redaction on lines that immediately follow a line that matches a filter. The selector field is used to identify lines, and the redactor field specifies a regular expression that runs on the line after any line identified by selector. If selector is empty, the redactor runs on every line. Using a selector is useful for removing values from pretty-printed JSON, where the value to be redacted is pretty-printed on the line beneath another value.



Matches to the regex are removed or redacted, depending on the construction of the regex. Any portion of a match not contained within a capturing group is removed entirely. The contents of capturing groups tagged mask are masked with ***HIDDEN***. Capturing groups tagged drop are dropped.
values (Optional) Specifies values to replace with the string ***HIDDEN***.
yamlPath (Optional) Specifies a .-delimited path to the items to be redacted from a YAML document. If an item in the path is the literal string *, the redactor is applied to all options at that level.



Files that fail to parse as YAML or do not contain any matches are not modified. Files that do contain matches are re-rendered, which removes comments and custom formatting. Multi-document YAML is not fully supported. Only the first document is checked for matches, and if a match is found, later documents are discarded entirely.
## KOTS Redactor Example {#example} The following example shows `regex` and `yamlPath` redaction for a support bundle: ```yaml apiVersion: troubleshoot.sh/v1beta2 kind: Redactor metadata: name: my-redactor-name spec: redactors: - name: all files # as no file is specified, this redactor will run against all files removals: regex: - redactor: (another)(?P.*)(here) # this will replace anything between the strings `another` and `here` with `***HIDDEN***` - selector: 'S3_ENDPOINT' # remove the value in lines immediately following those that contain the string `S3_ENDPOINT` redactor: '("value": ").*(")' yamlPath: - "abc.xyz.*" # redact all items in the array at key `xyz` within key `abc` in YAML documents ``` --- # admin-console garbage-collect-images Starts image garbage collection. The KOTS Admin Console must be running and an application must be installed in order to use this command. ### Usage ```bash kubectl kots admin-console garbage-collect-images -n ``` This command supports all [global flags](kots-cli-global-flags). | Flag | Type | Description | |:--------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-h, --help` | | help for admin-console | | `-n, --namespace` | string | the namespace where the Admin Console is running _(required)_ | | `--ignore-rollback` | string | force images garbage collection even if rollback is enabled for the application (default false). Note: this may impact the ability to rollback the application to a previous version. | ### Examples ```bash kubectl kots admin-console garbage-collect-images -n default ``` --- # admin-console generate-manifests Running this command will create a directory on the workstation containing the Replicated Admin Console manifests. These assets can be used to deploy KOTS to a cluster through other workflows, such as kubectl, to provide additional customization of the Admin Console before deploying. ### Limitations * `generate-manifests` does not support generating manifests for Red Hat OpenShift clusters or GKE Autopilot clusters if executed without a Kubernetes cluster context. * To upgrade a KOTS instance that has ever been on version 1.72.0 or earlier, you must run `generate-manifests` with a Kubernetes cluster context. * The `admin-console generate-manifests` command does not accept the [`--strict-security-context`](/reference/kots-cli-install#usage) flag, which deploys KOTS Pods with a security context. To generate Admin Console manifests with a security context, add the following to the Pod templates for Deployments and StatefulSets deployed by KOTS: ```yaml securityContext: fsGroup: 1001 runAsGroup: 1001 runAsNonRoot: true runAsUser: 1001 seccompProfile: type: RuntimeDefault supplementalGroups: - 1001 ``` ### Usage ```bash kubectl kots admin-console generate-manifests [flags] ``` This command supports the following flags:
Flag Type Description
--rootdir string Root directory where the YAML will be written (default `${HOME}` or `%USERPROFILE%`)
--namespace string Target namespace for the Admin Console
--shared-password string Shared password to use when deploying the Admin Console
--http-proxy string Sets HTTP_PROXY environment variable in all KOTS Admin Console components
--http-proxy string Sets HTTP_PROXY environment variable in all KOTS Admin Console
--kotsadm-namespace string

Set to override the registry namespace of KOTS Admin Console images. Used for air gap installations. For more information, see [Air Gap Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster-airgapped).

Note: Replicated recommends that you use --kotsadm-registry instead of --kotsadm-namespace to override both the registry hostname and, optionally, the registry namespace with a single flag.
--kotsadm-registry string Set to override the registry hostname and namespace of KOTS Admin Console images. Used for air gap installations. For more information, see [Air Gap Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster-airgapped).
--no-proxy string Sets NO_PROXY environment variable in all KOTS Admin Console components
--private-ca-configmap string Name of a ConfigMap containing private CAs to add to the kotsadm deployment
--registry-password string Password to use to authenticate with the application registry. Used for air gap installations.
--registry-username string Username to use to authenticate with the application registry. Used for air gap installations.
--with-minio bool Set to true to include a local minio instance to be used for storage (default true)
--minimal-rbac bool Set to true to include a local minio instance to be used for storage (default true)
--additional-namespaces string Comma delimited list to specify additional namespace(s) managed by KOTS outside where it is to be deployed. Ignored without with --minimal-rbac=true
--storage-class string Sets the storage class to use for the KOTS Admin Console components. Default: unset, which means the default storage class will be used
### Examples ```bash kubectl kots admin-console generate-manifests kubectl kots admin-console generate-manifests --rootdir ./manifests kubectl kots admin-console generate-manifests --namespace kotsadm --minimal-rbac=true --additional-namespaces="app1,app3" ``` --- # admin-console Enables access to the KOTS Admin Console from a local machine. This command opens localhost port 8800, which forwards to the `kotsadm` service. Alternatively you can specify the `--port` flag to specify a port other than 8800. To access the Admin Console, browse to http://localhost:8800 after running this command. ### Usage ```bash kubectl kots admin-console [flags] ``` This command supports all [global flags](kots-cli-global-flags) and also: | Flag | Type | Description | |:------------------|--------|---------------------------------------------------------------------------------| | `-h, --help` | | Help for admin-console. | | `-n, --namespace` | string | The namespace where the Admin Console is running. **Default:** "default" | | `--port` | string | Override the local port on which to access the Admin Console. **Default:** 8800 | ### Examples ```bash kubectl kots admin-console --namespace kots-sentry ``` --- # admin-console push-images Pushes images from an air gap bundle to a private registry. The air gap bundle can be either a KOTS Admin Console release or an application release. ### Usage ```bash kubectl kots admin-console push-images [airgap-bundle] [private-registry] [flags] ``` This command supports all [global flags](kots-cli-global-flags) and also: | Flag | Type | Description | |:------------------------|--------|-------------------------------------| | `-h, --help` | | Help for the command | | `--registry-username` | string | username for the private registry | | `--registry-password` | string | password for the private registry | | `--skip-registry-check` | bool | Set to `true` to skip the connectivity test and validation of the provided registry information. **Default:** `false` | ### Examples ```bash kubectl kots admin-console push-images ./kotsadm.tar.gz private.registry.host/app-name \ --registry-username rw-username \ --registry-password rw-password ``` --- # admin-console upgrade Upgrades the KOTS Admin Console to match the version of KOTS CLI. ### Usage ```bash kubectl kots admin-console upgrade [flags] ``` This command supports all [global flags](kots-cli-global-flags) and also: import StrictSecContextYaml from "./_strict-sec-context-yaml.mdx"
Flag Type Description
--ensure-rbac bool When false, KOTS does not attempt to create the RBAC resources necessary to manage applications. Default: true. If a role specification is needed, use the generate-manifests command.
-h, --help Help for the command.
--kotsadm-namespace string

Set to override the registry namespace of KOTS Admin Console images. Used for air gap installations. For more information, see [Air Gap Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster-airgapped).

Note: Replicated recommends that you use --kotsadm-registry instead of --kotsadm-namespace to override both the registry hostname and, optionally, the registry namespace with a single flag.
--kotsadm-registry string Set to override the registry hostname and namespace of KOTS Admin Console images. Used for air gap installations. For more information, see [Air Gap Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster-airgapped).
--registry-password string Password to use to authenticate with the application registry. Used for air gap installations.
--registry-username string Username to use to authenticate with the application registry. Used for air gap installations.
--skip-rbac-check bool When true, KOTS does not validate RBAC permissions. Default: false
--strict-security-context bool

Set to true to explicitly enable strict security contexts for all KOTS Pods and containers.

By default, KOTS Pods and containers are not deployed with a specific security context. When true, --strict-security-context does the following:

  • Ensures containers run as a non-root user
  • Sets the specific UID for the containers (1001)
  • Sets the GID for volume ownership and permissions (1001)
  • Applies the default container runtime seccomp profile for security
  • Ensures the container is not run with privileged system access
  • Prevents the container from gaining more privileges than its parent process
  • Ensures the container's root filesystem is mounted as read-only
  • Removes all Linux capabilities from the container

The following shows the securityContext for KOTS Pods when --strict-security-context is set:

Default: false

:::note Might not work for some storage providers. :::
--wait-duration string Timeout out to be used while waiting for individual components to be ready. Must be in Go duration format. Example: 10s, 2m
--with-minio bool When true, KOTS deploys a local MinIO instance for storage and attempts to change any MinIO-based snapshots (hostpath and NFS) to the local-volume-provider plugin. See local-volume-provider in GitHub. Default: true
### Examples ```bash kubectl kots admin-console upgrade --namespace kots-sentry kubectl kots admin-console upgrade --ensure-rbac=false ``` --- # backup Create a full instance snapshot for disaster recovery. ### Usage ```bash kubectl kots backup [flags] ``` This command supports the following flags: | Flag | Type | Description | | :---------------- | ------ | ------------------------------------------------------------------------------- | | `-h, --help` | | Help for `backup`. | | `-n, --namespace` | string | The namespace where the Admin Console is running. **Default:** `default` | | `-o, --output` | string | The output format. Supports JSON. Defaults to plain text if not set. | | `--wait`. | bool | Wait for the backup to finish. **Default:** true | ### Example ```bash kubectl kots backup --namespace kots-sentry ``` --- # backup ls :::note This command is deprecated. Use [`kubectl kots get backups`](/reference/kots-cli-get-backups) instead. ::: Show a list of all the available instance snapshots for disaster recovery. ### Usage ```bash kubectl kots backup ls [flags] ``` This command supports the following flags: | Flag | Type | Description | | :---------------- | ------ | ------------------------------------------------------------------- | | `-h, --help` | | Help for `backup ls`. | | `-n, --namespace` | string | Filter by the namespace the Admin Console was installed in. | ### Example ```bash kubectl kots backup ls --namespace kots-sentry ``` --- # docker ensure-secret Creates an image pull secret for Docker Hub that the Admin Console can utilize to avoid [rate limiting](/enterprise/image-registry-rate-limits). The credentials are validated before creating the image pull secret. Running this command creates a new application version, based on the latest version, with the new image pull secret added to all Kubernetes manifests that have images. In order for this secret to take effect to avoid rate limiting, the new version must be deployed. ### Usage ```bash kubectl kots docker ensure-secret [flags] ``` - _Provide `[flags]` according to the table below_ | Flag | Type | Description | | ----------------- | ------ | ------------------------------------------------------------------- | | `-h, --help` | | help for ensure-secret | | `--dockerhub-username` | string | DockerHub username to be used _(required)_ | | `--dockerhub-password` | string | DockerHub password to be used _(required)_ | | `-n, --namespace` | string | the namespace where the Admin Console is running _(required)_ | ### Example ```bash kubectl kots docker ensure-secret --dockerhub-username sentrypro --dockerhub-password password --namespace sentry-pro ``` --- # docker KOTS Docker interface ### Usage ```bash kubectl kots docker [command] ``` This command supports all [global flags](kots-cli-global-flags). --- # download Retrieves a copy of the application manifests from the cluster, and store them in a specific directory structure on your workstation. Requires a running application with the KOTS Admin Console. ## Usage ```bash kubectl kots download [app-slug] [flags] ``` * _Replace `[app-slug]` with the application slug provided by your software vendor (required)._ For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug) in _Managing Applications_. * _Provide `[flags]` according to the table below_ This command supports all [global flags](kots-cli-global-flags) and also: | Flag | Type | Description | |:----------------------------|--------|-----------------------------------------------------------------------------------------------------------------------| | `--decrypt-password-values` | bool | decrypt password values to plaintext | | `--dest` | string | the directory to store the application in _(defaults to current working dir)_ | | `--current` | bool | download the archive of the currently deployed app version | | `--sequence` | int | sequence of the app version to download the archive for (defaults to the latest version unless --current flag is set) | | `-h, --help` | | help for download | | `-n, --namespace` | string | the namespace to download from _(default `"default"`)_ | | `--overwrite` | | overwrite any local files, if present | | `-o, --output` | string | output format (currently supported: json) _(defaults to plain text if not set)_ | ## Example ```bash kubectl kots download kots-sentry --namespace kots-sentry --dest ./manifests --overwrite ``` --- # enable-ha (Deprecated) Runs the rqlite StatefulSet as three replicas for data replication and high availability. This command is deprecated and will be removed in a future release. The EKCO add-on for Replicated kURL now scales up the rqlite StatefulSet automatically when three or more nodes are healthy and the OpenEBS localpv storage class is available. For more information, see [EKCO add-on](https://kurl.sh/docs/add-ons/ekco#kotsadm) in the kURL documentation. ## Usage ```bash kubectl kots enable-ha [flags] ``` * _Provide `[flags]` according to the table below_ This command supports all [global flags](kots-cli-global-flags) and also: | Flag | Type | Description | |:---------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--wait-duration` | string | Timeout used while waiting for individual components to be ready. Must be in Go duration format. For example, `10s` or `2m`. See [func ParseDuration](https://pkg.go.dev/time#ParseDuration) in the Go documentation. | | `-h, --help` | | Help for `enable-ha`. | | `-n, --namespace` | string | The namespace where the Admin Console is running _(required)_ | ## Example ```bash kubectl kots enable-ha --namespace kots-sentry ``` --- # get apps The `kots get apps` command lists installed applications. ### Usage ```bash kubectl kots get apps [flags] ``` - _Provide `[flags]` according to the table below_ | Flag | Type | Description | | :---------------- | ------ | ------------------------------------------------------------------- | | `-h, --help` | | help for get apps | | `-n, --namespace` | string | the namespace where the Admin Console is running _(required)_ | ### Example ```bash kubectl kots get apps -n default ``` --- # get backups The `kots get backups` command lists available full snapshots (instance). ### Usage ```bash kubectl kots get backups [flags] ``` - _Provide `[flags]` according to the table below_ | Flag | Type | Description | | :---------------- | ------ | ------------------------------------------------------------------- | | `-h, --help` | | help for get backups | | `-n, --namespace` | string | filter by the namespace in which the Admin Console is/was installed | ### Examples Basic ```bash kubectl kots get backups ``` Filtering by a namespace ```bash kubectl kots get backups -n default ``` --- # get config The `kots get config` command returns the `configValues` file for an application. ### Usage ```bash kubectl kots get config [flags] ``` - _Provide `[flags]` according to the table below_ | Flag | Type | Description | | :---------------- | ------ | ------------------------------------------------------------------- | | `--appslug` | string | The slug of the target application. Required when more than one application is deployed. Your software vendor provides the application slug. For more information, see Get the Application Slug in Managing Applications.| | `--current` | bool | When set, the `configValues` file for the currently deployed version of the application is retrieved.| | `--sequence` | int | Retrieves the `configValues` file for the specified application sequence. **Default**: Latest (unless the `--current` flag is set).| | `--decrypt` | bool | Decrypts password items within the configuration.| | `-h, --help` | | Help for `get config`.| | `-n, --namespace` | string | (Required) The namespace where the Admin Console is running.| ### Example ```bash kubectl kots get config -n default --sequence 5 --appslug myapp ``` --- # get The `kots get` command shows information about one or more resources. ### Usage ```bash kubectl kots get [resource] [flags] ``` This command supports all [global flags](kots-cli-global-flags) and also: | Flag | Type | Description | |:----------------------|------|-------------| | `-o, --output` | | Output format. **Supported formats**: `json`. | ### Resources * `apps` lists installed applications. * `backups` lists available full snapshots (instance). * `config` lists the **configValues** for an application. * `restores` lists created full snapshot restores. * `versions` lists the versions available for a given `app-slug`. --- # get restores The `kots get restores` command lists created full snapshot restores. ### Usage ```bash kubectl kots get restores [flags] ``` - _Provide `[flags]` according to the table below_ | Flag | Type | Description | | :---------------- | ------ | ------------------------------------------------------------------- | | `-h, --help` | | help for get restores | | `-n, --namespace` | string | filter by the namespace in which the Admin Console is/was installed | ### Examples Basic ```bash kubectl kots get restores ``` Filtering by a namespace ```bash kubectl kots get restores -n default ``` --- # get versions The `kots get versions` command lists all versions of an application. > Introduced in KOTS v1.61.0 ### Usage ```bash kubectl kots get versions [app-slug] [flags] ``` - _Replace `[app-slug]` with the app slug for your KOTS application (required)._ - _Provide `[flags]` according to the table below_ | Flag | Type | Description | | :------------------------ | ------ | --------------------------------------------------------------------------------------------------- | | `-h, --help` | | Help for `get versions`. | | `-n, --namespace` | string | (Required) The namespace where the Admin Console is running. | | `--current-page` | int | Offset, by page size, at which to start retrieving versions. **Default:** 0 | | `--page-size` | int | Number of versions to return. **Default:** 20 | | `--pin-latest` | int | When set to true, always returns the latest version at the beginning. **Default:** false | | `--pin-latest-deployable` | int | When set to true, always returns the latest version that can be deployed. The latest deployable version can differ from the latest version if a required version, which cannot be skipped, is present. **Default:** false | | `-o, --output` | string | Output format. **Supported formats:** `json`. **Default:** Plain text | ### Example ```bash kubectl kots get versions kots-sentry -n default ``` --- # Install the KOTS CLI Users can interact with the Replicated KOTS CLI to install and manage applications with Replicated KOTS. The KOTS CLI is a kubectl plugin that runs locally on any computer. ## Prerequisite Install kubectl, the Kubernetes command-line tool. See [Install Tools](https://kubernetes.io/docs/tasks/tools/) in the Kubernetes documentation. :::note If you are using a cluster created with Replicated kURL, kURL already installed both kubectl and the KOTS CLI when provisioning the cluster. For more information, see [Online Installation with kURL](/enterprise/installing-kurl) and [Air Gap Installation with kURL](/enterprise/installing-kurl-airgap). ::: ## Install To install the latest version of the KOTS CLI to `/usr/local/bin`, run: ```bash curl https://kots.io/install | bash ``` To install to a directory other than `/usr/local/bin`, run: ```bash curl https://kots.io/install | REPL_INSTALL_PATH=/path/to/cli bash ``` To install a specific version of the KOTS CLI, run: ```bash curl https://kots.io/install/ | bash ``` To verify your installation, run: ```bash kubectl kots --help ``` ## Install without Root Access You can install the KOTS CLI on computers without root access or computers that cannot write to the `/usr/local/bin` directory. To install the KOTS CLI without root access, you can do any of the following: * (Online Only) [Install to a Different Directory](#install-to-a-different-directory) * (Online Only) [Install Using Sudo](#install-using-sudo) * (Online or Air Gap) [Manually Download and Install](#manually-download-and-install) ### Install to a Different Directory You can set the `REPL_INSTALL_PATH` environment variable to install the KOTS CLI to a directory other than `/usr/local/bin` that does not require elevated permissions. **Example:** In the following example, the installation script installs the KOTS CLI to `~/bin` in the local directory. You can use the user home symbol `~` in the `REPL_INSTALL_PATH` environment variable. The script expands `~` to `$HOME`. ```bash curl -L https://kots.io/install | REPL_INSTALL_PATH=~/bin bash ``` ### Install Using Sudo If you have sudo access to the directory where you want to install the KOTS CLI, you can set the `REPL_USE_SUDO` environment variable so that the installation script prompts you for your sudo password. When you set the `REPL_USE_SUDO` environment variable to any value, the installation script uses sudo to create and write to the installation directory as needed. The script prompts for a sudo password if it is required for the user executing the script in the specified directory. **Example:** In the following example, the script uses sudo to install the KOTS CLI to the default `/usr/local/bin` directory. ```bash curl -L https://kots.io/install | REPL_USE_SUDO=y bash ``` **Example:** In the following example, the script uses sudo to install the KOTS CLI to the `/replicated/bin` directory. ```bash curl -L https://kots.io/install | REPL_INSTALL_PATH=/replicated/bin REPL_USE_SUDO=y bash ``` ### Manually Download and Install You can manually download and install the KOTS CLI binary to install without root access, rather than using the installation script. Users in air gap environments can also follow this procedure to install the KOTS CLI. To manually download and install the KOTS CLI: 1. Download the KOTS CLI release for your operating system. 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)**: ```bash curl -L https://github.com/replicatedhq/kots/releases/latest/download/kots_darwin_all.tar.gz ``` * **Linux (AMD)**: ```bash curl -L https://github.com/replicatedhq/kots/releases/latest/download/kots_linux_amd64.tar.gz ``` * **Linux (ARM)**: ```bash curl -L https://github.com/replicatedhq/kots/releases/latest/download/kots_linux_arm64.tar.gz ``` 1. Unarchive the `.tar.gz` file that you downloaded: * **MacOS (AMD and ARM)**: ```bash tar xvf kots_darwin_all.tar.gz ``` * **Linux (AMD)**: ```bash tar xvf kots_linux_amd64.tar.gz ``` * **Linux (ARM)**: ```bash tar xvf kots_linux_arm64.tar.gz ``` 1. Rename the `kots` executable to `kubectl-kots` and move it to one of the directories that is in your PATH environment variable. This ensures that the system can access the executable when you run KOTS CLI commands. :::note You can run `echo $PATH` to view the list of directories in your PATH. ::: Run one of the following commands, depending on if you have write access to the target directory: * **You have write access to the directory**: ```bash mv kots /PATH_TO_TARGET_DIRECTORY/kubectl-kots ``` Replace `PATH_TO_TARGET_DIRECTORY` with the path to a directory that is in your PATH environment variable. For example, `/usr/local/bin`. * **You do _not_ have write access to the directory**: ```bash sudo mv kots /PATH_TO_TARGET_DIRECTORY/kubectl-kots ``` Replace `PATH_TO_TARGET_DIRECTORY` with the path to a directory that is in your PATH environment variable. For example, `/usr/local/bin`. 1. Verify the installation: ``` kubectl kots --help ``` ## Uninstall The KOTS CLI is a plugin for the Kubernetes kubectl command line tool. The KOTS CLI plugin is named `kubectl-kots`. For more information about working with kubectl, see [Command line tool (kubectl)](https://kubernetes.io/docs/reference/kubectl/) in the Kubernetes documentation. To uninstall the KOTS CLI: 1. Find the location where the `kubectl-kots` plugin is installed on your `PATH`: ``` kubectl plugin list kubectl-kots cli ``` 2. Delete `kubectl-kots`: ``` sudo rm PATH_TO_KOTS ``` Replace `PATH_TO_KOTS` with the location where `kubectl-kots` is installed. **Example**: ``` sudo rm /usr/local/bin/kubectl-kots ``` --- # Global flags All KOTS CLI commands support a set of global flags to be used to connect to the cluster. | Flag | Type | Description | |---|---|---| | `--as` | string | Username to impersonate for the operation | | `--as-group` | stringArray | Group to impersonate for the operation, this flag can be repeated to specify multiple groups. | | `--cache-dir` | string | Default HTTP cache directory (default "~/.kube/http-cache") | | `--certificate-authority` | string | Path to a cert file for the certificate authority | | `--client-certificate` | string | Path to a client certificate file for TLS | | `--client-key` | string | Path to a client key file for TLS | | `--cluster` | string | The name of the kubeconfig cluster to use | | `--context` | string | The name of the kubeconfig context to use | | `--insecure-skip-tls-verify` | bool | If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure | | `--kubeconfig` | string | Path to the kubeconfig file to use for CLI requests. | | `-n, --namespace` | string | If present, the namespace scope for this CLI request | | `--request-timeout` | string | The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0") | | `-s, --server` | string | The address and port of the Kubernetes API server | | `--token` | string | Bearer token for authentication to the API server | | `--user` | string | The name of the kubeconfig user to use | --- # install Installs the application and the KOTS Admin Console directly to a cluster. The `kots install` command pulls Kubernetes manifests from the remote upstream, deploys the manifests to the specified cluster, installs the Admin Console, and sets up port forwarding to make the Admin Console accessible on port 8800. Alternatively, you can specify the `--port` flag to override the default port. ### Usage ```bash kubectl kots install [upstream uri] [flags] ``` - _Replace [upstream-uri] with the URI for your KOTS application (required)._ - _If the KOTS application has been packaged by Replicated Vendor, the `--license-file` flag must be provided._ - _Provide [flags] according to the table below_ This command supports all [global flags](kots-cli-global-flags) and also: import StrictSecContextYaml from "./_strict-sec-context-yaml.mdx"
Flag Type Description
--additional-annotations bool Additional annotations to add to kotsadm pods.
--additional-labels bool Additional labels to add to kotsadm pods.
--airgap bool Set to true to run install in air gapped mode. Setting --airgap-bundle implies --airgap=true. Default: false. For more information, see Air Gap Installation in Existing Clusters with KOTS.
--airgap-bundle string Path to the application air gap bundle where application metadata will be loaded from. Setting --airgap-bundle implies --airgap=true. For more information, see Air Gap Installation in Existing Clusters with KOTS.
--app-version-label string The application version label to install. If not specified, the latest version is installed.
--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 Install with the KOTS CLI.
--copy-proxy-env bool Copy proxy environment variables from current environment into all Admin Console components. Default: false
--disable-image-push bool Set to true to disable images from being pushed to private registry. Default: false
--ensure-rbac bool When false, KOTS does not attempt to create the RBAC resources necessary to manage applications. Default: true. If a role specification is needed, use the [generate-manifests](kots-cli-admin-console-generate-manifests) command.
-h, --help Help for the command.
--http-proxy string Sets HTTP_PROXY environment variable in all Admin Console components.
--https-proxy string Sets HTTPS_PROXY environment variable in all Admin Console components.
--kotsadm-namespace string

Set to override the registry namespace of KOTS Admin Console images. Used for air gap installations. For more information, see [Air Gap Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster-airgapped).

Note: Replicated recommends that you use --kotsadm-registry instead of --kotsadm-namespace to override both the registry hostname and, optionally, the registry namespace with a single flag.
--kotsadm-registry string Set to override the registry hostname and namespace of KOTS Admin Console images. Used for air gap installations. For more information, see [Air Gap Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster-airgapped).
--license-file string Path to a license file.
--local-path string Specify a local-path to test the behavior of rendering a Replicated application locally. Only supported on Replicated application types.
--name string Name of the application to use in the Admin Console.
--no-port-forward bool Set to true to disable automatic port forward. Default: false
--no-proxy string Sets NO_PROXY environment variable in all Admin Console components.
--port string Override the local port to access the Admin Console. Default: 8800
--private-ca-configmap string Name of a ConfigMap containing private CAs to add to the kotsadm deployment.
--preflights-wait-duration string Timeout to be used while waiting for preflights to complete. Must be in [Go duration](https://pkg.go.dev/time#ParseDuration) format. For example, 10s, 2m. Default: 15m
--registry-password string Password to use to authenticate with the application registry. Used for air gap installations.
--registry-username string Username to use to authenticate with the application registry. Used for air gap installations.
--repo string Repo URI to use when installing a Helm chart.
--shared-password string Shared password to use when deploying the Admin Console.
--skip-compatibility-check bool Set to true to skip compatibility checks between the current KOTS version and the application. Default: false
--skip-preflights bool Set to true to skip preflight checks. Default: false. If any strict preflight checks are configured, the --skip-preflights flag is not honored because strict preflight checks must run and contain no failures before the application is deployed. For more information, see [Define Preflight Checks](/vendor/preflight-defining).
--skip-rbac-check bool Set to true to bypass RBAC check. Default: false
--skip-registry-check bool Set to true to skip the connectivity test and validation of the provided registry information. Default: false
--strict-security-context bool

Set to true to explicitly enable strict security contexts for all KOTS Pods and containers.

By default, KOTS Pods and containers are not deployed with a specific security context. When true, --strict-security-context does the following:

  • Ensures containers run as a non-root user
  • Sets the specific UID for the containers (1001)
  • Sets the GID for volume ownership and permissions (1001)
  • Applies the default container runtime seccomp profile for security
  • Ensures the container is not run with privileged system access
  • Prevents the container from gaining more privileges than its parent process
  • Ensures the container's root filesystem is mounted as read-only
  • Removes all Linux capabilities from the container

The following shows the securityContext for KOTS Pods when --strict-security-context is set:

Default: false

:::note Might not work for some storage providers. :::
--use-minimal-rbac bool When set to true, KOTS RBAC permissions are limited to the namespace where it is installed. To use --use-minimal-rbac, the application must support namespace-scoped installations and the user must have the minimum RBAC permissions required by KOTS in the target namespace. For a complete list of requirements, see [Namespace-scoped RBAC Requirements​](/enterprise/installing-general-requirements#namespace-scoped) in _Installation Requirements_. Default: false
--wait-duration string Timeout to be used while waiting for individual components to be ready. Must be in [Go duration](https://pkg.go.dev/time#ParseDuration) format. For example, 10s, 2m. Default: 2m
--with-minio bool When set to true, KOTS deploys a local MinIO instance for storage and uses MinIO for host path and NFS snapshot storage. Default: true
--storage-class string Sets the storage class to use for the KOTS Admin Console components. Default: unset, which means the default storage class will be used
### Examples ```bash kubectl kots install sentry/unstable --license-file ~/license.yaml kubectl kots install kots-sentry/stable --shared-password IgqG5OBc9Gp --license-file ~/sentry-license.yaml --namespace sentry-namespace --config-values ~/config-values.yaml kubectl kots install --ensure-rbac=false ``` --- # pull Running this command will create a directory on the workstation containing the application and Kubernetes manifests. These assets can be used to deploy KOTS to a cluster through other workflows, such as kubectl. This command is necessary when managing a application without the use of the Admin Console. ### Usage ```bash kubectl kots pull [upstream uri] [flags] ``` * _Replace `[upstream-uri]` with the URI for your KOTS application (required)._ * _If the KOTS application has been packaged by Replicated Vendor, the `--license-file` flag must be provided._ * _Provide `[flags]` according to the table below_ This command supports all [global flags](kots-cli-global-flags) and also: | Flag | Type | Description | |:-----|------|-------------| | `--downstream` | strings | the list of any downstreams to create/update | | `--exclude-admin-console` | bool | set to true to exclude the Admin Console _(only valid when `[upstream-uri]` points to a replicated app)_ | | `--exclude-kots-kinds` | bool | set to true to exclude rendering KOTS custom objects to the base directory _(default `true`)_ | | `-h, --help` | | help for pull | | `--image-namespace` | string | the namespace/org in the docker registry to push images to _(required when `--rewrite-images` is set)_ | | `--license-file` | string | path to a license file _(required when `[upstream-uri]` points to a replicated app)_ | | `--local-path` | string | specify a local-path to pull a locally available replicated app _(only valid when `[upstream-uri]` points to a replicated app)_ | | `-n, --namespace` | string | namespace to render the upstream to in the base _(default `"default"`)_ | | `--private-ca-configmap` | string | name of a ConfigMap containing private CAs to add to the kotsadm deployment. | `--registry-endpoint` | string | the endpoint of the local docker registry to use when pushing images _(required when `--rewrite-images` is set)_ | | `--rewrite-images` | bool | set to true to force all container images to be rewritten and pushed to a local registry | | `--rootdir` | string | root directory that will be used to write the yaml to _(default `${HOME}` or `%USERPROFILE%`)_ | | `--shared-password` | string | shared password to use when deploying the Admin Console | | `--http-proxy` | string | sets HTTP_PROXY environment variable in all KOTS Admin Console components | | `--https-proxy` | string | sets HTTPS_PROXY environment variable in all KOTS Admin Console components | | `--no-proxy` | string | sets NO_PROXY environment variable in all KOTS Admin Console components | | `--copy-proxy-env` | bool | copy proxy environment variables from current environment into all KOTS Admin Console components | | `--config-values` | string | path to a manifest containing config values (must be apiVersion: kots.io/v1beta1, kind: ConfigValues) | | `--with-minio` | bool | set to true to include a local minio instance to be used for storage _(default true)_ | | `--storage-class` | string | sets the storage class to use for the KOTS Admin Console components. _(default unset, which means the default storage class will be used)_ | ### Example ```bash kubectl kots pull sentry/unstable --license-file ~/license.yaml ``` --- # remove Remove application reference from the KOTS Admin Console. You can use the `kots remove` command to remove one or more installed applications from the Admin Console. By default, the deployed application is not removed from the cluster. Only the reference for the application is removed from the Admin Console. To completely remove the application and delete its resources from the cluster, use the `--undeploy` flag. ### Usage ```bash kubectl kots remove [app-slug] -n [namespace] ``` * _`[app-slug]` is the slug of the installed application to be removed (required)_ * _Provide `[flags]` according to the table below_ This command supports all [global flags](kots-cli-global-flags) and also:
Flag Type Description
--force bool

Removes the reference even if the application has already been deployed.
--undeploy bool

Un-deploys the application by deleting all its resources from the cluster. When --undeploy is set, the --force flag is set automatically.

Note: --undeploy can remove application resources only from the namespace where KOTS is installed and from any namespaces provided in the additionalNamespaces field in the Application custom resource.

The following describes how --undeploy removes application resources:

  • For applications deployed with kubectl apply (including standalone manifest files and Helm charts deployed with Replicated Helm), --undeploy identifies and removes resources based on a kots.io/app-slug: <app_slug> annotation that is applied to all application resources during deployment.
  • For Helm chart applications deployed with HelmChart custom resources with apiVersion: kots.io/v1beta2 or apiVersion: kots.io/v1beta1 and useHelmInstall: true, --undeploy runs helm uninstall.
-n string

The namespace where the target application is deployed. Use default for the default namespace.
### Example ```bash kubectl kots remove sentry -n default ``` --- # reset-password If you deployed an application with the KOTS Admin Console, the `kots reset-password` command will change the bcrypted password hash in the cluster, allowing you to log in again. ### Usage ```bash kubectl kots reset-password [namespace] [flags] ``` * _Replace `[namespace]` with the namespace where the Admin Console and your KOTS application resides (required)._ * _Provide `[flags]` according to the table below_ This command supports all [global flags](kots-cli-global-flags) and also: | Flag | Type | Description | |:----------------------|------|-------------| | `-h, --help` | | help for reset-password | | `-n, --namespace`| string | the namespace where the Admin Console is running | ### Examples ```bash kubectl kots reset-password sentry-namespace ``` --- # reset-tls If a bad TLS certificate is uploaded to the KOTS Admin Console or the kotsadm-tls secret is missing, the `kots reset-tls` command reapplies a default self-signed TLS certificate. For more information about the certificates stored in this secret, see [Setting up TLS Certificates](https://kurl.sh/docs/install-with-kurl/setup-tls-certs) in the open source kURL documentation. ### Usage ```bash kubectl kots reset-tls [namespace] [flags] ``` * _Replace `[namespace]` with the namespace where the Admin Console and your KOTS application resides (required)._ * _Provide `[flags]` according to the table below_ This command supports all [global flags](kots-cli-global-flags) and also: | Flag | Type | Description | |:----------------------|------|-------------| | `-h, --help` | | Help for `reset-tls`. | | `-n, --namespace`| string | The namespace where the Admin Console is running. | | `--accept-anonymous-uploads`| bool | Allow uploading a new certificate prior to authenticating. | ### Examples ```bash kubectl kots reset-tls sentry-namespace --- # restore Restore full snapshots for disaster recovery, or do a partial restore of the application only or the Replicated Admin Console only. ### Usage ```bash kubectl kots restore --from-backup [flags] ``` This command supports the following flags: | Flag | Type | Description | | :-------------------------- | ------ | --------------------------------------------------------------------------------------------- | | `--exclude-admin-console` | bool | Exclude restoring the Admin Console and only restore the applications. **Default:** false | | `--exclude-apps` | bool | Exclude restoring the applications and only restore the Admin Console. **Default:** false | | `--from-backup` | string | (Required) The name of the backup to restore from. | | `-h, --help` | | Help for `restore`. | | `-o, --output` | string | The output format. Supports JSON. Defaults to plain text if not set. | | `--velero-namespace` | string | (Required for minimal RBAC installations) The namespace where Velero is installed. | | `--wait-for-apps` | bool | Wait for all applications to be restored. **Default:** true | ### Example ```bash kubectl kots restore --from-backup instance-942kf ``` --- # restore ls :::note This command is deprecated. Use [`kubectl kots get restores`](/reference/kots-cli-get-restores) instead. ::: Show a list of all the available full snapshot restores for disaster recovery. ### Usage ```bash kubectl kots restore ls [flags] ``` This command supports the following flags: | Flag | Type | Description | | :---------------- | ------ | ------------------------------------------------------------------- | | `-h, --help` | | Help for `restore ls`. | | `-n, --namespace` | string | Filter by the namespace the Admin Console was installed in.| ### Example ```bash kubectl kots restore ls --namespace kots-sentry ``` --- # set config The `kots set config` allows setting values for application config items in the latest release version. > Introduced in KOTS v1.31.0 ## Usage ```bash kubectl kots set config [appSlug] [KEY_1=VAL_1 ... KEY_N=VAL_N] [flags] ``` - _Provide `[flags]` according to the table below_ | Flag | Type | Description | | :-------------------| ------ | ------------------------------------------------------------------------------------------------------------------------------------- | | `--config-file` | string | path to a manifest containing config values (must be `apiVersion: kots.io/v1beta1, kind: ConfigValues`) | | `--merge` | bool | when set to true, only keys specified in config file will be updated. This flag can only be used when `--config-file` flag is used. | |`--key` | string | name of a single key to set. This flag requires `--value` or `--value-from-file` flags | | `--value` | string | the value to set for the key specified in the `--key` flag. This flag cannot be used with `--value-from-file` flag. | | `--value-from-file` | string | path to the file containing the value to set for the key specified in the `--key` flag. This flag cannot be used with `--value` flag. | | `--deploy` | bool | when set, automatically deploy the latest version with the new configuration | | `--skip-preflights` | bool | set to true to skip preflight checks when deploying new version if no strict preflights exist; when strict preflights are present, all preflights still run, but non-strict failures are ignored | | `--current` | bool | set to true to use the currently deployed version of the app as the base for the new version | | `--sequence` | int | sequence of the app version to use as the base for the new version (defaults to the latest version unless --current flag is set) | | `-n, --namespace` | string | the namespace where the Admin Console is running _(required)_ | #### About Strict Preflight Checks If any strict preflight checks are configured, the `--skip-preflights` flag are not honored because the preflight checks must run and contain no failures before the application is deployed. When the `--deploy` option is provided and there are strict preflight checks, the preflight checks always run. The deployment waits for up to 15 minutes for the preflight checks to complete. If the checks complete without strict preflight failures, the release deploys. If the checks do not complete within 15 minutes, the release does not deploy. If there are one or more strict preflight failures, the release does not deploy. For more information about strict preflight checks, see [Define Preflight Checks](/vendor/preflight-defining). ## Examples ```bash kubectl kots set config myapp -n default --config-file /path/to/local/config.yaml ``` ```bash kubectl kots set config myapp -n default --key config-item-name --value-from-file /path/to/config/file/value.txt ``` ```bash kubectl kots set config myapp -n default config-item-name="config item value" ``` ```bash kubectl kots set config myapp -n default --key config-item-name --value "config item value" ``` --- # set Configure KOTS resources. ### Usage ```bash kubectl kots set [resource] [flags] ``` This command supports all [global flags](kots-cli-global-flags). ### Resources * `config` set config items for application. --- # upload Upload Kubernetes manifests from the local filesystem, creating a new version of the application that can be deployed. When you have a copy of an application that was created with `kots pull` or `kots download`, you can upload it back to the Admin Console using the `kots upload` command. ## Usage ```bash kubectl kots upload [source] [flags] ``` * _Replace `[source]` with a directory containing the manifests of your KOTS application (required)._ * _Provide `[flags]` according to the table below_ This command supports all [global flags](kots-cli-global-flags) and also: | Flag | Type | Description | |:----------------------|------|-------------| | `-h, --help` | | help for upload | | `--name`| string | the name of the kotsadm application to create | | `-n, --namespace`| string | the namespace to upload to _(default `"default"`)_ | | `--slug`| string | the application slug to use. if not present, a new one will be created | | `--upstream-uri`| string | the upstream uri that can be used to check for updates | | `--deploy`| bool | when set, automatically deploy the uploaded version | | `--skip-preflights`| bool | set to true to skip preflight checks if no strict preflights exist; when strict preflights are present, all preflights still run, but non-strict failures are ignored | | `-o, --output` | string | output format (currently supported: json) _(defaults to plain text if not set)_ | Any `plainText` values in the `upstream/userdata/config.yaml` file will be re-encrypted using the application cipher automatically, if the matching config item is a password type. If both an encrypted and plainText value is provided on a single item, the plainText value will overwrite the encrypted value, if they differ. #### About Strict Preflight Checks If any strict preflight checks are configured, the `--skip-preflights` flag are not honored because the preflight checks must run and contain no failures before the application is deployed. When the `--deploy` option is provided and there are strict preflight checks, the preflight checks always run. The deployment waits for up to 15 minutes for the preflight checks to complete. If the checks complete without strict preflight failures, the release deploys. If the checks do not complete within 15 minutes, the release does not deploy. If there are one or more strict preflight failures, the release does not deploy. For more information about strict preflight checks, see [Define Preflight Checks](/vendor/preflight-defining). ## Examples ```bash kubectl kots upload ./manifests --name kots-sentry --namespace kots-sentry --slug kots-sentry --upstream-uri kots-sentry/unstable ``` --- # upstream download The `kots upstream download` command retries downloading a failed update of the upstream application. ### Usage ```bash kubectl kots upstream download [app-slug] [flags] ``` * _Replace `[app-slug]` with the app slug for your KOTS application (required)._ * _Provide `[flags]` according to the table below._ | Flag | Type | Description | |:----------------------------------|--------|--------------------------------------------------------------------------------------------------| | `-h, --help` | | Help for `upstream download`. | | `--kubeconfig` | string | The kubeconfig to use. **Default**: `$KUBECONFIG`. If unset, then `$HOME/.kube/config`. | | `-n, --namespace` | string | (Required) The namespace where the Admin Console is running. | | `--sequence` | int | (Required) The local app sequence for the version to retry downloading. | | `--skip-preflights` | bool | Set to `true` to skip preflight checks if no strict preflights exist; when strict preflights are present, all preflights still run, but non-strict failures are ignored | | `--skip-compatibility-check` | bool | Set to `true` to skip compatibility checks between the current kots version and the update. | | `--wait` | bool | Set to `false` to download the update in the background. **Default**: `true`. | | `-o, --output` | string | Output format. **Supported formats**: `json`. **Default**: Plain text. | ### Example ```bash kubectl kots upstream download kots-sentry --namespace kots-sentry --sequence 8 ``` --- # upstream upgrade The `kots upstream upgrade` fetches the latest version of the upstream application. It is functionality equivalent to clicking the "Check For Updates" in the Admin Console. ## Usage ```bash kubectl kots upstream upgrade [app-slug] [flags] ``` * _Replace `[app-slug]` with the app slug for your KOTS application (required)._ * _Provide `[flags]` according to the table below_ | Flag | Type | Description | |:-------------------------|--------|--------------------------------------------------------------------------------------------------| | `-h, --help` | | help for upstream | | `--kubeconfig` | string | the kubeconfig to use. **Default:** `$KUBECONFIG`. If unset, then `$HOME/.kube/config` | | `-n, --namespace` | string | (Required) the namespace where the Admin Console is running | | `--deploy` | bool | ensures the latest available release is deployed | | `--deploy-version-label` | string | ensures the release with the provided version label is deployed | | `--skip-preflights` | bool | set to true to skip preflight checks if no strict preflights exist; when strict preflights are present, all preflights still run, but non-strict failures are ignored | | `--airgap-bundle` | string | path to the application airgap bundle where application images and metadata will be loaded from | | `--kotsadm-namespace` | string | the registry namespace to use for application images | | `--kotsadm-registry` | string | the registry endpoint where application images will be pushed | | `--registry-password` | string | the password to use to authenticate with the registry | | `--registry-username` | string | the username to use to authenticate with the registry | | `--disable-image-push` | bool | set to true to disable images from being pushed to private registry. **Default:** `false` | | `--skip-registry-check` | bool | Set to `true` to skip the connectivity test and validation of the provided registry information. **Default:** `false` | | `--wait` | bool | set to false to download the updates in the background **Default:** `true` | | `-o, --output` | string | output format (currently supported: json). **Default:** Plain text if not set | #### About Strict Preflight Checks If any strict preflight checks are configured, the `--skip-preflights` flag are not honored because the preflight checks must run and contain no failures before the application is deployed. When the `--deploy` option is provided and there are strict preflight checks, the preflight checks always run. The deployment waits for up to 15 minutes for the preflight checks to complete. If the checks complete without strict preflight failures, the release deploys. If the checks do not complete within 15 minutes, the release does not deploy. If there are one or more strict preflight failures, the release does not deploy. For more information about strict preflight checks, see [Define Preflight Checks](/vendor/preflight-defining). ## Example ```bash kubectl kots upstream upgrade kots-sentry --namespace kots-sentry ``` --- # upstream KOTS Upstream interface. ### Usage ```bash kubectl kots upstream [command] [flags] ``` This command supports all [global flags](kots-cli-global-flags). --- # velero configure-aws-s3 Configures snapshots to use an AWS S3 Bucket as a storage destination. This command supports auth via [IAM User Access Keys](https://github.com/vmware-tanzu/velero-plugin-for-aws#option-1-set-permissions-with-an-iam-user) and IAM Instance Roles for the velero-plugin-for-aws. Valid Subcommands: * `access-key` * `instance-role` ### Usage ```bash kubectl kots velero configure-aws-s3 [subcommand] ``` | Flag | Type | Description | |--------------|------|--------------------------| | `-h, --help` | | help for configure-aws-s3 | ### access-key ```bash kubectl kots velero configure-aws-s3 access-key [flags] ``` - _Provide `[flags]` according to the table below_ | Flag | Type | Description | |------------------------|--------|-------------------------------------------------------------------------------| | `-h, --help` | | help for access-key | | `-n, --namespace` | string | the namespace of the Admin Console _(required)_ | | `--access-key-id` | string | the aws access key id to use for accessing the bucket _(required)_ | | `--bucket` | string | name of the object storage bucket where backups should be stored _(required)_ | | `--path ` | string | path to a subdirectory in the object store bucket | | `--region ` | string | the region where the bucket exists _(required)_ | | `--secret-access-key ` | string | the aws secret access key to use for accessing the bucket _(required)_ | | `--skip-validation` | bool | skip the validation of the S3 Bucket _(default `false`)_ | #### Example ```bash kubectl kots velero configure-aws-s3 access-key --namespace default --region us-east-1 --bucket kots-snaps --access-key-id XXXXXXXJTJB7M2XZUV7D --secret-access-key ``` ### instance-role ```bash kubectl kots velero configure-aws-s3 instance-role [flags] ``` - _Provide `[flags]` according to the table below_ | Flag | Type | Description | |------------------------|--------|-------------------------------------------------------------------------------| | `-h, --help` | | help for access-key | | `-n, --namespace` | string | the namespace of the Admin Console _(required)_ | | `--bucket` | string | name of the object storage bucket where backups should be stored _(required)_ | | `--path ` | string | path to a subdirectory in the object store bucket | | `--region ` | string | the region where the bucket exists _(required)_ | | `--skip-validation` | bool | skip the validation of the S3 Bucket _(default `false`)_ | #### Example ```bash kubectl kots velero configure-aws-s3 instance-role --namespace default --region us-east-1 --bucket kots-snaps ``` --- # velero configure-azure Configures snapshots to use an Azure Blob Storage Container as a storage destination. Currently only the [Service Principle authentication method](https://github.com/vmware-tanzu/velero-plugin-for-microsoft-azure#option-1-create-service-principal) of the velero-plugin-for-microsoft-azure. Valid Subcommands: * service-principle ### Usage ```bash kubectl kots velero configure-azure [subcommand] ``` | Flag | Type | Description | |--------------|------|--------------------------| | `-h, --help` | | help for configure-azure | ### service-principle ```bash kubectl kots velero configure-azure service-principle [flags] ``` - _Provide `[flags]` according to the table below_ | Flag | Type | Description | |---------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------| | `-h, --help` | | help for service-principle | | `-n, --namespace` | string | the namespace of the Admin Console _(required)_ | | `--client-id` | string | the client ID of a Service Principle with access to the blob storage container _(required)_ | | `--client-secret` | string | the client secret of a Service Principle with access to the blob storage container _(required)_ | | `--cloud-name` | string | the Azure cloud target. Options: AzurePublicCloud, AzureUSGovernmentCloud, AzureChinaCloud, AzureGermanCloud _(default `AzurePublicCloud`)_ | | `--container` | string | name of the Azure blob storage container where backups should be stored _(required)_ | | `--path ` | string | path to a subdirectory in the blob storage container | | `--resource-group` | string | the resource group name of the blob storage container _(required)_ | | `--skip-validation` | bool | skip the validation of the blob storage container _(default `false`)_ | | `--storage-account` | string | the storage account name of the blob storage container _(required)_ | | `--subscription-id` | string | the subscription id associated with the blob storage container _(required)_ | | `--tenant-id ` | string | the tenant ID associated with the blob storage container _(required)_ | #### Example ```bash kubectl kots velero configure-azure service-principle --namespace default --container velero --resource-group Velero_Backups --storage-account velero1111362eb32b --subscription-id "1111111-1111-47a7-9671-c904d681c2b2" --tenant-id "1111111-1111-42e1-973b-ad2efc689308" --client-id "1111111-1111-4ac3-9e2b-bbea61392432" --client-secret "" ``` --- # velero configure-gcp Configures snapshots to use a Google Cloud Platform Object Storage Bucket as a storage destination. This command supports auth via [Serivce Account Credentials](https://github.com/vmware-tanzu/velero-plugin-for-gcp#option-1-set-permissions-with-a-service-account) or [Workload Identity](https://github.com/vmware-tanzu/velero-plugin-for-gcp#option-2-set-permissions-with-using-workload-identity-optional). Valid Subcommands: * `service-account` * `workload-identity` ### Usage ```bash kubectl kots velero configure-gcp [subcommand] ``` | Flag | Type | Description | |--------------|------|--------------------------| | `-h, --help` | | help for configure-aws-s3 | ### service-account ```bash kubectl kots velero configure-gcp service-account [flags] ``` - _Provide `[flags]` according to the table below_ | Flag | Type | Description | |---------------------|--------|-------------------------------------------------------------------------------| | `-h, --help` | | help for access-key | | `-n, --namespace` | string | the namespace of the Admin Console _(required)_ | | `--bucket` | string | name of the object storage bucket where backups should be stored _(required)_ | | `--json-file` | string | path to JSON credntials file for veloro _(required)_ | | `--path ` | string | path to a subdirectory in the object store bucket | | `--skip-validation` | bool | skip the validation of the GCP Bucket _(default `false`)_ | #### Example ```bash kubectl kots velero configure-gcp service-account --namespace default --bucket velero-backups --json-file sa-creds.json ``` ### workload-identity ```bash kubectl kots velero configure-gcp workload-identity [flags] ``` - _Provide `[flags]` according to the table below_ | Flag | Type | Description | |---------------------|--------|-------------------------------------------------------------------------------| | `-h, --help` | | help for access-key | | `-n, --namespace` | string | the namespace of the Admin Console _(required)_ | | `--bucket` | string | name of the object storage bucket where backups should be stored _(required)_ | | `--path ` | string | path to a subdirectory in the object store bucket | | `--service-account` | string | the service account to use if using Google Cloud instance role _(required)_ | | `--skip-validation` | bool | skip the validation of the GCP Bucket _(default `false`)_ | #### Example ```bash kubectl kots velero configure-gcp workload-identity --namespace default --bucket velero-backups --service-account ss-velero@gcp-project.iam.gserviceaccount.com ``` --- # velero configure-hostpath Configure snapshots to use a host path as storage destination. :::note The local-volume-provider (LVP) plugin supports only Restic. Velero 1.17 and later do not support LVP. By default, KOTS uses the S3-compatible filesystem MinIO path for HostPath storage when MinIO is enabled. KOTS uses LVP only when you disable MinIO or explicitly install the LVP plugin. For more information, see [Upgrade Velero for snapshots](/enterprise/snapshots-velero-upgrading). ::: ### Usage ```bash kubectl kots velero configure-hostpath [flags] ``` - _Provide `[flags]` according to the table below_
Flag Type Description
-h, --help Help for the command.
`-n, --namespace` string The namespace of the Admin Console (required)
`--hostpath` string A local host path on the node
--kotsadm-namespace string

Set to override the registry namespace of KOTS Admin Console images. Used for air gap installations. For more information, see [Air Gap Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster-airgapped).

Note: Replicated recommends that you use --kotsadm-registry instead of --kotsadm-namespace to override both the registry hostname and, optionally, the registry namespace with a single flag.
--kotsadm-registry string Set to override the registry hostname and namespace of KOTS Admin Console images. Used for air gap installations. For more information, see [Air Gap Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster-airgapped).
--registry-password string Password to use to authenticate with the application registry. Used for air gap installations.
--registry-username string Username to use to authenticate with the application registry. Used for air gap installations.
`--force-reset` bool Bypass the reset prompt and force resetting the nfs path. (default `false`)
`--output` string Output format. Supported values: `json`
### Examples Basic ```bash kubectl kots velero configure-hostpath --hostpath /mnt/kots-sentry-snapshots --namespace kots-sentry ``` Using a registry for airgapped installations ```bash kubectl kots velero configure-hostpath \ --hostpath /mnt/kots-sentry-snapshots \ --namespace kots-sentry \ --kotsadm-registry private.registry.host/kots-sentry \ --registry-username ro-username \ --registry-password ro-password ``` --- # velero configure-internal :::important The following command is applicable only to embedded clusters created by Replicated kURL and is _not_ recommended for production usage. Consider configuring one of the other available storage destinations. See [Configuring Other Storage Destinations](/enterprise/snapshots-storage-destinations). ::: Configures snapshots to use the internal object store in embedded clusters as a storage destination. ### Usage ```bash kubectl kots velero configure-internal [flags] ``` - _Provide `[flags]` according to the table below_ | Flag | Type | Description | |------------------------|--------|-------------------------------------------------------------------------------| | `-h, --help` | | help for access-key | | `--skip-validation` | bool | skip the validation of the S3 Bucket _(default `false`)_ | #### Example ```bash kubectl kots velero configure-internal ``` --- # velero configure-nfs Configures snapshots to use NFS as storage destination. :::note The local-volume-provider (LVP) plugin supports only Restic. Velero 1.17 and later do not support LVP. By default, KOTS uses the S3-compatible filesystem MinIO path for NFS storage when MinIO is enabled. KOTS uses LVP only when you disable MinIO or explicitly install the LVP plugin. For more information, see [Upgrade Velero for snapshots](/enterprise/snapshots-velero-upgrading). ::: ### Usage ```bash kubectl kots velero configure-nfs [flags] ``` - _Provide `[flags]` according to the table below_
Flag Type Description
-h, --help Help for the command.
`-n, --namespace` string The namespace of the Admin Console (required)
`--nfs-server` string The hostname or IP address of the NFS server (required)
`--nfs-path` string The path that is exported by the NFS server (required)
--kotsadm-namespace string

Set to override the registry namespace of KOTS Admin Console images. Used for air gap installations. For more information, see [Air Gap Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster-airgapped).

Note: Replicated recommends that you use --kotsadm-registry instead of --kotsadm-namespace to override both the registry hostname and, optionally, the registry namespace with a single flag.
--kotsadm-registry string Set to override the registry hostname and namespace of KOTS Admin Console images. Used for air gap installations. For more information, see [Air Gap Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster-airgapped).
--registry-password string Password to use to authenticate with the application registry. Used for air gap installations.
--registry-username string Username to use to authenticate with the application registry. Used for air gap installations.
`--force-reset` bool Bypass the reset prompt and force resetting the nfs path. (default `false`)
`--output` string Output format. Supported values: `json`
### Examples Basic ```bash kubectl kots velero configure-nfs --nfs-server 10.128.0.32 --nfs-path /mnt/nfs_share --namespace kots-sentry ``` Using a registry for airgapped installations ```bash kubectl kots velero configure-nfs \ --nfs-server 10.128.0.32 \ --nfs-path /mnt/nfs_share \ --namespace kots-sentry \ --kotsadm-registry private.registry.host/kots-sentry \ --registry-username ro-username \ --registry-password ro-password ``` --- # velero configure-other-s3 Configures snapshots to use an S3-compatible storage provider, such as Minio, as a storage destination. ### Usage ```bash kubectl kots velero configure-other-s3 [flags] ``` - _Provide `[flags]` according to the table below_
Flag Type Description
-h, --help Help for the command.
`-n, --namespace` string The namespace of the Admin Console (required)
`--access-key-id` string The AWS access key ID to use for accessing the bucket (required)
`--bucket` string Name of the object storage bucket where backups should be stored (required)
`--endpoint` string The S3 endpoint (for example, http://some-other-s3-endpoint) (required)
`--path` string Path to a subdirectory in the object store bucket
`--region` string The region where the bucket exists (required)
`--secret-access-key` string The AWS secret access key to use for accessing the bucket (required)
`--cacert` string File containing a certificate bundle to use when verifying TLS connections to the object store
`--skip-validation` bool Skip the validation of the S3 bucket (default `false`)
--kotsadm-namespace string

Set to override the registry namespace of KOTS Admin Console images. Used for air gap installations. For more information, see [Air Gap Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster-airgapped).

Note: Replicated recommends that you use --kotsadm-registry instead of --kotsadm-namespace to override both the registry hostname and, optionally, the registry namespace with a single flag.
--kotsadm-registry string Set to override the registry hostname and namespace of KOTS Admin Console images. Used for air gap installations. For more information, see [Air Gap Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster-airgapped).
--registry-password string Password to use to authenticate with the application registry. Used for air gap installations.
--registry-username string Username to use to authenticate with the application registry. Used for air gap installations.
#### Example ```bash kubectl kots velero configure-other-s3 --namespace default --endpoint http://minio --region us-east-1 --bucket kots-snaps --access-key-id XXXXXXXJTJB7M2XZUV7D --secret-access-key mysecretkey ``` --- # velero ensure-permissions Ensures the necessary permissions that enables Replicated KOTS to access Velero. ### Usage ```bash kubectl kots velero ensure-permissions [flags] ``` - _Provide `[flags]` according to the table below_ | Flag | Type | Description | | ----------------- | ------ | ------------------------------------------------------------------- | | `-h, --help` | | help for ensure-permissions | | `-n, --namespace` | string | the namespace where the Admin Console is running _(required)_ | | `--velero-namespace` | string | the namespace where velero is running _(required)_ | ### Example ```bash kubectl kots velero ensure-permissions --namespace kots-sentry --velero-namespace velero ``` --- # velero The KOTS Velero interface, which configures storage destinations for backups (snapshots), permissions, and print instructions fo set up. ### Usage ```bash kubectl kots velero [command] [global flags] ``` This command supports all [global flags](kots-cli-global-flags). The following `kots velero` commands are supported: - [`configure-aws-s3`](kots-cli-velero-configure-aws-s3): Configures an AWS S3 bucket as the storage destination. - [`configure-azure`](kots-cli-velero-configure-azure): Configures an Azure Blob Storage Container as the storage destination. - [`configure-gcp`](kots-cli-velero-configure-gcp): Configures a Google Cloud Platform Object Storage Bucket as The storage destination. - [`configure-internal`](kots-cli-velero-configure-internal): (Embedded clusters only) Configures the internal object store in the cluster as the storage destination. - [`configure-other-s3`](kots-cli-velero-configure-other-s3): Configures an S3-compatible storage provider as the storage destination. - [`configure-nfs`](kots-cli-velero-configure-nfs): Configures NFS as the storage destination. - [`configure-hostpath`](kots-cli-velero-configure-hostpath): Configures a host path as the storage destination. - [`ensure-permissions`](kots-cli-velero-ensure-permissions): Allows the KOTS Admin Console to access Velero. --- # velero print-fs-instructions :::note This command is deprecated. Use [`kubectl kots velero configure-hostpath`](/reference/kots-cli-velero-configure-hostpath) or [`kubectl kots velero configure-nfs`](/reference/kots-cli-velero-configure-nfs) instead. ::: Prints instructions for setting up a file system as the snapshots storage destination (such as NFS or host path). ### Usage ```bash kubectl kots velero print-fs-instructions [flags] ``` - _Provide `[flags]` according to the table below_ | Flag | Type | Description | | ----------------- | ------ | ------------------------------------------------------------------- | | `-h, --help` | | help for ensure-permissions | | `-n, --namespace` | string | the namespace of the Admin Console _(required)_ | ### Example Basic ```bash kubectl kots velero print-fs-instructions --namespace kots-sentry ``` --- # Linter Rules This topic describes the release linter and the linter rules. ## Overview The linter checks the manifest files in Replicated KOTS releases to ensure that there are no YAML syntax errors, that all required manifest files are present in the release to support installation with KOTS, and more. The linter runs automatically against KOTS releases that you create in the Replicated vendor portal, and displays any error or warning messages in the vendor portal UI. To lint manifest files from the command line, you can run the Replicated CLI `replicated release lint` command against the root directory of your application manifest files. You can also use the `--lint` flag when you create a release with the `replicated release create` command. For more information, see [release lint](/reference/replicated-cli-release-lint) and [release create](/reference/replicated-cli-release-create) in the _Replicated CLI_ section. ## Linter Rules This section lists the linter rules and the default rule levels (Info, Warn, Error). You can customize the default rule levels in the Replicated LinterConfig custom resource. For more information, see [LintConfig](custom-resource-lintconfig). ### allow-privilege-escalation
Description Notifies if any manifest file has allowPrivilegeEscalation set to true.
Level Info
Applies To All files
Example

Example of matching YAML for this rule:
### application-icon
Description Requires an application icon.
Level Warn
Applies To Files with kind: Application and apiVersion: kots.io/v1beta1.
Example

Example of correct YAML for this rule:
### application-spec
Description

Requires an Application custom resource manifest file.

Accepted value for kind: Application
Level Warn
Example

Example of matching YAML for this rule:
### application-statusInformers
Description Requires statusInformers.
Level Warn
Applies To Files with kind: Application and apiVersion: kots.io/v1beta1.
Example

Example of correct YAML for this rule:
### config-option-invalid-type
Description

Enforces valid types for Config items.

For more information, see Items in Config.
Level Error
Applies To All files
Example
### config-option-is-circular
Description Enforces that all ConfigOption items do not reference themselves.
Level Error
Applies To Files with kind: Config and apiVersion: kots.io/v1beta1.
Example
### config-option-not-found
Description Requires all ConfigOption items to be defined in the Config custom resource manifest file.
Level Warn
Applies To All files
### config-option-not-repeatable
Description Enforces that sub-templated ConfigOption items must be repeatable.
Level Error
Applies To All files
### config-option-password-type
Description

Requires ConfigOption items with any of the following names to have type set to password:

  • password
  • secret
  • token
Level Warn
Applies To All files
Example

Example of correct YAML for this rule:
### config-option-when-is-invalid
Description

Enforces valid ConfigOption.when.

For more information, see when in Config.
Level Error
Applies To Files with kind: Config and apiVersion: kots.io/v1beta1.
### config-option-invalid-regex-validator
Description

Enforces valid RE2 regular expressions pattern when regex validation is present.

For more information, see Validation in Config.
Level Error
Applies To Files with kind: Config and apiVersion: kots.io/v1beta1.
Example
### config-option-regex-validator-invalid-type
Description

Enforces valid item type when regex validation is present.

Item type should be text|textarea|password|file

For more information, see Validation in Config.
Level Error
Applies To Files with kind: Config and apiVersion: kots.io/v1beta1.
Example
### config-spec
Description

Requires a Config custom resource manifest file.

Accepted value for kind: Config

Accepted value for apiVersion: kots.io/v1beta1
Level Warn
Example

Example of matching YAML for this rule:
### container-image-latest-tag
Description Notifies if any manifest file has a container image tag appended with :latest.
Level Info
Applies To All files
Example

Example of matching YAML for this rule:
### container-image-local-image-name
Description Disallows any manifest file having a container image tag that includes LocalImageName.
Level Error
Applies To All files
Example

Example of matching YAML for this rule:
### container-resource-limits
Description Notifies if a spec.container has no resources.limits field.
Level Info
Applies To All files
Example

Example of matching YAML for this rule:
### container-resource-requests
Description Notifies if a spec.container has no resources.requests field.
Level Info
Applies To All files
Example

Example of matching YAML for this rule:
### container-resources
Description Notifies if a manifest file has no resources field.
Level Info
Applies To All files
Example

Example of matching YAML for this rule:
### deprecated-kubernetes-installer-version
Description

Disallows using the deprecated kURL installer apiVersion.

kurl.sh/v1beta1 is deprecated. Use cluster.kurl.sh/v1beta1 instead.
Level Warn
Applies To Files with kind: Installer and apiVersion: kurl.sh/v1beta1.
Example
### duplicate-helm-release-name
Description

Enforces unique spec.chart.releaseName across all HelmChart custom resource manifest files.
Level Error
Applies To Files with kind: HelmChart and apiVersion: kots.io/v1beta1.
### duplicate-kots-kind
Description

Disallows duplicate Replicated custom resources. A release can only include one of each kind of custom resource.

This rule disallows inclusion of more than one file with:

  • The same kind and apiVersion
  • kind: Troubleshoot and any Troubleshoot apiVersion
  • kind: Installer and any Installer apiVersion
Level Error
Applies To All files
### hardcoded-namespace
Description

Notifies if any manifest file has a metadata.namespace set to a static field.

Replicated strongly recommends not specifying a namespace to allow for flexibility when deploying into end user environments.

For more information, see Managing Application Namespaces.
Level Info
Applies To All files
Example

Example of matching YAML for this rule:
### helm-archive-missing
Description

Requires that a *.tar.gz file is present that matches what is in the HelmChart custom resource manifest file.
Level Error
Applies To Releases with a HelmChart custom resource manifest file containing kind: HelmChart and apiVersion: kots.io/v1beta1.
### helm-chart-missing
Description

Enforces that a HelmChart custom resource manifest file with kind: HelmChart is present if there is a *.tar.gz archive present.
Level Error
Applies To Releases with a *.tar.gz archive file present.
### helm-schema-violation
Description

Runs helm lint against each Helm chart archive in the release that is referenced by a HelmChart custom resource. Uses the chart's default values merged with spec.builder values from the HelmChart custom resource. Surfaces any violations reported by Helm, including JSON schema validation errors from the chart's values.schema.json.

Each top-level violation is reported as a separate finding so that individual schema errors are easier to read and address.

For more information about spec.builder, see builder in HelmChart v2.
Level Error
Applies To Helm v3 and later chart archives (*.tar.gz) that have a matching HelmChart custom resource. HelmChart custom resources with helmVersion: v2 are skipped.
### invalid-helm-release-name
Description

Enforces valid spec.chart.releaseName in the HelmChart custom resource manifest file.

spec.chart.releaseName must meet the following requirements:

  • Begin and end with a lowercase letter or number
  • Contain only lowercase letters, numbers, periods, and hyphens (-)
  • Contain a lowercase letter or number between any two symbols (periods or hyphens)
Level Warn
Applies To Files with kind: HelmChart and apiVersion: kots.io/v1beta1.
Example

Example of correct YAML for this rule:
### invalid-kubernetes-installer
Description

Enforces valid Replicated kURL add-on versions.

kURL add-ons included in the kURL installer must pin specific versions rather than latest or x-ranges (1.2.x).
Level Error
Applies To

Files with kind: Installer and one of the following values for apiVersion:

  • cluster.kurl.sh/v1beta1
  • kurl.sh/v1beta1
Example
### invalid-min-kots-version
Description

Requires minKotsVersion in the Application custom resource to use valid Semantic Versioning. See Semantic Versioning 2.0.0.

Accepts a v as an optional prefix, so both 1.0.0 and v1.0.0 are valid.
Level Error
Applies To Files with kind: Application and apiVersion: kots.io/v1beta1.
Example

Example of correct YAML for this rule:
### invalid-rendered-yaml
Description

Enforces valid YAML after rendering the manifests using the Config spec.
Level Error
Applies To YAML files
Example
### invalid-target-kots-version
Description

Requires targetKotsVersion in the Application custom resource to use valid Semantic Versioning. See Semantic Versioning 2.0.0.

Accepts a v as an optional prefix, so both 1.0.0 and v1.0.0 are valid.
Level Error
Applies To Files with kind: Application and apiVersion: kots.io/v1beta1
Example

Example of correct YAML for this rule:
### invalid-type
Description

Requires that the value of a property matches that property's expected type.
Level Error
Applies To All files
Example
### invalid-yaml
Description

Enforces valid YAML.
Level Error
Applies To YAML files
Example
### may-contain-secrets
Description Notifies if any manifest file may contain secrets.
Level Info
Applies To All files
Example

Example of matching YAML for this rule:
### missing-api-version-field
Description Requires the apiVersion: field in all files.
Level Error
Applies To All files
Example

Example of correct YAML for this rule:
### missing-kind-field
Description Requires the kind: field in all files.
Level Error
Applies To All files
Example

Example of correct YAML for this rule:
### nonexistent-status-informer-object
Description

Requires that each statusInformers entry references an existing Kubernetes workload.

The linter cannot evaluate statusInformers for Helm-managed resources because it does not template Helm charts during analysis.

If you configure status informers for Helm-managed resources, you can ignore nonexistent-status-informer-object warnings for those workloads. To disable nonexistent-status-informer-object warnings, change the level for this rule to info or off in the LintConfig custom resource manifest file. See LintConfig in Custom Resources.
Level Warning
Applies To

Compares statusInformer values in files with kind: Application and apiVersion: kots.io/v1beta1 to all manifests in the release.
### preflight-spec
Description

Requires a Preflight custom resource manifest file with:

kind: Preflight

and one of the following:

  • apiVersion: troubleshoot.replicated.com/v1beta1
  • apiVersion: troubleshoot.sh/v1beta2
Level Warn
Example

Example of matching YAML for this rule:
### privileged
Description Notifies if any manifest file has privileged set to true.
Level Info
Applies To All files
Example

Example of matching YAML for this rule:
### repeat-option-malformed-yamlpath
Description

Enforces ConfigOption yamlPath ending with square brackets denoting index position.

For more information, see Repeatable Item Template Targets in Config.
Level Error
Applies To All files
Example

Example of correct YAML for this rule:
### repeat-option-missing-template
Description

Disallows repeating Config item with undefined item.templates.

For more information, see Repeatable Item Template Targets in Config.
Level Error
Applies To All files
Example

Example of correct YAML for this rule:
### repeat-option-missing-valuesByGroup
Description

Disallows repeating Config item with undefined item.valuesByGroup.

For more information, see Repeatable Items in Config.
Level Error
Applies To All files
Example

Example of correct YAML for this rule:
### replicas-1
Description Notifies if any manifest file has replicas set to 1.
Level Info
Applies To All files
Example

Example of matching YAML for this rule:
### resource-limits-cpu
Description Notifies if a spec.container has no resources.limits.cpu field.
Level Info
Applies To All files
Example

Example of matching YAML for this rule:
### resource-limits-memory
Description Notifies if a spec.container has no resources.limits.memory field.
Level Info
Applies To All files
Example

Example of matching YAML for this rule:
### resource-requests-cpu
Description Notifies if a spec.container has no resources.requests.cpu field.
Level Info
Applies To All files
Example

Example of matching YAML for this rule:
### resource-requests-memory
Description Notifies if a spec.container has no resources.requests.memory field.
Level Info
Applies To All files
Example

Example of matching YAML for this rule:
### troubleshoot-spec
Description

Requires a Troubleshoot manifest file.

Accepted values for kind:

  • Collector
  • SupportBundle

Accepted values for apiVersion:

  • troubleshoot.replicated.com/v1beta1
  • troubleshoot.sh/v1beta2
Level Warn
Example

Example of matching YAML for this rule:
### troubleshoot-spec-in-chart-without-crd
Description

Notifies if a Helm chart contains a top-level kind: Preflight or kind: SupportBundle custom resource.

Preflight and SupportBundle custom resources cannot be applied directly from a Helm chart — they require cluster-side CRDs that are not available in most shared clusters and that need cluster-admin permissions to install. Embed the spec in a Kubernetes Secret with the troubleshoot.sh/kind label instead. See Define preflight checks and Add and customize support bundles.
Level Warn
Applies To Helm chart archives in the release
### volume-docker-sock
Description Notifies if a spec.volumes has hostPath set to /var/run/docker.sock.
Level Info
Applies To All files
Example

Example of matching YAML for this rule:
### volumes-host-paths
Description Notifies if a spec.volumes has defined a hostPath.
Level Info
Applies To All files
Example

Example of matching YAML for this rule:
--- # Event types and filters This topic lists the types of events supported for the Event Notifications feature. For more information about the Event Notifications feature, see [About event notifications](/vendor/event-notifications). ## Channel events ### Channel Created When a new channel is created for an application. #### Filters | Filter | JSON key | Required | Description | |--------|----------|----------|-------------| | Application | `appId` | No | Filter to a specific application | #### JSON definition ```json { "eventType": "channel.created", "filters": {} } ``` ### Channel Archived When a channel is archived. #### Filters | Filter | JSON key | Required | Description | |--------|----------|----------|-------------| | Application | `appId` | No | Filter to a specific application | | Channel | `channelId` | No | Filter to one or more specific channels | #### JSON definition ```json { "eventType": "channel.archived", "filters": { "channelId": ["channel1a2b3c4d"] } } ``` ## Customer events ### Customer Created When a new customer is created. #### Filters | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Application | `appId` | No | Any application in your account | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | | Channel | `channelId` | No | Any channel for the selected application | | Expiration Status | `expirationStatus` | No | `active`, `expiring_soon`, `perpetual` | #### JSON definition ```json { "eventType": "customer.created", "filters": { "licenseType": ["paid", "trial"] } } ``` ### Customer Updated When a customer's details or license is updated. #### Filters | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Application | `appId` | No | Any application in your account | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | | Channel | `channelId` | No | Any channel for the selected application | | Customer | `customerId` | No | Any customer for the selected application | | Change Type | `changeType` | No | `customer_name`, `license_type`, `expiration`, `channel`, `install_options`, `helm_email`, `entitlement` | #### JSON definition ```json { "eventType": "customer.updated", "filters": { "changeType": ["license_type", "expiration"] } } ``` ### Customer Archived When a customer is archived. #### Filters | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Application | `appId` | No | Any application in your account | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | | Channel | `channelId` | No | Any channel for the selected application | | Customer | `customerId` | No | Any customer for the selected application | #### JSON definition ```json { "eventType": "customer.archived", "filters": {} } ``` ### Customer Unarchived (Restored) When a customer is restored from archived state. #### Filters | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Application | `appId` | No | Any application in your account | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | | Channel | `channelId` | No | Any channel for the selected application | | Customer | `customerId` | No | Any customer for the selected application | #### JSON definition ```json { "eventType": "customer.unarchived", "filters": {} } ``` ### Customer License Expiring Time-based warning of an upcoming license expiration. #### Filters | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Application | `appId` | No | Any application in your account | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | | Channel | `channelId` | No | Any channel for the selected application | | Customer | `customerId` | No | Any customer for the selected application | | Days Until Expiry | `daysUntilExpiry` | No | `0`, `1`, `7`, `14`, `30`, `60`, `90` | #### JSON definition ```json { "eventType": "customer.license_expiring", "filters": { "daysUntilExpiry": ["7", "30"] } } ``` ### Pending Self-Service Signup When someone signs up via the self-service portal (if enabled). #### Filters | Filter | JSON key | Required | Description | |--------|----------|----------|-------------| | Application | `appId` | No | Filter to a specific application | #### JSON definition ```json { "eventType": "customer.pending_signup", "filters": {} } ``` ### Enterprise Portal Invite Sent When a vendor sends an Enterprise Portal invite to a user. #### Filters | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Application | `appId` | No | Any application in your account | | Customer | `customerId` | No | Any customer for the selected application | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | #### JSON definition ```json { "eventType": "customer.ep_invite_sent", "filters": {} } ``` ### Enterprise Portal Access Granted When a user accesses the Enterprise Portal. #### Filters
Filter JSON key Required Options
Application appId No Any application in your account
Customer customerId No Any customer for the selected application
Access Method accessMethod No invite, self_signup, saml_jit
License Type licenseType No paid, trial, community, dev
Access Type accessType No
  • any (default): Triggers a notification every time a user accesses the Enterprise Portal.
  • first_for_license_type: Triggers a notification the first time that a customer with a specific license type accesses the Enterprise Portal. For example, if you select "Paid" for the License Type filter, then you will receive a notification the first time that a customer with a Paid license access the Enterprise Portal, even if they previously logged in when they had a Trial license.

First Access for Selected License Type only tracks Enterprise Portal access events that occur after March 27, 2026.
#### JSON definition ```json { "eventType": "customer.ep_access_granted", "filters": { "licenseType": ["paid"], "accessType": "first_for_license_type" } } ``` ### Enterprise Portal User Joined When a user joins an Enterprise Portal customer. #### Filters | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Application | `appId` | No | Any application in your account | | Customer | `customerId` | No | Any customer for the selected application | | Access Method | `accessMethod` | No | `invite`, `self_signup`, `saml_jit` | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | #### JSON definition ```json { "eventType": "customer.ep_user_joined", "filters": {} } ``` ## Instance events :::note Instance event notifications use the **Instance Name** if set. Otherwise, they use the Instance ID. ::: ### Instance Created When a new instance sends its first check-in. #### Filters | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Application | `appId` | No | Any application in your account | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | | Channel | `channelId` | No | Any channel for the selected application | | Customer | `customerId` | No | Any customer for the selected application | #### JSON definition ```json { "eventType": "instance.created", "filters": {} } ``` ### Instance Ready When a new instance's application status is Ready for the first time. #### Filters | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Application | `appId` | No | Any application in your account | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | | Channel | `channelId` | No | Any channel for the selected application | | Customer | `customerId` | No | Any customer for the selected application | #### JSON definition ```json { "eventType": "instance.ready", "filters": {} } ``` ### Instance Upgrade Started When an instance begins upgrading to a new release version. This event fires when the Vendor Portal receives the first telemetry with a new release version, whether or not the application status is Ready. #### Filters | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Application | `appId` | No | Any application in your account | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | | Channel | `channelId` | No | Any channel for the selected application | | Customer | `customerId` | No | Any customer for the selected application | #### JSON definition ```json { "eventType": "instance.upgrade_started", "filters": {} } ``` ### Instance Upgrade Completed When an instance's application status is Ready after upgrading to a new release version. #### Filters | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Application | `appId` | No | Any application in your account | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | | Channel | `channelId` | No | Any channel for the selected application | | Customer | `customerId` | No | Any customer for the selected application | #### JSON definition ```json { "eventType": "instance.upgrade_completed", "filters": {} } ``` ### Instance Version Behind When an instance falls behind by a specified number of versions. #### Filters | Filter | JSON key | Required | Description | |--------|----------|----------|-------------| | Versions Behind | `versionsBehind` | **Yes** | Minimum number of versions behind to trigger the notification. Provide as a string (for example, `"3"`). | | Application | `appId` | No | Any application in your account | | Channel | `channelId` | No | Any channel for the selected application | | Customer | `customerId` | No | Any customer for the selected application | #### JSON definition ```json { "eventType": "instance.version_behind", "filters": { "versionsBehind": "3" } } ``` ### Instance Inactive When an instance has not checked-in for 24 hours (declared "Inactive"). Air-gapped instances are excluded from this event type. #### Filters | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Application | `appId` | No | Any application in your account | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | | Channel | `channelId` | No | Any channel for the selected application | | Customer | `customerId` | No | Any customer for the selected application | #### JSON definition ```json { "eventType": "instance.inactive", "filters": {} } ``` ### Instance State Duration When an instance has been in a specific state (such as Unavailable or Degraded) for a specified duration. The Instance State Duration event type requires you to specify the target state and duration threshold. Only one Instance State Duration event is allowed per subscription. | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | State | `state` | **Yes** | `ready`, `unavailable`, `degraded`, `updating`, `missing` | | Duration (minutes) | `durationMinutes` | **Yes** | `"5"`, `"10"`, `"15"`, `"30"`, `"60"`, `"120"`, `"240"`, `"480"`, `"1440"` | | Application | `appId` | No | Any application in your account | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | | Channel | `channelId` | No | Any channel for the selected application | | Customer | `customerId` | No | Any customer for the selected application | The `state` filter accepts one or more values as an array. The `durationMinutes` value must be provided as a string. The notification triggers when an instance has been in the specified state for at least the configured duration. If the instance recovers and later re-enters the monitored state, the notification can trigger again after the duration threshold is met. #### JSON definition ```json { "eventType": "instance.state.duration", "filters": { "state": ["unavailable", "degraded"], "durationMinutes": "60" } } ``` ### Instance State Flapping When an instance is changing states frequently within a configured time window. The Instance State Flapping event type requires you to specify the sensitivity of flapping detection: | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Minimum State Changes | `minStateChanges` | **Yes** | `"3"`, `"5"`, `"10"`, `"15"`, `"20"` | | Time Window (minutes) | `windowMinutes` | **Yes** | `"30"`, `"60"`, `"120"` | | Cooldown Period (minutes) | `cooldownMinutes` | No | `"15"`, `"30"`, `"60"`, `"120"`, `"1440"` (default: `"60"`) | | Application | `appId` | No | Any application in your account | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | | Channel | `channelId` | No | Any channel for the selected application | | Customer | `customerId` | No | Any customer for the selected application | The numeric filter values (`minStateChanges`, `windowMinutes`, `cooldownMinutes`) must be provided as strings. The notification triggers when an instance accumulates the specified number of state changes within the time window. The cooldown period prevents repeated notifications for the same instance within the configured interval. #### JSON definition ```json { "eventType": "instance.state.flapping", "filters": { "minStateChanges": "5", "windowMinutes": "60", "cooldownMinutes": "60" } } ``` ### Custom Metric Threshold Reached When a custom metric value reported by an instance meets a configured threshold condition. The Custom Metric Threshold Reached event type requires a metric name, comparison operator, and notification frequency. You can include only one Custom Metric Threshold Reached event per subscription. #### Filters | Filter | JSON key | Required | Description | |--------|----------|----------|-------------| | Metric Name | `metricName` | **Yes** | The name of the custom metric to monitor | | Operator | `operator` | **Yes** | Comparison operator. The operators available depend on the metric type. For more information, see [Available operators](#available-operators). | | Threshold Value | `thresholdValue` | Conditional | Required for all operators except `is_true`, `is_false`, `exists`, and `not_exists`. Provide as a string. | | Frequency | `frequency` | **Yes** | Controls how often you receive the notification. For more information, see [Frequency options](#frequency-options). | | Application | `appId` | No | Any application in your account | | Customer | `customerId` | No | Any customer for the selected application | #### Available operators The available operators depend on the type of metric value: | Metric Type | Available operators (JSON value) | |-------------|----------------------------------| | Number | `gt` (greater than), `gte` (greater than or equal), `lt` (less than), `lte` (less than or equal), `eq` (equals), `neq` (does not equal), `exists`, `not_exists` | | Boolean | `is_true`, `is_false`, `eq` (equals), `neq` (does not equal), `exists`, `not_exists` | | String | `contains`, `starts_with`, `ends_with`, `eq` (equals), `neq` (does not equal), `exists`, `not_exists` | #### Frequency options The following frequency options control how often the notification triggers: | Frequency | JSON value | Behavior | |-----------|------------|----------| | Send Once | `once` | Notifies the first time the metric meets the threshold. Does not notify again until the condition clears and the metric meets the threshold again. | | When Changed | `when_changed` | Notifies when the metric meets the threshold and its value has changed since the last notification. | | Each Time | `each_time` | Notifies every time a metric report meets the threshold condition. | #### JSON definition ```json { "eventType": "instance.custom_metric_threshold_reached", "filters": { "metricName": "error_rate", "operator": "gt", "thresholdValue": "0.05", "frequency": "when_changed" } } ``` ## Platform events Platform events are account-level events that are not scoped to a single application instance, customer, release, or channel. ### Egress Threshold Reached When monthly registry egress for the team reaches a configured threshold. The Egress Threshold Reached event evaluates the current calendar month's registry egress for the team. When the total reaches or exceeds the configured threshold, Replicated sends one notification for the subscription, threshold, and month. The notification can fire again in a later month, or if the threshold configuration is changed. #### Filters | Filter | JSON key | Required | Description | |--------|----------|----------|-------------| | Threshold (TiB) | `thresholdTiB` | **Yes** | Monthly registry egress threshold in tebibytes. Provide as a string, for example `"5"` or `"5.5"`. | #### JSON definition ```json { "eventType": "platform.egress_threshold_reached", "filters": { "thresholdTiB": "5" } } ``` ## Release events ### Release Created When a new release is created. #### Filters | Filter | JSON key | Required | Description | |--------|----------|----------|-------------| | Application | `appId` | No | Filter to a specific application | #### JSON definition ```json { "eventType": "release.created", "filters": {} } ``` ### Release Promoted When a release is promoted to a channel. #### Filters | Filter | JSON key | Required | Description | |--------|----------|----------|-------------| | Application | `appId` | No | Filter to a specific application | | Channel | `channelId` | No | Filter to one or more channels | #### JSON definition ```json { "eventType": "release.promoted", "filters": { "channelId": ["channel1a2b3c4d"] } } ``` ### Release Demoted (Unpublished) When a release is demoted from a channel. #### Filters | Filter | JSON key | Required | Description | |--------|----------|----------|-------------| | Application | `appId` | No | Filter to a specific application | | Channel | `channelId` | No | Filter to one or more channels | #### JSON definition ```json { "eventType": "release.unpublished", "filters": {} } ``` ### Release Build Failed When a release build fails for a release on a channel. #### Filters | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Application | `appId` | No | Any application in your account | | Channel | `channelId` | No | Any channel for the selected application | #### JSON definition ```json { "eventType": "release.build_failed", "filters": { "appId": "app1a2b3c4d" } } ``` ### Release Assets Downloaded {#release-assets-downloaded} When a customer pulls a release asset (Helm chart, Embedded Cluster bundle, or proxy registry image). Each individual asset pull triggers one Release Assets Downloaded event. #### Filters
Filter JSON key Required Options
Application appId No Any application in your account
Channel channelId No Any channel for the selected application
Customer customerId No Any customer for the selected application
License Type licenseType No paid, trial, community, dev
Asset Type assetType No helm_chart, embedded_cluster_bundle, proxy_image
Pull Type pullType No
  • any (default): Triggers a notification on every asset pull.
  • first: Triggers a notification only the first time that a customer pulls a release asset.
  • first_for_license_type: Triggers a notification the first time that a customer pulls a release asset with the selected license type. For example, if you select "Paid" for the License Type filter, you will receive a notification the first time that a customer pulls a release asset using a Paid license, even if the customer had previously pulled assets using a Trial license.

For customers who pulled software before March 18, 2026, the Vendor Portal applies is_first_customer_pull: false on all subsequent pulls. Also, First Pull for Selected License Type only tracks asset pulls that occur after March 27, 2026.
#### JSON definition ```json { "eventType": "release.asset_downloaded", "filters": { "assetType": "helm_chart", "pullType": "first_for_license_type", "licenseType": ["paid"] } } ``` ## Support events :::note Use **Support Bundle Uploaded** when you need an immediate notification that a bundle has arrived. Use **Support Bundle Analyzed** when you need to filter or route based on instance tags, bundle metadata, or bundle name. The Analyzed event fires after the bundle is extracted, so it can resolve the instance and evaluate tags when that information is available. Not all bundles will have a resolved instance or tags, but only the Analyzed event supports instance tag filtering. If you are unsure which to use, start with Support Bundle Analyzed. ::: ### Support Bundle Uploaded When a support bundle is uploaded. #### Filters | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Application | `appId` | No | Any application in your account | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | | Channel | `channelId` | No | Any channel for the selected application | | Customer | `customerId` | No | Any customer for the selected application | #### JSON definition ```json { "eventType": "support.bundle.uploaded", "filters": {} } ``` ### Support Bundle Analyzed When a support bundle analysis is completed. #### Filters | Filter | JSON key | Required | Options | |--------|----------|----------|---------| | Application | `appId` | No | Any application in your account | | License Type | `licenseType` | No | `paid`, `trial`, `community`, `dev` | | Channel | `channelId` | No | Any channel for the selected application | | Customer | `customerId` | No | Any customer for the selected application | #### JSON definition ```json { "eventType": "support.bundle.analyzed", "filters": {} } ``` --- # replicated api get Make ad-hoc GET API calls to the Replicated API ### Synopsis This is essentially like curl for the Replicated API, but uses your local credentials and prints the response unmodified. We recommend piping the output to jq for easier reading. Pass the PATH of the request as the final argument. Do not include the host or version. ``` replicated api get [flags] ``` ### Examples ``` replicated api get /v3/apps ``` ### Options ``` -h, --help help for get ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated api](replicated-cli-api) - Make ad-hoc API calls to the Replicated API --- # replicated api patch Make ad-hoc PATCH API calls to the Replicated API ### Synopsis This is essentially like curl for the Replicated API, but uses your local credentials and prints the response unmodified. We recommend piping the output to jq for easier reading. Pass the PATH of the request as the final argument. Do not include the host or version. ``` replicated api patch [flags] ``` ### Examples ``` replicated api patch /v3/customer/2VffY549paATVfHSGpJhjh6Ehpy -b '{"name":"Valuable Customer"}' ``` ### Options ``` -b, --body string JSON body to send with the request -h, --help help for patch ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated api](replicated-cli-api) - Make ad-hoc API calls to the Replicated API --- # replicated api post Make ad-hoc POST API calls to the Replicated API ### Synopsis This is essentially like curl for the Replicated API, but uses your local credentials and prints the response unmodified. We recommend piping the output to jq for easier reading. Pass the PATH of the request as the final argument. Do not include the host or version. ``` replicated api post [flags] ``` ### Examples ``` replicated api post /v3/app/2EuFxKLDxKjPNk2jxMTmF6Vxvxu/channel -b '{"name":"marc-waz-here"}' ``` ### Options ``` -b, --body string JSON body to send with the request -h, --help help for post ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated api](replicated-cli-api) - Make ad-hoc API calls to the Replicated API --- # replicated api put Make ad-hoc PUT API calls to the Replicated API ### Synopsis This is essentially like curl for the Replicated API, but uses your local credentials and prints the response unmodified. We recommend piping the output to jq for easier reading. Pass the PATH of the request as the final argument. Do not include the host or version. ``` replicated api put [flags] ``` ### Examples ``` replicated api put /v3/app/2EuFxKLDxKjPNk2jxMTmF6Vxvxu/channel/2QLPm10JPkta7jO3Z3Mk4aXTPyZ -b '{"name":"marc-waz-here2"}' ``` ### Options ``` -b, --body string JSON body to send with the request -h, --help help for put ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated api](replicated-cli-api) - Make ad-hoc API calls to the Replicated API --- # replicated api Make ad-hoc API calls to the Replicated API ### Options ``` -h, --help help for api ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated api get](replicated-cli-api-get) - Make ad-hoc GET API calls to the Replicated API * [replicated api patch](replicated-cli-api-patch) - Make ad-hoc PATCH API calls to the Replicated API * [replicated api post](replicated-cli-api-post) - Make ad-hoc POST API calls to the Replicated API * [replicated api put](replicated-cli-api-put) - Make ad-hoc PUT API calls to the Replicated API --- # replicated app create Create a new application ### Synopsis Create a new application in your Replicated account. This command allows you to initialize a new application that can be distributed and managed using the KOTS platform. When you create a new app, it will be set up with default configurations, which you can later customize. The NAME argument is required and will be used as the application's name. ``` replicated app create NAME [flags] ``` ### Examples ``` # Create a new app named "My App" replicated app create "My App" # Create a new app and output the result in JSON format replicated app create "Another App" --output json # Create a new app with a specific name and view details in table format replicated app create "Custom App" --output table ``` ### Options ``` -h, --help help for create ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated app](replicated-cli-app) - Manage applications --- # replicated app hostname ls List custom hostnames for an application ### Synopsis List all custom hostnames configured for an application. This command fetches and displays all custom hostname configurations including: - Registry hostnames - Proxy hostnames - Download Portal hostnames - Replicated App hostnames The app ID or slug can be provided via the --app flag or from the .replicated config file. ``` replicated app hostname ls [flags] ``` ### Aliases ``` ls, list ``` ### Examples ``` # List all custom hostnames for an app replicated app hostname ls --app myapp # List hostnames and output as JSON replicated app hostname ls --app myapp --output json ``` ### Options ``` -h, --help help for ls ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated app hostname](replicated-cli-app-hostname) - Manage custom hostnames for applications --- # replicated app hostname Manage custom hostnames for applications ### Synopsis The hostname command allows you to manage custom hostnames for your application. This command provides subcommands for listing and viewing custom hostname configurations including registry, proxy, download portal, and replicated app hostnames. ### Examples ``` # List all custom hostnames for an app replicated app hostname ls --app myapp # List hostnames and output as JSON replicated app hostname ls --app myapp --output json ``` ### Options ``` -h, --help help for hostname ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated app](replicated-cli-app) - Manage applications * [replicated app hostname ls](replicated-cli-app-hostname-ls) - List custom hostnames for an application --- # replicated app ls List applications ### Synopsis List all applications in your Replicated account, or search for a specific application by name or ID. This command displays information about your applications, including their names, IDs, and associated channels. If a NAME argument is provided, it will filter the results to show only applications that match the given name or ID. The output can be customized using the --output flag to display results in either table or JSON format. ``` replicated app ls [NAME] [flags] ``` ### Aliases ``` ls, list ``` ### Examples ``` # List all applications replicated app ls # Search for a specific application by name replicated app ls "My App" # List applications and output in JSON format replicated app ls --output json # Search for an application and display results in table format replicated app ls "App Name" --output table ``` ### Options ``` -h, --help help for ls ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated app](replicated-cli-app) - Manage applications --- # replicated app rm Delete an application ### Synopsis Delete an application from your Replicated account. This command allows you to permanently remove an application from your account. Once deleted, the application and all associated data will be irretrievably lost. Use this command with caution as there is no way to undo this operation. ``` replicated app rm NAME [flags] ``` ### Aliases ``` rm, delete ``` ### Examples ``` # Delete a app named "My App" replicated app delete "My App" # Delete an app and skip the confirmation prompt replicated app delete "Another App" --force # Delete an app and output the result in JSON format replicated app delete "Custom App" --output json ``` ### Options ``` -f, --force Skip confirmation prompt. There is no undo for this action. -h, --help help for rm ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated app](replicated-cli-app) - Manage applications --- # replicated app Manage applications ### Synopsis The app command allows you to manage applications in your Replicated account. This command provides a suite of subcommands for creating, listing, and deleting applications. You can perform operations such as creating new apps, viewing app details, and removing apps from your account. Use the various subcommands to: - Create new applications - List all existing applications - Delete applications from your account ### Examples ``` # List all applications replicated app ls # Create a new application replicated app create "My New App" # Delete an application replicated app rm "app-slug" # List applications with custom output format replicated app ls --output json ``` ### Options ``` -h, --help help for app ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated app create](replicated-cli-app-create) - Create a new application * [replicated app hostname](replicated-cli-app-hostname) - Manage custom hostnames for applications * [replicated app ls](replicated-cli-app-ls) - List applications * [replicated app rm](replicated-cli-app-rm) - Delete an application --- # replicated channel create Create a new channel in your app ### Synopsis Create a new channel in your app and print the channel on success. ``` replicated channel create [flags] ``` ### Examples ``` replicated channel create --name Beta --description 'New features subject to change' ``` ### Options ``` --description string A longer description of this channel -h, --help help for create --name string The name of this channel ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated channel](replicated-cli-channel) - Manage channels --- # replicated channel demote Demote a release from a channel ### Synopsis Demote a channel release from a channel using a channel sequence or release sequence. ``` replicated channel demote CHANNEL_ID_OR_NAME [flags] ``` ### Examples ``` # Demote a release from a channel by channel sequence replicated channel demote Beta --channel-sequence 15 # Demote a release from a channel by release sequence replicated channel demote Beta --release-sequence 12 ``` ### Options ``` --channel-sequence int The channel sequence to demote -h, --help help for demote --release-sequence int The release sequence to demote ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated channel](replicated-cli-channel) - Manage channels --- # replicated channel disable-semantic-versioning Disable semantic versioning for CHANNEL_ID ### Synopsis Disable semantic versioning for the CHANNEL_ID. ``` replicated channel disable-semantic-versioning CHANNEL_ID [flags] ``` ### Examples ``` replicated channel disable-semantic-versioning CHANNEL_ID ``` ### Options ``` -h, --help help for disable-semantic-versioning ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated channel](replicated-cli-channel) - Manage channels --- # replicated channel enable-semantic-versioning Enable semantic versioning for CHANNEL_ID ### Synopsis Enable semantic versioning for the CHANNEL_ID. ``` replicated channel enable-semantic-versioning CHANNEL_ID [flags] ``` ### Examples ``` replicated channel enable-semantic-versioning CHANNEL_ID ``` ### Options ``` -h, --help help for enable-semantic-versioning ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated channel](replicated-cli-channel) - Manage channels --- # replicated channel inspect Show full details for a channel ### Synopsis Show full details for a channel ``` replicated channel inspect CHANNEL_ID [flags] ``` ### Options ``` -h, --help help for inspect ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated channel](replicated-cli-channel) - Manage channels --- # replicated channel ls List all channels in your app ### Synopsis List all channels in your app ``` replicated channel ls [flags] ``` ### Aliases ``` ls, list ``` ### Options ``` -h, --help help for ls ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated channel](replicated-cli-channel) - Manage channels --- # replicated channel releases List all releases in a channel ### Synopsis List all releases promoted to a channel, including demoted releases. Accepts a channel ID or name. ``` replicated channel releases CHANNEL_ID_OR_NAME [flags] ``` ### Examples ``` # List releases for a channel by name replicated channel releases Stable # List releases for a channel by ID replicated channel releases 2abc123 # JSON output for scripting or AI agents replicated channel releases Stable --output json # Paginate (second page of 50) replicated channel releases Stable --page 1 --page-size 50 ``` ### Options ``` -h, --help help for releases --page int The page to fetch (KOTS apps only). --page-size int The number of releases per page (KOTS apps only). ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated channel](replicated-cli-channel) - Manage channels --- # replicated channel rm Remove (archive) a channel ### Synopsis Remove (archive) a channel ``` replicated channel rm CHANNEL_ID_OR_NAME [flags] ``` ### Aliases ``` rm, delete ``` ### Options ``` -h, --help help for rm ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated channel](replicated-cli-channel) - Manage channels --- # replicated channel un-demote Un-demote a release from a channel ### Synopsis Un-demote a channel release from a channel using a channel sequence or release sequence. ``` replicated channel un-demote CHANNEL_ID_OR_NAME [flags] ``` ### Examples ``` # Un-demote a release from a channel by channel sequence replicated channel un-demote Beta --channel-sequence 15 # Un-demote a release from a channel by release sequence replicated channel un-demote Beta --release-sequence 12 ``` ### Options ``` --channel-sequence int The channel sequence to un-demote -h, --help help for un-demote --release-sequence int The release sequence to un-demote ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated channel](replicated-cli-channel) - Manage channels --- # replicated channel Manage channels ### Synopsis The channel command allows vendors to create, manage, and inspect their channels. ### Options ``` -h, --help help for channel ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated channel create](replicated-cli-channel-create) - Create a new channel in your app * [replicated channel demote](replicated-cli-channel-demote) - Demote a release from a channel * [replicated channel disable-semantic-versioning](replicated-cli-channel-disable-semantic-versioning) - Disable semantic versioning for CHANNEL_ID * [replicated channel enable-semantic-versioning](replicated-cli-channel-enable-semantic-versioning) - Enable semantic versioning for CHANNEL_ID * [replicated channel inspect](replicated-cli-channel-inspect) - Show full details for a channel * [replicated channel ls](replicated-cli-channel-ls) - List all channels in your app * [replicated channel releases](replicated-cli-channel-releases) - List all releases in a channel * [replicated channel rm](replicated-cli-channel-rm) - Remove (archive) a channel * [replicated channel un-demote](replicated-cli-channel-un-demote) - Un-demote a release from a channel --- # replicated cluster addon create object-store Create an object store bucket for a cluster. ### Synopsis Creates an object store bucket for a cluster, requiring a bucket name prefix. The bucket name will be auto-generated using the format "[BUCKET_PREFIX]-[ADDON_ID]-cmx". This feature provisions an object storage bucket that can be used for storage in your cluster environment. ``` replicated cluster addon create object-store CLUSTER_ID_OR_NAME --bucket-prefix BUCKET_PREFIX [flags] ``` ### Examples ``` # Create an object store bucket with a specified prefix replicated cluster addon create object-store CLUSTER_ID_OR_NAME --bucket-prefix mybucket # Create an object store bucket and wait for it to be ready (up to 5 minutes) replicated cluster addon create object-store CLUSTER_ID_OR_NAME --bucket-prefix mybucket --wait 5m # Perform a dry run to validate inputs without creating the bucket replicated cluster addon create object-store CLUSTER_ID_OR_NAME --bucket-prefix mybucket --dry-run # Create an object store bucket and output the result in JSON format replicated cluster addon create object-store CLUSTER_ID_OR_NAME --bucket-prefix mybucket --output json # Create an object store bucket with a custom prefix and wait for 10 minutes replicated cluster addon create object-store CLUSTER_ID_OR_NAME --bucket-prefix custom-prefix --wait 10m ``` ### Options ``` --bucket-prefix string A prefix for the bucket name to be created (required) --dry-run Simulate creation to verify that your inputs are valid without actually creating an add-on -h, --help help for object-store --wait duration Wait duration for add-on to be ready before exiting (leave empty to not wait) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster addon create](replicated-cli-cluster-addon-create) - Create cluster add-ons. --- # replicated cluster addon create Create cluster add-ons. ### Synopsis Create new add-ons for a cluster. This command allows you to add functionality or services to a cluster by provisioning the required add-ons. ### Examples ``` # Create an object store bucket add-on for a cluster replicated cluster addon create object-store CLUSTER_ID_OR_NAME --bucket-prefix mybucket # Perform a dry run for creating an object store add-on replicated cluster addon create object-store CLUSTER_ID_OR_NAME --bucket-prefix mybucket --dry-run ``` ### Options ``` -h, --help help for create ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster addon](replicated-cli-cluster-addon) - Manage cluster add-ons. * [replicated cluster addon create object-store](replicated-cli-cluster-addon-create-object-store) - Create an object store bucket for a cluster. --- # replicated cluster addon ls List cluster add-ons for a cluster. ### Synopsis The 'cluster addon ls' command allows you to list all add-ons for a specific cluster. This command provides a detailed overview of the add-ons currently installed on the cluster, including their status and any relevant configuration details. This can be useful for monitoring the health and configuration of add-ons or performing troubleshooting tasks. ``` replicated cluster addon ls CLUSTER_ID_OR_NAME [flags] ``` ### Aliases ``` ls, list ``` ### Examples ``` # List add-ons for a cluster with default table output replicated cluster addon ls CLUSTER_ID_OR_NAME # List add-ons for a cluster with JSON output replicated cluster addon ls CLUSTER_ID_OR_NAME --output json # List add-ons for a cluster with wide table output replicated cluster addon ls CLUSTER_ID_OR_NAME --output wide ``` ### Options ``` -h, --help help for ls ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster addon](replicated-cli-cluster-addon) - Manage cluster add-ons. --- # replicated cluster addon rm Remove cluster add-on by ID. ### Synopsis The 'cluster addon rm' command allows you to remove a specific add-on from a cluster by specifying the cluster ID or name and the add-on ID. This command is useful when you want to deprovision an add-on that is no longer needed or when troubleshooting issues related to specific add-ons. The add-on will be removed immediately, and you will receive confirmation upon successful removal. ``` replicated cluster addon rm CLUSTER_ID_OR_NAME --id ADDON_ID [flags] ``` ### Aliases ``` rm, delete ``` ### Examples ``` # Remove an add-on with ID 'abc123' from cluster 'cluster456' replicated cluster addon rm cluster456 --id abc123 ``` ### Options ``` -h, --help help for rm --id string The ID of the cluster add-on to remove (required) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster addon](replicated-cli-cluster-addon) - Manage cluster add-ons. --- # replicated cluster addon Manage cluster add-ons. ### Synopsis The 'cluster addon' command allows you to manage add-ons installed on a test cluster. Add-ons are additional components or services that can be installed and configured to enhance or extend the functionality of the cluster. You can use various subcommands to create, list, remove, or check the status of add-ons on a cluster. This command is useful for adding databases, object storage, monitoring, security, or other specialized tools to your cluster environment. ### Examples ``` # List all add-ons installed on a cluster replicated cluster addon ls CLUSTER_ID_OR_NAME # Remove an add-on from a cluster replicated cluster addon rm CLUSTER_ID_OR_NAME --id ADDON_ID # Create an object store bucket add-on for a cluster replicated cluster addon create object-store CLUSTER_ID_OR_NAME --bucket-prefix mybucket # List add-ons with JSON output replicated cluster addon ls CLUSTER_ID_OR_NAME --output json ``` ### Options ``` -h, --help help for addon ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster](replicated-cli-cluster) - Manage test Kubernetes clusters. * [replicated cluster addon create](replicated-cli-cluster-addon-create) - Create cluster add-ons. * [replicated cluster addon ls](replicated-cli-cluster-addon-ls) - List cluster add-ons for a cluster. * [replicated cluster addon rm](replicated-cli-cluster-addon-rm) - Remove cluster add-on by ID. --- # replicated cluster create Create test clusters. ### Synopsis The 'cluster create' command provisions a new test cluster with the specified Kubernetes distribution and configuration. You can customize the cluster's size, version, node groups, disk space, IP family, and other parameters. This command supports creating clusters on multiple Kubernetes distributions, including setting up node groups with different instance types and counts. You can also specify a TTL (Time-To-Live) to automatically terminate the cluster after a set duration. If no TTL is specified, the default TTL is 1 hour. Use the '--dry-run' flag to simulate the creation process and get an estimated cost without actually provisioning the cluster. ``` replicated cluster create [flags] ``` ### Examples ``` # Create a new cluster with basic configuration replicated cluster create --distribution eks --version 1.21 --nodes 3 --instance-type t3.large --disk 100 --ttl 24h # Create a cluster with a custom node group replicated cluster create --distribution eks --version 1.21 --nodegroup name=workers,instance-type=t3.large,nodes=5 --ttl 24h # Simulate cluster creation (dry-run) replicated cluster create --distribution eks --version 1.21 --nodes 3 --disk 100 --ttl 24h --dry-run # Create a cluster with autoscaling configuration replicated cluster create --distribution eks --version 1.21 --min-nodes 2 --max-nodes 5 --instance-type t3.large --ttl 24h # Create a cluster with multiple node groups replicated cluster create --distribution eks --version 1.21 \ --nodegroup name=workers,instance-type=t3.large,nodes=3 \ --nodegroup name=cpu-intensive,instance-type=c5.2xlarge,nodes=2 \ --ttl 24h # Create a cluster with custom tags replicated cluster create --distribution eks --version 1.21 --nodes 3 --tag env=test --tag project=demo --ttl 24h # Create a cluster with addons replicated cluster create --distribution eks --version 1.21 --nodes 3 --addon object-store --ttl 24h ``` ### Options ``` --addon stringArray Addons to install on the cluster (can be specified multiple times) --bucket-prefix string A prefix for the bucket name to be created (required by '--addon object-store') --disk int Disk Size (GiB) to request per node (default 50) --distribution string Kubernetes distribution of the cluster to provision --dry-run Dry run -h, --help help for create --instance-type string The type of instance to use (e.g. m6i.large) --ip-family string IP Family to use for the cluster (ipv4|ipv6|dual). --license-id string License ID to use for the installation (required for Embedded Cluster distribution) --max-nodes string Maximum Node count (non-negative number) (only for EKS, AKS and GKE clusters). --min-nodes string Minimum Node count (non-negative number) (only for EKS, AKS and GKE clusters). --name string Cluster name (defaults to random name) --network-policy string The network policy to use for the cluster --nodegroup stringArray Node group to create (name=?,instance-type=?,nodes=?,min-nodes=?,max-nodes=?,disk=? format, can be specified multiple times). For each nodegroup, at least one flag must be specified. The flags min-nodes and max-nodes are mutually dependent. --nodes int Node count (default 1) --tag stringArray Tag to apply to the cluster (key=value format, can be specified multiple times) --ttl string Cluster TTL (duration, max 48h) --version string Kubernetes version to provision (format is distribution dependent) --wait duration Wait duration for cluster to be ready (leave empty to not wait) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster](replicated-cli-cluster) - Manage test Kubernetes clusters. --- # replicated cluster kubeconfig Download credentials for a test cluster. ### Synopsis The 'cluster kubeconfig' command downloads the credentials (kubeconfig) required to access a test cluster. You can either merge these credentials into your existing kubeconfig file or save them as a new file. This command ensures that the kubeconfig is correctly configured for use with your Kubernetes tools. You can specify the cluster by ID or name directly as an argument, or by using the '--id' or '--name' flags. Additionally, the kubeconfig can be written to a specific file path or printed to stdout. You can also use this command to automatically update your current Kubernetes context with the downloaded credentials. ``` replicated cluster kubeconfig [ID_OR_NAME] [flags] ``` ### Examples ``` # Download and merge kubeconfig into your existing configuration replicated cluster kubeconfig CLUSTER_ID_OR_NAME # Save the kubeconfig to a specific file replicated cluster kubeconfig CLUSTER_ID_OR_NAME --output-path ./kubeconfig # Print the kubeconfig to stdout replicated cluster kubeconfig CLUSTER_ID_OR_NAME --stdout # Download kubeconfig for a cluster by name using a flag replicated cluster kubeconfig --name "My Cluster" # Download kubeconfig for a cluster by ID using a flag replicated cluster kubeconfig --id CLUSTER_ID ``` ### Options ``` -h, --help help for kubeconfig --id string id of the cluster to download credentials for (when name is not provided) (DEPRECATED: use ID_OR_NAME arguments instead) --name string name of the cluster to download credentials for (when id is not provided) (DEPRECATED: use ID_OR_NAME arguments instead) --output-path string path to kubeconfig file to write to, if not provided, it will be merged into your existing kubeconfig --stdout write kubeconfig to stdout ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster](replicated-cli-cluster) - Manage test Kubernetes clusters. --- # replicated cluster ls List test clusters. ### Synopsis The 'cluster ls' command lists all test clusters. This command provides information about the clusters, such as their status, name, distribution, version, and creation time. The output can be formatted in different ways, depending on your needs. You can filter the list of clusters by time range and status (e.g., show only terminated clusters). You can also watch clusters in real-time, which updates the list every few seconds. Clusters that have been deleted will be shown with a 'deleted' status. ``` replicated cluster ls [flags] ``` ### Aliases ``` ls, list ``` ### Examples ``` # List all clusters with default table output replicated cluster ls # Show clusters created after a specific date replicated cluster ls --start-time 2023-01-01T00:00:00Z # Watch for real-time updates replicated cluster ls --watch # List clusters with JSON output replicated cluster ls --output json # List only terminated clusters replicated cluster ls --show-terminated # List clusters with wide table output replicated cluster ls --output wide ``` ### Options ``` --end-time string end time for the query (Format: 2006-01-02T15:04:05Z) -h, --help help for ls --show-terminated when set, only show terminated clusters --start-time string start time for the query (Format: 2006-01-02T15:04:05Z) -w, --watch watch clusters ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster](replicated-cli-cluster) - Manage test Kubernetes clusters. --- # replicated cluster nodegroup ls List node groups for a cluster. ### Synopsis The 'cluster nodegroup ls' command lists all the node groups associated with a given cluster. Each node group defines a specific set of nodes with particular configurations, such as instance types and scaling options. You can view information about the node groups within the specified cluster, including their ID, name, node count, and other configuration details. You must provide the cluster ID or name to list its node groups. ``` replicated cluster nodegroup ls [ID_OR_NAME] [flags] ``` ### Aliases ``` ls, list ``` ### Examples ``` # List all node groups in a cluster with default table output replicated cluster nodegroup ls CLUSTER_ID_OR_NAME # List node groups with JSON output replicated cluster nodegroup ls CLUSTER_ID_OR_NAME --output json # List node groups with wide table output replicated cluster nodegroup ls CLUSTER_ID_OR_NAME --output wide ``` ### Options ``` -h, --help help for ls ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster nodegroup](replicated-cli-cluster-nodegroup) - Manage node groups for clusters. --- # replicated cluster nodegroup Manage node groups for clusters. ### Synopsis The 'cluster nodegroup' command provides functionality to manage node groups within a cluster. This command allows you to list node groups in a Kubernetes or VM-based cluster. Node groups define a set of nodes with specific configurations, such as instance types, node counts, or scaling rules. You can use subcommands to perform various actions on node groups. ### Examples ``` # List all node groups for a cluster replicated cluster nodegroup ls CLUSTER_ID_OR_NAME ``` ### Options ``` -h, --help help for nodegroup ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster](replicated-cli-cluster) - Manage test Kubernetes clusters. * [replicated cluster nodegroup ls](replicated-cli-cluster-nodegroup-ls) - List node groups for a cluster. --- # replicated cluster port expose Expose a port on a cluster to the public internet. ### Synopsis The 'cluster port expose' command is used to expose a specified port on a cluster to the public internet. When exposing a port, the command automatically creates a DNS entry and, if using the "https" protocol, provisions a TLS certificate for secure communication. You can also create a wildcard DNS entry and TLS certificate by specifying the "--wildcard" flag. Please note that creating a wildcard certificate may take additional time. This command supports different protocols including "http", "https", "ws", and "wss" for web traffic and web socket communication. NOTE: Currently, this feature only supports VM-based cluster distributions. ``` replicated cluster port expose CLUSTER_ID_OR_NAME --port PORT [flags] ``` ### Examples ``` # Expose port for Embedded Cluster (Port: 30000) with HTTP Protocol replicated cluster port expose CLUSTER_ID_OR_NAME --port 30000 --protocol http # Expose port 8080 with HTTPS protocol and wildcard DNS replicated cluster port expose CLUSTER_ID_OR_NAME --port 8080 --protocol https --wildcard # Expose port 8080 with multiple protocols replicated cluster port expose CLUSTER_ID_OR_NAME --port 8080 --protocol http,https # Expose port 8080 and display the result in JSON format replicated cluster port expose CLUSTER_ID_OR_NAME --port 8080 --protocol https --output json ``` ### Options ``` -h, --help help for expose --port int Port to expose (required) --protocol strings Protocol to expose (valid values are "http", "https", "ws" and "wss") (default [http,https]) --wildcard Create a wildcard DNS entry and TLS certificate for this port ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster port](replicated-cli-cluster-port) - Manage cluster ports. --- # replicated cluster port ls List cluster ports for a cluster. ### Synopsis The 'cluster port ls' command lists all the ports configured for a specific cluster. You must provide the cluster ID or name to retrieve and display the ports. This command is useful for viewing the current port configurations, protocols, and other related settings of your test cluster. The output format can be customized to suit your needs, and the available formats include table, JSON, and wide views. ``` replicated cluster port ls CLUSTER_ID_OR_NAME [flags] ``` ### Aliases ``` ls, list ``` ### Examples ``` # List ports for a cluster in the default table format replicated cluster port ls CLUSTER_ID_OR_NAME # List ports for a cluster in JSON format replicated cluster port ls CLUSTER_ID_OR_NAME --output json # List ports for a cluster in wide format replicated cluster port ls CLUSTER_ID_OR_NAME --output wide ``` ### Options ``` -h, --help help for ls ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster port](replicated-cli-cluster-port) - Manage cluster ports. --- # replicated cluster port rm Remove cluster port by ID. ### Synopsis The 'cluster port rm' command removes a specific port from a cluster. You must provide the ID or name of the cluster and either the ID of the port or the port number and protocol(s) to remove. This command is useful for managing the network settings of your test clusters by allowing you to clean up unused or incorrect ports. After removing a port, the updated list of ports will be displayed. Note that you can only use either the port ID or port number when removing a port, not both at the same time. ``` replicated cluster port rm CLUSTER_ID_OR_NAME --id PORT_ID [flags] ``` ### Aliases ``` rm, delete ``` ### Examples ``` # Remove a port using its ID replicated cluster port rm CLUSTER_ID_OR_NAME --id PORT_ID # Remove a port using its number (deprecated) replicated cluster port rm CLUSTER_ID_OR_NAME --port 8080 --protocol http,https # Remove a port and display the result in JSON format replicated cluster port rm CLUSTER_ID_OR_NAME --id PORT_ID --output json ``` ### Options ``` -h, --help help for rm --id string ID of the port to remove (required) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster port](replicated-cli-cluster-port) - Manage cluster ports. --- # replicated cluster port Manage cluster ports. ### Synopsis The 'cluster port' command is a parent command for managing ports in a cluster. It allows users to list, remove, or expose specific ports used by the cluster. Use the subcommands (such as 'ls', 'rm', and 'expose') to manage port configurations effectively. This command provides flexibility for handling ports in various test clusters, ensuring efficient management of cluster networking settings. ### Examples ``` # List all exposed ports in a cluster replicated cluster port ls [CLUSTER_ID_OR_NAME] # Remove an exposed port from a cluster replicated cluster port rm [CLUSTER_ID_OR_NAME] [PORT] # Expose a new port in a cluster replicated cluster port expose [CLUSTER_ID_OR_NAME] [PORT] ``` ### Options ``` -h, --help help for port ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster](replicated-cli-cluster) - Manage test Kubernetes clusters. * [replicated cluster port expose](replicated-cli-cluster-port-expose) - Expose a port on a cluster to the public internet. * [replicated cluster port ls](replicated-cli-cluster-port-ls) - List cluster ports for a cluster. * [replicated cluster port rm](replicated-cli-cluster-port-rm) - Remove cluster port by ID. --- # replicated cluster prepare Prepare cluster for testing. ### Synopsis The 'cluster prepare' command provisions a Kubernetes cluster and installs an application using a Helm chart or KOTS YAML configuration. This command is designed to be used in CI environments to prepare a cluster for testing by deploying a Helm chart or KOTS application with entitlements and custom values. You can specify the cluster configuration, such as the Kubernetes distribution, version, node count, and instance type, and then install your application automatically. Alternatively, if you prefer deploying KOTS applications, you can specify YAML manifests for the release and use the '--shared-password' flag for the KOTS admin console. You can also pass entitlement values to configure the cluster's customer entitlements. Note: - The '--chart' flag cannot be used with '--yaml', '--yaml-file', or '--yaml-dir'. - If deploying a Helm chart, use the '--set' flags to pass chart values. When deploying a KOTS application, the '--shared-password' flag is required. ``` replicated cluster prepare [flags] ``` ### Examples ``` replicated cluster prepare --distribution eks --version 1.27 --instance-type c6.xlarge --node-count 3 --chart ./your-chart.tgz --values ./values.yaml --set chart-key=value --set chart-key2=value2 ``` ### Options ``` --app-ready-timeout duration Timeout to wait for the application to be ready. Must be in Go duration format (e.g., 10s, 2m). (default 5m0s) --chart string Path to the helm chart package to deploy --cluster-id string The ID of an existing cluster to use instead of creating a new one. --config-values-file string Path to a manifest containing config values (must be apiVersion: kots.io/v1beta1, kind: ConfigValues). --disk int Disk Size (GiB) to request per node. (default 50) --distribution string Kubernetes distribution of the cluster to provision --entitlements strings The entitlements to set on the customer. Can be specified multiple times. -h, --help help for prepare --instance-type string the type of instance to use clusters (e.g. x5.xlarge) --name string Cluster name --namespace string The namespace into which to deploy the KOTS application or Helm chart. (default "default") --node-count int Node count. (default 1) --set stringArray Set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2). --set-file stringArray Set values from respective files specified via the command line (can specify multiple or separate values with commas: key1=path1,key2=path2). --set-json stringArray Set JSON values on the command line (can specify multiple or separate values with commas: key1=jsonval1,key2=jsonval2). --set-literal stringArray Set a literal STRING value on the command line. --set-string stringArray Set STRING values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2). --shared-password string Shared password for the KOTS admin console. --ttl string Cluster TTL (duration, max 48h) --values strings Specify values in a YAML file or a URL (can specify multiple). --version string Kubernetes version to provision (format is distribution dependent) --wait duration Wait duration for cluster to be ready. (default 5m0s) --yaml string The YAML config for this release. Use '-' to read from stdin. Cannot be used with the --yaml-file flag. --yaml-dir string The directory containing multiple yamls for a KOTS release. Cannot be used with the --yaml flag. --yaml-file string The YAML config for this release. Cannot be used with the --yaml flag. ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster](replicated-cli-cluster) - Manage test Kubernetes clusters. --- # replicated cluster rm Remove test clusters. ### Synopsis The 'rm' command removes test clusters immediately. You can remove clusters by specifying a cluster ID or name, or by using other criteria such as cluster tags. Alternatively, you can remove all clusters in your account at once. When specifying a name that matches multiple clusters, all clusters with that name will be removed. This command can also be used in a dry-run mode to simulate the removal without actually deleting anything. You cannot mix the use of cluster IDs or names with other options like removing by tag or removing all clusters at once. ``` replicated cluster rm ID_OR_NAME [ID_OR_NAME …] [flags] ``` ### Aliases ``` rm, delete ``` ### Examples ``` # Remove a specific cluster by ID or name replicated cluster rm CLUSTER_ID_OR_NAME # Remove multiple clusters by ID or name replicated cluster rm CLUSTER_ID_1 CLUSTER_NAME_2 # Remove all clusters replicated cluster rm --all ``` ### Options ``` --all remove all clusters --dry-run Dry run -h, --help help for rm --name stringArray Name of the cluster to remove (can be specified multiple times) (DEPRECATED: use ID_OR_NAME arguments instead) --tag stringArray Tag of the cluster to remove (key=value format, can be specified multiple times) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster](replicated-cli-cluster) - Manage test Kubernetes clusters. --- # replicated cluster shell Open a new shell with kubeconfig configured. ### Synopsis The 'shell' command opens a new shell session with the kubeconfig configured for the specified test cluster. This allows you to have immediate kubectl access to the cluster within the shell environment. You can either specify the cluster ID or name directly as an argument, or provide the cluster name or ID using flags. The shell will inherit your existing environment and add the necessary kubeconfig context for interacting with the Kubernetes cluster. Once inside the shell, you can use 'kubectl' to interact with the cluster. To exit the shell, press Ctrl-D or type 'exit'. When the shell closes, the kubeconfig will be reset back to your default configuration. ``` replicated cluster shell [ID_OR_NAME] [flags] ``` ### Examples ``` # Open a shell for a cluster by ID or name replicated cluster shell CLUSTER_ID_OR_NAME # Open a shell for a cluster by name using a flag replicated cluster shell --name "My Cluster" # Open a shell for a cluster by ID using a flag replicated cluster shell --id CLUSTER_ID ``` ### Options ``` -h, --help help for shell --id string id of the cluster to have kubectl access to (when name is not provided) (DEPRECATED: use ID_OR_NAME arguments instead) --name string name of the cluster to have kubectl access to. (DEPRECATED: use ID_OR_NAME arguments instead) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster](replicated-cli-cluster) - Manage test Kubernetes clusters. --- # replicated cluster update nodegroup Update a nodegroup for a test cluster. ### Synopsis The 'nodegroup' command allows you to update the configuration of a nodegroup within a test cluster. You can update attributes like the number of nodes, minimum and maximum node counts for autoscaling, and more. If you do not provide the nodegroup ID, the command will try to resolve it based on the nodegroup name provided. ``` replicated cluster update nodegroup [ID_OR_NAME] [flags] ``` ### Examples ``` # Update the number of nodes in a nodegroup replicated cluster update nodegroup CLUSTER_ID_OR_NAME --nodegroup-id NODEGROUP_ID --nodes 3 # Update the autoscaling limits for a nodegroup replicated cluster update nodegroup CLUSTER_ID_OR_NAME --nodegroup-id NODEGROUP_ID --min-nodes 2 --max-nodes 5 ``` ### Options ``` -h, --help help for nodegroup --max-nodes string The maximum number of nodes in the nodegroup --min-nodes string The minimum number of nodes in the nodegroup --nodegroup-id string The ID of the nodegroup to update --nodegroup-name string The name of the nodegroup to update --nodes int The number of nodes in the nodegroup ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output --id string id of the cluster to update (when name is not provided) --name string Name of the cluster to update. -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster update](replicated-cli-cluster-update) - Update cluster settings. --- # replicated cluster update ttl Update TTL for a test cluster. ### Synopsis The 'ttl' command allows you to update the Time-To-Live (TTL) of a test cluster. The TTL represents the duration for which the cluster will remain active before it is automatically terminated. The duration starts from the moment the cluster becomes active. You must provide a valid duration, with a maximum limit of 48 hours. If no TTL is specified, the default TTL is 1 hour. ``` replicated cluster update ttl [ID_OR_NAME] [flags] ``` ### Examples ``` # Update the TTL for a specific cluster replicated cluster update ttl CLUSTER_ID_OR_NAME --ttl 24h ``` ### Options ``` -h, --help help for ttl --ttl string Update TTL which starts from the moment the cluster is running (duration, max 48h). ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output --id string id of the cluster to update (when name is not provided) --name string Name of the cluster to update. -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster update](replicated-cli-cluster-update) - Update cluster settings. --- # replicated cluster update Update cluster settings. ### Synopsis The 'update' command allows you to update various settings of a test cluster, such as its name or ID. You can either specify the cluster ID directly or provide the cluster name, and the command will resolve the corresponding cluster ID. This allows you to modify the cluster's configuration based on the unique identifier or the name of the cluster. ### Examples ``` # Update a cluster using its ID replicated cluster update --id [subcommand] # Update a cluster using its name replicated cluster update --name [subcommand] ``` ### Options ``` -h, --help help for update --id string id of the cluster to update (when name is not provided) --name string Name of the cluster to update. ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster](replicated-cli-cluster) - Manage test Kubernetes clusters. * [replicated cluster update nodegroup](replicated-cli-cluster-update-nodegroup) - Update a nodegroup for a test cluster. * [replicated cluster update ttl](replicated-cli-cluster-update-ttl) - Update TTL for a test cluster. --- # replicated cluster upgrade Upgrade a test cluster. ### Synopsis The 'upgrade' command upgrades a Kubernetes test cluster to a specified version. You must provide a cluster ID or name and the version to upgrade to. The upgrade can be simulated with a dry-run option, or you can choose to wait for the cluster to be fully upgraded. ``` replicated cluster upgrade [ID_OR_NAME] [flags] ``` ### Examples ``` # Upgrade a cluster to a new Kubernetes version replicated cluster upgrade CLUSTER_ID_OR_NAME --version 1.31 # Perform a dry run of a cluster upgrade without making any changes replicated cluster upgrade CLUSTER_ID_OR_NAME --version 1.31 --dry-run # Upgrade a cluster and wait for it to be ready replicated cluster upgrade CLUSTER_ID_OR_NAME --version 1.31 --wait 30m ``` ### Options ``` --dry-run Dry run -h, --help help for upgrade --version string Kubernetes version to upgrade to (format is distribution dependent) --wait duration Wait duration for cluster to be ready (leave empty to not wait) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster](replicated-cli-cluster) - Manage test Kubernetes clusters. --- # replicated cluster versions List cluster versions. ### Synopsis The 'versions' command lists available Kubernetes versions for supported distributions. You can filter the versions by specifying a distribution and choose between different output formats. ``` replicated cluster versions [flags] ``` ### Examples ``` # List all available Kubernetes cluster versions replicated cluster versions # List available versions for a specific distribution (e.g., eks) replicated cluster versions --distribution eks # Output the versions in JSON format replicated cluster versions --output json ``` ### Options ``` --distribution string Kubernetes distribution to filter by. -h, --help help for versions ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated cluster](replicated-cli-cluster) - Manage test Kubernetes clusters. --- # replicated cluster Manage test Kubernetes clusters. ### Synopsis The 'cluster' command allows you to manage and interact with Kubernetes clusters used for testing purposes. With this command, you can create, list, remove, and manage node groups within clusters, as well as retrieve information about available clusters. ### Examples ``` # Create a single-node EKS cluster replicated cluster create --distribution eks --version 1.31 # List all clusters replicated cluster ls # Remove a specific cluster by ID replicated cluster rm # List all nodegroups in a specific cluster replicated cluster nodegroup ls ``` ### Options ``` -h, --help help for cluster ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated cluster addon](replicated-cli-cluster-addon) - Manage cluster add-ons. * [replicated cluster create](replicated-cli-cluster-create) - Create test clusters. * [replicated cluster kubeconfig](replicated-cli-cluster-kubeconfig) - Download credentials for a test cluster. * [replicated cluster ls](replicated-cli-cluster-ls) - List test clusters. * [replicated cluster nodegroup](replicated-cli-cluster-nodegroup) - Manage node groups for clusters. * [replicated cluster port](replicated-cli-cluster-port) - Manage cluster ports. * [replicated cluster prepare](replicated-cli-cluster-prepare) - Prepare cluster for testing. * [replicated cluster rm](replicated-cli-cluster-rm) - Remove test clusters. * [replicated cluster shell](replicated-cli-cluster-shell) - Open a new shell with kubeconfig configured. * [replicated cluster update](replicated-cli-cluster-update) - Update cluster settings. * [replicated cluster upgrade](replicated-cli-cluster-upgrade) - Upgrade a test cluster. * [replicated cluster versions](replicated-cli-cluster-versions) - List cluster versions. --- # replicated completion Generate completion script ``` replicated completion [bash|zsh|fish|powershell] ``` ### Examples ``` To load completions: Bash: This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager. $ source <(replicated completion bash) # To load completions for each session, execute once: # Linux: $ replicated completion bash > /etc/bash_completion.d/replicated # macOS: $ replicated completion bash > $(brew --prefix)/etc/bash_completion.d/replicated Zsh: # If shell completion is not already enabled in your environment, # you will need to enable it. You can execute the following once: $ echo "autoload -U compinit; compinit" >> ~/.zshrc # To load completions for each session, execute once: $ replicated completion zsh > "${fpath[1]}/_replicated" # You will need to start a new shell for this setup to take effect. fish: $ replicated completion fish | source # To load completions for each session, execute once: $ replicated completion fish > ~/.config/fish/completions/replicated.fish PowerShell: PS> replicated completion powershell | Out-String | Invoke-Expression # To load completions for every new session, run: PS> replicated completion powershell > replicated.ps1 # and source this file from your PowerShell profile. ``` ### Options ``` -h, --help help for completion ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated --- # replicated config init Initialize a .replicated config file for your project ### Synopsis Initialize a .replicated config file for your project. This command will guide you through setting up a .replicated configuration file by prompting for common settings like app ID, chart paths, and linting preferences. It will also attempt to auto-detect Helm charts and preflight specs in your project. ``` replicated config init [flags] ``` ### Examples ``` # Initialize with interactive prompts replicated config init # Initialize with auto-detected resources only (no prompts) replicated config init --non-interactive # Initialize without auto-detection replicated config init --skip-detection ``` ### Options ``` -h, --help help for init --non-interactive Run without prompts, using defaults and auto-detected values --skip-detection Skip auto-detection of resources ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated config](replicated-cli-config) - Manage .replicated configuration --- # replicated config Manage .replicated configuration ### Synopsis Manage .replicated configuration files for your project. ### Options ``` -h, --help help for config ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated config init](replicated-cli-config-init) - Initialize a .replicated config file for your project --- # replicated customer archive Archive a customer ### Synopsis Archive a customer for the current application. This command allows you to archive a customer record. Archiving a customer will make their license inactive and remove them from active customer lists. This action is reversible - you can unarchive a customer later if needed. The customer can be specified by either their name or ID. ``` replicated customer archive [flags] ``` ### Examples ``` # Archive a customer by name replicated customer archive "Acme Inc" # Archive a customer by ID replicated customer archive cus_abcdef123456 # Archive multiple customers by ID replicated customer archive cus_abcdef123456 cus_xyz9876543210 # Archive a customer in a specific app (if you have multiple apps) replicated customer archive --app myapp "Acme Inc" ``` ### Options ``` -h, --help help for archive ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated customer](replicated-cli-customer) - Manage customers --- # replicated customer create Create a new customer for the current application ### Synopsis Create a new customer for the current application with specified attributes. This command allows you to create a customer record with various properties such as name, custom ID, channel, license type, and feature flags. You can set expiration dates, enable or disable specific features, and assign the customer to a channel. The --app flag must be set to specify the target application. ``` replicated customer create [flags] ``` ### Examples ``` # Create a basic customer with a name and assigned to a channel replicated customer create --app myapp --name "Acme Inc" --channel stable # Create a paid customer with specific features enabled replicated customer create --app myapp --name "Enterprise Ltd" --type paid --channel enterprise --airgap --snapshot # Create a trial customer with an expiration date replicated customer create --app myapp --name "Trial User" --type trial --channel stable --expires-in 720h # Create a customer with all available options replicated customer create --app myapp --name "Full Options Inc" --custom-id "FULL001" \ --channel stable --type paid --email "contact@fulloptions.com" --expires-in 8760h \ --airgap --snapshot --kots-install --embedded-cluster-download \ --support-bundle-upload --ensure-channel ``` ### Options ``` --airgap If set, the license will allow airgap installs. --channel string Release channel to which the customer should be assigned --custom-id string Set a custom customer ID to more easily tie this customer record to your external data systems --developer-mode If set, Replicated SDK installed in dev mode will use mock data. --email string Email address of the customer that is to be created. --embedded-cluster-download If set, the license will allow Embedded Cluster downloads. --embedded-cluster-multinode If set, users can add nodes to Embedded Cluster instances. (default true) --ensure-channel If set, channel will be created if it does not exist. --expires-in duration If set, an expiration date will be set on the license. Supports Go durations like '72h' or '3600m' --geo-axis If set, the license will allow Geo Axis usage. --gitops If set, the license will allow the GitOps usage. --helm-install If set, the license will allow Helm installs. Requires --email. --helmvm-cluster-download If set, the license will allow helmvm cluster downloads. -h, --help help for create --identity-service If set, the license will allow Identity Service usage. --installer-support If set, the license will allow installer support. --kots-install If set, the license will allow KOTS install. Otherwise license will allow Helm CLI installs only. (default true) --kurl-install If set, the license will allow kURL installs. --name string Name of the customer --snapshot If set, the license will allow Snapshots. --support-bundle-upload If set, the license will allow uploading support bundles. --type string The license type to create. One of: dev|trial|paid|community|test (default: dev) (default "dev") ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated customer](replicated-cli-customer) - Manage customers --- # replicated customer download-license Download a customer's license ### Synopsis The download-license command allows you to retrieve and save a customer's license. This command fetches the license for a specified customer and either outputs it to stdout or saves it to a file. The license contains crucial information about the customer's subscription and usage rights. You must specify the customer using either their name or ID with the --customer flag. ``` replicated customer download-license [flags] ``` ### Examples ``` # Download license for a customer by ID and output to stdout replicated customer download-license --customer cus_abcdef123456 # Download license for a customer by name and save to a file replicated customer download-license --customer "Acme Inc" --output license.yaml # Download license for a customer in a specific app (if you have multiple apps) replicated customer download-license --app myapp --customer "Acme Inc" --output license.yaml ``` ### Options ``` --customer string The Customer Name or ID -h, --help help for download-license -o, --output string Path to output license to. Defaults to stdout (default "-") ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated customer](replicated-cli-customer) - Manage customers --- # replicated customer inspect Show detailed information about a specific customer ### Synopsis The inspect command provides comprehensive details about a customer. This command retrieves and displays full information about a specified customer, including their assigned channels, registry information, and other relevant attributes. It's useful for getting an in-depth view of a customer's configuration and status. You must specify the customer using either their name or ID with the --customer flag. ``` replicated customer inspect [flags] ``` ### Examples ``` # Inspect a customer by ID replicated customer inspect --customer cus_abcdef123456 # Inspect a customer by name replicated customer inspect --customer "Acme Inc" # Inspect a customer and output in JSON format replicated customer inspect --customer cus_abcdef123456 --output json # Inspect a customer for a specific app (if you have multiple apps) replicated customer inspect --app myapp --customer "Acme Inc" ``` ### Options ``` --customer string The Customer Name or ID -h, --help help for inspect ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated customer](replicated-cli-customer) - Manage customers --- # replicated customer ls List customers for the current application ### Synopsis List customers associated with the current application. This command displays information about customers linked to your application. By default, it shows all non-test customers. You can use flags to: - Filter customers by a specific app version - Include test customers in the results - Change the output format (table or JSON) The command requires an app to be set using the --app flag. ``` replicated customer ls [flags] ``` ### Aliases ``` ls, list ``` ### Examples ``` # List all customers for the current application replicated customer ls --app myapp # Output results in JSON format replicated customer ls --app myapp --output json # Combine multiple flags replicated customer ls --app myapp --output json ``` ### Options ``` --app-version string Filter customers by a specific app version -h, --help help for ls --include-test Include test customers in the results ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated customer](replicated-cli-customer) - Manage customers --- # replicated customer update Update an existing customer ### Synopsis Update an existing customer's information and settings. This command allows you to modify various attributes of a customer, including their name, custom ID, assigned channel, license type, and feature flags. You can update expiration dates, enable or disable specific features, and change the channel assignment. The --customer flag is required to specify which customer to update. ``` replicated customer update --customer --name [options] [flags] ``` ### Examples ``` # Update a customer's name replicated customer update --customer cus_abcdef123456 --name "New Company Name" # Change a customer's channel replicated customer update --customer cus_abcdef123456 --channel stable # Enable airgap installations for a customer replicated customer update --customer cus_abcdef123456 --airgap # Update multiple attributes at once replicated customer update --customer cus_abcdef123456 --name "Updated Corp" --type paid --channel enterprise --airgap --snapshot # Set an expiration date for a customer's license replicated customer update --customer cus_abcdef123456 --expires-in 8760h # Update a customer and output the result in JSON format replicated customer update --customer cus_abcdef123456 --name "JSON Corp" --output json ``` ### Options ``` --airgap If set, the license will allow airgap installs. --channel string Release channel to which the customer should be assigned --custom-id string Set a custom customer ID to more easily tie this customer record to your external data systems --customer string The ID of the customer to update --developer-mode If set, Replicated SDK installed in dev mode will use mock data. --email string Email address of the customer that is to be updated. --embedded-cluster-download If set, the license will allow Embedded Cluster downloads. --embedded-cluster-multinode If set, users can add nodes to Embedded Cluster instances. (default true) --ensure-channel If set, channel will be created if it does not exist. --expires-in duration If set, an expiration date will be set on the license. Supports Go durations like '72h' or '3600m' --geo-axis If set, the license will allow Geo Axis usage. --gitops If set, the license will allow the GitOps usage. --helm-install If set, the license will allow Helm installs. --helmvm-cluster-download If set, the license will allow helmvm cluster downloads. -h, --help help for update --identity-service If set, the license will allow Identity Service usage. --kots-install If set, the license will allow KOTS install. Otherwise license will allow Helm CLI installs only. (default true) --kurl-install If set, the license will allow kURL installs. --name string Name of the customer --snapshot If set, the license will allow Snapshots. --support-bundle-upload If set, the license will allow uploading support bundles. --type string The license type to update. One of: dev|trial|paid|community|test (default: dev) (default "dev") ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated customer](replicated-cli-customer) - Manage customers --- # replicated customer Manage customers ### Synopsis The customers command allows vendors to create, display, modify end customer records. ### Options ``` -h, --help help for customer ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated customer archive](replicated-cli-customer-archive) - Archive a customer * [replicated customer create](replicated-cli-customer-create) - Create a new customer for the current application * [replicated customer download-license](replicated-cli-customer-download-license) - Download a customer's license * [replicated customer inspect](replicated-cli-customer-inspect) - Show detailed information about a specific customer * [replicated customer ls](replicated-cli-customer-ls) - List customers for the current application * [replicated customer update](replicated-cli-customer-update) - Update an existing customer --- # replicated default clear-all Clear all default values ### Synopsis Clears all default values that are used by other commands. This command removes all default values that are used by other commands run by the current user. ``` replicated default clear-all [flags] ``` ### Examples ``` # Clear all default values replicated default clear-all ``` ### Options ``` -h, --help help for clear-all ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated default](replicated-cli-default) - Manage default values used by other commands --- # replicated default clear Clear default value for a key ### Synopsis Clears default value for the specified key. This command removes default values that are used by other commands run by the current user. Supported keys: - app: the default application to use ``` replicated default clear KEY [flags] ``` ### Examples ``` # Clear default application replicated default clear app ``` ### Options ``` -h, --help help for clear ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated default](replicated-cli-default) - Manage default values used by other commands --- # replicated default set Set default value for a key ### Synopsis Sets default value for the specified key. This command sets default values that will be used by other commands run by the current user. Supported keys: - app: the default application to use The output can be customized using the --output flag to display results in either table or JSON format. ``` replicated default set KEY VALUE [flags] ``` ### Examples ``` # Set default application replicated default set app my-app-slug ``` ### Options ``` -h, --help help for set ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated default](replicated-cli-default) - Manage default values used by other commands --- # replicated default show Show default value for a key ### Synopsis Shows defaul values for the specified key. This command shows default values that will be used by other commands run by the current user. Supported keys: - app: the default application to use The output can be customized using the --output flag to display results in either table or JSON format. ``` replicated default show KEY [flags] ``` ### Examples ``` # Show default application replicated default show app ``` ### Options ``` -h, --help help for show ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated default](replicated-cli-default) - Manage default values used by other commands --- # replicated default Manage default values used by other commands ### Options ``` -h, --help help for default ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated default clear](replicated-cli-default-clear) - Clear default value for a key * [replicated default clear-all](replicated-cli-default-clear-all) - Clear all default values * [replicated default set](replicated-cli-default-set) - Set default value for a key * [replicated default show](replicated-cli-default-show) - Show default value for a key --- # replicated installer create Create a new installer spec ### Synopsis Create a new installer spec by providing YAML configuration for a https://kurl.sh cluster. ``` replicated installer create [flags] ``` ### Options ``` --auto generate default values for use in CI -y, --confirm-auto auto-accept the configuration generated by the --auto flag --ensure-channel When used with --promote , will create the channel if it doesn't exist -h, --help help for create --promote string Channel name (case sensitive) or id to promote this installer to --yaml string The YAML config for this installer. Use '-' to read from stdin. Cannot be used with the --yaml-file flag. --yaml-file string The file name with YAML config for this installer. Cannot be used with the --yaml flag. ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated installer](replicated-cli-installer) - Manage Kubernetes installers --- # replicated installer ls List an app's Kubernetes Installers ### Synopsis List an app's https://kurl.sh Kubernetes Installers ``` replicated installer ls [flags] ``` ### Aliases ``` ls, list ``` ### Options ``` -h, --help help for ls ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated installer](replicated-cli-installer) - Manage Kubernetes installers --- # replicated installer Manage Kubernetes installers ### Synopsis The installers command allows vendors to create, display, modify and promote kurl.sh specs for managing the installation of Kubernetes. ### Options ``` -h, --help help for installer ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated installer create](replicated-cli-installer-create) - Create a new installer spec * [replicated installer ls](replicated-cli-installer-ls) - List an app's Kubernetes Installers --- # Install the Replicated CLI This topic describes how to install and run the Replicated CLI. You can use the Replicated CLI to manage your applications with Replicated programmatically, rather than using the Replicated Vendor Portal. ## Prerequisites Complete the following prerequisites before installing the Replicated CLI: - Create a vendor account. See [Create a Vendor Account](/vendor/vendor-portal-creating-account). - To run on Linux or Mac, install [curl](https://curl.haxx.se/). - To run through a Docker container, install [docker](https://www.docker.com). - (Recommended) For Windows users, install Linux on Windows using WSL2. See [How to install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install). ## Install You can install and run the Replicated CLI in the following environments: * Directly on MacOS * Directly on Linux * On Windows Subsystem for Linux (WSL) * Through Docker (Useful for GitHub Actions or computers without sufficient access) ### MacOS To install and run the latest Replicated CLI on MacOS: 1. :::note If you do not have root access to the `/usr/local/bin` directory, you can install with sudo by running `sudo mv replicated /usr/local/bin/replicated` instead of `mv replicated /usr/local/bin/replicated`. ::: 1. 1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth). ### Linux / Windows Subsystem for Linux (WSL) {#linux-wsl2} To install and run the latest Replicated CLI on Linux or Windows Subsystem for Linux (WSL): 1. For Windows users, first install Linux on Windows using WSL2. See [How to install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install). 1. :::note If you do not have root access to the `/usr/local/bin` directory, you can install with sudo by running `sudo mv replicated /usr/local/bin/replicated` instead of `mv replicated /usr/local/bin/replicated`. ::: 1. 1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](#auth). ### Docker :::note For Windows users, Replicated recommends using Windows Subsystem for Linux (WSL2) and installing the Replicated using the Linux installations above. See [Linux / Windows Subsystem for Linux (WSL2)](#linux-wsl2). ::: To install and run the latest Replicated CLI in Docker environments: 1. Generate a service account or user API token in the vendor portal. To create new releases, the token must have `Read/Write` access. See [Generating API Tokens](/vendor/replicated-api-tokens). 1. Get the latest Replicated CLI installation files from the [replicatedhq/replicated repository](https://github.com/replicatedhq/replicated/releases) on GitHub. Download and install the files. For simplicity, the usage in the next step is represented assuming that the CLI is downloaded and installed to the desktop. 1. To begin using the Replicated CLI to manage your applications, authenticate with your Replicated credentials. See [Authenticate](/reference/replicated-cli-installing#auth). :::note Installing in Docker environments requires that you set the `REPLICATED_API_TOKEN` environment variable to authorize the Replicated CLI with an API token. For more information, see [Set Environment Variables](/reference/replicated-cli-installing#env-var). ::: ## Authenticate {#auth} After installing the Replicated CLI, authenticate with your Replicated credentials using one of the following methods: * Set the `REPLICATED_API_TOKEN` environment variable to your API token * Create a Replicated profile at `~/.replicated/config.yaml` to store your API token * Generate a single authentication token by running `replicated login` The Replicated CLI determines which credentials to use for authentication in the following order: 1. `REPLICATED_API_TOKEN` environment variable. Environment variables take precedence, allowing temporary overrides without modifying stored profiles. 2. Replicated profile passed with the `--profile` flag. This allows for a per-command override of the default Replicated profile. 3. Default Replicated profile from `~/.replicated/config.yaml` 4. Single token auth with `replicated login` ### Add Replicated Profiles {#profiles} The Replicated CLI supports multiple authentication profiles, allowing you to manage and switch between different API credentials. This is useful when working with multiple Replicated accounts or environments. Authentication profiles store your API token and can also optionally store custom API endpoints. Profiles are stored securely in `~/.replicated/config.yaml` with file permissions 600 (owner read/write only). The following examples show how to add and work with Replicated profiles: ```bash # Add a production profile using an existing environment variable replicated profile add prod --token='$REPLICATED_API_TOKEN' # Add a development profile with a direct token replicated profile add dev --token=your-dev-token # List all profiles replicated profile ls # Switch to production profile replicated profile use prod # Use development profile for a single command replicated app ls --profile=dev # Edit a profile's token replicated profile edit dev --token=new-dev-token # Remove a profile replicated profile rm dev # Add profiles for different accounts replicated profile add company-a --token=token-a replicated profile add company-b --token=token-b # Switch between accounts replicated profile use company-a replicated app ls # Lists apps for company-a replicated profile use company-b replicated app ls # Lists apps for company-b ``` For more information, see [replicated profile](/reference/replicated-cli-profile). ### Set Environment Variables {#env-var} #### Set REPLICATED_API_TOKEN The `REPLICATED_API_TOKEN` environment variable can be set to a service account or user API token generated from a Vendor Portal team or individual account. The `REPLICATED_API_TOKEN` environment variable is required to authorize the Replicated CLI when installing and running the CLI in Docker containers. It is also helpful for running Replicated CLI commands as part of automation in CI/CD pipelines. To set the `REPLICATED_API_TOKEN` environment variable: 1. Generate a service account or user API token in the vendor portal. To create new releases, the token must have `Read/Write` access. See [Generating API Tokens](/vendor/replicated-api-tokens). 1. Set the environment variable, replacing `TOKEN` with the token you generated in the previous step: * **MacOs or Linux**: ``` export REPLICATED_API_TOKEN=TOKEN ``` * **Docker**: ``` docker run \ -e REPLICATED_API_TOKEN=$TOKEN \ replicated/vendor-cli --help ``` * **Windows**: ``` docker.exe run \ -e REPLICATED_API_TOKEN=%TOKEN% \ replicated/vendor-cli --help ``` #### Set REPLICATED_APP {#replicated_app} When using the Replicated CLI to manage applications through your vendor account, you can set the `REPLICATED_APP` environment variable to the target application slug to avoid having to pass the slug with each command. To set the `REPLICATED_APP` environment variable: 1. Get the application slug: ``` replicated app ls ``` Or, in the [Vendor Portal](https://vendor.replicated.com), go to the **Application Settings** page and copy the slug for the target application. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug) in _Managing Application_. 1. Set the environment variable, replacing `APP_SLUG` with the slug that you copied in the previous step: * **MacOs or Linux**: ``` export REPLICATED_APP=APP_SLUG ``` * **Docker**: ``` docker run \ -e REPLICATED_APP=$APP_SLUG replicated/vendor-cli --help ``` For more information about the `docker run` command, see [docker run](https://docs.docker.com/engine/reference/commandline/run/) in the Docker documentation. * **Windows**: ``` docker.exe run \ -e REPLICATED_APP=%APP_SLUG% \ replicated/vendor-cli --help ``` ### `replicated login` {#login} The `replicated login` command creates a token after you log in to your vendor account in a browser and saves it to a config file. Using the `replicated login` command requires browser access. If you do not have access to a browser, you can authenticate by adding a Replicated profile or setting the `REPLICATED_API_TOKEN` environment variable instead. See [Add Replicated Profiles](#profiles) or [Set Environment Variables](#env-var). To authenticate using `replicated login`: 1. 1. ## Project configuration After installing and authenticating the Replicated CLI, create a `.replicated` configuration file at the root of your project repository. For more information, see [.replicated configuration file](replicated-config-file). --- # replicated instance inspect Show full details for a customer instance ### Synopsis Show full details for a customer instance ``` replicated instance inspect [flags] ``` ### Options ``` --customer string Customer Name or ID -h, --help help for inspect --instance string Instance Name or ID ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated instance](replicated-cli-instance) - Manage instances --- # replicated instance ls list customer instances ### Synopsis list customer instances ``` replicated instance ls [flags] ``` ### Aliases ``` ls, list ``` ### Options ``` --customer string Customer Name or ID -h, --help help for ls --tag stringArray Tags to use to filter instances (key=value format, can be specified multiple times). Only one tag needs to match (an OR operation) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated instance](replicated-cli-instance) - Manage instances --- # replicated instance tag tag an instance ### Synopsis remove or add instance tags ``` replicated instance tag [flags] ``` ### Options ``` --customer string Customer Name or ID -h, --help help for tag --instance string Instance Name or ID --tag stringArray Tags to apply to instance. Leave value empty to remove tag. Tags not specified will not be removed. ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated instance](replicated-cli-instance) - Manage instances --- # replicated instance Manage instances ### Synopsis The instance command allows vendors to display and tag customer instances. ### Options ``` -h, --help help for instance ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated instance inspect](replicated-cli-instance-inspect) - Show full details for a customer instance * [replicated instance ls](replicated-cli-instance-ls) - list customer instances * [replicated instance tag](replicated-cli-instance-tag) - tag an instance --- # replicated login Log in to Replicated ### Synopsis This command will open your browser to ask you authentication details and create / retrieve an API token for the CLI to use. ``` replicated login [flags] ``` ### Options ``` -h, --help help for login ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated --- # replicated logout Logout from Replicated ### Synopsis This command will remove any stored credentials from the CLI. ``` replicated logout [flags] ``` ### Options ``` -h, --help help for logout ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated --- # replicated network ls List test networks ``` replicated network ls [flags] ``` ### Aliases ``` ls, list ``` ### Options ``` --end-time string end time for the query (Format: 2006-01-02T15:04:05Z) -h, --help help for ls --show-reports when set, only show networks that have reports --show-terminated when set, only show terminated networks --start-time string start time for the query (Format: 2006-01-02T15:04:05Z) -w, --watch watch networks ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated network](replicated-cli-network) - Manage test networks for VMs and Clusters --- # replicated network report Get network report ### Synopsis Get a network report showing detailed network activity for a specified network. The report shows individual network events including source/destination IPs, ports, protocols, pods, processes, and DNS queries. Reports must be enabled with 'replicated network update NETWORK_ID --collect-report'. Output formats: - Default: Full event details in JSON format - --summary: Aggregated statistics with top domains and destinations - --watch: Continuous stream of new events in JSON Lines format ``` replicated network report [NETWORK_ID] [flags] ``` ### Examples ``` # Get full network traffic report (external traffic only) replicated network report NETWORK_ID # Get aggregated summary with statistics. Only available for networks that have been terminated. replicated network report NETWORK_ID --summary # Watch for new network events in real-time replicated network report NETWORK_ID --watch ``` ### Options ``` -h, --help help for report --id string Network ID to get report for --summary Get aggregated report summary with statistics instead of individual events -w, --watch Watch for new network events in real-time (polls every 2 seconds) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated network](replicated-cli-network) - Manage test networks for VMs and Clusters --- # replicated network update Update network settings ### Synopsis The 'update' command allows you to update various settings of a test network, including network policy and report collection. You can either specify the network ID or name directly as a positional argument, or provide it using the '--id' or '--name' flags. Network policies control network traffic behavior: - open: No restrictions on network traffic (default) - airgap: Blocks all network egress to simulate air-gapped environments ``` replicated network update [ID_OR_NAME] [flags] ``` ### Examples ``` # Set network policy to airgap replicated network update NETWORK_ID --policy airgap # Set network policy to open replicated network update NETWORK_ID --policy open # Enable network traffic reporting replicated network update NETWORK_ID --collect-report # Disable network reporting replicated network update NETWORK_ID --collect-report=false # Update multiple settings at once replicated network update NETWORK_ID --policy airgap --collect-report ``` ### Options ``` -r, --collect-report Enable report collection on this network (use --collect-report=false to disable) -h, --help help for update --id string id of the network to update (when name is not provided) --name string Name of the network to update -p, --policy string Update network policy setting ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated network](replicated-cli-network) - Manage test networks for VMs and Clusters --- # replicated network Manage test networks for VMs and Clusters ### Synopsis The 'network' command allows you to manage and interact with networks used for testing purposes. With this command you can list the networks in use by VMs and clusters. ### Examples ``` # List all networks replicated network ls # Update a network with an airgap policy replicated network update NETWORK_ID --policy airgap ``` ### Options ``` -h, --help help for network ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated network ls](replicated-cli-network-ls) - List test networks * [replicated network report](replicated-cli-network-report) - Get network report * [replicated network update](replicated-cli-network-update) - Update network settings --- # replicated notification email resend-verification Resend a verification email ``` replicated notification email resend-verification [flags] ``` ### Options ``` --email string Email address to verify -h, --help help for resend-verification ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification email](replicated-cli-notification-email) - Manage notification email verification --- # replicated notification email verify Verify an email address for notifications ``` replicated notification email verify [flags] ``` ### Options ``` --code string Verification code --email string Email address to verify -h, --help help for verify ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification email](replicated-cli-notification-email) - Manage notification email verification --- # replicated notification email Manage notification email verification ### Options ``` -h, --help help for email ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification](replicated-cli-notification) - Manage event notifications * [replicated notification email resend-verification](replicated-cli-notification-email-resend-verification) - Resend a verification email * [replicated notification email verify](replicated-cli-notification-email-verify) - Verify an email address for notifications --- # replicated notification event ls List notification delivery events ``` replicated notification event ls [flags] ``` ### Aliases ``` ls, list ``` ### Options ``` --current-page int Pagination page index --end-time string Filter events before this time (RFC3339) --event-type stringArray Filter by event type key (repeatable) -h, --help help for ls --page-size int Pagination page size (default 20) --search string Search event content --start-time string Filter events after this time (RFC3339) --status string Filter by status: success|pending|failed --subscription-id string Filter by subscription ID --subscription-type string Filter by subscription type: personal|team --type string Filter by category prefix: all|instance|release|customer|channel|support|support_bundle ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification event](replicated-cli-notification-event) - Manage notification delivery events --- # replicated notification event retry Retry a notification event ``` replicated notification event retry EVENT_ID [flags] ``` ### Options ``` -h, --help help for retry ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification event](replicated-cli-notification-event) - Manage notification delivery events --- # replicated notification event-type ls List notification event types ``` replicated notification event-type ls [flags] ``` ### Aliases ``` ls, list ``` ### Options ``` -h, --help help for ls --limit int Maximum results to request from the API (0 means no limit) --q string Search query ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification event-type](replicated-cli-notification-event-type) - List available notification event types --- # replicated notification event-type List available notification event types ### Options ``` -h, --help help for event-type ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification](replicated-cli-notification) - Manage event notifications * [replicated notification event-type ls](replicated-cli-notification-event-type-ls) - List notification event types --- # replicated notification event Manage notification delivery events ### Options ``` -h, --help help for event ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification](replicated-cli-notification) - Manage event notifications * [replicated notification event ls](replicated-cli-notification-event-ls) - List notification delivery events * [replicated notification event retry](replicated-cli-notification-event-retry) - Retry a notification event --- # replicated notification subscription create Create a notification subscription from a JSON file ``` replicated notification subscription create [flags] ``` ### Options ``` --file string Path to a JSON file containing the subscription definition -h, --help help for create ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification subscription](replicated-cli-notification-subscription) - Manage notification subscriptions --- # replicated notification subscription events List delivery events for a notification subscription ``` replicated notification subscription events ID [flags] ``` ### Options ``` -h, --help help for events ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification subscription](replicated-cli-notification-subscription) - Manage notification subscriptions --- # replicated notification subscription get Get a notification subscription ``` replicated notification subscription get ID [flags] ``` ### Options ``` -h, --help help for get ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification subscription](replicated-cli-notification-subscription) - Manage notification subscriptions --- # replicated notification subscription ls List notification subscriptions ``` replicated notification subscription ls [flags] ``` ### Aliases ``` ls, list ``` ### Options ``` -h, --help help for ls --search string Text search filter --type string Filter by subscription type: personal|team ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification subscription](replicated-cli-notification-subscription) - Manage notification subscriptions --- # replicated notification subscription rm Delete a notification subscription ``` replicated notification subscription rm ID [flags] ``` ### Aliases ``` rm, delete, remove ``` ### Options ``` -h, --help help for rm ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification subscription](replicated-cli-notification-subscription) - Manage notification subscriptions --- # replicated notification subscription update Update a notification subscription from a JSON file ``` replicated notification subscription update ID [flags] ``` ### Options ``` --file string Path to a JSON file containing the subscription patch -h, --help help for update ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification subscription](replicated-cli-notification-subscription) - Manage notification subscriptions --- # replicated notification subscription Manage notification subscriptions ### Options ``` -h, --help help for subscription ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification](replicated-cli-notification) - Manage event notifications * [replicated notification subscription create](replicated-cli-notification-subscription-create) - Create a notification subscription from a JSON file * [replicated notification subscription events](replicated-cli-notification-subscription-events) - List delivery events for a notification subscription * [replicated notification subscription get](replicated-cli-notification-subscription-get) - Get a notification subscription * [replicated notification subscription ls](replicated-cli-notification-subscription-ls) - List notification subscriptions * [replicated notification subscription rm](replicated-cli-notification-subscription-rm) - Delete a notification subscription * [replicated notification subscription update](replicated-cli-notification-subscription-update) - Update a notification subscription from a JSON file --- # replicated notification webhook test Send a test webhook from a JSON file ``` replicated notification webhook test [flags] ``` ### Options ``` --file string Path to a JSON file containing the webhook test payload -h, --help help for test ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification webhook](replicated-cli-notification-webhook) - Test notification webhooks --- # replicated notification webhook Test notification webhooks ### Options ``` -h, --help help for webhook ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated notification](replicated-cli-notification) - Manage event notifications * [replicated notification webhook test](replicated-cli-notification-webhook-test) - Send a test webhook from a JSON file --- # replicated notification Manage event notifications ### Synopsis List, create, update, test, and manage event notification subscriptions and delivery events. ### Options ``` -h, --help help for notification ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated notification email](replicated-cli-notification-email) - Manage notification email verification * [replicated notification event](replicated-cli-notification-event) - Manage notification delivery events * [replicated notification event-type](replicated-cli-notification-event-type) - List available notification event types * [replicated notification subscription](replicated-cli-notification-subscription) - Manage notification subscriptions * [replicated notification webhook](replicated-cli-notification-webhook) - Test notification webhooks --- # replicated policy create Create an RBAC policy ### Synopsis Create a new RBAC policy from a JSON definition file. The definition file must be valid JSON in the following format: ```json { "v1": { "name": "My Policy", "resources": { "allowed": ["**/*"], "denied": [] } } } ``` Vendors not on an enterprise plan cannot create policies. ``` replicated policy create [flags] ``` ### Examples ``` # Create a policy from a definition file replicated policy create --name "My Policy" --definition policy.json # Create a policy with a description replicated policy create --name "My Policy" --description "Custom access policy" --definition policy.json ``` ### Options ``` --definition string Path to the JSON file containing the policy definition --description string Description of the policy -h, --help help for create --name string Name of the policy ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated policy](replicated-cli-policy) - Manage RBAC policies --- # replicated policy get Get an RBAC policy ### Synopsis Display details for an RBAC policy. Use --output-file to save the policy definition to a JSON file. ``` replicated policy get NAME_OR_ID [flags] ``` ### Examples ``` # Get a policy by name replicated policy get "My Policy" # Get a policy and save its definition to a file replicated policy get "My Policy" --output-file policy.json # Get a policy in JSON format replicated policy get "My Policy" --output json ``` ### Options ``` -h, --help help for get --output-file string If set, saves the policy definition to the specified file ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated policy](replicated-cli-policy) - Manage RBAC policies --- # replicated policy ls List RBAC policies ### Synopsis List all RBAC policies for your team. ``` replicated policy ls [flags] ``` ### Aliases ``` ls, list ``` ### Examples ``` # List all policies replicated policy ls # List policies in JSON format replicated policy ls --output json ``` ### Options ``` -h, --help help for ls ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated policy](replicated-cli-policy) - Manage RBAC policies --- # replicated policy rm Remove an RBAC policy ### Synopsis Remove an RBAC policy. The Admin, Read Only, Sales, and Support policies cannot be removed. Vendors not on an enterprise plan cannot remove policies. ``` replicated policy rm NAME_OR_ID [flags] ``` ### Aliases ``` rm, delete ``` ### Examples ``` # Remove a policy by name replicated policy rm "My Policy" # Remove a policy by ID replicated policy rm pol_abc123 ``` ### Options ``` -h, --help help for rm ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated policy](replicated-cli-policy) - Manage RBAC policies --- # replicated policy update Update an RBAC policy ### Synopsis Update an existing RBAC policy. At least one of --name, --description, or --definition must be provided. The Admin, Read Only, Sales, and Support policies cannot be updated. Vendors not on an enterprise plan cannot update policies. ``` replicated policy update NAME_OR_ID [flags] ``` ### Examples ``` # Update a policy's definition from a file replicated policy update "My Policy" --definition updated-policy.json # Rename a policy replicated policy update "My Policy" --name "New Policy Name" # Update a policy's description and definition replicated policy update "My Policy" --description "Updated description" --definition policy.json ``` ### Options ``` --definition string Path to the JSON file containing the updated policy definition --description string New description for the policy -h, --help help for update --name string New name for the policy ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated policy](replicated-cli-policy) - Manage RBAC policies --- # replicated policy Manage RBAC policies ### Synopsis The policy command allows vendors to list, create, update, and remove RBAC policies. ### Options ``` -h, --help help for policy ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated policy create](replicated-cli-policy-create) - Create an RBAC policy * [replicated policy get](replicated-cli-policy-get) - Get an RBAC policy * [replicated policy ls](replicated-cli-policy-ls) - List RBAC policies * [replicated policy rm](replicated-cli-policy-rm) - Remove an RBAC policy * [replicated policy update](replicated-cli-policy-update) - Update an RBAC policy --- # replicated profile add Add a new authentication profile ### Synopsis Add a new authentication profile with the specified name. You can provide an API token via the --token flag, or you will be prompted to enter it securely. Optionally, you can specify custom API and registry origins. If a profile with the same name already exists, it will be updated. The profile will be stored in ~/.replicated/config.yaml with file permissions 600 (owner read/write only). ``` replicated profile add [profile-name] [flags] ``` ### Examples ``` # Add a production profile (will prompt for token) replicated profile add prod # Add a production profile with token flag replicated profile add prod --token=your-prod-token # Add a development profile with custom origins replicated profile add dev \ --token=your-dev-token \ --api-origin=https://vendor-api-noahecampbell.okteto.repldev.com \ --registry-origin=vendor-registry-v2-noahecampbell.okteto.repldev.com ``` ### Options ``` --api-origin string API origin (optional, e.g., https://api.replicated.com/vendor). Mutually exclusive with --namespace -h, --help help for add --namespace string Okteto namespace for dev environments (e.g., 'noahecampbell'). Auto-generates service URLs. Mutually exclusive with --api-origin and --registry-origin --registry-origin string Registry origin (optional, e.g., registry.replicated.com). Mutually exclusive with --namespace --token string API token for this profile (optional, will prompt if not provided) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command ``` ### SEE ALSO * [replicated profile](replicated-cli-profile) - Manage authentication profiles --- # replicated profile edit Edit an existing authentication profile ### Synopsis Edit an existing authentication profile. You can update the API token, API origin, and/or registry origin for an existing profile. Only the flags you provide will be updated; other fields will remain unchanged. The profile will be stored in ~/.replicated/config.yaml with file permissions 600 (owner read/write only). ``` replicated profile edit [profile-name] [flags] ``` ### Examples ``` # Update the token for a profile replicated profile edit dev --token=new-dev-token # Update the API origin for a profile replicated profile edit dev --api-origin=https://vendor-api-noahecampbell.okteto.repldev.com # Update multiple fields at once replicated profile edit dev \ --token=new-token \ --api-origin=https://vendor-api-noahecampbell.okteto.repldev.com \ --registry-origin=vendor-registry-v2-noahecampbell.okteto.repldev.com ``` ### Options ``` --api-origin string New API origin (optional, e.g., https://api.replicated.com/vendor). Mutually exclusive with --namespace -h, --help help for edit --namespace string Okteto namespace for dev environments (e.g., 'noahecampbell'). Auto-generates service URLs. Mutually exclusive with --api-origin and --registry-origin --registry-origin string New registry origin (optional, e.g., registry.replicated.com). Mutually exclusive with --namespace --token string New API token for this profile (optional) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command ``` ### SEE ALSO * [replicated profile](replicated-cli-profile) - Manage authentication profiles --- # replicated profile ls List all authentication profiles ### Synopsis List all authentication profiles configured in ~/.replicated/config.yaml. The default profile is indicated with an asterisk (*). ``` replicated profile ls [flags] ``` ### Examples ``` # List all profiles replicated profile ls ``` ### Options ``` -h, --help help for ls ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated profile](replicated-cli-profile) - Manage authentication profiles --- # replicated profile rm Remove an authentication profile ### Synopsis Remove an authentication profile by name. If the removed profile was the default profile, the default will be automatically set to another available profile (if any exist). ``` replicated profile rm [profile-name] [flags] ``` ### Examples ``` # Remove a profile replicated profile rm dev ``` ### Options ``` -h, --help help for rm ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated profile](replicated-cli-profile) - Manage authentication profiles --- # replicated profile set-default Set the default authentication profile ### Synopsis Set the default authentication profile that will be used when no --profile flag is specified and no environment variables are set. ``` replicated profile set-default [profile-name] [flags] ``` ### Examples ``` # Set production as the default profile replicated profile set-default prod ``` ### Options ``` -h, --help help for set-default ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated profile](replicated-cli-profile) - Manage authentication profiles --- # replicated profile use Set the default authentication profile ### Synopsis Set the default authentication profile that will be used when no --profile flag is specified and no environment variables are set. ``` replicated profile use [profile-name] [flags] ``` ### Examples ``` # Use production as the default profile replicated profile use prod ``` ### Options ``` -h, --help help for use ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated profile](replicated-cli-profile) - Manage authentication profiles --- # replicated profile Manage authentication profiles ### Synopsis The profile command allows you to manage authentication profiles for the Replicated CLI. Profiles let you store multiple sets of credentials and easily switch between them. This is useful when working with different Replicated accounts (production, development, etc.) or different API endpoints. Credentials are stored in ~/.replicated/config.yaml with file permissions set to 600 (owner read/write only). Authentication priority: 1. REPLICATED_API_TOKEN environment variable (highest priority) 2. --profile flag (per-command override) 3. Default profile from ~/.replicated/config.yaml 4. Legacy single token (backward compatibility) Use the various subcommands to: - Add new profiles - Edit existing profiles - List all profiles - Remove profiles - Set the default profile ### Examples ``` # Add a production profile (will prompt for token) replicated profile add prod # Add a production profile with token flag replicated profile add prod --token=your-prod-token # Add a development profile with custom API origin replicated profile add dev --token=your-dev-token --api-origin=https://vendor-api-dev.com # Edit an existing profile's API origin replicated profile edit dev --api-origin=https://vendor-api-noahecampbell.okteto.repldev.com # List all profiles replicated profile ls # Set default profile replicated profile set-default prod # Remove a profile replicated profile rm dev ``` ### Options ``` -h, --help help for profile ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated profile add](replicated-cli-profile-add) - Add a new authentication profile * [replicated profile edit](replicated-cli-profile-edit) - Edit an existing authentication profile * [replicated profile ls](replicated-cli-profile-ls) - List all authentication profiles * [replicated profile rm](replicated-cli-profile-rm) - Remove an authentication profile * [replicated profile set-default](replicated-cli-profile-set-default) - Set the default authentication profile * [replicated profile use](replicated-cli-profile-use) - Set the default authentication profile --- # replicated registry add dockerhub Add a DockerHub registry ### Synopsis Add a DockerHub registry using a username/password or an account token ``` replicated registry add dockerhub [flags] ``` ### Options ``` --app-ids string Comma-separated list of app IDs to scope this registry to --authtype string Auth type for the registry (default "password") -h, --help help for dockerhub --name string Name for the registry --password string The password to authenticate to the registry with --password-stdin Take the password from stdin --token string The token to authenticate to the registry with --token-stdin Take the token from stdin --username string The userame to authenticate to the registry with ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --skip-validation Skip validation of the registry (not recommended) ``` ### SEE ALSO * [replicated registry add](replicated-cli-registry-add) - add --- # replicated registry add ecr Add an ECR registry ### Synopsis Add an ECR registry using an Access Key ID and Secret Access Key ``` replicated registry add ecr [flags] ``` ### Options ``` --accesskeyid string The access key id to authenticate to the registry with --app-ids string Comma-separated list of app IDs to scope this registry to --endpoint string The ECR endpoint -h, --help help for ecr --name string Name for the registry --secretaccesskey string The secret access key to authenticate to the registry with --secretaccesskey-stdin Take the secret access key from stdin ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --skip-validation Skip validation of the registry (not recommended) --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated registry add](replicated-cli-registry-add) - add --- # replicated registry add gar Add a Google Artifact Registry ### Synopsis Add a Google Artifact Registry using a service account key ``` replicated registry add gar [flags] ``` ### Options ``` --app-ids string Comma-separated list of app IDs to scope this registry to --authtype string Auth type for the registry (default "serviceaccount") --endpoint string The GAR endpoint -h, --help help for gar --name string Name for the registry --serviceaccountkey string The service account key to authenticate to the registry with --serviceaccountkey-stdin Take the service account key from stdin --token string The token to use to auth to the registry with --token-stdin Take the token from stdin ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --skip-validation Skip validation of the registry (not recommended) ``` ### SEE ALSO * [replicated registry add](replicated-cli-registry-add) - add --- # replicated registry add gcr Add a Google Container Registry ### Synopsis Add a Google Container Registry using a service account key ``` replicated registry add gcr [flags] ``` ### Options ``` --app-ids string Comma-separated list of app IDs to scope this registry to --endpoint string The GCR endpoint -h, --help help for gcr --name string Name for the registry --serviceaccountkey string The service account key to authenticate to the registry with --serviceaccountkey-stdin Take the service account key from stdin ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --skip-validation Skip validation of the registry (not recommended) --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated registry add](replicated-cli-registry-add) - add --- # replicated registry add ghcr Add a GitHub Container Registry ### Synopsis Add a GitHub Container Registry using a username and personal access token (PAT) ``` replicated registry add ghcr [flags] ``` ### Options ``` --app-ids string Comma-separated list of app IDs to scope this registry to -h, --help help for ghcr --name string Name for the registry --token string The token to use to auth to the registry with --token-stdin Take the token from stdin ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --skip-validation Skip validation of the registry (not recommended) ``` ### SEE ALSO * [replicated registry add](replicated-cli-registry-add) - add --- # replicated registry add other Add a generic registry ### Synopsis Add a generic registry using a username/password ``` replicated registry add other [flags] ``` ### Options ``` --app-ids string Comma-separated list of app IDs to scope this registry to --endpoint string endpoint for the registry -h, --help help for other --name string Name for the registry --password string The password to authenticate to the registry with --password-stdin Take the password from stdin --username string The userame to authenticate to the registry with ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --skip-validation Skip validation of the registry (not recommended) --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated registry add](replicated-cli-registry-add) - add --- # replicated registry add quay Add a quay.io registry ### Synopsis Add a quay.io registry using a username/password (or a robot account) ``` replicated registry add quay [flags] ``` ### Options ``` --app-ids string Comma-separated list of app IDs to scope this registry to -h, --help help for quay --name string Name for the registry --password string The password to authenticate to the registry with --password-stdin Take the password from stdin --username string The userame to authenticate to the registry with ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --skip-validation Skip validation of the registry (not recommended) --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated registry add](replicated-cli-registry-add) - add --- # replicated registry add add ### Synopsis add ### Options ``` -h, --help help for add --skip-validation Skip validation of the registry (not recommended) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated registry](replicated-cli-registry) - Manage registries * [replicated registry add dockerhub](replicated-cli-registry-add-dockerhub) - Add a DockerHub registry * [replicated registry add ecr](replicated-cli-registry-add-ecr) - Add an ECR registry * [replicated registry add gar](replicated-cli-registry-add-gar) - Add a Google Artifact Registry * [replicated registry add gcr](replicated-cli-registry-add-gcr) - Add a Google Container Registry * [replicated registry add ghcr](replicated-cli-registry-add-ghcr) - Add a GitHub Container Registry * [replicated registry add other](replicated-cli-registry-add-other) - Add a generic registry * [replicated registry add quay](replicated-cli-registry-add-quay) - Add a quay.io registry --- # replicated registry ls list registries ### Synopsis list registries, or a single registry by name ``` replicated registry ls [NAME] [flags] ``` ### Aliases ``` ls, list ``` ### Options ``` -h, --help help for ls ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated registry](replicated-cli-registry) - Manage registries --- # replicated registry rm remove registry ### Synopsis remove registry by name ``` replicated registry rm [NAME] [flags] ``` ### Aliases ``` rm, delete ``` ### Options ``` -h, --help help for rm ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated registry](replicated-cli-registry) - Manage registries --- # replicated registry test test registry ### Synopsis test registry ``` replicated registry test NAME [flags] ``` ### Options ``` -h, --help help for test --image string The image to test pulling ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated registry](replicated-cli-registry) - Manage registries --- # replicated registry Manage registries ### Synopsis registry can be used to manage existing registries and add new registries to a team ### Options ``` -h, --help help for registry ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated registry add](replicated-cli-registry-add) - add * [replicated registry ls](replicated-cli-registry-ls) - list registries * [replicated registry rm](replicated-cli-registry-rm) - remove registry * [replicated registry test](replicated-cli-registry-test) - test registry --- # replicated release compatibility Report release compatibility ### Synopsis Report release compatibility for a kubernetes distribution and version ``` replicated release compatibility SEQUENCE [flags] ``` ### Options ``` --distribution string Kubernetes distribution of the cluster to report on. --failure If set, the compatibility will be reported as a failure. -h, --help help for compatibility --notes string Additional notes to report. --success If set, the compatibility will be reported as a success. --version string Kubernetes version of the cluster to report on (format is distribution dependent) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated release](replicated-cli-release) - Manage app releases --- # replicated release create Create a new release ### Synopsis Create a new release by providing application manifests for the next release in your sequence. If no flags are provided, the command will automatically use the configuration from .replicated file in the current directory (or parent directories). The config should specify charts and manifests to include. Charts will be automatically packaged using helm, and manifests will be collected using glob patterns. ``` replicated release create [flags] ``` ### Examples ``` # .replicated config: appSlug: "my-app" charts: - path: ./chart manifests: - ./manifests/*.yaml # With this config, simply run: replicated release create --version 1.0.0 --promote Unstable # To mark a release as required during upgrades: replicated release create --version 1.0.0 --promote Unstable --required ``` ### Options ``` --auto generate default values for use in CI (DEPRECATED: use a .replicated file instead) -y, --confirm-auto skip the confirmation prompt --ensure-channel When used with --promote , will create the channel if it doesn't exist --fail-on string The minimum severity to cause the command to exit with a non-zero exit code. Supported values are [info, warn, error, none]. (default "error") -h, --help help for create --lint Lint a manifests directory prior to creation of the KOTS Release. --no-upload Build the release locally but do not upload it. Use with --output-dir to inspect or reuse the staged artifacts. Cannot be used with --promote. --notify-users When used with --promote , notify Enterprise Portal users of this release promotion --output-dir string Stage the release artifacts (packaged charts and manifests) to this directory. Existing contents of the directory are removed before each run. The directory is preserved after the command completes. --promote string Channel name (case sensitive) or id to promote this release to --release-notes string When used with --promote , sets the **markdown** release notes --required When used with --promote , marks this release as required during upgrades. --version string When used with --promote , sets the version label for the release in this channel --wait-for-airgap When used with --promote , wait for airgap bundle builds to complete (KOTS apps only) --wait-for-airgap-timeout duration Timeout for waiting on airgap bundle builds (default 30m0s) --yaml-dir string The directory containing multiple yamls for a Kots release. Cannot be used with the --yaml flag. ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated release](replicated-cli-release) - Manage app releases --- # replicated release download Download application manifests for a release. ### Synopsis Download application manifests for a release to a specified file or directory. For KOTS applications: - Downloads release as a .tgz file if no RELEASE_SEQUENCE specified - Can specify --channel to download the current release from that channel - Auto-generates filename as app-slug.tgz if --dest not provided For non-KOTS applications, this is equivalent to the 'release inspect' command. If no app is specified via --app flag, the app slug will be loaded from the .replicated config file. ``` replicated release download [RELEASE_SEQUENCE] [flags] ``` ### Examples ``` # Download latest release as autoci.tgz replicated release download # Download specific sequence replicated release download 42 --dest my-release.tgz # Download current release from Unstable channel replicated release download --channel Unstable # Download to directory (KOTS only with sequence) replicated release download 1 --dest ./manifests ``` ### Options ``` -c, --channel string Download the current release from this channel (case sensitive) -d, --dest string File or directory to which release should be downloaded. Auto-generated if not specified. -h, --help help for download ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated release](replicated-cli-release) - Manage app releases --- # replicated release image ls List images in a channel's current or specified release ### Synopsis List all container images in the current release or a specific version of a channel ``` replicated release image ls --channel CHANNEL_NAME_OR_ID [--version SEMVER] [--keep-proxy] [flags] ``` ### Examples ``` # List images in current release of a channel by name replicated release image ls --channel Stable # List images in a specific version of a channel replicated release image ls --channel Stable --version 1.2.1 # List images in a channel by ID replicated release image ls --channel 2abc123 # Keep proxy registry domains in the image names replicated release image ls --channel Stable --keep-proxy ``` ### Options ``` --channel string The channel name, slug, or ID (required) -h, --help help for ls --include-installer-images string Include installer images in the output (valid values: online, airgap) --keep-proxy Keep proxy registry domain in image names instead of stripping it --version string The specific semver version to get images for (optional, defaults to current release) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated release image](replicated-cli-release-image) - Manage release images --- # replicated release image Manage release images ### Synopsis Manage release images ### Options ``` -h, --help help for image ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated release](replicated-cli-release) - Manage app releases * [replicated release image ls](replicated-cli-release-image-ls) - List images in a channel's current or specified release --- # replicated release inspect Long: information about a release ### Synopsis Show information about the specified application release. This command displays detailed information about a specific release of an application. The output can be customized using the --output flag to display results in either table or JSON format. ``` replicated release inspect RELEASE_SEQUENCE [flags] ``` ### Examples ``` # Display information about a release replicated release inspect 123 # Display information about a release in JSON format replicated release inspect 123 --output json ``` ### Options ``` -h, --help help for inspect ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated release](replicated-cli-release) - Manage app releases --- # replicated release lint Lint a directory of KOTS manifests or local resources ### Synopsis Lint a directory of KOTS manifests or local resources. Behavior depends on the release-validation-v2 feature flag. ``` replicated release lint [flags] ``` ### Options ``` --fail-on string The minimum severity to cause the command to exit with a non-zero exit code. Supported values are [info, warn, error, none]. (default "error") -h, --help help for lint -v, --verbose Show detailed output including extracted container images (local lint only) --yaml-dir yaml The directory containing multiple yamls for a Kots release. Cannot be used with the yaml flag. ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated release](replicated-cli-release) - Manage app releases --- # replicated release ls List all of an app's releases ### Synopsis List all of an app's releases ``` replicated release ls [flags] ``` ### Aliases ``` ls, list ``` ### Options ``` -h, --help help for ls ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated release](replicated-cli-release) - Manage app releases --- # replicated release promote Set the release for a channel ### Synopsis Set the release for a channel ``` replicated release promote SEQUENCE CHANNEL_ID [flags] ``` ### Examples ``` replicated release promote 15 fe4901690971757689f022f7a460f9b2 ``` ### Options ``` -h, --help help for promote --notify-users Notify Enterprise Portal users of this release promotion --optional If set, this release can be skipped --release-notes string The **markdown** release notes --required If set, this release can't be skipped --version string A version label for the release in this channel --wait-for-airgap Wait for airgap bundle builds to complete (KOTS apps only) --wait-for-airgap-timeout duration Timeout for waiting on airgap bundle builds (default 30m0s) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated release](replicated-cli-release) - Manage app releases --- # replicated release test Test the application release ### Synopsis Test the application release ``` replicated release test SEQUENCE [flags] ``` ### Options ``` -h, --help help for test ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated release](replicated-cli-release) - Manage app releases --- # replicated release update Updated a release's yaml config ### Synopsis Updated a release's yaml config ``` replicated release update SEQUENCE [flags] ``` ### Options ``` -h, --help help for update --yaml string The new YAML config for this release. Use '-' to read from stdin. Cannot be used with the --yaml-file flag. --yaml-dir string The directory containing multiple yamls for a Kots release. Cannot be used with the --yaml flag. --yaml-file string The file name with YAML config for this release. Cannot be used with the --yaml flag. ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated release](replicated-cli-release) - Manage app releases --- # replicated release Manage app releases ### Synopsis The release command allows vendors to create, display, and promote their releases. ### Options ``` -h, --help help for release ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated release compatibility](replicated-cli-release-compatibility) - Report release compatibility * [replicated release create](replicated-cli-release-create) - Create a new release * [replicated release download](replicated-cli-release-download) - Download application manifests for a release. * [replicated release image](replicated-cli-release-image) - Manage release images * [replicated release inspect](replicated-cli-release-inspect) - Long: information about a release * [replicated release lint](replicated-cli-release-lint) - Lint a directory of KOTS manifests or local resources * [replicated release ls](replicated-cli-release-ls) - List all of an app's releases * [replicated release promote](replicated-cli-release-promote) - Set the release for a channel * [replicated release test](replicated-cli-release-test) - Test the application release * [replicated release update](replicated-cli-release-update) - Updated a release's yaml config --- # replicated version upgrade Upgrade the replicated CLI to the latest version ### Synopsis Download, verify, and upgrade the Replicated CLI to the latest version ``` replicated version upgrade [flags] ``` ### Options ``` -h, --help help for upgrade ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated version](replicated-cli-version) - Print the current version and exit --- # replicated version Print the current version and exit ### Synopsis Print the current version and exit ``` replicated version [flags] ``` ### Options ``` -h, --help help for version ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated version upgrade](replicated-cli-version-upgrade) - Upgrade the replicated CLI to the latest version --- # replicated vm create Create one or more test VMs with specified distribution, version, and configuration options. ### Synopsis Create one or more test VMs with a specified distribution, version, and a variety of customizable configuration options. This command allows you to provision VMs with different distributions (e.g., Ubuntu, RHEL), versions, instance types, and more. You can set the number of VMs to create, disk size, and specify the network to use. If no network is provided, a new network will be created automatically. You can also assign tags to your VMs and use a TTL (Time-To-Live) to define how long the VMs should live. If no TTL is specified, the default TTL is 1 hour. By default, the command provisions one VM, but you can customize the number of VMs to create by using the "--count" flag. Additionally, you can use the "--dry-run" flag to simulate the creation without actually provisioning the VMs. The command also supports a "--wait" flag to wait for the VMs to be ready before returning control, with a customizable timeout duration. VMs are currently a beta feature. ``` replicated vm create [flags] ``` ### Examples ``` # Create a single Ubuntu 22.04 VM replicated vm create --distribution ubuntu --version 22.04 # Create 3 Ubuntu 22.04 VMs replicated vm create --distribution ubuntu --version 22.04 --count 3 # Create 5 Ubuntu VMs with a custom instance type and disk size replicated vm create --distribution ubuntu --version 22.04 --count 5 --instance-type r1.medium --disk 100 # Create a VM with an SSH public key replicated vm create --distribution ubuntu --version 22.04 --ssh-public-key ~/.ssh/id_rsa.pub # Create a VM with multiple SSH public keys replicated vm create --distribution ubuntu --version 22.04 --ssh-public-key ~/.ssh/id_rsa.pub --ssh-public-key ~/.ssh/id_ed25519.pub # Create a VM with an SSH public key, then SSH in. # The Linux user provisioned on the VM is taken from the part of the key's # comment before the first '@'. A key with comment "ci@host" creates user "ci", # so pass --username to vm ssh-endpoint to connect as that user. ssh-keygen -t ed25519 -C ci@host -f /tmp/ci_key -N "" replicated vm create --distribution ubuntu --ssh-public-key /tmp/ci_key.pub --name my-vm --wait 5m ssh -i /tmp/ci_key $(replicated vm ssh-endpoint my-vm --username ci) ``` ### Options ``` --count int Number of matching VMs to create (default 1) --disk int Disk Size (GiB) to request per node (default 50) --distribution string Distribution of the VM to provision --dry-run Dry run -h, --help help for create --instance-type string The type of instance to use (e.g. r1.medium) --name string VM name (defaults to random name) --network string The network to use for the VM(s). If not supplied, create a new network --network-policy string The network policy to use for the VM(s) --ssh-public-key stringArray Path to SSH public key file to add to the VM (can be specified multiple times). The Linux user that receives the key is derived from the key's comment: the portion before the first '@'. For example, a comment of 'runner@host' creates a user named 'runner'; pass that name via 'replicated vm ssh-endpoint --username runner' to connect. --tag stringArray Tag to apply to the VM (key=value format, can be specified multiple times) --ttl string VM TTL (duration, max 48h) --version string Version to provision (format is distribution dependent) --wait duration Wait duration for VM(s) to be ready (leave empty to not wait) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated vm](replicated-cli-vm) - Manage test virtual machines. --- # replicated vm ls List test VMs and their status, with optional filters for start/end time and terminated VMs. ### Synopsis List all test VMs in your account, including their current status, distribution, version, and more. You can use optional flags to filter the output based on VM termination status, start time, or end time. This command can also watch the VM status in real-time. By default, the command will return a table of all VMs, but you can switch to JSON or wide output formats for more detailed information. The command supports filtering to show only terminated VMs or to specify a time range for the query. You can use the '--watch' flag to monitor VMs continuously. This will refresh the list of VMs every 2 seconds, displaying any updates in real-time, such as new VMs being created or existing VMs being terminated. The command also allows you to customize the output format, supporting 'json', 'table', and 'wide' views for flexibility based on your needs. VMs are currently a beta feature. ``` replicated vm ls [flags] ``` ### Aliases ``` ls, list ``` ### Examples ``` # List all active VMs replicated vm ls # List all VMs that were created after a specific start time replicated vm ls --start-time 2024-10-01T00:00:00Z # Show only terminated VMs replicated vm ls --show-terminated # Watch VM status changes in real-time replicated vm ls --watch ``` ### Options ``` --end-time string end time for the query (Format: 2006-01-02T15:04:05Z) -h, --help help for ls --show-terminated when set, only show terminated vms --start-time string start time for the query (Format: 2006-01-02T15:04:05Z) -w, --watch watch vms ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated vm](replicated-cli-vm) - Manage test virtual machines. --- # replicated vm port expose Expose a port on a vm to the public internet. ### Synopsis The 'vm port expose' command is used to expose a specified port on a vm to the public internet. When exposing a port, the command automatically creates a DNS entry and, if using the "https" protocol, provisions a TLS certificate for secure communication. This command supports different protocols including "http", "https", "ws", and "wss" for web traffic and web socket communication. VMs are currently a beta feature. ``` replicated vm port expose VM_ID_OR_NAME --port PORT [flags] ``` ### Examples ``` # Expose port for Embedded Cluster (Port: 30000) with HTTP Protocol replicated vm port expose VM_ID_OR_NAME --port 30000 --protocol http # Expose port 8080 with HTTPS protocol replicated vm port expose VM_ID_OR_NAME --port 8080 --protocol https # Expose port 8080 with multiple protocols replicated vm port expose VM_ID_OR_NAME --port 8080 --protocol http,https # Expose port 8080 and display the result in JSON format replicated vm port expose VM_ID_OR_NAME --port 8080 --protocol https --output json ``` ### Options ``` -h, --help help for expose --port int Port to expose (required) --protocol strings Protocol to expose (valid values are "http", "https", "ws" and "wss") (default [http,https]) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated vm port](replicated-cli-vm-port) - Manage VM ports. --- # replicated vm port ls List vm ports for a vm. ### Synopsis The 'vm port ls' command lists all the ports configured for a specific vm. You must provide the vm ID or name to retrieve and display the ports. This command is useful for viewing the current port configurations, protocols, and other related settings of your test vm. The output format can be customized to suit your needs, and the available formats include table, JSON, and wide views. VMs are currently a beta feature. ``` replicated vm port ls VM_ID_OR_NAME [flags] ``` ### Examples ``` # List ports for a vm in the default table format replicated vm port ls VM_ID_OR_NAME # List ports for a vm in JSON format replicated vm port ls VM_ID_OR_NAME --output json # List ports for a vm in wide format replicated vm port ls VM_ID_OR_NAME --output wide ``` ### Options ``` -h, --help help for ls ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated vm port](replicated-cli-vm-port) - Manage VM ports. --- # replicated vm port rm Remove vm port by ID. ### Synopsis The 'vm port rm' command removes a specific port from a vm. You must provide the ID or name of the vm and the ID of the port to remove. This command is useful for managing the network settings of your test vms by allowing you to clean up unused or incorrect ports. After removing a port, the updated list of ports will be displayed. VMs are currently a beta feature. ``` replicated vm port rm VM_ID_OR_NAME --id PORT_ID [flags] ``` ### Examples ``` # Remove a port using its ID replicated vm port rm VM_ID_OR_NAME --id PORT_ID # Remove a port and display the result in JSON format replicated vm port rm VM_ID_OR_NAME --id PORT_ID --output json ``` ### Options ``` -h, --help help for rm --id string ID of the port to remove (required) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated vm port](replicated-cli-vm-port) - Manage VM ports. --- # replicated vm port Manage VM ports. ### Synopsis The 'vm port' command is a parent command for managing ports in a vm. It allows users to list, remove, or expose specific ports used by the vm. Use the subcommands (such as 'ls', 'rm', and 'expose') to manage port configurations effectively. This command provides flexibility for handling ports in various test vms, ensuring efficient management of vm networking settings. VMs are currently a beta feature. ### Examples ``` # List all exposed ports in a vm replicated vm port ls VM_ID_OR_NAME # Remove an exposed port from a vm replicated vm port rm VM_ID_OR_NAME --id PORT_ID # Expose a new port in a vm replicated vm port expose VM_ID_OR_NAME --port PORT ``` ### Options ``` -h, --help help for port ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated vm](replicated-cli-vm) - Manage test virtual machines. * [replicated vm port expose](replicated-cli-vm-port-expose) - Expose a port on a vm to the public internet. * [replicated vm port ls](replicated-cli-vm-port-ls) - List vm ports for a vm. * [replicated vm port rm](replicated-cli-vm-port-rm) - Remove vm port by ID. --- # replicated vm rm Remove test VM(s) immediately, with options to filter by name, tag, or remove all VMs. ### Synopsis The 'rm' command allows you to remove test VMs from your account immediately. You can specify one or more VM IDs or names directly, or use flags to filter which VMs to remove based on their tags, or simply remove all VMs at once. This command supports multiple filtering options, including removing VMs by their name or ID, by specific tags, or by specifying the '--all' flag to remove all VMs in your account. When specifying a name that matches multiple VMs, all VMs with that name will be removed. You can also use the '--dry-run' flag to simulate the removal without actually deleting the VMs. VMs are currently a beta feature. ``` replicated vm rm ID_OR_NAME [ID_OR_NAME …] [flags] ``` ### Aliases ``` rm, delete ``` ### Examples ``` # Remove a VM by ID or name replicated vm rm aaaaa11 # Remove multiple VMs by ID or name replicated vm rm aaaaa11 bbbbb22 ccccc33 # Remove all VMs with a specific tag replicated vm rm --tag env=dev # Remove all VMs replicated vm rm --all # Perform a dry run of removing all VMs replicated vm rm --all --dry-run ``` ### Options ``` --all remove all vms --dry-run Dry run -h, --help help for rm --name stringArray Name of the vm to remove (can be specified multiple times) (DEPRECATED: use ID_OR_NAME arguments instead) --tag stringArray Tag of the vm to remove (key=value format, can be specified multiple times) ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated vm](replicated-cli-vm) - Manage test virtual machines. --- # replicated vm scp-endpoint Get the SCP endpoint of a VM ### Synopsis Get the SCP endpoint and port of a VM. The output will be in the format: scp://username@hostname:port You can identify the VM either by its unique ID or by its name. By default, the username in the endpoint is the GitHub username linked to your Vendor Portal account. If the VM was created with 'replicated vm create --ssh-public-key', the Linux user on the VM is derived from the key's comment (the portion before the first '@') instead — pass that username via --username so the endpoint matches the user the key was added to. Note: SCP endpoints can only be retrieved from VMs in the "running" state. VMs are currently a beta feature. ``` replicated vm scp-endpoint VM_ID_OR_NAME [flags] ``` ### Examples ``` # Get SCP endpoint for a specific VM by ID replicated vm scp-endpoint aaaaa11 # Get SCP endpoint for a specific VM by name replicated vm scp-endpoint my-test-vm # Get SCP endpoint with a custom username replicated vm scp-endpoint my-test-vm --username custom-user # Use the endpoint to SCP a file to a VM by name scp /tmp/my-file $(replicated vm scp-endpoint my-test-vm)//dst/path/my-file # Use the endpoint to SCP a file from a VM by name scp $(replicated vm scp-endpoint my-test-vm)//src/path/my-file /tmp/my-file ``` ### Options ``` -h, --help help for scp-endpoint --username string Custom username to use in SCP endpoint instead of the GitHub username set in Vendor Portal. If the VM was created with 'replicated vm create --ssh-public-key', set this to the username derived from the key's comment (the portion before the first '@') so the endpoint matches the user the key was added to. ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated vm](replicated-cli-vm) - Manage test virtual machines. --- # replicated vm ssh-endpoint Get the SSH endpoint of a VM ### Synopsis Get the SSH endpoint and port of a VM. The output will be in the format: ssh://username@hostname:port You can identify the VM either by its unique ID or by its name. By default, the username in the endpoint is the GitHub username linked to your Vendor Portal account. If the VM was created with 'replicated vm create --ssh-public-key', the Linux user on the VM is derived from the key's comment (the portion before the first '@') instead — pass that username via --username so the endpoint matches the user the key was added to. Note: SSH endpoints can only be retrieved from VMs in the "running" state. VMs are currently a beta feature. ``` replicated vm ssh-endpoint VM_ID_OR_NAME [flags] ``` ### Examples ``` # Get SSH endpoint for a specific VM by ID replicated vm ssh-endpoint aaaaa11 # Get SSH endpoint for a specific VM by name replicated vm ssh-endpoint my-test-vm # Get SSH endpoint with a custom username replicated vm ssh-endpoint my-test-vm --username custom-user # Use the endpoint to SSH to a VM by name ssh $(replicated vm ssh-endpoint my-test-vm) ``` ### Options ``` -h, --help help for ssh-endpoint --username string Custom username to use in SSH endpoint instead of the GitHub username set in Vendor Portal. If the VM was created with 'replicated vm create --ssh-public-key', set this to the username derived from the key's comment (the portion before the first '@') so the endpoint matches the user the key was added to. ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated vm](replicated-cli-vm) - Manage test virtual machines. --- # replicated vm update ttl Update TTL for a test VM. ### Synopsis The 'ttl' command allows you to update the Time to Live (TTL) for a test VM. This command modifies the lifespan of a running VM by updating its TTL, which is a duration starting from the moment the VM is provisioned. The TTL specifies how long the VM will run before it is automatically terminated. You can specify a duration up to a maximum of 48 hours. If no TTL is specified, the default TTL is 1 hour. The command accepts a VM ID or name as an argument and requires the '--ttl' flag to specify the new TTL value. You can also specify the output format (json, table, wide) using the '--output' flag. VMs are currently a beta feature. ``` replicated vm update ttl [ID_OR_NAME] [flags] ``` ### Examples ``` # Update the TTL of a VM to 2 hours replicated vm update ttl aaaaa11 --ttl 2h # Update the TTL of a VM to 30 minutes using VM name replicated vm update ttl my-test-vm --ttl 30m ``` ### Options ``` -h, --help help for ttl --ttl string Update TTL which starts from the moment the vm is running (duration, max 48h). ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output --id string id of the vm to update (when name is not provided) --name string Name of the vm to update. -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated vm update](replicated-cli-vm-update) - Update VM settings. --- # replicated vm update Update VM settings. ### Synopsis The 'vm update' command allows you to modify the settings of a virtual machine. You can update a VM either by providing its ID or name directly as an argument to subcommands, or by using the '--id' or '--name' flags. This command supports updating various VM settings, which will be handled by specific subcommands. - To update the VM by its ID or name, use the subcommand directly with the ID or name as an argument. - Alternatively, to update the VM by its ID, use the '--id' flag. - Alternatively, to update the VM by its name, use the '--name' flag. Subcommands will allow for more specific updates like TTL. VMs are currently a beta feature. ### Examples ``` # Update a VM TTL by specifying its ID or name directly replicated vm update ttl my-test-vm --ttl 12h # Update a VM by specifying its ID with a flag replicated vm update --id aaaaa11 --ttl 12h # Update a VM by specifying its name with a flag replicated vm update --name my-test-vm --ttl 12h ``` ### Options ``` -h, --help help for update --id string id of the vm to update (when name is not provided) --name string Name of the vm to update. ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated vm](replicated-cli-vm) - Manage test virtual machines. * [replicated vm update ttl](replicated-cli-vm-update-ttl) - Update TTL for a test VM. --- # replicated vm versions List available VM versions. ### Synopsis The 'vm versions' command lists all the available versions of virtual machines that can be provisioned. This includes the available distributions and their respective versions. - You can filter the list by a specific distribution using the '--distribution' flag. - The output can be formatted as a table or in JSON format using the '--output' flag. VMs are currently a beta feature. ``` replicated vm versions [flags] ``` ### Examples ``` # List all available VM versions replicated vm versions # List VM versions for a specific distribution (e.g., Ubuntu) replicated vm versions --distribution ubuntu # Display the output in JSON format replicated vm versions --output json ``` ### Options ``` --distribution string Kubernetes distribution to filter by. -h, --help help for versions ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated vm](replicated-cli-vm) - Manage test virtual machines. --- # replicated vm Manage test virtual machines. ### Synopsis The 'vm' command allows you to manage and interact with virtual machines (VMs) used for testing purposes. With this command, you can create, list, remove, update, and manage VMs, as well as retrieve information about available VM versions. VMs are currently a beta feature. ### Examples ``` # Create a single Ubuntu VM replicated vm create --distribution ubuntu --version 20.04 # List all VMs replicated vm ls # Remove a specific VM by ID replicated vm rm # Update TTL for a specific VM replicated vm update ttl --ttl 24h ``` ### Options ``` -h, --help help for vm ``` ### Options inherited from parent commands ``` --app string The app slug or app id to use in all calls --debug Enable debug output -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated](replicated) - Manage your Commercial Software Distribution Lifecycle using Replicated * [replicated vm create](replicated-cli-vm-create) - Create one or more test VMs with specified distribution, version, and configuration options. * [replicated vm ls](replicated-cli-vm-ls) - List test VMs and their status, with optional filters for start/end time and terminated VMs. * [replicated vm port](replicated-cli-vm-port) - Manage VM ports. * [replicated vm rm](replicated-cli-vm-rm) - Remove test VM(s) immediately, with options to filter by name, tag, or remove all VMs. * [replicated vm scp-endpoint](replicated-cli-vm-scp-endpoint) - Get the SCP endpoint of a VM * [replicated vm ssh-endpoint](replicated-cli-vm-ssh-endpoint) - Get the SSH endpoint of a VM * [replicated vm update](replicated-cli-vm-update) - Update VM settings. * [replicated vm versions](replicated-cli-vm-versions) - List available VM versions. --- # Replicated CLI project configuration The `.replicated` file is a per-project configuration file that the Replicated CLI uses. Place this file at the root of your project repository. It tells the CLI which application, Helm charts, Kubernetes manifests, and preflight checks belong to this project. When you run commands like `replicated release create` without explicit flags, the CLI searches for this file in the current directory. It continues searching upward through parent directories. `replicated release lint` uses `.replicated` only when the release validation v2 feature flag is active or when the `REPLICATED_RELEASE_VALIDATION_V2` environment variable is set to `1`. ## File location and name Place the file at the root of your project. The CLI searches from the current working directory up through parent directories. It accepts either of these names: - `.replicated` - `.replicated.yaml` ## What it configures The `.replicated` file configures the following: * **Application identity:** which Replicated app this project belongs to * **Charts:** Helm charts to package as part of a release * **Manifests:** raw Kubernetes YAML files to include in a release * **Preflights:** preflight check specs to validate before install * **Linting:** local lint tool configuration and version pinning ## Field reference ### `appSlug` (string, optional) The slug of your Replicated application. Commands that need to know which app to operate on, such as `replicated release create`, use this field. You can also provide this with the `--app` flag or the `REPLICATED_APP` environment variable. ```yaml appSlug: "my-application" ``` ### `appId` (string, optional) The UUID of your Replicated application. Alternative to `appSlug`. If both are present, the CLI prefers `appSlug`. ```yaml appId: "12345678-1234-1234-1234-123456789abc" ``` ### `charts` (list, optional) Helm charts to package when creating a release. Each entry is a chart with the following fields: | Field | Type | Required | Description | |-------|------|----------|-------------| | `path` | string | Yes | Path to the chart directory. Can be a glob pattern. Resolved relative to the `.replicated` file. | | `chartVersion` | string | No | Override the chart version. | | `appVersion` | string | No | Override the application version. | ```yaml charts: - path: ./chart - path: ./charts/backend chartVersion: "1.2.3" appVersion: "v2.0.0" ``` ### `manifests` (list of strings, optional) Glob patterns that match Kubernetes manifest YAML files to include in the release. Resolve these patterns relative to the `.replicated` file. ```yaml manifests: - ./manifests/*.yaml - ./crds/**/*.yaml ``` ### `preflights` (list, optional) Preflight check specifications to lint and validate. Each entry has the following fields: | Field | Type | Required | Description | |-------|------|----------|-------------| | `path` | string | Yes | Path to the preflight spec file. | | `chartName` | string | No | Explicit chart name to associate with this preflight. | | `chartVersion` | string | No | Explicit chart version. Provide this together with `chartName`. | ```yaml preflights: - path: ./preflight.yaml - path: ./preflights/ha-checks.yaml chartName: my-app chartVersion: "1.0.0" ``` ### `repl-lint` (object, optional) Configuration for the local linting engine. This controls which linters run and which tool versions to use. | Field | Type | Description | |-------|------|-------------| | `version` | integer | Lint config schema version. Defaults to `1`. | | `linters` | object | Toggle individual linters on or off. | | `tools` | map | Pin tool versions (e.g. `helm: "3.14.4"`). Defaults to `"latest"`. | #### Linter configuration Each linter in `linters` supports a `disabled` boolean: ```yaml repl-lint: version: 1 linters: helm: disabled: false # on by default preflight: disabled: false # on by default support-bundle: disabled: false # on by default embedded-cluster: disabled: true # off by default (opt-in) ``` The `kots` linter is parsed by the config but is not currently implemented. Enabling it has no effect. The `embedded-cluster` linter also supports: | Field | Type | Description | |-------|------|-------------| | `disable-checks` | list of strings | Checker IDs to skip. Defaults to `["helmchart-archive", "ecconfig-helmchart-archive"]`. | | `binary-path` | string | Path to a custom embedded-cluster binary. | #### Tool version pinning You can pin the versions of external tools that the linters use: ```yaml repl-lint: tools: helm: "3.14.4" preflight: "latest" support-bundle: "latest" ``` Versions must be either a semantic version (`1.2.3` or `v1.2.3`) or the string `latest`. The `embedded-cluster` linter discovers its version from the manifests instead of the `tools` map. Setting it in `.replicated` has no effect. ## App resolution precedence When a command needs to know which app to target, it resolves the value in this order: 1. `--app` flag 2. `REPLICATED_APP` environment variable 3. `.replicated` file (`appSlug` or `appId`) 4. Cached default app from `replicated default app ` ## Monorepo support If you have a monorepo with multiple apps, you can place a `.replicated` file in each app subdirectory. The CLI searches upward from the current working directory and merges all found configuration files: - Scalar fields (`appSlug`, `appId`): child overrides parent. - Resource arrays (`charts`, `preflights`, `manifests`): accumulate from all levels. - `repl-lint`: child overrides parent settings. This lets you define common settings at the repo root and app-specific settings in subdirectories. ## Examples ### Minimal Helm-only project ```yaml appSlug: "my-helm-app" charts: - path: ./chart ``` ### KOTS manifests project ```yaml appSlug: "my-kots-app" manifests: - ./manifests/*.yaml - ./crds/**/*.yaml ``` ### Multi-chart project with linting ```yaml appSlug: "my-platform" charts: - path: ./charts/api - path: ./charts/worker manifests: - ./manifests/*.yaml - ./configmaps/*.yaml preflights: - path: ./preflights/cluster-checks.yaml chartName: api chartVersion: "1.0.0" repl-lint: version: 1 linters: helm: disabled: false preflight: disabled: false support-bundle: disabled: true ``` ### Monorepo root configuration ```yaml # At repo root: .replicated repl-lint: version: 1 linters: helm: disabled: false ``` ```yaml # At apps/frontend/.replicated appSlug: "frontend-app" charts: - path: ./chart manifests: - ./manifests/*.yaml ``` ```yaml # At apps/backend/.replicated appSlug: "backend-app" charts: - path: ./chart manifests: - ./manifests/*.yaml ``` ## Create a configuration file Run the interactive initialization command to generate a `.replicated` file for your project: ```bash replicated config init ``` For non-interactive environments (e.g., CI): ```bash replicated config init --non-interactive ``` --- # Replicated SDK API The Replicated SDK provides an API that you can use to embed Replicated functionality in your Helm chart application. For example, if your application includes a UI where users manage their application instance, then you can use the `/api/v1/app/updates` endpoint to include messages in the UI that encourage users to upgrade when new versions are available. You could also revoke access to the application during runtime when a license expires using the `/api/v1/license/fields` endpoint. For more information about how to get started with the Replicated SDK, see [About the Replicated SDK](/vendor/replicated-sdk-overview). For information about how to develop against the Replicated SDK API with mock data, see [Developing Against the Replicated SDK](/vendor/replicated-sdk-development). ## app ### GET /app/info List details about an application instance, including the app name, location of the Helm chart in the Replicated OCI registry, and details about the current application release that the instance is running. ```bash GET http://replicated:3000/api/v1/app/info ``` Response: ```json { "instanceID": "8dcdb181-5cc4-458c-ad95-c0a1563cb0cb", "appSlug": "my-app", "appName": "My App", "appStatus": "ready", "helmChartURL": "oci://registry.replicated.com/my-app/beta/my-helm-chart", "currentRelease": { "versionLabel": "0.1.72", "channelID": "2CBDxNwDH1xyYiIXRTjiB7REjKX", "channelName": "Beta", "createdAt": "2023-05-28T16:31:21Z", "releaseNotes": "", "helmReleaseName": "my-helm-chart", "helmReleaseRevision": 5, "helmReleaseNamespace": "my-helm-chart" }, "channelID": "2CBDxNwDH1xyYiIXRTjiB7REjKX", "channelName": "Beta", "channelSequence": 4, "releaseSequence": 30 } ``` ### GET /app/status List details about an application status, including the list of individual resource states and the overall application state. ```bash GET http://replicated:3000/api/v1/app/status ``` Response: ```json { "appStatus": { "appSlug": "my-app", "resourceStates": [ { "kind": "deployment", "name": "api", "namespace": "default", "state": "ready" } ], "updatedAt": "2024-12-19T23:01:52.207162284Z", "state": "ready", "sequence": 268 } } ``` ### GET /app/updates List details about the releases that are available to an application instance for upgrade, including the version label, created timestamp, and release notes. ```bash GET http://replicated:3000/api/v1/app/updates ``` Response: ```json [ { "versionLabel": "0.1.15", "createdAt": "2023-05-12T15:48:45.000Z", "releaseNotes": "Awesome new features!" } ] ``` ### GET /app/history List details about the releases that an application instance has installed previously. ```bash GET http://replicated:3000/api/v1/app/history ``` Response: ```json { "releases": [ { "versionLabel": "0.1.70", "channelID": "2CBDxNwDH1xyYiIXRTjiB7REjKX", "channelName": "Stable", "createdAt": "2023-05-12T17:43:51Z", "releaseNotes": "", "helmReleaseName": "echo-server", "helmReleaseRevision": 2, "helmReleaseNamespace": "echo-server-helm" } ] } ``` ### POST /app/custom-metrics Send custom application metrics. For more information and examples see [Configure Custom Metrics](/vendor/custom-metrics). ### PATCH /app/custom-metrics Send partial custom application metrics for upserting. ```bash PATCH http://replicated:3000/api/v1/app/custom-metrics ``` Request: ```json { "data": { "numProjects": 20, } } ``` Response: Status `200` OK ### DELETE /app/custom-metrics/\{metric_name\} Delete an application custom metric. ```bash DELETE http://replicated:3000/api/v1/app/custom-metrics/numProjects ``` Response: Status `204` No Content ### POST /app/instance-tags Programmatically set new instance tags or overwrite existing tags. Instance tags are key-value pairs, where the key and the value are strings. Setting a tag with the `name` key will set the instance's name in the vendor portal. The `force` parameter defaults to `false`. If `force` is `false`, conflicting pre-existing tags will not be overwritten and the existing tags take precedence. If the `force` parameter is set to `true`, any conflicting pre-existing tags will be overwritten. To delete a particular tag, set the key's value to an empty string `""`. ```bash POST http://replicated:3000/api/v1/app/instance-tags ``` Request: ```json { "data": { "force": false, "tags": { "name": "my-instance-name", "preExistingKey": "will-not-be-overwritten", "cpuCores": "10", "supportTier": "basic" } } } ``` Response: Status `200` OK ## supportbundle ### POST /supportbundle Upload a support bundle through the SDK. The bundle is streamed to Replicated for analysis and is available in the Vendor Portal. **Requirements:** * Replicated SDK 1.17.1 or later * The environment must have outbound internet access * The request must include the `Content-Length` header ```bash POST http://replicated:3000/api/v1/supportbundle Content-Type: application/gzip Content-Length: ``` Response: Status `201` Created ```json { "bundleId": "abc123-def456", "slug": "my-app-supportbundle-abc123" } ``` ### POST /supportbundle/metadata Set support bundle metadata (key-value pairs) by replacing any existing metadata. The SDK stores metadata as top-level keys in a Kubernetes secret named `replicated-support-metadata` in the SDK namespace. You can use the `supportBundleMetadata` collector to include this metadata in support bundles. For more information about this collector, see [Support Bundle Metadata](https://troubleshoot.sh/docs/collect/support-bundle-metadata) in the Troubleshoot documentation. ```bash POST http://replicated:3000/api/v1/supportbundle/metadata ``` Request: ```json { "data": { "key1": "value1", "key2": "value2" } } ``` Response: Status `200` OK ### PATCH /supportbundle/metadata Merge support bundle metadata (key-value pairs) with any existing metadata. `PATCH /supportbundle/metadata` adds new keys and updates existing keys. It preserves any keys excluded from the request. The SDK stores metadata as top-level keys in a Kubernetes secret named `replicated-support-metadata` in the SDK namespace. You can use the `supportBundleMetadata` collector to include this metadata in a support bundle. For more information about this collector, see [Support Bundle Metadata](https://troubleshoot.sh/docs/collect/support-bundle-metadata) in the Troubleshoot documentation. ```bash PATCH http://replicated:3000/api/v1/supportbundle/metadata ``` Request: ```json { "data": { "key3": "value3" } } ``` Response: Status `200` OK ## license ### GET /license/info List details about the license that was used to install, including the license ID, type, the customer name, and the channel the customer is assigned. ```bash GET http://replicated:3000/api/v1/license/info ``` Response: ```json { "licenseID": "YiIXRTjiB7R...", "appSlug": "my-app", "channelID": "2CBDxNwDH1xyYiIXRTjiB7REjKX", "channelName": "Stable", "customerName": "Example Customer", "customerEmail": "username@example.com", "licenseType": "dev", "licenseSequence": 1, "isAirgapSupported": false, "isGitOpsSupported": false, "isIdentityServiceSupported": false, "isGeoaxisSupported": false, "isSnapshotSupported": false, "isSupportBundleUploadSupported": false, "isSemverRequired": true, "endpoint": "https://replicated.app", "entitlements": { "expires_at": { "title": "Expiration", "description": "License Expiration", "value": "", "valueType": "String" }, "numSeats": { "title": "Number of Seats", "value": 10, "valueType": "Integer" } } } ``` ### GET /license/fields List details about all the fields in the license that was used to install, including the field names, descriptions, values, and signatures. ```bash GET http://replicated:3000/api/v1/license/fields ``` Response: ```json { "expires_at": { "name": "expires_at", "title": "Expiration", "description": "License Expiration", "value": "2023-05-30T00:00:00Z", "valueType": "String", "signature": { "v1": "Vs+W7+sF0RA6UrFEJcyHAbC5YCIT67hdsDdqtJTRBd4ZitTe4pr1D/SZg2k0NRIozrBP1mXuTgjQgeI8PyQJc/ctQwZDikIEKFW0sVv0PFPQV7Uf9fy7wRgadfUxkagcCS8O6Tpcm4WqlhEcgiJGvPBki3hZLnMO9Ol9yOepZ7UtrUMVsBUKwcTJWCytpFpvvOLfSNoHxMnPuSgpXumbHZjvdXrJoJagoRDXPiXXKGh02DOr58ncLofYqPzze+iXWbE8tqdFBZc72lLayT1am3MN0n3ejCNWNeX9+CiBJkqMqLLkjN4eugUmU/gBiDtJgFUB2gq8ejVVcohqos69WA==" } }, "numSeats": { "name": "numSeats", "title": "Number of Seats", "value": 10, "valueType": "Integer", "signature": { "v1": "UmsYlVr4+Vg5TWsJV6goagWUM4imdj8EUUcdau7wIzfcU0MuZnv3UNVlwVE/tCuROCMcbei6ygjm4j5quBdkAGUyq86BCtohg/SqRsgVoNV6BN0S+tnqJ7w4/nqRVBc2Gsn7wTYNXiszLMkmfeNOrigLgsrtaGJmZ4IsczwI1V5Tr+AMAgrACL/UyLg78Y6EitKFW4qvJ9g5Q8B3uVmT+h9xTBxJFuKTQS6qFcDx9XCu+bKqoSmJDZ8lwgwpJDAiBzIhxiAd66lypHX9cpOg5A7cKEW+FLdaBKQdNRcPHQK2O9QwFj/NKEeCJEufuD3OeV8MSbN2PCehMzbj7tXSww==" } } } ``` ### GET /license/fields/\{field_name\} List details about one of the fields in the license that was used to install, including the field name, description, value, and signature. ```bash GET http://replicated:3000/api/v1/license/fields/\{field_name\} ``` Example request: ```bash curl replicated:3000/api/v1/license/fields/expires_at ``` Response: ```json { "name": "expires_at", "title": "Expiration", "description": "License Expiration", "value": "2023-05-30T00:00:00Z", "valueType": "String", "signature": { "v1": "c6rsImpilJhW0eK+Kk37jeRQvBpvWgJeXK2MD0YBlIAZEs1zXpmvwLdfcoTsZMOj0lZbxkPN5dPhEPIVcQgrzfzwU5HIwQbwc2jwDrLBQS4hGOKdxOWXnBUNbztsHXMqlAYQsmAhspRLDhBiEoYpFV/8oaaAuNBrmRu/IVAW6ahB4KtP/ytruVdBup3gn1U/uPAl5lhzuBifaW+NDFfJxAXJrhdTxMBxzfdKa6dGmlGu7Ou/xqDU1bNF3AuWoP3C78GzSBQrD1ZPnu/d+nuEjtakKSX3EK6VUisNucm8/TFlEVKUuX7hex7uZ9Of+UgS1GutQXOhXzfMZ7u+0zHXvQ==" } } ``` ## Integration ### GET /api/v1/integration/status Get status of Development Mode. When this mode is enabled, the `app` API will use mock data. This value cannot be set programmatically. It is controlled by the installed license. ```json { "isEnabled": true } ``` ### GET /api/v1/integration/mock-data Get mock data that is used when Development Mode is enabled. ```json { "appStatus": "ready", "helmChartURL": "oci://registry.replicated.com/dev-app/dev-channel/dev-parent-chart", "currentRelease": { "versionLabel": "0.1.3", "releaseNotes": "release notes 0.1.3", "createdAt": "2023-05-23T20:58:07Z", "deployedAt": "2023-05-23T21:58:07Z", "helmReleaseName": "dev-parent-chart", "helmReleaseRevision": 3, "helmReleaseNamespace": "default" }, "deployedReleases": [ { "versionLabel": "0.1.1", "releaseNotes": "release notes 0.1.1", "createdAt": "2023-05-21T20:58:07Z", "deployedAt": "2023-05-21T21:58:07Z", "helmReleaseName": "dev-parent-chart", "helmReleaseRevision": 1, "helmReleaseNamespace": "default" }, { "versionLabel": "0.1.2", "releaseNotes": "release notes 0.1.2", "createdAt": "2023-05-22T20:58:07Z", "deployedAt": "2023-05-22T21:58:07Z", "helmReleaseName": "dev-parent-chart", "helmReleaseRevision": 2, "helmReleaseNamespace": "default" }, { "versionLabel": "0.1.3", "releaseNotes": "release notes 0.1.3", "createdAt": "2023-05-23T20:58:07Z", "deployedAt": "2023-05-23T21:58:07Z", "helmReleaseName": "dev-parent-chart", "helmReleaseRevision": 3, "helmReleaseNamespace": "default" } ], "availableReleases": [ { "versionLabel": "0.1.4", "releaseNotes": "release notes 0.1.4", "createdAt": "2023-05-24T20:58:07Z", "deployedAt": "2023-05-24T21:58:07Z", "helmReleaseName": "", "helmReleaseRevision": 0, "helmReleaseNamespace": "" }, { "versionLabel": "0.1.5", "releaseNotes": "release notes 0.1.5", "createdAt": "2023-06-01T20:58:07Z", "deployedAt": "2023-06-01T21:58:07Z", "helmReleaseName": "", "helmReleaseRevision": 0, "helmReleaseNamespace": "" } ] } ``` ### POST /api/v1/integration/mock-data Programmatically set mock data that is used when Development Mode is enabled. The payload will overwrite the existing mock data. Any data that is not included in the payload will be removed. For example, to remove release data, simply include empty arrays: ```bash POST http://replicated:3000/api/v1/integration/mock-data ``` Request: ```json { "appStatus": "ready", "helmChartURL": "oci://registry.replicated.com/dev-app/dev-channel/dev-parent-chart", "currentRelease": { "versionLabel": "0.1.3", "releaseNotes": "release notes 0.1.3", "createdAt": "2023-05-23T20:58:07Z", "deployedAt": "2023-05-23T21:58:07Z", "helmReleaseName": "dev-parent-chart", "helmReleaseRevision": 3, "helmReleaseNamespace": "default" }, "deployedReleases": [], "availableReleases": [] } ``` Response: Status `201` Created ## Examples This section provides example use cases for the Replicated SDK API. ### Support Update Checks in Your Application The `api/v1/app/updates` endpoint returns details about new releases that are available to an instance for upgrade. You could use the `api/v1/app/updates` endpoint to allow your users to easily check for available updates from your application. Additionally, to make it easier for users to upgrade to new versions of your application, you could provide customer-specific upgrade instructions in your application by injecting values returned by the `/api/v1/license/info` and `/api/v1/app/info` endpoints. The following examples show how you could include a page in your application that lists available updates and also provides customer-specific upgrade instructions: ![a user interface showing a list of available releases](/images/slackernews-update-page.png) [View a larger version of this image](/images/slackernews-update-page.png) ![user-specific application upgrade instructions displayed in a dialog](/images/slackernews-update-instructions.png) [View a larger version of this image](/images/slackernews-update-instructions.png) To use the SDK API to check for available application updates and provide customer-specific upgrade instructions: 1. From your application, call the `api/v1/app/updates` endpoint to return available updates for the application instance. Use the response to display available upgrades for the customer. ```bash curl replicated:3000/api/v1/app/updates ``` **Example response**: ```json [ { "versionLabel": "0.1.15", "createdAt": "2023-05-12T15:48:45.000Z", "releaseNotes": "Awesome new features!" } ] ``` 1. For each available release, add logic that displays the required upgrade commands with customer-specific values. To upgrade, users must first run `helm registry login` to authenticate to the Replicated registry. Then, they can run `helm upgrade`: 1. Inject customer-specific values into the `helm registry login` command: ```bash helm registry login REGISTRY_DOMAIN --username EMAIL --password LICENSE_ID ``` The `helm registry login` command requires the following components: * `REGISTRY_DOMAIN`: The domain for the registry where your Helm chart is pushed. The registry domain is either `replicated.registry.com` or a custom domain that you added. * `EMAIL`: The customer email address is available from the `/api/v1/license/info` endpoint in the `customerEmail` field. * `LICENSE_ID` The customer license ID is available from the `/api/v1/license/info` endpoint in the `licenseID` field. 1. Inject customer-specific values into the `helm upgrade` command: ```bash helm upgrade -n NAMESPACE RELEASE_NAME HELM_CHART_URL ``` The following describes where the values in the `helm upgrade` command are available: * `NAMESPACE`: The release namespace is available from the `/api/v1/app/info` endpoint in the `currentRelease.helmReleaseNamespace` * `RELEASE_NAME`: The release name is available from the `/api/v1/app/info` endpoint in the `currentRelease.helmReleaseName` field. * `HELM_CHART_URL`: The URL of the Helm chart at the OCI registry is available from the `/api/v1/app/info` endpoint in the `helmChartURL` field. ### Automate Support Bundle Collection and Upload You can use the support bundle SDK API endpoints to build an automated support workflow directly into your application. This lets your application attach structured metadata to support bundles, upload them programmatically, and enable your team to receive and process them without requiring customers to manually transfer files. For more information about enabling direct bundle uploads, see [Enable Support Bundle Uploads](/vendor/support-enabling-direct-bundle-uploads). To automate support bundle collection and upload from your application: 1. From your application, use the `PATCH /api/v1/supportbundle/metadata` endpoint to attach contextual metadata before a bundle is generated. This metadata is included in the bundle automatically when you use the `supportBundleMetadata` collector in your support bundle spec. For more information about this collector, see [Support Bundle Metadata](https://troubleshoot.sh/docs/collect/support-bundle-metadata) in the Troubleshoot documentation. ```bash curl -X PATCH replicated:3000/api/v1/supportbundle/metadata \ -H "Content-Type: application/json" \ -d '{ "data": { "severity": "error", "ticketId": "SUPPORT-1234", "environment": "production", "component": "ingestion-pipeline" } }' ``` `PATCH` merges new keys with any existing metadata. Use `POST /api/v1/supportbundle/metadata` instead if you want to replace all existing metadata. :::note Your application can call this endpoint at any time to keep metadata current. For example, you might update the `severity` or `ticketId` fields when a user opens a support request from your application's UI, so that the next bundle collected includes that context. ::: 1. After collecting a support bundle (for example, using the [support-bundle kubectl plugin](https://troubleshoot.sh/docs/support-bundle/collecting/)), use the `POST /api/v1/supportbundle` endpoint to upload it through the SDK. The bundle is streamed to Replicated and becomes available under the **Troubleshoot** tab in the Vendor Portal. ```bash curl -X POST replicated:3000/api/v1/supportbundle \ -H "Content-Type: application/gzip" \ -H "Content-Length: $(wc -c < bundle.tar.gz)" \ --data-binary @bundle.tar.gz ``` **Example response**: ```json { "bundleId": "abc123-def456", "slug": "my-app-supportbundle-abc123" } ``` The `bundleId` in the response identifies the bundle for retrieval through the Vendor API. :::note The upload endpoint requires Replicated SDK 1.17.1 or later, outbound internet access, and the `Content-Length` header. ::: 1. (Optional) To automate what happens after a bundle is uploaded, configure notification events for **Support Bundle Uploaded** or **Support Bundle Analyzed**. These events can trigger webhooks to route bundles to your support tools (such as Zendesk or ServiceNow) based on the metadata your application attached. For more information about configuring these events, see [Support Events](/reference/notifications-events-filters#support-events). 1. To retrieve bundle details and analysis results programmatically from the vendor side, use the Vendor API v3 support bundle endpoints with the `bundleId` from the upload response: ```bash curl -H "Authorization: $REPLICATED_API_TOKEN" \ "https://api.replicated.com/vendor/v3/supportbundle/$BUNDLE_ID" ``` To download the bundle file: ```bash curl -L -H "Authorization: $REPLICATED_API_TOKEN" \ "https://api.replicated.com/vendor/v3/supportbundle/$BUNDLE_ID/download" \ -o bundle.tar.gz ``` ### Revoke Access at Runtime When a License Expires You can use the Replicated SDK API `/api/v1/license/fields/{field_name}` endpoint to revoke a customer's access to your application during runtime when their license expires. To revoke access to your application when a license expires: 1. In the vendor portal, click **Customers**. Select the target customer and click the **Manage customer** tab. Alternatively, click **+ Create customer** to create a new customer. 1. Under **Expiration policy**: 1. Enable **Customer's license has an expiration date**. 1. For **When does this customer expire?**, use the calendar to set an expiration date for the license. expiration policy field in the manage customer page [View a larger version of this image](/images/customer-expiration-policy.png) 1. Install the Replicated SDK as a standalone component in your cluster. This is called _integration mode_. Installing in integration mode allows you to develop locally against the SDK API without needing to create releases for your application in the vendor portal. See [Develop Against the SDK API](/vendor/replicated-sdk-development). 1. In your application, use the `/api/v1/license/fields/expires_at` endpoint to get the `expires_at` field that you defined in the previous step. **Example:** ```bash curl replicated:3000/api/v1/license/fields/expires_at ``` ```json { "name": "expires_at", "title": "Expiration", "description": "License Expiration", "value": "2023-05-30T00:00:00Z", "valueType": "String", "signature": { "v1": "c6rsImpilJhW0eK+Kk37jeRQvBpvWgJeXK2M..." } } ``` 1. Add logic to your application to revoke access if the current date and time is more recent than the expiration date of the license. 1. (Recommended) Use signature verification in your application to ensure the integrity of the license field. See [Verify License Field Signatures with the Replicated SDK API](/vendor/licenses-verify-fields-sdk-api). --- # replicated Manage your Commercial Software Distribution Lifecycle using Replicated ### Synopsis The 'replicated' CLI allows Replicated customers (vendors) to manage their Commercial Software Distribution Lifecycle (CSDL) using the Replicated API. ### Options ``` --app string The app slug or app id to use in all calls --debug Enable debug output -h, --help help for replicated -o, --output string The output format to use. Supported formats vary by command (json, table, wide). (default 'table', override with REPLICATED_OUTPUT env var) (default "table") --profile string The authentication profile to use for this command --token string The API token to use to access your app in the Vendor API ``` ### SEE ALSO * [replicated api](replicated-cli-api) - Make ad-hoc API calls to the Replicated API * [replicated app](replicated-cli-app) - Manage applications * [replicated channel](replicated-cli-channel) - Manage channels * [replicated cluster](replicated-cli-cluster) - Manage test Kubernetes clusters. * [replicated completion](replicated-cli-completion) - Generate completion script * [replicated config](replicated-cli-config) - Manage .replicated configuration * [replicated customer](replicated-cli-customer) - Manage customers * [replicated default](replicated-cli-default) - Manage default values used by other commands * [replicated installer](replicated-cli-installer) - Manage Kubernetes installers * [replicated instance](replicated-cli-instance) - Manage instances * [replicated login](replicated-cli-login) - Log in to Replicated * [replicated logout](replicated-cli-logout) - Logout from Replicated * [replicated network](replicated-cli-network) - Manage test networks for VMs and Clusters * [replicated notification](replicated-cli-notification) - Manage event notifications * [replicated policy](replicated-cli-policy) - Manage RBAC policies * [replicated profile](replicated-cli-profile) - Manage authentication profiles * [replicated registry](replicated-cli-registry) - Manage registries * [replicated release](replicated-cli-release) - Manage app releases * [replicated version](replicated-cli-version) - Print the current version and exit * [replicated vm](replicated-cli-vm) - Manage test virtual machines. --- # About Replicated template functions This topic describes Replicated template functions, including information about use cases, template function contexts, syntax. ## Overview Replicated provides a set of custom template functions based on the Go text/template library. Common use cases for Replicated template functions include rendering values during installation or upgrade, such as: * Customer-specific license field values * User-provided configuration values * Information about the customer environment, such the number of nodes or the Kubernetes version in the cluster where the application is installed * Random strings Replicated template functions can also be used to work with integer, boolean, float, and string values, such as doing mathematical operations, trimming leading and trailing spaces, or converting string values to integers or booleans. Replicated template functions support all functionality of the Go templating language, including if statements, loops, and variables. For more information about the Go library, see [text/template](https://golang.org/pkg/text/template/) in the Go documentation. ## Supported file types You can use Replicated template functions in Kubernetes manifest files, such as: * Custom resources in the `kots.io` API group like Application, Config, or HelmChart * Custom resources in other API groups like Preflight or SupportBundle * Kubernetes objects like Deployments, Services, Secrets, or ConfigMaps * Kubernetes Operators Replicated template functions are _not_ directly supported in Helm charts. However, the HelmChart custom resource provides a way to map values rendered by Replicated template functions to Helm chart values. This allows you to use Replicated template functions with Helm charts without making changes to those Helm charts. For information about how to map values from the HelmChart custom resource to Helm chart `values.yaml` files, see [values](/reference/custom-resource-helmchart-v2#values) in _HelmChart v2_. ## Template function rendering During application installation and upgrade, Replicated templates all Kubernetes manifest files in a release at the same time during a single process. The Config custom resource is an exception. For the [Config](/reference/custom-resource-config) custom resource, Replicated templates each item separately. This allows you to use template functions in fields in the Config custom resource that render user-supplied values from other fields. For examples of this, see [Template function examples](/reference/template-functions-examples). ## Limitations * Not all fields in the Config and Application custom resources support templating. For more information, see [Application](/reference/custom-resource-application) and [Config](/reference/custom-resource-config). * The [Embedded Cluster Config](/embedded-cluster/v3/embedded-config) resource doesn't support Go templating in any fields. * Replicated template functions are not directly supported in Helm charts. For more information, see [Supported file types](#supported-file-types) on this page. * For installations with Embedded Cluster v3, the following template functions aren't supported: * HasLocalRegistry * LocalRegistryAddress * LocalRegistryHost * LocalRegistryNamespace * LocalImageName These template functions are typically used to conditionally rewrite image references in air gap installations to reference the local image registry. For Embedded Cluster v3 installations, use the ReplicatedImageName and ReplicatedImageRegistry template functions instead. For more information, see [Template Functions for Embedded Cluster](/embedded-cluster/v3/template-functions). ## Syntax {#syntax} The Replicated template function syntax supports the following functionally equivalent delimiters: * [`repl{{ ... }}`](#syntax-integer) * [`{{repl ... }}`](#syntax-string) ### Syntax requirements Replicated template function syntax has the following requirements: * For both syntax options, `repl{{ ... }}` and `{{repl ... }}`, there must be no whitespace between `repl` and the `{{` delimiter. * The manifests where you use Replicated template functions must be valid YAML, because Replicated lints the YAML manifests before rendering the template functions. ### `repl{{ ... }}` {#syntax-integer} Replicated recommends this syntax for most use cases. Replicated strips any quotation marks wrapped around this syntax during rendering. If you need the rendered value in quotes, pipe into quote (`| quote`) or use the [`{{repl ... }}`](#syntax-string) syntax instead. #### Integer example ```yaml http: port: repl{{ ConfigOption "load_balancer_port" }} ``` ```yaml http: port: 8888 ``` #### Example with `| quote` ```yaml customTag: repl{{ ConfigOption "tag" | quote }} ``` ```yaml customTag: 'key: value' ``` #### If-else example ```yaml http: port: repl{{ if ConfigOptionEquals "ingress_type" "load_balancer" }}repl{{ ConfigOption "load_balancer_port" }}repl{{ else }}8081repl{{ end }} ``` ```yaml http: port: 8081 ``` For more examples, see [Template function examples](/reference/template-functions-examples). ### `{{repl ... }}` {#syntax-string} Use this syntax when placing delimiters outside the template function improves YAML readability, such as in multi-line or if-else statements. To use this syntax at the beginning of a YAML value, you must wrap it in quotes. YAML values cannot start with `{`, and KOTS requires valid YAML manifests. When you wrap this syntax in quotes, the rendered value is also wrapped in quotes. #### Example with quotes The following example includes quotes because it appears at the beginning of a YAML value: ```yaml customTag: '{{repl ConfigOption "tag" }}' ``` ```yaml customTag: 'key: value' ``` #### If-else example ```yaml my-service: type: '{{repl if ConfigOptionEquals "ingress_type" "load_balancer" }}LoadBalancer{{repl else }}ClusterIP{{repl end }}' ``` ```yaml my-service: type: 'LoadBalancer' ``` For more examples, see [Template Function Examples](/reference/template-functions-examples). ## Contexts {#contexts} Replicated groups template functions into different contexts based on the lifecycle phase when the function is available and the data provided. ### Static context The context necessary to render the static template functions is always available. The static context also includes the Masterminds Sprig function library. For more information, see [Sprig Function Documentation](http://masterminds.github.io/sprig/) on the sprig website. For a list of all Replicated template functions available in the static context, see [Static Context](template-functions-static-context). ### Config context Template functions in the config context are available when rendering an application that includes the Replicated [Config](/reference/custom-resource-config) custom resource. This custom resource defines the app configuration screen in the Replicated installer UI. At execution time, template functions in the config context also can use the static context functions. For more information about configuring the config screen, see [About the Configuration Screen](/vendor/config-screen-about). For a list of all Replicated template functions available in the config context, see [Config Context](template-functions-config-context). ### License context Template functions in the license context have access to customer license and version data. For more information about managing customer licenses, see [About Customers and Licensing](/vendor/licenses-about). For a list of all Replicated template functions available in the license context, see [License Context](template-functions-license-context). ### kURL context :::note Replicated kURL is available only for existing customers. If you are not an existing kURL user, use Replicated Embedded Cluster instead. For more information, see [Use Embedded Cluster](/embedded-cluster/v3/embedded-overview). kURL is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: Template functions in the kURL context have access to information about applications installed with Replicated kURL. For more information about kURL, see [Introduction to kURL](/vendor/kurl-about). For a list of all Replicated template functions available in the kURL context, see [kURL Context](template-functions-kurl-context). --- # Config Context This topic provides a list of the Replicated template functions in the Config context. Template functions in the config context are available when rendering an application that includes the Replicated [Config](/reference/custom-resource-config) custom resource. This custom resource defines the app configuration screen in the Replicated installer UI. At execution time, template functions in the config context also can use the static context functions. For more information about configuring the config screen, see [About the Configuration Screen](/vendor/config-screen-about). ## ConfigOption ```go func ConfigOption(optionName string) string ``` Returns the value of the specified option from the Replicated Config custom resource as a string. For the `file` config option type, `ConfigOption` returns the base64 encoded file. To return the decoded contents of a file, use [ConfigOptionData](#configoptiondata) instead. ```yaml '{{repl ConfigOption "hostname" }}' ``` #### Example The following [HelmChart](/reference/custom-resource-helmchart-v2) custom resource uses the ConfigOption template function to set the port, node port, and annotations for a LoadBalancer service using the values supplied by the user on the config screen. These values are then mapped to the `values.yaml` file for the associated Helm chart during deployment. ```yaml # HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: chart: name: samplechart chartVersion: 3.1.7 values: myapp: service: type: LoadBalancer port: repl{{ ConfigOption "myapp_load_balancer_port"}} nodePort: repl{{ ConfigOption "myapp_load_balancer_node_port"}} annotations: repl{{ ConfigOption `myapp_load_balancer_annotations` | nindent 14 }} ``` For more information, see [values](/reference/custom-resource-helmchart-v2#values) in _HelmChart v2_. ## ConfigOptionData ```go func ConfigOptionData(optionName string) string ``` For the `file` config option type, `ConfigOptionData` returns the base64 decoded contents of the file. To return the base64 encoded file, use [ConfigOption](#configoption) instead. ```yaml '{{repl ConfigOptionData "ssl_key"}}' ``` #### Example The following [HelmChart](/reference/custom-resource-helmchart-v2) custom resource uses the ConfigOptionData template function to set the TLS cert and key using the files supplied by the user on the config screen. These values are then mapped to the `values.yaml` file for the associated Helm chart during deployment. ```yaml # HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: chart: name: samplechart chartVersion: 3.1.7 values: myapp: tls: enabled: true genSelfSignedCert: repl{{ ConfigOptionEquals "myapp_ingress_tls_type" "self_signed" }} cert: repl{{ print `|`}}repl{{ ConfigOptionData `tls_certificate_file` | nindent 12 }} key: repl{{ print `|`}}repl{{ ConfigOptionData `tls_private_key_file` | nindent 12 }} ``` For more information, see [values](/reference/custom-resource-helmchart-v2#values) in _HelmChart v2_. ## ConfigOptionFilename ```go func ConfigOptionFilename(optionName string) string ``` `ConfigOptionFilename` returns the filename associated with a `file` config option. It will return an empty string if used erroneously with other types. ```yaml '{{repl ConfigOptionFilename "pom_file"}}' ``` #### Example For example, if you have the following Config defined: ```yaml apiVersion: kots.io/v1beta1 kind: Config metadata: name: my-application spec: groups: - name: java_settings title: Java Settings description: Configures the Java Server build parameters items: - name: pom_file type: file required: true ``` The following example shows how to use `ConfigOptionFilename` in a Pod Spec to mount a file: ```yaml apiVersion: v1 kind: Pod metadata: name: configmap-demo-pod spec: containers: - name: some-java-app image: busybox command: ["bash"] args: - "-C" - "cat /config/{{repl ConfigOptionFilename pom_file}}" volumeMounts: - name: config mountPath: "/config" readOnly: true volumes: - name: config configMap: name: demo-configmap items: - key: data_key_one path: repl{{ ConfigOptionFilename pom_file }} --- apiVersion: v1 kind: ConfigMap metadata: name: demo-configmap data: data_key_one: repl{{ ConfigOptionData pom_file }} ``` ## ConfigOptionEquals ```go func ConfigOptionEquals(optionName string, expectedValue string) bool ``` Returns true if the configuration option value is equal to the supplied value. ```yaml '{{repl ConfigOptionEquals "http_enabled" "1" }}' ``` #### Example The following [HelmChart](/reference/custom-resource-helmchart-v2) custom resource uses the ConfigOptionEquals template function to set the `postgres.enabled` value depending on if the user selected the `embedded_postgres` option on the config screen. This value is then mapped to the `values.yaml` file for the associated Helm chart during deployment. ```yaml # HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: chart: name: samplechart chartVersion: 3.1.7 values: postgresql: enabled: repl{{ ConfigOptionEquals `postgres_type` `embedded_postgres`}} ``` For more information, see [values](/reference/custom-resource-helmchart-v2#values) in _HelmChart v2_. ## ConfigOptionNotEquals ```go func ConfigOptionNotEquals(optionName string, expectedValue string) bool ``` Returns true if the configuration option value is not equal to the supplied value. ```yaml '{{repl ConfigOptionNotEquals "http_enabled" "1" }}' ``` ## LocalRegistryAddress :::note The LocalRegistryAddress template function is not supported for installations with Embedded Cluster v3. See [Template Functions for Embedded Cluster (Beta)](/embedded-cluster/v3/template-functions). ::: ```go func LocalRegistryAddress() string ``` Returns the local registry host or host/namespace that's configured. This will always return everything before the image name and tag. ## LocalRegistryHost :::note The LocalRegistryHost template function is not supported for installations with Embedded Cluster v3. See [Template Functions for Embedded Cluster (Beta)](/embedded-cluster/v3/template-functions). ::: ```go func LocalRegistryHost() string ``` Returns the host of the local registry that the user configured. Alternatively, for air gap installations with Replicated Embedded Cluster or Replicated kURL, LocalRegistryHost returns the host of the built-in registry. Includes the port if one is specified. #### Example The following [HelmChart](/reference/custom-resource-helmchart-v2) custom resource uses the HasLocalRegistry, LocalRegistryHost, and LocalRegistryNamespace template functions to conditionally rewrite an image registry and repository depending on if a local registry is used. These values are then mapped to the `values.yaml` file for the associated Helm chart during deployment. ```yaml # HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: chart: name: samplechart chartVersion: 3.1.7 values: myapp: image: registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "images.mycompany.com" }}' repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/myapp/quay.io/my-org" }}/nginx' tag: v1.0.1 ``` For more information, see [values](/reference/custom-resource-helmchart-v2#values) in _HelmChart v2_. ## LocalRegistryNamespace :::note The LocalRegistryNamespace template function is not supported for installations with Embedded Cluster v3. See [Template Functions for Embedded Cluster (Beta)](/embedded-cluster/v3/template-functions). ::: ```go func LocalRegistryNamespace() string ``` Returns the namespace of the local registry that the user configured. Alternatively, for air gap installations with Embedded Cluster or kURL, LocalRegistryNamespace returns the namespace of the built-in registry. #### Example The following [HelmChart](/reference/custom-resource-helmchart-v2) custom resource uses the HasLocalRegistry, LocalRegistryHost, and LocalRegistryNamespace template functions to conditionally rewrite an image registry and repository depending on if a local registry is used. These values are then mapped to the `values.yaml` file for the associated Helm chart during deployment. ```yaml # HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: chart: name: samplechart chartVersion: 3.1.7 values: myapp: image: registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "images.mycompany.com" }}' repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/myapp/quay.io/my-org" }}/nginx' tag: v1.0.1 ``` For more information, see [values](/reference/custom-resource-helmchart-v2#values) in _HelmChart v2_. ## LocalImageName :::note The LocalImageName template function is not supported for installations with Embedded Cluster v3. See [Template Functions for Embedded Cluster (Beta)](/embedded-cluster/v3/template-functions). ::: ```go func LocalImageName(remoteImageName string) string ``` Given a `remoteImageName`, rewrite the `remoteImageName` so that it can be pulled to local hosts. A common use case for the `LocalImageName` function is to ensure that a Kubernetes Operator can determine the names of container images on Pods created at runtime. For more information, see [Reference Images](/vendor/operator-referencing-images) in the _Packaging a Kubernetes Operator Application_ section. `LocalImageName` rewrites the `remoteImageName` in one of the following ways, depending on if a private registry is configured and if the image must be proxied: * If there is a private registry configured in the customer's environment, such as in air gapped environments, rewrite `remoteImageName` to reference the private registry locally. For example, rewrite `elasticsearch:7.6.0` as `registry.somebigbank.com/my-app/elasticsearch:7.6.0`. * If there is no private registry configured in the customer's environment, but the image must be proxied, rewrite `remoteImageName` so that the image can be pulled through the proxy registry. For example, rewrite `"quay.io/orgname/private-image:v1.2.3"` as `proxy.replicated.com/proxy/app-name/quay.io/orgname/private-image:v1.2.3`. * If there is no private registry configured in the customer's environment and the image does not need to be proxied, return `remoteImageName` without changes. For more information about the Replicated proxy registry, see [About the Proxy Registry](/vendor/private-images-about). ## LocalRegistryImagePullSecret ```go func LocalRegistryImagePullSecret() string ``` Returns the base64 encoded local registry image pull secret value. This is often needed when an operator is deploying images to a namespace that is not managed by the Replicated installer. Image pull secrets must be present in the namespace of the pod. #### Example ```yaml apiVersion: v1 kind: Secret metadata: name: my-image-pull-secret namespace: my-namespace type: kubernetes.io/dockerconfigjson data: .dockerconfigjson: '{{repl LocalRegistryImagePullSecret }}' --- apiVersion: v1 kind: Pod metadata: name: dynamic-pod namespace: my-namespace spec: containers: - image: '{{repl LocalImageName "registry.replicated.com/my-app/my-image:abcdef" }}' name: my-container imagePullSecrets: - name: my-image-pull-secret ``` ## ImagePullSecretName ```go func ImagePullSecretName() string ``` Returns the name of the image pull secret that can be added to pod specs that use private images. The secret will be automatically created in all application namespaces. It will contain authentication information for any private registry used with the application. #### Example ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: my-deployment spec: template: spec: imagePullSecrets: - name: repl{{ ImagePullSecretName }} ``` ## HasLocalRegistry :::note The HasLocalRegistry template function is not supported for installations with Embedded Cluster v3. See [Template Functions for Embedded Cluster (Beta)](/embedded-cluster/v3/template-functions). ::: ```go func HasLocalRegistry() bool ``` Returns true if the environment is configured to rewrite images to a local registry. HasLocalRegistry is always true for air gap installations. HasLocalRegistry is true in online installations if the user pushed images to a local registry. #### Example The following [HelmChart](/reference/custom-resource-helmchart-v2) custom resource uses the HasLocalRegistry, LocalRegistryHost, and LocalRegistryNamespace template functions to conditionally rewrite an image registry and repository depending on if a local registry is used. These values are then mapped to the `values.yaml` file for the associated Helm chart during deployment. ```yaml # HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: chart: name: samplechart chartVersion: 3.1.7 values: myapp: image: registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "images.mycompany.com" }}' repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/myapp/quay.io/my-org" }}/nginx' tag: v1.0.1 ``` For more information, see [values](/reference/custom-resource-helmchart-v2#values) in _HelmChart v2_. --- # Template function examples This topic provides examples of how to use Replicated template functions in various common use cases. For more information about working with Replicated template functions, including the supported syntax and the types of files that support Replicated template functions, see [About Replicated Template Functions](template-functions-about). ## Overview Replicated template functions are based on the Go text/template library. All functionality of the Go templating language, including if statements, loops, and variables, is supported with Replicated template functions. For more information, see [text/template](https://golang.org/pkg/text/template/) in the Go documentation. Additionally, Replicated template functions can be used with all functions in the Sprig library. Sprig provides several template functions for the Go templating language, such as type conversion, string, and integer math functions. For more information, see [Sprig Function Documentation](https://masterminds.github.io/sprig/). Common use cases for Replicated template functions include rendering values during installation or upgrade, such as: * Customer-specific license field values * User-provided configuration values * Information about the customer environment, such the number of nodes or the Kubernetes version in the cluster where the application is installed * Random strings Replicated template functions can also be used to work with integer, boolean, float, and string values, such as doing mathematical operations, trimming leading and trailing spaces, or converting string values to integers or booleans. For examples demonstrating these use cases and more, see the following sections. ## Comparison examples This section includes examples of how to use Replicated template functions to compare different types of data. ### Boolean comparison Use boolean values in comparisons to evaluate if a given statement is true or false. Because many Replicated template functions return string values, comparing boolean values often requires using the Replicated [ParseBool](/reference/template-functions-static-context#parsebool) template function to return the boolean represented by the string. One common use case for working with boolean values is to check that a given field is present in the customer's license. For example, you might need to show a configuration option only when the customer's license includes a certain entitlement. The following example creates a conditional statement in the Replicated Config custom resource. The statement evaluates to true when a specified license field is present in the customer's license _and_ the customer enables a specified configuration option. ```yaml # Replicated Config custom resource apiVersion: kots.io/v1beta1 kind: Config metadata: name: config-sample spec: groups: - name: example_group title: Example Config items: - name: radio_example title: Select One type: radio items: - name: option_one title: Option One - name: option_two title: Option Two - name: conditional_item title: Conditional Item type: text # Display this item only when the customer enables the option_one config field *and* # has the feature-1 entitlement in their license when: repl{{ and (LicenseFieldValue "feature-1" | ParseBool) (ConfigOptionEquals "radio_example" "option_one")}} ``` This example uses the following Replicated template functions: * [LicenseFieldValue](/reference/template-functions-license-context#licensefieldvalue) to return the string value of a boolean type license field named `feature-1` :::note The LicenseFieldValue template function always returns a string, regardless of the license field type. ::: * [ParseBool](/reference/template-functions-static-context#parsebool) to convert the string returned by the LicenseFieldValue template function to a boolean * [ConfigOptionEquals](/reference/template-functions-config-context#configoptionequals) to return a boolean that evaluates to true if the configuration option value is equal to the supplied value ### Integer comparison You can compare integer values using operators such as greater than, less than, equal to, and so on. Because many Replicated template functions return string values, you might need another function to return the integer represented by the string, such as: * Replicated [ParseInt](/reference/template-functions-static-context#parseint), which returns the integer value represented by the string with the option to provide a `base` other than 10 * Sprig [atoi](https://masterminds.github.io/sprig/conversion.html), which is equivalent to ParseInt(s, 10, 0), converted to type integer A common use case for comparing integer values is to display different configuration options depending on values from the customer's license. For example, licenses might include an entitlement that defines the number of seats available to the customer. In this case, you can conditionally display or hide certain fields on the configuration screen depending on the customer's team size. The following example uses: * Replicated [LicenseFieldValue](/reference/template-functions-license-context#licensefieldvalue) template function to evaluate the number of seats permitted by the license * Sprig [atoi](https://masterminds.github.io/sprig/conversion.html) function to convert the string values returned by LicenseFieldValue to integers * [Go binary comparison operators](https://pkg.go.dev/text/template#hdr-Functions) `gt`, `lt`, `ge`, and `le` to compare the integers ```yaml # Replicated Config custom resource apiVersion: kots.io/v1beta1 kind: Config metadata: name: config-sample spec: groups: - name: example_group title: Example Config items: - name: small title: Small (100 or Fewer Seats) type: text default: Default for small teams # Use le and atoi functions to display this config item # only when the value of the numSeats entitlement is # less than or equal to 100 when: repl{{ le (atoi (LicenseFieldValue "numSeats")) 100 }} - name: medium title: Medium (101-1000 Seats) type: text default: Default for medium teams # Use ge, le, and atoi functions to display this config item # only when the value of the numSeats entitlement is # greater than or equal to 101 and less than or equal to 1000 when: repl{{ (and (ge (atoi (LicenseFieldValue "numSeats")) 101) (le (atoi (LicenseFieldValue "numSeats")) 1000)) }} - name: large title: Large (More Than 1000 Seats) type: text default: Default for large teams # Use gt and atoi functions to display this config item # only when the value of the numSeats entitlement is # greater than 1000 when: repl{{ gt (atoi (LicenseFieldValue "numSeats")) 1000 }} ``` As shown in the image below, if the user's license contains `numSeats: 150`, then the `medium` item is displayed on the **Config** page and the `small` and `large` items are not displayed: Config page displaying the Medium (101-1000 Seats) item [View a larger version of this image](/images/config-example-numseats.png) ### String comparison A common use case for string comparison is to compare the rendered value of a Replicated template function against a string. You can use this to conditionally show or hide fields based on details about the customer's environment. For example, use a string comparison to check the Kubernetes distribution of the cluster where the application runs. The following example uses: * Replicated [Distribution](/reference/template-functions-static-context#distribution) template function to return the Kubernetes distribution of the cluster * [eq](https://pkg.go.dev/text/template#hdr-Functions) (_equal_) Go binary operator to compare the rendered value of the Distribution template function to a string, then return the boolean truth of the comparison ```yaml # Replicated Config custom resource apiVersion: kots.io/v1beta1 kind: Config metadata: name: config-sample spec: groups: - name: example_settings title: My Example Config description: Example fields for using Distribution template function items: - name: gke_distribution type: label title: "You are deploying to GKE" # Use the eq binary operator to check if the rendered value # of the Distribution template function is equal to gke when: repl{{ eq Distribution "gke" }} - name: openshift_distribution type: label title: "You are deploying to OpenShift" when: repl{{ eq Distribution "openShift" }} - name: eks_distribution type: label title: "You are deploying to EKS" when: repl{{ eq Distribution "eks" }} ... ``` The following image shows how only the `gke_distribution` item appears on the app configuration screen: Config page with the text You are deploying to GKE ### Not equal to comparison It can be useful to compare the rendered value of a Replicated template function against another value to check if the two values are different. For example, you can conditionally show certain fields only when the Kubernetes distribution of the cluster where the application runs is _not_ [Replicated Embedded Cluster](/embedded-cluster/v3/embedded-overview). In the following example, the `ingress_type` field appears on the configuration page only when the distribution of the cluster is _not_ [Replicated Embedded Cluster](/embedded-cluster/v3/embedded-overview). This ensures that only users deploying to their own existing cluster are able to select the method for ingress. The following example uses: * Replicated [Distribution](/reference/template-functions-static-context#distribution) template function to return the Kubernetes distribution of the cluster * [ne](https://pkg.go.dev/text/template#hdr-Functions) (_not equal_) Go binary operator to compare the rendered value of the Distribution template function to a string, then return `true` if the values are not equal to one another ```yaml apiVersion: kots.io/v1beta1 kind: Config metadata: name: config spec: groups: # Ingress settings - name: ingress_settings title: Ingress Settings description: Configure Ingress items: - name: ingress_type title: Ingress Type help_text: | Select how traffic will ingress to the appliction. type: radio items: - name: ingress_controller title: Ingress Controller - name: load_balancer title: Load Balancer default: "ingress_controller" required: true when: 'repl{{ ne Distribution "embedded-cluster" }}' # Database settings - name: database_settings title: Database items: - name: postgres_type help_text: Would you like to use an embedded postgres instance, or connect to an external instance that you manage? type: radio title: Postgres default: embedded_postgres items: - name: embedded_postgres title: Embedded Postgres - name: external_postgres title: External Postgres ``` The following image shows how the `ingress_type` field does not appear when the distribution of the cluster is `embedded-cluster`. Only the `postgres_type` item appears: Config page with a Postgres field [View a larger version of this image](/images/config-example-distribution-not-ec.png) Conversely, when the distribution of the cluster is not `embedded-cluster`, both fields appear: Config page with Ingress and Postgres fields [View a larger version of this image](/images/config-example-distribution-not-ec-2.png) ### Logical AND comparison Logical comparisons such as AND, OR, and NOT work with Replicated template functions. A common use case for logical AND comparisons is to construct more complex conditional statements where two different conditions must both be true. The following example shows how to use an `and` operator that evaluates to true when two different configuration options are both enabled. This example uses the Replicated [ConfigOptionEquals](/reference/template-functions-config-context#configoptionequals) template function to return a boolean that evaluates to true if the configuration option value is equal to the supplied value. ```yaml # Replicated Config custom resource apiVersion: kots.io/v1beta1 kind: Config metadata: name: config-sample spec: groups: - name: example_group title: Example Config items: - name: radio_example title: Select One Example type: radio items: - name: option_one title: Option One - name: option_two title: Option Two - name: boolean_example title: Boolean Example type: bool default: "0" - name: conditional_item title: Conditional Item type: text # Display this item only when *both* specified config options are enabled when: repl{{ and (ConfigOptionEquals "radio_example" "option_one") (ConfigOptionEquals "boolean_example" "1")}} ``` As shown in the following image, when the user selects both `Option One` and `Boolean Example`, the conditional statement evaluates to true and the `Conditional Item` field appears: Conditional item displayed [View a larger version of this image](/images/conditional-item-true.png) Alternatively, if either `Option One` or `Boolean Example` is not selected, then the conditional statement evaluates to false and the `Conditional Item` field is not displayed: Option two selected [View a larger version of this image](/images/conditional-item-false-option-two.png) Boolean field deselected [View a larger version of this image](/images/conditional-item-false-boolean.png) ## Conditional statement examples This section includes examples of using Replicated template functions to construct conditional statements. Use conditional statements with Replicated template functions to render different values depending on a given condition. ### If-else statements A common use case for if-else statements is to conditionally set values for application resources or objects, such as custom annotations or service types. :::note For more complex or nested if-else statements, use templating in your Helm chart `templates` instead of in the Replicated HelmChart custom resource. For more information, see [If/Else](https://helm.sh/docs/chart_template_guide/control_structures/#ifelse) in the Helm documentation. ::: For most use cases, use single-line formatting for if-else statements. Multi-line formatting can be useful to improve the readability of YAML files for longer or more complex if-else statements. You can construct multi-line if-else statements using YAML block scalars and block chomping characters to ensure the rendered result is valid YAML: * Use the greater than (`>`) character for a _folded_ block scalar style. With the folded style, Go treats single line breaks in the string as a space. * Use the block chomping minus (`-`) character to remove all the line breaks at the end of a string. For more information about working with these characters, see [Block Style Productions](https://yaml.org/spec/1.2.2/#chapter-8-block-style-productions) in the YAML documentation. The following example shows if-else statements in the Replicated HelmChart custom resource `values` field. The statements render different values depending on whether the user selects a load balancer or an ingress controller as the ingress type. This example uses the Replicated [ConfigOptionEquals](/reference/template-functions-config-context#configoptionequals) template function to return a boolean that evaluates to true if the configuration option value is equal to the supplied value. ```yaml # Replicated HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: my-app spec: chart: name: my-app chartVersion: 0.23.0 values: services: my-service: enabled: true appName: ["my-app"] # Render the service type based on the user's selection # '{{repl ...}}' syntax is used for `type` to improve readability of the if-else statement and render a string type: '{{repl if ConfigOptionEquals "ingress_type" "load_balancer" }}LoadBalancer{{repl else }}ClusterIP{{repl end }}' ports: http: enabled: true # Render the HTTP port for the service depending on the user's selection # repl{{ ... }} syntax is used for `port` to render an integer value port: repl{{ if ConfigOptionEquals "ingress_type" "load_balancer" }}repl{{ ConfigOption "load_balancer_port" }}repl{{ else }}8081repl{{ end }} protocol: HTTP targetPort: 8081 ``` ### Ternary operators Ternary operators are useful for templating strings where certain values must render differently based on a condition. They work best when you need to render a small portion of a string conditionally, rather than choosing between entirely different values. For example, you could use ternary operators to template the path to an image repository based on user-supplied values. The following example uses ternary operators to render the registry and repository for a private nginx image. The rendered value depends on whether the customer uses a local image registry. This example uses the following Replicated template functions: * [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry) to return true if the environment rewrites images to a local registry * [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost) to return the local registry host configured by the user * [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) to return the local registry namespace configured by the user ```yaml # Replicated HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: samplechart spec: values: image: # If a local registry is configured, use the local registry host. # Otherwise, use proxy.replicated.com registry: repl{{ HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }} # If a local registry is configured, use the local registry's namespace. # Otherwise, use proxy/my-app/quay.io/my-org repository: repl{{ HasLocalRegistry | ternary LocalRegistryNamespace "proxy/my-app/quay.io/my-org" }}/nginx tag: v1.0.1 ``` ## Formatting examples This section includes examples of how to format the rendered output of Replicated template functions. In addition to the examples in this section, Replicated template functions in the Static context include several formatting options. These include converting strings to upper or lower case and trimming leading and trailing space characters. For more information, see [Static Context](/reference/template-functions-static-context). ### Indentation When using template functions within nested YAML, indent the rendered template functions correctly so that the YAML renders. A common use case for indentation is templating annotations in resource or object metadata based on user-supplied values. The [nindent](https://masterminds.github.io/sprig/strings.html) function adds a new line to the beginning of the string and indents the string by a specified number of spaces. The following example shows templating a Helm chart value that sets annotations for an Ingress object. This example uses the Replicated [ConfigOption](/reference/template-functions-config-context#configoption) template function to return user-supplied annotations from the configuration screen in the Replicated installer UI. It also uses [nindent](https://masterminds.github.io/sprig/strings.html) to indent the rendered value ten spaces. ```yaml # Replicated HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: myapp spec: values: services: myservice: annotations: repl{{ ConfigOption "additional_annotations" | nindent 10 }} ``` ### Render quoted values To wrap a rendered value in quotes, you can pipe the result from Replicated template functions with the `repl{{ ... }}` syntax into quotes using `| quote`. Or, you can use the `'{{repl ... }}'` syntax instead. One use case for quoted values in YAML is when values include indicator characters. In YAML, indicator characters (`-`, `?`, `:`) have special semantics and require escaping when used in values. For more information, see [Indicator Charactors](https://yaml.org/spec/1.2.2/#53-indicator-characters) in the YAML documentation. #### Example with `'{{repl ... }}'` syntax ```yaml customTag: '{{repl ConfigOption "tag" }}' ``` #### Example with `| quote` ```yaml customTag: repl{{ ConfigOption "tag" | quote }} ``` The result for both examples is: ```yaml customTag: 'key: value' ``` ## Variables example This section includes an example of using variables with Replicated template functions. For more information, see [Variables](https://pkg.go.dev/text/template#hdr-Variables) in the Go documentation. ### Using variables to generate TLS certificates in JSON You can use the Sprig [genCA](https://masterminds.github.io/sprig/crypto.html) and [genSignedCert](https://masterminds.github.io/sprig/crypto.html) functions with Replicated template functions to generate certificate authorities (CAs) and signed certificates in JSON. One use case for this is to generate default CAs, certificates, and keys that users can override with their own values. The Sprig [genCA](https://masterminds.github.io/sprig/crypto.html) and [genSignedCert](https://masterminds.github.io/sprig/crypto.html) functions require the subject's common name and the certificate's validity duration in days. The `genSignedCert` function also requires the CA that will sign the certificate. You can use variables and Replicated template functions to provide the necessary parameters when calling these functions. The following example shows how to use variables and Replicated template functions in the `default` property of a [`hidden`](/reference/custom-resource-config#hidden) item. The example passes parameters to the `genCA` and `genSignedCert` functions to generate a CA, certificate, and key. It uses a `hidden` item (not displayed on the configuration screen) to generate the certificate chain. In the Replicated Config custom resource, you can only access variables from the same item where you declared them. For this reason, `hidden` items are useful for evaluating complex templates. This example uses the following: * Replicated [ConfigOption](/reference/template-functions-config-context#configoption) template function to render the user-supplied value for the ingress hostname. Pass this as a parameter to the [genCA](https://masterminds.github.io/sprig/crypto.html) and [genSignedCert](https://masterminds.github.io/sprig/crypto.html) functions * Sprig [genCA](https://masterminds.github.io/sprig/crypto.html) and [genSignedCert](https://masterminds.github.io/sprig/crypto.html) functions to generate a CA and a certificate signed by the CA * Sprig [dict](https://masterminds.github.io/sprig/dicts.html), [set](https://masterminds.github.io/sprig/dicts.html), and [dig](https://masterminds.github.io/sprig/dicts.html) dictionary functions to create a dictionary with entries for both the CA and the certificate, then traverse the dictionary to return the values of the CA, certificate, and key. * [toJson](https://masterminds.github.io/sprig/defaults.html) and [fromJson](https://masterminds.github.io/sprig/defaults.html) Sprig functions to encode the CA and certificate into a JSON string, then decode the JSON for the purpose of displaying the values on the configuration screen as defaults :::important Replicated treats default values as ephemeral. Replicated recalculates the following certificate chain each time you modify the application configuration. Before using this example with your application, be sure that your application can handle updating these parameters dynamically. ::: ```yaml apiVersion: kots.io/v1beta1 kind: Config metadata: name: config-sample spec: groups: - name: example_settings title: My Example Config items: - name: ingress_hostname title: Ingress Hostname help_text: Enter a DNS hostname to use as the cert's CN. type: text - name: tls_json title: TLS JSON type: textarea hidden: true default: |- repl{{ $ca := genCA (ConfigOption "ingress_hostname") 365 }} repl{{ $tls := dict "ca" $ca }} repl{{ $cert := genSignedCert (ConfigOption "ingress_hostname") (list ) (list (ConfigOption "ingress_hostname")) 365 $ca }} repl{{ $_ := set $tls "cert" $cert }} repl{{ toJson $tls }} - name: tls_ca title: Signing Authority type: textarea default: repl{{ fromJson (ConfigOption "tls_json") | dig "ca" "Cert" "" }} - name: tls_cert title: TLS Cert type: textarea default: repl{{ fromJson (ConfigOption "tls_json") | dig "cert" "Cert" "" }} - name: tls_key title: TLS Key type: textarea default: repl{{ fromJson (ConfigOption "tls_json") | dig "cert" "Key" "" }} ``` The following image shows how the default values for the CA, certificate, and key appear on the configuration screen: Default values for CA, certificate, and key on the Config page [View a larger version of this image](/images/certificate-chain-default-values.png) --- # kURL Context This topic provides a list of the Replicated template functions in the kURL context. :::note Replicated kURL is available only for existing customers. If you are not an existing kURL user, use Replicated Embedded Cluster instead. For more information, see [Use Embedded Cluster](/embedded-cluster/v3/embedded-overview). kURL is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview Template functions in the kURL context have access to information about applications installed with Replicated kURL. For more information about kURL, see [Introduction to kURL](/vendor/kurl-about). The creation of the kURL Installer custom resource will reflect both install script changes made by posting YAML to the kURL API and changes made with -s flags at runtime. These functions are not available on the KOTS Admin Console config page. KurlBool, KurlInt, KurlString, and KurlOption all take a string yamlPath as a param. This is the path from the manifest file, and is delineated between add-on and subfield by a period ’.’. For example, the kURL Kubernetes version can be accessed as `{{repl KurlString "Kubernetes.Version" }}`. KurlBool, KurlInt, KurlString respectively return a bool, integer, and string value. If used on a valid field but with the wrong type these will return the falsy value for their type, false, 0, and “string respectively. The `KurlOption` function will convert all bool, int, and string fields to string. All functions will return falsy values if there is nothing at the yamlPath specified, or if these functions are run in a cluster with no installer custom resource (as in, not a cluster created by kURL). ## KurlBool ```go func KurlBool(yamlPath string) bool ``` Returns the value at the yamlPath if there is a valid boolean there, or false if there is not. ```yaml '{{repl KurlBool "Docker.NoCEonEE" }}' ``` ## KurlInt ```go func KurlInt(yamlPath string) int ``` Returns the value at the yamlPath if there is a valid integer there, or 0 if there is not. ```yaml '{{repl KurlInt "Rook.CephReplicaCount" }}' ``` ## KurlString ```go func KurlString(yamlPath string) string ``` Returns the value at the yamlPath if there is a valid string there, or "" if there is not. ```yaml '{{repl KurlString "Kubernetes.Version" }}' ``` ## KurlOption ```go func KurlOption(yamlPath string) string ``` Returns the value at the yamlPath if there is a valid string, int, or bool value there, or "" if there is not. Int and Bool values will be converted to string values. ```yaml '{{repl KurlOption "Rook.CephReplicaCount" }}' ``` ## KurlAll ```go func KurlAll() string ``` Returns all values in the Installer custom resource as key:value pairs, sorted by key. ```yaml '{{repl KurlAll }}' ``` --- # License Context This topic provides a list of the Replicated template functions in the License context. Template functions in the license context have access to customer license and version data. For more information about managing customer licenses, see [About Customers and Licensing](/vendor/licenses-about). ## LicenseFieldValue ```go func LicenseFieldValue(name string) string ``` LicenseFieldValue returns the value of the specified license field. LicenseFieldValue accepts custom license fields and all built-in license fields. For a list of all built-in fields, see [Built-In License Fields](/vendor/licenses-using-builtin-fields). LicenseFieldValue always returns a string, regardless of the license field type. To return integer or boolean values, you need to use the [ParseInt](/reference/template-functions-static-context#parseint) or [ParseBool](/reference/template-functions-static-context#parsebool) template function to convert the string value. #### String License Field The following example returns the value of the built-in `customerName` license field: ```yaml customerName: '{{repl LicenseFieldValue "customerName" }}' ``` #### Integer License Field The following example returns the value of a custom integer license field named `numSeats`: ```yaml numSeats: repl{{ LicenseFieldValue "numSeats" | ParseInt }} ``` This example uses [ParseInt](/reference/template-functions-static-context#parseint) to convert the returned value to an integer. #### Boolean License Field The following example returns the value of a custom boolean license field named `feature-1`: ```yaml feature-1: repl{{ LicenseFieldValue "feature-1" | ParseBool }} ``` This example uses [ParseBool](/reference/template-functions-static-context#parsebool) to convert the returned value to a boolean. ## LicenseDockerCfg ```go func LicenseDockerCfg() string ``` LicenseDockerCfg returns a value that can be written to a secret if needed to deploy manually. Replicated KOTS creates and injects this secret automatically in normal conditions, but some deployments (with static, additional namespaces) may need to include this. ```yaml apiVersion: v1 kind: Secret type: kubernetes.io/dockerconfigjson metadata: name: myapp-registry namespace: my-other-namespace data: .dockerconfigjson: repl{{ LicenseDockerCfg }} ``` ## Sequence ```go func Sequence() int64 ``` Sequence is the sequence of the application deployed. This will start at 0 for each installation, and increase with every app update, config change, license update and registry setting change. ```yaml '{{repl Sequence }}' ``` ## Cursor ```go func Cursor() string ``` Cursor is the channel sequence of the app. For instance, if 5 releases have been promoted to the channel that the app is running, then this would return the string `5`. ```yaml '{{repl Cursor }}' ``` ## ChannelName ```go func ChannelName() string ``` ChannelName is the name of the deployed channel of the app. ```yaml '{{repl ChannelName }}' ``` ## VersionLabel ```go func VersionLabel() string ``` VersionLabel is the semantic version of the app, as specified when promoting a release to a channel. ```yaml '{{repl VersionLabel }}' ``` ## ReleaseNotes ```go func ReleaseNotes() string ``` ReleaseNotes is the release notes of the current version of the app. ```yaml '{{repl ReleaseNotes }}' ``` ## IsAirgap ```go func IsAirgap() bool ``` IsAirgap is `true` when the app is installed via uploading an airgap package, false otherwise. ```yaml '{{repl IsAirgap }}' ``` --- # Static Context This topic provides a list of the Replicated template functions in the Static context. The context necessary to render the static template functions is always available. The static context also includes the Masterminds Sprig function library. For more information, see [Sprig Function Documentation](http://masterminds.github.io/sprig/) on the sprig website. ## Certificate Functions ### PrivateCACert >Introduced in KOTS v1.117.0 ```go func PrivateCACert() string ``` PrivateCACert returns the name of a ConfigMap containing one or more private CA certificates. PrivateCACert returns the name of the ConfigMap even if the ConfigMap has no entries. If no ConfigMap exists, PrivateCACert returns the empty string. The Replicated installer (Embedded Cluster or KOTS) mounts the ConfigMap returned by the PrivateCACert template function as a volume. It then uses the private CA from the host when making outbound network requests. For KOTS installations in existing clusters, the end user can also optionally create and pass the ConfigMap to the `install` command using the `--private-ca-configmap` flag. For more information, see [install](/reference/kots-cli-install). You can use the PrivateCACert template function to ensure the Replicated installer trusts private CA certificates from TLS man-in-the-middle proxies in the end user's environment. You can use also the PrivateCACert template function to mount the ConfigMap in your own application container. ## Cluster Information Functions ### Distribution ```go func Distribution() string ``` Distribution returns the Kubernetes distribution detected. The possible return values are: * aks * digitalOcean * dockerDesktop * eks * embedded-cluster * gke * ibm * k0s * k3s * kind * kurl * microk8s * minikube * oke * openShift * rke2 :::note [IsKurl](#iskurl) can also be used to detect kURL instances. ::: #### Detect the Distribution ```yaml repl{{ Distribution }} ``` #### Equal To Comparison ```yaml repl{{ eq Distribution "gke" }} ``` #### Not Equal To Comparison ```yaml repl{{ ne Distribution "embedded-cluster" }} ``` See [Functions](https://pkg.go.dev/text/template#hdr-Functions) in the Go documentation. ### IsKurl ```go func IsKurl() bool ``` IsKurl returns true if running within a kurl-based installation. #### Detect kURL Installations ```yaml repl{{ IsKurl }} ``` #### Detect Non-kURL Installations ```yaml repl{{ not IsKurl }} ``` See [Functions](https://pkg.go.dev/text/template#hdr-Functions) in the Go documentation. ### KotsVersion ```go func KotsVersion() string ``` KotsVersion returns the current version of KOTS. ```yaml repl{{ KotsVersion }} ``` You can compare the KOTS version as follows: ```yaml repl{{KotsVersion | semverCompare ">= 1.19"}} ``` This returns `true` if the KOTS version is greater than or equal to `1.19`. For more complex comparisons, see [Semantic Version Functions](https://masterminds.github.io/sprig/semver.html) in the sprig documentation. ### KubernetesMajorVersion > Introduced in KOTS v1.92.0 ```go func KubernetesMajorVersion() string ``` KubernetesMajorVersion returns the Kubernetes server *major* version. ```yaml repl{{ KubernetesMajorVersion }} ``` You can compare the Kubernetes major version as follows: ```yaml repl{{lt (KubernetesMajorVersion | ParseInt) 2 }} ``` This returns `true` if the Kubernetes major version is less than `2`. ### KubernetesMinorVersion > Introduced in KOTS v1.92.0 ```go func KubernetesMinorVersion() string ``` KubernetesMinorVersion returns the Kubernetes server *minor* version. ```yaml repl{{ KubernetesMinorVersion }} ``` You can compare the Kubernetes minor version as follows: ```yaml repl{{gt (KubernetesMinorVersion | ParseInt) 19 }} ``` This returns `true` if the Kubernetes minor version is greater than `19`. ### KubernetesVersion > Introduced in KOTS v1.92.0 ```go func KubernetesVersion() string ``` KubernetesVersion returns the Kubernetes server version. ```yaml repl{{ KubernetesVersion }} ``` You can compare the Kubernetes version as follows: ```yaml repl{{KubernetesVersion | semverCompare ">= 1.19"}} ``` This returns `true` if the Kubernetes version is greater than or equal to `1.19`. For more complex comparisons, see [Semantic Version Functions](https://masterminds.github.io/sprig/semver.html) in the sprig documentation. ### Namespace ```go func Namespace() string ``` Namespace returns the Kubernetes namespace that the application belongs to. ```yaml '{{repl Namespace}}' ``` ### NodeCount ```go func NodeCount() int ``` NodeCount returns the number of nodes detected within the Kubernetes cluster. ```yaml repl{{ NodeCount }} ``` ### Lookup > Introduced in KOTS v1.103.0 ```go func Lookup(apiversion string, resource string, namespace string, name string) map[string]interface{} ``` Lookup is also supported for installations with Embedded Cluster v3. For more information, see [Lookup](/embedded-cluster/v3/template-functions#lookup) in _Template Functions for Embedded Cluster (Beta)_. Lookup searches resources in a running cluster and returns a resource or resource list. Lookup uses the Helm lookup function to search resources and has the same functionality as the Helm lookup function. For more information, see [lookup](https://helm.sh/docs/chart_template_guide/functions_and_pipelines/#using-the-lookup-function) in the Helm documentation. ```yaml repl{{ Lookup "API_VERSION" "KIND" "NAMESPACE" "NAME" }} ``` Both `NAME` and `NAMESPACE` are optional and can be passed as an empty string (""). The following combination of parameters are possible:
Behavior Lookup function
kubectl get pod mypod -n mynamespace repl{{ Lookup "v1" "Pod" "mynamespace" "mypod" }}
kubectl get pods -n mynamespace repl{{ Lookup "v1" "Pod" "mynamespace" "" }}
kubectl get pods --all-namespaces repl{{ Lookup "v1" "Pod" "" "" }}
kubectl get namespace mynamespace repl{{ Lookup "v1" "Namespace" "" "mynamespace" }}
kubectl get namespaces repl{{ Lookup "v1" "Namespace" "" "" }}
The following describes working with values returned by the Lookup function: * When Lookup finds an object, it returns a dictionary with the key value pairs from the object. This dictionary can be navigated to extract specific values. For example, the following returns the annotations for the `mynamespace` object: ``` repl{{ (Lookup "v1" "Namespace" "" "mynamespace").metadata.annotations }} ``` * When Lookup returns a list of objects, it is possible to access the object list through the `items` field. For example: ``` services: | repl{{- range $index, $service := (Lookup "v1" "Service" "mynamespace" "").items }} - repl{{ $service.metadata.name }} repl{{- end }} ``` For an array value type, omit the `|`. For example: ``` services: repl{{- range $index, $service := (Lookup "v1" "Service" "mynamespace" "").items }} - repl{{ $service.metadata.name }} repl{{- end }} ``` * When no object is found, Lookup returns an empty value. This can be used to check for the existence of an object. ## Date Functions ### Now ```go func Now() string ``` Returns the current timestamp as an RFC3339 formatted string. ```yaml '{{repl Now }}' ``` ### NowFmt ```go func NowFmt(format string) string ``` Returns the current timestamp as a formatted string. For information about Go time formatting guidelines, see [Constants](https://golang.org/pkg/time/#pkg-constants) in the Go documentation. ```yaml '{{repl NowFmt "20060102" }}' ``` ## Encoding Functions ### Base64Decode ```go func Base64Decode(stringToDecode string) string ``` Returns decoded string from a Base64 stored value. ```yaml '{{repl ConfigOption "base_64_encoded_name" | Base64Decode }}' ``` ### Base64Encode ```go func Base64Encode(stringToEncode string) string ``` Returns a Base64 encoded string. ```yaml '{{repl ConfigOption "name" | Base64Encode }}' ``` ### UrlEncode ```go func UrlEncode(stringToEncode string) string ``` Returns the string, url encoded. Equivalent to the `QueryEscape` function within the golang `net/url` library. For more information, see [func QueryEscape](https://godoc.org/net/url#QueryEscape) in the Go documentation. ```yaml '{{repl ConfigOption "smtp_email" | UrlEncode }}:{{repl ConfigOption "smtp_password" | UrlEncode }}@smtp.example.com:587' ``` ### UrlPathEscape ```go func UrlPathEscape(stringToEncode string) string ``` Returns the string, url *path* encoded. Equivalent to the `PathEscape` function within the golang `net/url` library. For more information, see [func PathEscape](https://godoc.org/net/url#PathEscape) in the Go documentation. ```yaml '{{repl ConfigOption "smtp_email" | UrlPathEscape }}:{{repl ConfigOption "smtp_password" | UrlPathEscape }}@smtp.example.com:587' ``` ## Encryption Functions ### KubeSeal ```go func KubeSeal(certData string, namespace string, name string, value string) string ``` ## Integer and Float Functions ### HumanSize ```go func HumanSize(size interface{}) string ``` HumanSize returns a human-readable approximation of a size in bytes capped at 4 valid numbers (eg. "2.746 MB", "796 KB"). The size must be a integer or floating point number. ```yaml '{{repl ConfigOption "min_size_bytes" | HumanSize }}' ``` ## Proxy Functions ### HTTPProxy ```go func HTTPProxy() string ``` HTTPProxy returns the address of the proxy that the Admin Console is configured to use. ```yaml repl{{ HTTPProxy }} ``` ### HTTPSProxy ```go func HTTPSProxy() string ``` HTTPSProxy returns the address of the proxy that the Admin Console is configured to use. ```yaml repl{{ HTTPSProxy }} ``` ### NoProxy ```go func NoProxy() string ``` NoProxy returns the comma-separated list of no-proxy addresses that the Admin Console is configured to use. ```yaml repl{{ NoProxy }} ``` ## Math Functions ### Add ```go func Add(x interface{}, y interface{}) interface{} ``` Adds x and y. If at least one of the operands is a floating point number, the result will be a floating point number. If both operands are integers, the result will be an integer. ```yaml '{{repl Add (ConfigOption "maximum_users") 1}}' ``` ### Div ```go func Div(x interface{}, y interface{}) interface{} ``` Divides x by y. If at least one of the operands is a floating point number, the result will be a floating point number. If both operands are integers, the result will be an integer and will be rounded down. ```yaml '{{repl Div (ConfigOption "maximum_users") 2.0}}' ``` ### Mult ```go func Mult(x interface{}, y interface{}) interface{} ``` Multiplies x and y. Both operands must be either an integer or a floating point number. If at least one of the operands is a floating point number, the result will be a floating point number. If both operands are integers, the result will be an integer. ```yaml '{{repl Mult (NodePrivateIPAddressAll "DB" "redis" | len) 2}}' ``` If a template function returns a string, the value must be converted to an integer or a floating point number first: ```yaml '{{repl Mult (ConfigOption "session_cookie_age" | ParseInt) 86400}}' ``` ### Sub ```go func Sub(x interface{}, y interface{}) interface{} ``` Subtracts y from x. If at least one of the operands is a floating point number, the result will be a floating point number. If both operands are integers, the result will be an integer. ```yaml '{{repl Sub (ConfigOption "maximum_users") 1}}' ``` ## String Functions ### ParseBool ```go func ParseBool(str string) bool ``` ParseBool returns the boolean value represented by the string. ```yaml '{{repl ConfigOption "str_value" | ParseBool }}' ``` ### ParseFloat ```go func ParseFloat(str string) float64 ``` ParseFloat returns the float value represented by the string. ```yaml '{{repl ConfigOption "str_value" | ParseFloat }}' ``` ### ParseInt ```go func ParseInt(str string, args ...int) int64 ``` ParseInt returns the integer value represented by the string with optional base (default 10). ```yaml '{{repl ConfigOption "str_value" | ParseInt }}' ``` ### ParseUint ```go func ParseUint(str string, args ...int) uint64 ``` ParseUint returns the unsigned integer value represented by the string with optional base (default 10). ```yaml '{{repl ConfigOption "str_value" | ParseUint }}' ``` ### RandomString ```go func RandomString(length uint64, providedCharset ...string) string ``` Returns a random string with the desired length and charset. Provided charsets must be Perl formatted and match individual characters. If no charset is provided, `[_A-Za-z0-9]` will be used. #### Examples The following example generates a 64-character random string: ```yaml '{{repl RandomString 64}}' ``` The following example generates a 64-character random string that contains `a`s and `b`s: ```yaml '{{repl RandomString 64 "[ab]" }}' ``` #### Generating Persistent and Ephemeral Strings When you assign the RandomString template function to a `value` key in the Config custom resource, you can use the `hidden` and `readonly` properties to control the behavior of the RandomString function each time it is called. The RandomString template function is called each time the user deploys a change to the configuration settings for the application. Depending on if the `hidden` and `readonly` properties are `true` or `false`, the random string generated by a RandomString template function in a `value` key is either ephemeral or persistent between configuration changes: * **Ephemeral**: The value of the random string _changes_ when the user deploys a change to the configuration settings for the application. * **Persistent**: The value of the random string does _not_ change when the user deploys a change to the configuration settings for the application. For more information about these properties, see [`hidden`](custom-resource-config#hidden) and [`readonly`](custom-resource-config#readonly) in _Config_. :::note If you assign the RandomString template function to a `default` key in the Config custom resource rather than a `value` key, then the `hidden` and `readonly` properties do _not_ affect the behavior of the RandomString template function. For more information about the behavior of the `default` key in the Config custom resource, see [`default`](custom-resource-config#default) in _Config_. ::: The following table describes the behavior of the RandomString template function when it is assigned to a `value` key in the Config custom resource and the `hidden` and `readonly` properties are `true` or `false`:
readonly hidden Outcome Use Case
false true Persistent

Set readonly to false and hidden to true if:

  • The random string must not change each time the user deploys a change to the application's configuration settings.
  • The user does not need to see or change, or must be prevented from seeing or changing, the value of the random string.
true false Ephemeral

Set readonly to true and hidden to false if:

  • The random string must change each time the user deploys a change to the application's configuration settings.
  • The user does not need to change, or must be prevented from changing, the value of the random string.
  • The user must be able to see the value of the random string.
true true Ephemeral

Set readonly to true and hidden to true if:

  • The random string must change each time the user deploys a change to the application's configuration settings.
  • The user does not need to see or change, or must be preventing from seeing or changing, the value of the random string.
false false Persistent

Set readonly to false and hidden to false if:

  • The random string must not change each time the user deploys a change to the application's configuration settings.
  • The user must be able to see and change the value of the random string.

For example, set both readonly and hidden to false to generate a random password that users must be able to see and then change to a different value that they choose.
### Split ```go func Split(s string, sep string) []string ``` Split slices s into all substrings separated by sep and returns an array of the substrings between those separators. ```yaml '{{repl Split "A,B,C" "," }}' ``` Combining `Split` and `index`: Assuming the `github_url` param is set to `https://github.mycorp.internal:3131`, the following would set `GITHUB_HOSTNAME` to `github.mycorp.internal`. ```yaml '{{repl index (Split (index (Split (ConfigOption "github_url") "/") 2) ":") 0}}' ``` ### ToLower ```go func ToLower(stringToAlter string) string ``` Returns the string, in lowercase. ```yaml '{{repl ConfigOption "company_name" | ToLower }}' ``` ### ToUpper ```go func ToUpper(stringToAlter string) string ``` Returns the string, in uppercase. ```yaml '{{repl ConfigOption "company_name" | ToUpper }}' ``` ### Trim ```go func Trim(s string, args ...string) string ``` Trim returns a string with all leading and trailing strings contained in the optional args removed (default space). ```yaml '{{repl Trim (ConfigOption "str_value") "." }}' ``` ### TrimSpace ```go func TrimSpace(s string) string ``` Trim returns a string with all leading and trailing spaces removed. ```yaml '{{repl ConfigOption "str_value" | TrimSpace }}' ``` ### YamlEscape ```go func YamlEscape(input string) string ``` YamlEscape returns an escaped and quoted version of the input string, suitable for use within a YAML document. This can be useful when dealing with user-uploaded files that may include null bytes and other nonprintable characters. For more information about printable characters, see [Character Set](https://yaml.org/spec/1.2.2/#51-character-set) in the YAML documentation. ```yaml repl{{ ConfigOptionData "my_file_upload" | YamlEscape }} ``` --- # Use the Vendor API v3 This topic describes how to use Replicated Vendor API authentication tokens to make API calls. ## About the Vendor API The Vendor API is the API for the Vendor Portal. This API can be used to complete tasks programmatically, including all tasks for packaging and managing applications, and managing artifacts such as teams and license files. ## API token requirement To use the Vendor API v3, you need a token for authorization. You provide the token as the value of the `Authorization` header of Vendor API calls. For example, to pass a token as the authorization header in a request: ``` curl --request GET \ --url https://api.replicated.com/vendor/v3/customers \ --header 'Accept: application/json' \ --header 'Authorization: my-token' ``` Generate a service account or user API token in the Vendor Portal. The token must have `Read/Write` access to create new releases. See [Generating API Tokens](/vendor/replicated-api-tokens). ## Vendor API v3 documentation For Vendor API documentation and an interactive API console, see [Vendor API v3 Reference](https://replicated-vendor-api.readme.io/v3/reference/createapp). For the Vendor API swagger specification, see [vendor-api-v3.json](https://api.replicated.com/vendor/v3/spec/vendor-api-v3.json). ![vendor api documentation page](/images/vendor-api-docs.png) [View a larger version of this image](/images/vendor-api-docs.png) --- # Add links to the dashboard This topic describes how to use the Kubernetes SIG Application custom resource to add links to the Replicated KOTS Admin Console dashboard. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview Replicated recommends that every application include a Kubernetes SIG Application custom resource. The Kubernetes SIG Application custom resource provides a standard API for creating, viewing, and managing applications. For more information, see [Kubernetes Applications](https://github.com/kubernetes-sigs/application#kubernetes-applications) in the kubernetes-sigs GitHub repository. You can include the Kubernetes SIG Application custom resource in your releases to add links to the Admin Console dashboard. Common use cases include adding links to documentation, dashboards, or a landing page for the application. For example, the following shows an **Open App** button on the dashboard of the Admin Console for an application named Gitea: Admin Console dashboard with Open App link [View a larger version of this image](/images/gitea-open-app.png) :::note KOTS uses the Kubernetes SIG Application custom resource as metadata and does not require or use an in-cluster controller to handle this custom resource. An application that follows best practices does not require cluster admin privileges or any cluster-wide components to be installed. ::: ## Add a link To add a link to the Admin Console dashboard, include a [Kubernetes SIG Application](https://github.com/kubernetes-sigs/application#kubernetes-applications) custom resource in the release with a `spec.descriptor.links` field. The `spec.descriptor.links` field is an array of links that are displayed on the Admin Console dashboard after the application is deployed. Each link in the `spec.descriptor.links` array contains two fields: * `description`: The link text that will appear on the Admin Console dashboard. * `url`: The target URL. For example: ```yaml # App.k8s.io/v1beta1 application custom resource apiVersion: app.k8s.io/v1beta1 kind: Application metadata: name: "gitea" spec: descriptor: links: - description: About Wordpress url: "https://wordpress.org/" ``` When the application is deployed, the "About Wordpress" link is displayed on the Admin Console dashboard as shown below: About Wordpress link on the Admin Console dashboard [View a larger version of this image](/images/dashboard-link-about-wordpress.png) For an additional example of a Kubernetes SIG Application custom resource, see [application.yaml](https://github.com/kubernetes-sigs/application/blob/master/docs/examples/wordpress/application.yaml) in the kubernetes-sigs GitHub repository. ### Create URLs with user-supplied values using Replicated template functions {#url-template} You can use Replicated template functions to template URLs in the Kubernetes SIG Application custom resource. This can be useful when all or some of the URL is a user-supplied value. For example, an application might allow users to provide their own ingress controller or load balancer. In this case, the URL can be templated to render the hostname that the user provides on the Admin Console Config screen. The following examples show how to use the KOTS [ConfigOption](/reference/template-functions-config-context#configoption) template function in the Kubernetes SIG Application custom resource `spec.descriptor.links.url` field to render one or more user-supplied values: * In the example below, the URL hostname is a user-supplied value for an ingress controller that the user configures during installation. ```yaml apiVersion: app.k8s.io/v1beta1 kind: Application metadata: name: "my-app" spec: descriptor: links: - description: Open App url: 'http://{{repl ConfigOption "ingress_host" }}' ``` * In the example below, both the URL hostname and a node port are user-supplied values. It might be necessary to include a user-provided node port if you are exposing NodePort services for installations on VMs or bare metal servers with [Replicated Embedded Cluster](/embedded-cluster/v3/embedded-overview) or [Replicated kURL](/vendor/kurl-about). ```yaml apiVersion: app.k8s.io/v1beta1 kind: Application metadata: name: "my-app" spec: descriptor: links: - description: Open App url: 'http://{{repl ConfigOption "hostname" }}:{{repl ConfigOption "node_port"}}' ``` For more information about working with Replicated template functions, see [About Replicated Template Functions](/reference/template-functions-about). --- # Customize the application icon You can add a custom application icon that displays in the Replicated Admin Console and the download portal. Adding a custom icon helps ensure that your brand is reflected for your customers. :::note You can also use a custom domain for the download portal. For more information, see [About Custom Domains](custom-domains). ::: :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Add a custom icon For information about how to choose an image file for your custom application icon that displays well in the Admin Console, see [Icon Image File Recommendations](#icon-image-file-recommendations) below. To add a custom application icon: 1. In the [Vendor Portal](https://vendor.replicated.com/apps), click **Releases**. Click **Create release** to create a new release, or click **Edit YAML** to edit an existing release. 1. Create or open the Application custom resource manifest file. An Application custom resource manifest file has `apiVersion: kots.io/v1beta1` and `kind: Application`. 1. In the preview section of the Help pane: 1. If your Application manifest file is already populated with an `icon` key, the icon displays in the preview. Click **Preview a different icon** to access the preview options. 1. Drag and drop an icon image file to the drop zone. Alternatively, paste a link or Base64 encoded data URL in the text box. Click **Preview**. ![Application icon preview](/images/app-icon-preview.png) 1. (Air gap only) If you paste a link to the image in the text box, click **Preview** and **Base64 encode icon** to convert the image to a Base64 encoded data URL. An encoded URL displays that you can copy and paste into the Application manifest. Base64 encoding is required for images used with air gap installations. :::note If you pasted a Base64 encoded data URL into the text box, the **Base64 encode icon** button does not display because the image is already encoded. If you drag and drop an icon, the icon is automatically encoded for you. ::: ![Base64 encode image button](/images/app-icon-preview-base64.png) 1. Click **Preview a different icon** to preview a different icon if needed. 1. In the Application manifest, under `spec`, add an `icon` key that includes a link or the Base64 encoded data URL to the desired image. **Example**: ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: my-application spec: title: My Application icon: https://kots.io/images/kotsadm-logo-large@2x.png ``` 1. Click **Save Release**. ## Icon image file recommendations For your custom application icon to look best in the Admin Console, consider the following recommendations: * Use a PNG or JPG file. * Use an image that is at least 250 by 250 pixels. * Export the image file at 2x. --- # Create and edit configuration fields This topic describes how to use the Replicated Config custom resource manifest file to add and edit fields in the KOTS Admin Console configuration screen. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## About the Config custom resource Applications distributed with Replicated KOTS can include a configuration screen in the Admin Console to collect required or optional values from your users that are used to run your application. For more information about the configuration screen, see [About the Configuration Screen](config-screen-about). To include a configuration screen in the Admin Console for your application, you add a Config custom resource manifest file to a release for the application. You define the fields that appear on the configuration screen as an array of `groups` and `items` in the Config custom resource: * `groups`: A set of `items`. Each group must have a `name`, `title`, `description`, and `items`. For example, you can create a group of several user input fields that are all related to configuring an SMTP mail server. * `items`: An array of user input fields. Each array under `items` must have a `name`, `title`, and `type`. You can also include several optional properties. For example, in a group for configuring a SMTP mail server, you can have user input fields under `items` for the SMTP hostname, port, username, and password. There are several types of `items` supported in the Config manifest that allow you to collect different types of user inputs. For example, you can use the `password` input type to create a text field on the configuration screen that hides user input. For more information about the syntax of the Config custom resource manifest, see [Config](/reference/custom-resource-config). ## About regular expression validation You can use [RE2 regular expressions](https://github.com/google/re2/wiki/Syntax) (regex) to validate user input for config items, ensuring conformity to certain standards, such as valid email addresses, password complexity rules, IP addresses, and URLs. This prevents users from deploying an application with a verifiably invalid configuration. You add the `validation`, `regex`, `pattern` and `message` fields to items in the Config custom resource. Validation is supported for `text`, `textarea`, `password` and `file` config item types. For more information about regex validation fields, see [Item Validation](/reference/custom-resource-config#item-validation) in _Config_. The following example shows a common password complexity rule: ``` - name: smtp-settings title: SMTP Settings items: - name: smtp_password title: SMTP Password type: password help_text: Set SMTP password validation: regex: pattern: ^(?:[\w@#$%^&+=!*()_\-{}[\]:;"'<>,.?\/|]){8,16}$ message: The password must be between 8 and 16 characters long and can contain a combination of uppercase letter, lowercase letters, digits, and special characters. ``` ## Add fields to the configuration screen To add fields to the Admin Console configuration screen: 1. In the [Vendor Portal](https://vendor.replicated.com/apps), click **Releases**. Then, either click **Create release** to create a new release, or click **Edit YAML** to edit an existing release. 1. Create or open the Config custom resource manifest file in the desired release. A Config custom resource manifest file has `kind: Config`. 1. In the Config custom resource manifest file, define custom user-input fields in an array of `groups` and `items`. **Example**: ```yaml apiVersion: kots.io/v1beta1 kind: Config metadata: name: my-application spec: groups: - name: smtp_settings title: SMTP Settings description: Configure SMTP Settings items: - name: enable_smtp title: Enable SMTP help_text: Enable SMTP type: bool default: "0" - name: smtp_host title: SMTP Hostname help_text: Set SMTP Hostname type: text - name: smtp_port title: SMTP Port help_text: Set SMTP Port type: text - name: smtp_user title: SMTP User help_text: Set SMTP User type: text - name: smtp_password title: SMTP Password type: password default: 'password' ``` The example above includes a single group with the name `smtp_settings`. The `items` array for the `smtp_settings` group includes the following user-input fields: `enable_smtp`, `smtp_host`, `smtp_port`, `smtp_user`, and `smtp_password`. Additional item properties are available, such as `affix` to make items appear horizontally on the same line. For more information about item properties, see [Item Properties](/reference/custom-resource-config#item-properties) in Config. The following screenshot shows how the SMTP Settings group from the example YAML above displays in the Admin Console configuration screen during application installation: ![User input fields on the configuration screen for the SMTP settings](/images/config-screen-smtp-example-large.png) 1. (Optional) Add default values for the fields. You can add default values using one of the following properties: * **With the `default` property**: When you include the `default` key, KOTS uses this value when rendering the manifest files for your application. The value then displays as a placeholder on the configuration screen in the Admin Console for your users. KOTS only uses the default value if the user does not provide a different value. :::note If you change the `default` value in a later release of your application, installed instances of your application receive the updated value only if your users did not change the default from what it was when they initially installed the application. If a user did change a field from its default, the Admin Console does not overwrite the value they provided. ::: * **With the `value` property**: When you include the `value` key, KOTS does not overwrite this value during an application update. The value that you provide for the `value` key is visually indistinguishable from other values that your user provides on the Admin Console configuration screen. KOTS treats user-supplied values and the value that you provide for the `value` key as the same. 2. (Optional) Add regular expressions to validate user input for `text`, `textarea`, `password` and `file` config item types. For more information, see [About Regular Expression Validation](#about-regular-expression-validation). **Example**: ```yaml - name: smtp_host title: SMTP Hostname help_text: Set SMTP Hostname type: text validation: regex: ​ pattern: ^[a-zA-Z]([a-zA-Z0-9\-]+[\.]?)*[a-zA-Z0-9]$ message: Valid hostname starts with a letter (uppercase/lowercase), followed by zero or more groups of letters (uppercase/lowercase), digits, or hyphens, optionally followed by a period. Ends with a letter or digit. ``` 3. (Optional) Mark fields as required by including `required: true`. When there are required fields, the user is prevented from proceeding with the installation until they provide a valid value for required fields. **Example**: ```yaml - name: smtp_password title: SMTP Password type: password required: true ``` 4. Save and promote the release to a development environment to test your changes. ## Next steps After you add user input fields to the configuration screen, you use template functions to map the user-supplied values to manifest files in your release. If you use a Helm chart for your application, you map the values to the Helm chart `values.yaml` file using the HelmChart custom resource. For more information, see [Map User-Supplied Values](config-screen-map-inputs). --- # Add resource status informers This topic describes how to add status informers for your application. Status informers apply only to applications installed with Replicated KOTS. For information about how to collect application status data for applications installed with Helm, see [Enabling and Understanding Application Status](insights-app-status). :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## About status informers _Status informers_ are a feature of KOTS that report on the status of supported Kubernetes resources deployed as part of your application. You enable status informers by listing the target resources under the `statusInformers` property in the Replicated Application custom resource. KOTS watches all of the resources that you add to the `statusInformers` property for changes in state. Possible resource statuses are Ready, Updating, Degraded, Unavailable, and Missing. For more information, see [Understanding Application Status](#understanding-application-status). When you one or more status informers to your application, KOTS automatically does the following: * Displays application status for your users on the dashboard of the Admin Console. This can help users diagnose and troubleshoot problems with their instance. The following shows an example of how an Unavailable status displays on the Admin Console dashboard: Unavailable status on the Admin Console dashboard * Sends application status data to the Vendor Portal. This is useful for viewing insights on instances of your application running in customer environments, such as the current status and the average uptime. For more information, see [Instance Details](instance-insights-details). The following shows an example of the Vendor Portal **Instance details** page with data about the status of an instance over time: Instance details full page [View a larger version of this image](/images/instance-details.png) ## Add status informers To create status informers for your application, add one or more supported resource types to the `statusInformers` property in the Application custom resource. See [`statusInformers`](/reference/custom-resource-application#statusinformers) in _Application_. The following resource types are supported: * Deployment * StatefulSet * Service * Ingress * PersistentVolumeClaims (PVC) * DaemonSet You can target resources of the supported types that are deployed in any of the following ways: * Deployed by KOTS. * Deployed by a Kubernetes Operator that is deployed by KOTS. For more information, see [About Packaging a Kubernetes Operator Application](operator-packaging-about). * Deployed by Helm. For more information, see [About Distributing Helm Charts with KOTS](/vendor/helm-native-about). ### Examples Status informers are in the format `[namespace/]type/name`, where namespace is optional and defaults to the current namespace. **Example**: ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: my-application spec: statusInformers: - deployment/my-web-svc - deployment/my-worker ``` The `statusInformers` property also supports template functions. Using template functions allows you to include or exclude a status informer based on a customer-provided configuration value: **Example**: ```yaml statusInformers: - deployment/my-web-svc - '{{repl if ConfigOptionEquals "option" "value"}}deployment/my-worker{{repl else}}{{repl end}}' ``` In the example above, the `deployment/my-worker` status informer is excluded unless the statement in the `ConfigOptionEquals` template function evaluates to true. For more information about using template functions in application manifest files, see [About Replicated Template Functions](/reference/template-functions-about). ## Understanding application status This section provides information about how Replicated interprets and aggregates the status of Kubernetes resources for your application to report an application status. ### Resource statuses Possible resource statuses are Ready, Updating, Degraded, Unavailable, and Missing. The following table lists the supported Kubernetes resources and the conditions that contribute to each status:
Deployment StatefulSet Service Ingress PVC DaemonSet
Ready Ready replicas equals desired replicas Ready replicas equals desired replicas All desired endpoints are ready, any load balancers have been assigned All desired backend service endpoints are ready, any load balancers have been assigned Claim is bound Ready daemon pods equals desired scheduled daemon pods
Updating The deployed replicas are from a different revision The deployed replicas are from a different revision N/A N/A N/A The deployed daemon pods are from a different revision
Degraded At least 1 replica is ready, but more are desired At least 1 replica is ready, but more are desired At least one endpoint is ready, but more are desired At least one backend service endpoint is ready, but more are desired N/A At least one daemon pod is ready, but more are desired
Unavailable No replicas are ready No replicas are ready No endpoints are ready, no load balancer has been assigned No backend service endpoints are ready, no load balancer has been assigned Claim is pending or lost No daemon pods are ready
Missing Missing is an initial deployment status indicating that informers have not reported their status because the application has just been deployed and the underlying resource has not been created yet. After the resource is created, the status changes. However, if a resource changes from another status to Missing, then the resource was either deleted or the informers failed to report a status.
### Aggregate application status When you provide more than one Kubernetes resource, Replicated aggregates all resource statuses to display a single application status. Replicated uses the least available resource status to represent the aggregate application status. For example, if at least one resource has an Unavailable status, then the aggregate application status is Unavailable. The following table describes the resource statuses that define each aggregate application status:
Resource Statuses Aggregate Application Status
No status available for any resource Missing
One or more resources Unavailable Unavailable
One or more resources Degraded Degraded
One or more resources Updating Updating
All resources Ready Ready
--- # Port forward services with KOTS This topic describes how to add one or more ports to the Replicated KOTS port forward tunnel by configuring the `ports` key in the Replicated Application custom resource. The information in this topic applies to existing cluster installations. For information about exposing services for Replicated kURL or Replicated Embedded Cluster installations, see [Exposing Services Using NodePorts](kurl-nodeport-services). :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview For installations into existing clusters, KOTS automatically creates a port forward tunnel and exposes the Admin Console on port 8800 where it can be accessed by users. In addition to the 8800 Admin Console port, you can optionally add one or more extra ports to the port forward tunnel. Adding ports to the port forward tunnel allows you to port forward application services without needing to manually run the `kubectl port-forward` command. You can also add a link to the Admin Console dashboard that points to port-forwarded services. This can be particularly useful when developing and testing KOTS releases for your application, because it provides a quicker way to access an application after installation compared to setting up an ingress controller or adding a load balancer. ## Port forward a service with the KOTS application `ports` key To port forward a service with KOTS for existing cluster installations: 1. In a new release, configure the [`ports`](/reference/custom-resource-application#ports) key in the Replicated Application custom resource with details for the target service. For example: ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: my-application spec: ports: - serviceName: my-service servicePort: 3000 localPort: 8888 ``` The following table provides more information about how to configure each field:
Field Instructions
`ports.serviceName` Add the name of the service. KOTS can create a port forward to ClusterIP, NodePort, or LoadBalancer services. For more information about Kubernetes service types, see [Service](https://kubernetes.io/docs/concepts/services-networking/service/) in the Kubernetes documentation.
`ports.servicePort`

Add the `containerPort` of the Pod where the service is running. This is the port where KOTS forwards traffic.

Go templates are not supported in the `localPort` or `servicePort` field. For more information, see [`ports`](/reference/custom-resource-application#ports) in _Application_.
`ports.localPort`

Add the port to map on the local workstation.

Go templates are not supported in the `localPort` or `servicePort` field. For more information, see [`ports`](/reference/custom-resource-application#ports) in _Application_..
1. Promote the release to the channel that you use for internal testing, then install in a development environment to test your changes. When the application is in a Ready state and the KOTS port forward is running, you will see output similar to the following: ```bash • Press Ctrl+C to exit • Go to http://localhost:8800 to access the Admin Console • Go to http://localhost:8888 to access the application ``` Confirm that you can access the service at the URL provided in the KOTS CLI output. 1. (Optional) Add a link to the service on the Admin Console dashboard. See [Add a Link to a Port-Forwarded Service on the Admin Console Dashboard](#add-link) below. ## Add a link to a port-forwarded service on the Admin Console dashboard {#add-link} After you add a service to the KOTS port forward tunnel, you can also optionally add a link to the port-forwarded service on the Admin Console dashboard. To add a link to a port-forwarded service, add the _same_ URL in the Replicated Application custom resource `ports.applicationURL` and Kubernetes SIG Application custom resource `spec.descriptor.links.url` fields. When the URLs in these fields match, KOTS adds a link on the Admin Console dashboard where the given service can be accessed. This process automatically links to the hostname in the browser (where the Admin Console is being accessed) and appends the specified `localPort`. To add a link to a port-forwarded service on the Admin Console dashboard: 1. In a new release, open the Replicated Application custom resource and add a URL to the `ports.applicationURL` field. For example: ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: my-application spec: ports: - serviceName: my-service servicePort: 3000 localPort: 8888 applicationUrl: "http://my-service" ``` Consider the following guidelines for this URL: * Use HTTP instead of HTTPS unless TLS termination takes place in the application Pod. * KOTS rewrites the URL with the hostname in the browser during deployment. So, you can use any hostname for the URL, such as the name of the service. For example, `http://my-service`. 1. Add a Kubernetes SIG Application custom resource in the release. For example: ```yaml # app.k8s.io/v1beta1 Application Custom resource apiVersion: app.k8s.io/v1beta1 kind: Application metadata: name: "my-application" spec: descriptor: links: - description: Open App # url matches ports.applicationURL in the Replicated Application custom resource url: "http://my-service" ``` 1. For `spec.descriptor.links.description`, add the link text that will appear on the Admin Console dashboard. For example, `Open App`. 1. For `spec.descriptor.links.url`, add the _same_ URL that you used in the `ports.applicationURL` in the Replicated Application custom resource. 1. Promote the release to the channel that you use for internal testing, then install in a development environment to test your changes. When the application is in a Ready state, confirm that you can access the service by clicking the link that appears on the dashboard. For example: Admin Console dashboard with Open App link [View a larger version of this image](/images/gitea-open-app.png) ## Access port-forwarded services This section describes how to access port-forwarded services. ### Command line Run [`kubectl kots admin-console`](/reference/kots-cli-admin-console-index) to open the KOTS port forward tunnel. The `kots admin-console` command runs the equivalent of `kubectl port-forward svc/myapplication-service :`, then prints a message with the URLs where the Admin Console and any port-forwarded services can be accessed. For more information about the `kubectl port-forward` command, see [port-forward](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#port-forward) in the Kubernetes documentation. For example: ```bash kubectl kots admin-console --namespace gitea ``` ```bash • Press Ctrl+C to exit • Go to http://localhost:8800 to access the Admin Console • Go to http://localhost:8888 to access the application ``` ### Admin Console You can optionally add a link to a port-forwarded service from the Admin Console dashboard. This requires additional configuration. For more information, see [Add a Link to a Port-Forwarded Service on the Admin Console Dashboard](#add-link). The following example shows an **Open App** link on the dashboard of the Admin Console for an application named Gitea: Admin Console dashboard with Open App link [View a larger version of this image](/images/gitea-open-app.png) ## Example: Nginx application with clusterip and nodeport services The following example demonstrates how to link to a port-forwarded ClusterIP service for existing cluster KOTS installations. It also shows how to use the `ports` key to add a link to a NodePort service for Embedded Cluster or kURL installations. Although the primary purpose of the `ports` key is to port forward services for existing cluster KOTS installations, it is also possible to use the `ports` key so that links to NodePort services for Embedded Cluster or kURL installations use the hostname in the browser. For information about exposing NodePort services for Embedded Cluster or kURL installations, see [Exposing Services Using NodePorts](kurl-nodeport-services). To test this example: 1. Add the `example-service.yaml`, `example-deployment.yaml`, `kots-app.yaml`, `k8s-app.yaml`, and `embedded-cluster.yaml` files provided below to a new, empty release in the Vendor Portal. Promote to the channel that you use for internal testing. For more information, see [Manage Releases with the Vendor Portal](releases-creating-releases).
Description

The YAML below contains ClusterIP and NodePort specifications for a service named nginx. Each specification uses the kots.io/when annotation with the Replicated Distribution template function to conditionally include the service based on the installation type (existing cluster or Embedded Cluster/kURL cluster). For more information, see Conditionally Including or Excluding Resources.

As shown below, both the ClusterIP and NodePort nginx services are exposed on port 80.

YAML
```yaml apiVersion: v1 kind: Service metadata: name: nginx labels: app: nginx annotations: kots.io/when: 'repl{{ and (ne Distribution "embedded-cluster") (ne Distribution "kurl")}}' spec: type: ClusterIP ports: - port: 80 selector: app: nginx --- apiVersion: v1 kind: Service metadata: name: nginx labels: app: nginx annotations: kots.io/when: 'repl{{ or (eq Distribution "embedded-cluster") (eq Distribution "kurl")}}' spec: type: NodePort ports: - port: 80 nodePort: 8888 selector: app: nginx ```
Description

A basic Deployment specification for the NGINX application.

YAML
```yaml apiVersion: apps/v1 kind: Deployment metadata: name: nginx labels: app: nginx spec: selector: matchLabels: app: nginx template: metadata: labels: app: nginx annotations: backup.velero.io/backup-volumes: nginx-content spec: containers: - name: nginx image: nginx resources: limits: memory: '256Mi' cpu: '500m' requests: memory: '32Mi' cpu: '100m' ```
Description

The Replicated Application custom resource below adds port 80 to the KOTS port forward tunnel and maps port 8888 on the local machine. The specification also includes applicationUrl: "http://nginx" so that a link to the service can be added to the Admin Console dashboard.

YAML
```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: nginx spec: title: App Name icon: https://raw.githubusercontent.com/cncf/artwork/master/projects/kubernetes/icon/color/kubernetes-icon-color.png statusInformers: - deployment/nginx ports: - serviceName: "nginx" servicePort: 80 localPort: 8888 applicationUrl: "http://nginx" ```
Description

The Kubernetes Application custom resource lists the same URL as the `ports.applicationUrl` field in the Replicated Application custom resource (`"http://nginx"`). This adds a link to the port-forwarded service on the Admin Console dashboard that uses the hostname in the browser and appends the specified `localPort`. The label to be used for the link in the Admin Console is "Open App".

YAML
```yaml apiVersion: app.k8s.io/v1beta1 kind: Application metadata: name: "nginx" spec: descriptor: links: - description: Open App # needs to match applicationUrl in kots-app.yaml url: "http://nginx" ```
Description

To install your application with Embedded Cluster, an Embedded Cluster Config must be present in the release. At minimum, the Embedded Cluster Config sets the version of Embedded Cluster that will be installed. You can also define several characteristics about the cluster.

YAML
```yaml apiVersion: embeddedcluster.replicated.com/v1beta1 kind: Config spec: version: 2.10.0+k8s-1.33 ``` 1. Install the release into an existing cluster and confirm that the service was port-forwarded successfully by clicking **Open App** on the Admin Console dashboard. For more information, see [Online Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster). 1. Install the release on a VM and confirm that you can open the application by clicking **Open App** on the Admin Console dashboard. For more information, see [Online Installation with Embedded Cluster](/embedded-cluster/v3/installing-embedded) or [Online Installation with kURL](/enterprise/installing-kurl). :::note Ensure that the VM where you install allows HTTP traffic. ::: :::note If you used Replicated Compatibility Matrix to create the VM, follow the steps in [Expose Ports on a VM Using the Vendor Portal](/vendor/testing-ingress#expose-ports-vendor-portal) to add these DNS records to the VM: * A DNS record with a **Target Port** of **30000** to get a hostname where you can access the Admin Console * A DNS record with a **Target Port** of **8888** to get a hostname where you can access the NGINX application ::: --- # Add custom graphs This topic describes how to customize the graphs that are displayed on the Replicated Admin Console dashboard. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview of monitoring with Prometheus The KOTS Admin Console can use the open source systems monitoring tool Prometheus to collect metrics on an application and the cluster where the application is installed. Prometheus components include the main Prometheus server, which scrapes and stores time series data, an Alertmanager for alerting on metrics, and Grafana for visualizing metrics. For more information about Prometheus, see [What is Prometheus?](https://prometheus.io/docs/introduction/overview/) in the Prometheus documentation. The Admin Console exposes graphs with key metrics collected by Prometheus in the **Monitoring** section of the dashboard. By default, the Admin Console displays the following graphs: * Cluster disk usage * Pod CPU usage * Pod memory usage In addition to these default graphs, application developers can also expose business and application level metrics and alerts on the dashboard. The following screenshot shows an example of the **Monitoring** section on the Admin Console dashboard with the Disk Usage, CPU Usage, and Memory Usage default graphs: Graphs on the Admin Console dashboard [View a larger version of this image](/images/kotsadm-dashboard-graph.png) ## About customizing graphs If your application exposes Prometheus metrics, you can add custom graphs to the Admin Console dashboard to expose these metrics to your users. You can also modify or remove the default graphs. To customize the graphs that are displayed on the Admin Console, edit the [`graphs`](/reference/custom-resource-application#graphs) property in the Replicated Application custom resource manifest file. At a minimum, each graph in the `graphs` property must include the following fields: * `title`: Defines the graph title that is displayed on the Admin Console. * `query`: A valid PromQL Prometheus query. You can also include a list of multiple queries by using the `queries` property. For more information about querying Prometheus with PromQL, see [Querying Prometheus](https://prometheus.io/docs/prometheus/latest/querying/basics/) in the Prometheus documentation. :::note By default, a kURL cluster exposes the Prometheus expression browser at NodePort 30900. For more information, see [Expression Browser](https://prometheus.io/docs/visualization/browser/) in the Prometheus documentation. ::: ## Limitation Monitoring applications with Prometheus is not supported for installations with [Replicated Embedded Cluster](/embedded-cluster/v3/embedded-overview). ## Add and modify graphs To customize graphs on the Admin Console dashboard: 1. In the [Vendor Portal](https://vendor.replicated.com/), click **Releases**. Then, either click **Create release** to create a new release, or click **Edit YAML** to edit an existing release. 1. Create or open the [Replicated Application](/reference/custom-resource-application) custom resource manifest file. 1. In the Application manifest file, under `spec`, add a `graphs` property. Edit the `graphs` property to modify or remove existing graphs or add a new custom graph. For more information, see [graphs](/reference/custom-resource-application#graphs) in _Application_. **Example**: The following example shows the YAML for adding a custom graph that displays the total number of user signups for an application. ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: my-application spec: graphs: - title: User Signups query: 'sum(user_signup_events_total)' ``` 1. (Optional) Under `graphs`, copy and paste the specs for the default Disk Usage, CPU Usage, and Memory Usage Admin Console graphs provided in the YAML below. Adding these default graphs to the Application custom resource manifest ensures that they are not overwritten when you add one or more custom graphs. When the default graphs are included in the Application custom resource, the Admin Console displays them in addition to any custom graphs. Alternatively, you can exclude the YAML specs for the default graphs to remove them from the Admin Console dashboard. ```yaml apiVersion: kots.io/v1beta1 kind: Application metadata: name: my-application spec: graphs: - title: User Signups query: 'sum(user_signup_events_total)' # Disk Usage, CPU Usage, and Memory Usage below are the default graphs - title: Disk Usage queries: - query: 'sum((node_filesystem_size_bytes{job="node-exporter",fstype!="",instance!=""} - node_filesystem_avail_bytes{job="node-exporter", fstype!=""})) by (instance)' legend: 'Used: {{ instance }}' - query: 'sum((node_filesystem_avail_bytes{job="node-exporter",fstype!="",instance!=""})) by (instance)' legend: 'Available: {{ instance }}' yAxisFormat: bytes - title: CPU Usage query: 'sum(rate(container_cpu_usage_seconds_total{namespace="{{repl Namespace}}",container!="POD",pod!=""}[5m])) by (pod)' legend: '{{ pod }}' - title: Memory Usage query: 'sum(container_memory_usage_bytes{namespace="{{repl Namespace}}",container!="POD",pod!=""}) by (pod)' legend: '{{ pod }}' yAxisFormat: bytes ``` 1. Save and promote the release to a development environment to test your changes. --- # About integrating with CI/CD This topic provides an introduction to integrating Replicated CLI commands in your continuous integration and continuous delivery (CI/CD) pipelines, including Replicated's best practices and recommendations. ## Overview Using CI/CD workflows to automatically compile code and run tests improves the speed at which teams can test, iterate on, and deliver releases to customers. When you integrate Replicated CLI commands into your CI/CD workflows, you can automate the process of deploying your application to clusters for testing, rather than needing to manually create and then archive channels, customers, and environments for testing. You can also include continuous delivery workflows to automatically promote a release to a shared channel in your Replicated team. This allows you to more easily share releases with team members for internal testing and iteration, and then to promote releases when they are ready to be shared with customers. ## Best practices and recommendations The following are Replicated's best practices and recommendations for CI/CD: * Include unique workflows for development and for releasing your application. This allows you to run tests on every commit, and then to promote releases to internal and customer-facing channels only when ready. For more information about the workflows that Replicated recommends, see [Recommended CI/CD Workflows](ci-workflows). * Integrate Replicated Compatibility Matrix (CMX) into your CI/CD workflows to quickly create multiple different types of clusters where you can deploy and test your application. Supported distributions include OpenShift, GKE, EKS, and more. For more information, see [About CMX](testing-about). * If you use the GitHub Actions CI/CD platform, integrate the custom GitHub actions that Replicated maintains to replace repetitive tasks related to distributing application with Replicated or using CMX. For more information, see [Use Replicated GitHub Actions in CI/CD](/vendor/ci-workflows-github-actions). * To help show you are conforming to a secure supply chain, sign all commits and container images. Additionally, provide a verification mechanism for container images. * Use custom RBAC policies to control the actions that can be performed in your CI/CD workflows. For example, you can create a policy that blocks the ability to promote releases to your production channel. For more information about creating custom RBAC policies in the Vendor Portal, see [Configure RBAC Policies](/vendor/team-management-rbac-configuring). For a full list of available RBAC resources, see [RBAC Resource Names](/vendor/team-management-rbac-resource-names). * Incorporating code tests into your CI/CD workflows is important for ensuring that developers receive quick feedback and can make updates in small iterations. Replicated recommends that you create and run all of the following test types as part of your CI/CD workflows: * **Application Testing:** Traditional application testing includes unit, integration, and end-to-end tests. These tests are critical for application reliability, and CMX is designed to to incorporate and use your application testing. * **Performance Testing:** Performance testing is used to benchmark your application to ensure it can handle the expected load and scale gracefully. Test your application under a range of workloads and scenarios to identify any bottlenecks or performance issues. Make sure to optimize your application for different Kubernetes distributions and configurations by creating all of the environments you need to test in. * **Smoke Testing:** Using a single, conformant Kubernetes distribution to test basic functionality of your application with default (or standard) configuration values is a quick way to get feedback if something is likely to be broken for all or most customers. Replicated also recommends that you include each Kubernetes version that you intend to support in your smoke tests. * **Compatibility Testing:** Because applications run on various Kubernetes distributions and configurations, it is important to test compatibility across different environments. CMX provides this infrastructure. * **Canary Testing:** Before releasing to all customers, consider deploying your application to a small subset of your customer base as a _canary_ release. This lets you monitor the application's performance and stability in real-world environments, while minimizing the impact of potential issues. CMX enables canary testing by simulating exact (or near) customer environments and configurations to test your application with. --- # Use Replicated GitHub actions in CI/CD This topic describes how to integrate Replicated's custom GitHub actions into continuous integration and continuous delivery (CI/CD) workflows that use the GitHub Actions platform. ## Overview Replicated maintains a set of custom GitHub actions that are designed to replace repetitive tasks related to distributing your application with Replicated and related to using Replicated Compatibility Matrix (CMX), such as: * Creating and removing customers, channels, and clusters * Promoting releases * Creating a matrix of clusters for testing based on the Kubernetes distributions and versions where your customers are running application instances * Reporting the success or failure of tests If you use GitHub Actions as your CI/CD platform, you can include these custom actions in your workflows rather than using Replicated CLI commands. Integrating the Replicated GitHub actions into your CI/CD pipeline helps you quickly build workflows with the required inputs and outputs, without needing to manually create the required CLI commands for each step. To view all the available GitHub actions that Replicated maintains, see the [replicatedhq/replicated-actions](https://github.com/replicatedhq/replicated-actions/) repository in GitHub. ## GitHub actions workflow examples The [replicatedhq/replicated-actions](https://github.com/replicatedhq/replicated-actions#examples) repository in GitHub contains example workflows that use the Replicated GitHub actions. You can use these workflows as a template for your own GitHub Actions CI/CD workflows: * For a simplified development workflow, see [development-helm-prepare-cluster.yaml](https://github.com/replicatedhq/replicated-actions/blob/main/example-workflows/development-helm-prepare-cluster.yaml). * For a customizable development workflow for applications installed with the Helm CLI, see [development-helm.yaml](https://github.com/replicatedhq/replicated-actions/blob/main/example-workflows/development-helm.yaml). * For a customizable development workflow for applications installed with KOTS, see [development-kots.yaml](https://github.com/replicatedhq/replicated-actions/blob/main/example-workflows/development-kots.yaml). * For a release workflow, see [release.yaml](https://github.com/replicatedhq/replicated-actions/blob/main/example-workflows/release.yaml). ## Integrate GitHub actions The following table lists GitHub actions that are maintained by Replicated that you can integrate into your CI/CI workflows. The table also describes when to use the action in a workflow and indicates the related Replicated CLI command where applicable. :::note For an up-to-date list of the avilable custom GitHub actions, see the [replicatedhq/replicated-actions](https://github.com/replicatedhq/replicated-actions/) repository in GitHub. :::
GitHub Action When to Use Related Replicated CLI Commands
archive-channel

In release workflows, a temporary channel is created to promote a release for testing. This action archives the temporary channel after tests complete.

See Archive the temporary channel and customer in Recommended CI/CD Workflows.

 channel delete
archive-customer

In release workflows, a temporary customer is created so that a release can be installed for testing. This action archives the temporary customer after tests complete.

See Archive the temporary channel and customer in Recommended CI/CD Workflows.

 N/A
create-cluster

In release workflows, use this action to create one or more clusters for testing.

See Create cluster matrix, deploy, and test in Recommended CI/CD Workflows.

 cluster create
create-release

In release workflows, use this action to create a release to be installed and tested, and optionally to be promoted to a shared channel after tests complete.

See Create a release and promote to a temporary channel in Recommended CI/CD Workflows.

release create
get-customer-instances

In release workflows, use this action to create a matrix of clusters for running tests based on the Kubernetes distributions and versions of active instances of your application running in customer environments.

See Create cluster matrix, deploy, and test in Recommended CI/CD Workflows.

 N/A
helm-install

In development or release workflows, use this action to install a release using the Helm CLI in one or more clusters for testing.

See Create cluster matrix, deploy, and test in Recommended CI/CD Workflows.

 N/A
kots-install

In development or release workflows, use this action to install a release with Replicated KOTS in one or more clusters for testing.

See Create cluster matrix, deploy, and test in Recommended CI/CD Workflows.

 N/A
prepare-cluster

In development workflows, use this action to create a cluster, create a temporary customer of type test, and install an application in the cluster.

See Prepare clusters, deploy, and test in Recommended CI/CD Workflows.

 cluster prepare
promote-release

In release workflows, use this action to promote a release to an internal or customer-facing channel (such as Unstable, Beta, or Stable) after tests pass.

See Promote to a shared channel in Recommended CI/CD Workflows.

 release promote
remove-cluster

In development or release workflows, use this action to remove a cluster after running tests if no ttl was set for the cluster.

See Prepare clusters, deploy, and test and Create cluster matrix, deploy, and test in Recommended CI/CD Workflows.

 cluster rm
report-compatibility-result In development or release workflows, use this action to report the success or failure of tests that ran in clusters provisioned by CMX. release compatibility
upgrade-cluster In release workflows, use this action to test your application's compatibility with Kubernetes API resource version migrations after upgrading. cluster upgrade
--- # Recommended CI/CD workflows This topic provides Replicated's recommended development and release workflows for your continuous integration and continuous delivery (CI/CD) pipelines. ## Overview Replicated recommends that you maintain unique CI/CD workflows for development (continuous integration) and for releasing your software (continuous delivery). The development and release workflows in this topic describe the recommended steps and jobs to include in your own workflows, including how to integrate Replicated Compatibility Matrix (CMX) into your workflows for testing. For more information about CMX, see [About CMX](testing-about). For each step, the corresponding Replicated CLI command is provided. Additionally, for users of the GitHub Actions platform, a corresponding custom GitHub action that is maintained by Replicated is also provided. For more information about using the Replicated CLI, see [Install the Replicated CLI](/reference/replicated-cli-installing). For more information about the Replicated GitHub actions, see [Use Replicated GitHub Actions in CI/CD](ci-workflows-github-actions). :::note How you implement CI/CD workflows varies depending on the platform, such as GitHub, GitLab, CircleCI, TravisCI, or Jenkins. Refer to the documentation for your CI/CD platform for additional guidance on how to create jobs and workflows. ::: ## About creating RBAC policies for CI/CD Replicated recommends using custom RBAC policies to control the actions that can be performed in your CI/CD workflows. For example, you can create a policy using the [`kots/app/[]/channel/[]/promote`](/vendor/team-management-rbac-resource-names#kotsappchannelpromote) resource that blocks the ability to promote releases to your production channel. This allows for using CI/CD for the purpose of testing, without accidentally releasing to customers. For more information about creating custom RBAC policies in the Vendor Portal, including examples, see [Configure RBAC Policies](/vendor/team-management-rbac-configuring). For a full list of available RBAC resources, see [RBAC Resource Names](/vendor/team-management-rbac-resource-names). ## Development workflow In a development workflow (which runs multiple times per day and is triggered by a commit to the application code repository), the source code is built and the application is deployed to clusters for testing. Additionally, for applications managed in the Replicated vendor portal, a release is created and promoted to a channel in the Replicated Vendor Portal where it can be shared with internal teams. The following diagram shows the recommended development workflow, where a commit to the application code repository triggers the source code to be built and the application to be deployed to clusters for testing: ![Development CI workflow](/images/ci-workflow-dev.png) [View a larger version of this image](/images/ci-workflow-dev.png) The following describes the recommended steps to include in release workflows, as shown in the diagram above: 1. [Define workflow triggers](#dev-triggers) 1. [Build source code](#dev-build) 1. [Prepare clusters, deploy, and test](#dev-deploy) ### Define workflow triggers {#dev-triggers} Run a development workflow on every commit to a branch in your code repository that is _not_ `main`. The following example shows defining a workflow trigger in GitHub Actions that runs the workflow when a commit is pushed to any branch other than `main`: ```yaml name: development-workflow-example on: push: branches: - '*' # matches every branch that doesn't contain a '/' - '*/*' # matches every branch containing a single '/' - '**' # matches every branch - '!main' # excludes main jobs: ... ``` ### Build source code {#dev-build} Add one or more jobs to compile your application source code and build images. The build jobs that you create vary depending upon your application and your CI/CD platform. For additional guidance, see the documentation for your CI/CD platform. ### Prepare clusters, deploy, and test {#dev-deploy} Add a job with the following steps to prepare clusters with CMX, deploy the application, and run tests: 1. Use CMX to prepare one or more clusters and deploy the application. Consider the following recommendations: * For development workflows, Replicated recommends that you use the `cluster prepare` command to provision one or more clusters with CMX. The `cluster prepare` command creates a cluster, creates a release, and installs the release in the cluster, without the need to promote the release to a channel or create a temporary customer. See the [`cluster prepare`](/reference/replicated-cli-cluster-prepare) Replicated CLI command. Or, for GitHub Actions workflows, see the [prepare-cluster](https://github.com/replicatedhq/replicated-actions/tree/main/prepare-cluster) GitHub action. :::note The `cluster prepare` command is Beta. It is recommended for development only and is not recommended for production releases. For production releases, Replicated recommends that you use the `cluster create` command instead. For more information, see [Create cluster matrix and deploy](#rel-deploy) in _Release Workflow_ below. ::: * The type and number of clusters that you choose to provision as part of a development workflow depends on how frequently you intend the workflow to run. For example, for workflows that run multiple times a day, you might prefer to provision cluster distributions that can be created quickly, such as kind clusters. 1. Run tests, such as integration, smoke, and canary tests. For more information about recommended types of tests to run, see [Best Practices and Recommendations](/vendor/ci-overview#best-practices-and-recommendations) in _About Integrating with CI/CD_. 1. After the tests complete, remove the cluster. Alternatively, if you used the `--ttl` flag with the `cluster prepare` command, the cluster is automatically removed when the time period provided is reached. See the [`cluster remove`](/reference/replicated-cli-cluster-prepare) Replicated CLI command. Or, for GitHub Actions workflows, see the [remove-cluster](https://github.com/replicatedhq/replicated-actions/tree/main/remove-cluster) action. ## CMX-only development workflow In a development workflow (which runs multiple times per day and is triggered by a commit to the application code repository), the source code is built and the application is deployed to clusters for testing. This example development workflow does _not_ create releases or customers in the Replicated vendor platform. This workflow is useful for applications that are not distributed or managed in the Replicated platform. The following describes the recommended steps to include in a development workflow using CMX: 1. [Define workflow triggers](#dev-triggers) 1. [Build source code](#dev-build) 1. [Create cluster matrix, deploy, and test](#dev-deploy) ### Define workflow triggers {#dev-triggers} Run a development workflow on every commit to a branch in your code repository that is _not_ `main`. The following example shows defining a workflow trigger in GitHub Actions that runs the workflow when a commit is pushed to any branch other than `main`: ```yaml name: development-workflow-example on: push: branches: - '*' # matches every branch that doesn't contain a '/' - '*/*' # matches every branch containing a single '/' - '**' # matches every branch - '!main' # excludes main jobs: ... ``` ### Build source code {#dev-build} Add one or more jobs to compile your application source code and build images. The build jobs that you create vary depending upon your application and your CI/CD platform. For additional guidance, see the documentation for your CI/CD platform. ### Create cluster matrix, deploy, and test {#dev-deploy} Add a job with the following steps to provision clusters with CMX, deploy your application to the clusters, and run tests: 1. Use CMX to create a matrix of different Kubernetes cluster distributions and versions to run tests against. See the [cluster create](/reference/replicated-cli-cluster-create) Replicated CLI command. Or, for GitHub Actions workflows, see the [create-cluster](https://github.com/replicatedhq/replicated-actions/tree/main/create-cluster) action. The following example shows creating a matrix of clusters of different distributions and versions using GitHub Actions: ```yaml # github actions cluster matrix example compatibility-matrix-example: runs-on: ubuntu-22.04 strategy: matrix: cluster: - {distribution: kind, version: "1.25"} - {distribution: kind, version: "1.26"} - {distribution: eks, version: "1.26"} - {distribution: gke, version: "1.27"} - {distribution: openshift, version: "4.13.0-okd"} ``` 1. For each cluster created, use the cluster's kubeconfig to update Kubernetes context and then install the target application in the cluster. For more information about accessing the kubeconfig for clusters created with CMX, see [cluster kubeconfig](/reference/replicated-cli-cluster-kubeconfig). 1. Run tests, such as integration, smoke, and canary tests. For more information about recommended types of tests to run, see [Best Practices and Recommendations](/vendor/ci-overview#best-practices-and-recommendations) in _About Integrating with CI/CD_. 1. Delete the cluster when the tests complete. See the [cluster rm](/reference/replicated-cli-cluster-rm) Replicated CLI command. Or, for GitHub Actions workflows, see the [remove-cluster](https://github.com/replicatedhq/replicated-actions/tree/main/remove-cluster) action. ## Replicated Platform release workflow In a release workflow (which is triggered by an action such as a commit to `main` or a tag being pushed to the repository), the source code is built, the application is deployed to clusters for testing, and then the application is made available to customers. In this example release workflow, a release is created and promoted to a channel in the Replicated vendor platform so that it can be installed by internal teams or by customers. The following diagram demonstrates a release workflow that promotes a release to the Beta channel when a tag with the format `"v*.*.*-beta.*"` is pushed: ![Workflow that promotes to Beta channel](/images/ci-workflow-beta.png) [View a larger version of this image](/images/ci-workflow-beta.png) The following describes the recommended steps to include in release workflows, as shown in the diagram above: 1. [Define workflow triggers](#rel-triggers) 1. [Build source code](#rel-build) 1. [Create a release and promote to a temporary channel](#rel-release) 1. [Create cluster matrix, deploy, and test](#rel-deploy) 1. [Promote to a shared channel](#rel-promote) 1. [Archive the temporary channel and customer](#rel-cleanup) ### Define workflow triggers {#rel-triggers} Create unique workflows for promoting releases to your team's internal-only, beta, and stable channels. Define unique event triggers for each of your release workflows so that releases are only promoted to a channel when a given condition is met: * On every commit to the `main` branch in your code repository, promote a release to the channel that your team uses for internal testing (such as the default Unstable channel). The following example shows a workflow trigger in GitHub Actions that runs the workflow on commits to `main`: ```yaml name: unstable-release-example on: push: branches: - 'main' jobs: ... ``` * On pushing a tag that contains a version label with the semantic versioning format `x.y.z-beta-n` (such as `1.0.0-beta.1` or `v1.0.0-beta.2`), promote a release to your team's Beta channel. The following example shows a workflow trigger in GitHub Actions that runs the workflow when a tag that matches the format `v*.*.*-beta.*` is pushed: ```yaml name: beta-release-example on: push: tags: - "v*.*.*-beta.*" jobs: ... ``` * On pushing a tag that contains a version label with the semantic versioning format `x.y.z` (such as `1.0.0` or `v1.0.01`), promote a release to your team's Stable channel. The following example shows a workflow trigger in GitHub Actions that runs the workflow when a tag that matches the format `v*.*.*` is pushed: ```yaml name: stable-release-example on: push: tags: - "v*.*.*" jobs: ... ``` ### Build source code {#rel-build} Add one or more jobs to compile your application source code and build images. The build jobs that you create vary depending upon your application and your CI/CD platform. For additional guidance, see the documentation for your CI/CD platform. ### Create a release and promote to a temporary channel {#rel-release} Add a job that creates and promotes a release to a temporary channel. This allows the release to be installed for testing in the next step. See the [release create](/reference/replicated-cli-release-create) Replicated CLI command. Or, for GitHub Actions workflows, see [create-release](https://github.com/replicatedhq/replicated-actions/tree/main/create-release). Consider the following requirements and recommendations: * Use a consistent naming pattern for the temporary channels. Additionally, configure the workflow so that a new temporary channel with a unique name is created each time that the release workflow runs. * Use semantic versioning for the release version label. :::note If semantic versioning is enabled on the channel where you promote the release, then the release version label _must_ be a valid semantic version number. See [Semantic Versioning](releases-about#semantic-versioning) in _About Channels and Releases_. ::: * For Helm chart-based applications, the release version label must match the version in the `version` field of the Helm chart `Chart.yaml` file. To automatically update the `version` field in the `Chart.yaml` file, you can define a step in this job that updates the version label before packaging the Helm chart into a `.tgz` archive. * For releases that will be promoted to a customer-facing channel such as Beta or Stable, Replicated recommends that the version label for the release matches the tag that triggered the release workflow. For example, if the tag `1.0.0-beta.1` was used to trigger the workflow, then the version label for the release is also `1.0.0-beta.1`. ### Create cluster matrix, deploy, and test {#rel-deploy} Add a job with the following steps to provision clusters with CMX, deploy the release to the clusters, and run tests: 1. Create a temporary customer for installing the release. See the [customer create](/reference/replicated-cli-customer-create) Replicated CLI command. Or, for GitHub Actions workflows, see the [create-customer](https://github.com/replicatedhq/replicated-actions/tree/main/create-customer) action. 1. Use CMX to create a matrix of different Kubernetes cluster distributions and versions to run tests against. See the [cluster create](/reference/replicated-cli-cluster-create) Replicated CLI command. Or, for GitHub Actions workflows, see the [create-cluster](https://github.com/replicatedhq/replicated-actions/tree/main/create-cluster) action. Consider the following recommendations: * For release workflows, Replicated recommends that you run tests against multiple clusters of different Kubernetes distributions and versions. To help build the matrix, you can review the most common Kubernetes distributions and versions used by your customers on the **Customers > [Customer Name] > Reporting** page in the Replicated vendor portal. For more information, see [Customer Reporting](/vendor/customer-reporting). * When using the Replicated CLI, a list of representative customer instances can be obtained using the `api get` command. For example, `replicated api get /v3/app/[APP_ID]/cluster-usage | jq .` You can further filter these results by `channel_id`, `channel_sequence`, and `version_label`. * GitHub Actions users can also use the `get-customer-instances` action to automate the creation of a cluster matrix based on the distributions of clusters where instances of your application are installed and running. For more information, see the [example workflow](https://github.com/replicatedhq/replicated-actions/blob/main/example-workflows/development-dynamic.yaml) that makes use of [get-customer-instances](https://github.com/replicatedhq/replicated-actions/tree/main/get-customer-instances) in GitHub. The following example shows creating a matrix of clusters of different distributions and versions using GitHub Actions: ```yaml # github actions cluster matrix example compatibility-matrix-example: runs-on: ubuntu-22.04 strategy: matrix: cluster: - {distribution: kind, version: "1.25.3"} - {distribution: kind, version: "1.26.3"} - {distribution: eks, version: "1.26"} - {distribution: gke, version: "1.27"} - {distribution: openshift, version: "4.13.0-okd"} ``` 1. For each cluster created, use the cluster's kubeconfig to update Kubernetes context and then install the target application in the cluster. For more information about accessing the kubeconfig for clusters created with CMX, see [cluster kubeconfig](/reference/replicated-cli-cluster-kubeconfig). For more information about installing in an existing cluster, see: * [Installing with Helm](/vendor/install-with-helm) * [Online Installation in Existing Clusters with KOTS](/enterprise/installing-existing-cluster) 1. Run tests, such as integration, smoke, and canary tests. For more information about recommended types of tests to run, see [Best Practices and Recommendations](/vendor/ci-overview#best-practices-and-recommendations) in _About Integrating with CI/CD_. 1. Delete the cluster when the tests complete. See the [cluster rm](/reference/replicated-cli-cluster-rm) Replicated CLI command. Or, for GitHub Actions workflows, see the [remove-cluster](https://github.com/replicatedhq/replicated-actions/tree/main/remove-cluster) action. ### Promote to a shared channel {#rel-promote} Add a job that promotes the release to a shared internal-only or customer-facing channel, such as the default Unstable, Beta, or Stable channel. See the [release promote](/reference/replicated-cli-release-promote) Replicated CLI command. Or, for GitHub Actions workflows, see the [promote-release](https://github.com/replicatedhq/replicated-actions/tree/main/promote-release) action. Consider the following requirements and recommendations: * Replicated recommends that you include the `--version` flag with the `release promote` command to explicitly declare the version label for the release. Use the same version label that was used when the release was created as part of [Create a release and promote to a temporary channel](#rel-release) above. Although the `--version` flag is not required, declaring the same release version label during promotion provides additional consistency that makes the releases easier to track. * The channel to which the release is promoted depends on the event triggers that you defined for the workflow. For example, if the workflow runs on every commit to the `main` branch, then promote the release to an internal-only channel, such as Unstable. For more information, see [Define Workflow Triggers](#rel-triggers) above. * Use the `--release-notes` flag to include detailed release notes in markdown. * For release versions that must not be skipped during upgrades (such as versions that include a required database migration), use the `--required` flag to mark the release as required. This flag can be used with both `release create --promote` and `release promote` commands. For more information about required releases, see [Required Releases](/vendor/releases-about#required-releases) in _About Channels and Releases_. ### Archive the temporary channel and customer {#rel-cleanup} Finally, add a job to archive the temporary channel and customer that you created. This ensures that these artifacts are removed from your Replicated team and that they do not have to be manually archived after the release is promoted. See the [channel rm](/reference/replicated-cli-channel-rm) Replicated CLI command and the [customer/\{customer_id\}/archive](https://replicated-vendor-api.readme.io/reference/archivecustomer) endpoint in the Vendor API v3 documentation. Or, for GitHub Actions workflows, see the [archive-channel](https://github.com/replicatedhq/replicated-actions/tree/main/archive-channel) and [archive-customer](https://github.com/replicatedhq/replicated-actions/tree/main/archive-customer) actions. --- # CMX usage history This topic describes using the Replicated Vendor Portal to understand Replicated Compatibility Matrix (CMX) usage across your team. ## View historical usage The **Compatibility Matrix > History** page provides historical information about both clusters and VMs, as shown below: ![Compatibility Matrix History Page](/images/compatibility-matrix-history.png) [View a larger version of this image](/images/compatibility-matrix-history.png) The **History** page displays clusters and VMs with one of the following statuses: * Terminated * Error * Queued Timeout. A Queued Timeout status indicates that the cluster or VM was automatically removed after being in a _queued_ state for more than 24 hours. The top of the **History** page displays the total number of non-running clusters and VMs in the selected time period as well as the total cost and usage time for the non-running resources. The total cost is calculated at termination and is based on the time the resource was running. Clusters and VMs that never entered the _running_ state are not included in the total cost and usage time. The table includes cluster and VM entries with the following columns: - **Name:** The name of the cluster or VM. - **By:** The actor that created the resource. - **Cost:** The cost of the resource. This is calculated at termination and is based on the time the resource was running. - **Distribution:** The distribution and version of the resource. For example, `kind 1.32.1`. - **Type:** The distribution type of the resource. Kubernetes clusters are listed as `kubernetes` and VMs are listed as `vm`. - **Status:** The status of the resource. For example `terminated` or `error`. - **Instance:** The instance type of the resource. For example `r1.small`. - **Nodes:** The node count for "kubernetes" resources. VMs do not use this field. - **Node Groups:** The node group count for "kubernetes" resources. VMs do not use this field. - **Created At:** The time the resource was created. - **Running At:** The time the resource started running. For billing purposes, this is the time when Replicated began charging for the resource. - **Terminated At:** The time the resource was terminated. For billing purposes, this is the time when Replicated stopped charging for the resource. - **TTL:** The time-to-live for the resource. This is the maximum amount of time the resource can run before it is automatically terminated. - **Duration:** The total time the resource was running. This is the time between the `running` and `terminated` states. - **Tag:** Any tags that were applied to the resource. ## Filter and sort usage history Each of the fields on the **History** page can be filtered and sorted. To sort by a specific field, click on the column header. To filter by a specific field, click on the filter icon in the column header, then use each specific filter input to filter the results, as shown below: ![Compatibility Matrix History Page, filter input](/images/compatibility-matrix-column-filter-input.png) [View a larger version of this image](/images/compatibility-matrix-column-filter-input.png) ## Get usage history with the vendor API v3 For more information about using the Vendor API v3 to get CMX usage history information, see the following API endpoints within the Vendor API v3 documentation: * [/v3/cmx/stats](https://replicated-vendor-api.readme.io/reference/getcmxstats) * [/v3/vms](https://replicated-vendor-api.readme.io/reference/listvms) * [/v3/clusters](https://replicated-vendor-api.readme.io/reference/listclusters) * [/v3/cmx/history](https://replicated-vendor-api.readme.io/reference/listcmxhistory) For examples of using these endpoints, see the sections below. ### Credit balance and summarized usage You can use the `/v3/cmx/stats` endpoint to get summarized usage information in addition to your CMX credit balance. This endpoint returns: - **`cluster_count`:** The total number of terminated clusters. - **`vm_count`:** The total number of terminated VMs. - **`usage_minutes`:** The total number of billed usage minutes. - **`cost`:** The total cost of the terminated clusters and VMs in cents. - **`credit_balance`:** The remaining credit balance in cents. ```shell curl --request GET \ --url https://api.replicated.com/vendor/v3/customers \ --header 'Accept: application/json' \ --header 'Authorization: $REPLICATED_API_TOKEN' {"cluster_count":2,"vm_count":4,"usage_minutes":152,"cost":276,"credit_balance":723}% ``` The `v3/cmx/stats` endpoint also supports filtering by `start-time` and `end-time`. For example, the following request gets usage information for January 2025: ```shell curl --request GET \ --url 'https://api.replicated.com/vendor/v3/cmx/stats?start-time=2025-01-01T00:00:00Z&end-time=2025-01-31T23:59:59Z' \ --header 'Authorization: $REPLICATED_API_TOKEN' \ --header 'accept: application/json' ``` ### Currently active clusters To get a list of active clusters: ```shell curl --request GET \ --url 'https://api.replicated.com/vendor/v3/clusters' \ --header 'Authorization: $REPLICATED_API_TOKEN' \ --header 'accept: application/json' ``` You can also use a tool such as `jq` to filter and iterate over the output: ```shell curl --request GET \ --url 'https://api.replicated.com/vendor/v3/clusters' \ --header 'Authorization: $REPLICATED_API_TOKEN' \ --header 'accept: application/json' | \ jq '.clusters[] | {name: .name, ttl: .ttl, distribution: .distribution, version: .version}' { "name": "friendly_brown", "ttl": "1h", "distribution": "kind", "version": "1.32.1" } ``` ### Currently active virtual machines To get a list of active VMs: ```shell curl --request GET \ --url 'https://api.replicated.com/vendor/v3/vms' \ --header 'Authorization: $REPLICATED_API_TOKEN' \ --header 'accept: application/json' ``` ### Historical usage To fetch historical usage information: ```shell curl --request GET \ --url 'https://api.replicated.com/vendor/v3/cmx/history' \ --header 'Authorization: $REPLICATED_API_TOKEN' \ --header 'accept: application/json' ``` You can also filter the response from the `/v3/cmx/history` endpoint by `distribution-type`, which allows you to get a list of either clusters or VMs: - **For clusters use `distribution-type=kubernetes`:** ```shell curl --request GET \ --url 'https://api.replicated.com/vendor/v3/cmx/history?distribution-type=kubernetes' \ --header 'Authorization: $REPLICATED_API_TOKEN' \ --header 'accept: application/json' ``` - **For VMs use `distribution-type=vm`:** ```shell curl --request GET \ --url 'https://api.replicated.com/vendor/v3/cmx/history?distribution-type=vm' \ --header 'Authorization: $REPLICATED_API_TOKEN' \ --header 'accept: application/json' ``` ### Filtering endpoint results Each of these endpoints supports pagination and filtering. You can use the following query parameters to filter the results. :::note Each of the examples below uses the `v3/cmx/history` endpoint, but the same query parameters can be used with the other endpoints as well. ::: - **Pagination:** Use the `pageSize` and `currentPage` query parameters to paginate through the results: ```shell curl --request GET \ --url 'https://api.replicated.com/vendor/v3/cmx/history?pageSize=10¤tPage=1' \ --header 'Authorization: $REPLICATED_API_TOKEN' \ --header 'accept: application/json' ``` - **Filter by date:** Use the `start-time` and `end-time` query parameters to filter the results by a specific date range: ```shell curl --request GET \ --url 'https://api.replicated.com/vendor/v3/cmx/history?start-time=2025-01-01T00:00:00Z&end-time=2025-01-31T23:59:59Z' \ --header 'Authorization: $REPLICATED_API_TOKEN' \ --header 'accept: application/json' ``` - **Sort by:** Use the `tag-sort-key` query parameter to sort the results by a specific field. The field can be any of the fields returned in the response. By default, the results are sorted in ascending order, use `sortDesc=true` to sort in descending order: ```shell curl --request GET \ --url 'https://api.replicated.com/vendor/v3/cmx/history?tag-sort-key=created_at&sortDesc=true' \ --header 'Authorization: $REPLICATED_API_TOKEN' \ --header 'accept: application/json' ``` - **Tag filters:** Use the `tag-filter` query parameter to filter the results by a specific tag: ```shell curl --request GET \ --url 'https://api.replicated.com/vendor/v3/cmx/history?tag-filter=tag1' \ --header 'Authorization: $REPLICATED_API_TOKEN' \ --header 'accept: application/json' ``` - **Actor filters:** Use the `actor-filter` query parameter to filter the actor that created the resource, or the type of actor such as `Web UI` or `Replicated CLI`: ```shell curl --request GET \ --url 'https://api.replicated.com/vendor/v3/cmx/history?actor-filter=name' \ --header 'Authorization: $REPLICATED_API_TOKEN' \ --header 'accept: application/json' ``` :::note If any filter is passed for an object that does not exist, no warning is given. For example, if you filter by `actor-filter=name` and there are no results the response will be empty. ::: --- # About application delivery ## Publish release artifacts Publish releases in multiple formats to support different installation methods and customer environments. Some enterprise customers with Kubernetes expertise will install in their own cluster. Others will install on a VM or bare metal server. Enterprises with strict security requirements might deploy software in air gap environments with no outbound internet access. A vendor might need to publish all of the following for a single release: * Helm charts and container images * Downloadable archives containing release images for air gap installations * Installation scripts for Kubernetes clusters or VMs Cryptographically sign all release artifacts so that enterprise customers can verify the authenticity and integrity of the software before installing. ### Supply chain metadata With the Enterprise Portal Security Center, you can include supply chain metadata for each release. This provides proof that your software supply chain is secure and traceable. For example: * SBOMs (Software Bill of Materials) generated in SPDX JSON format * Results of vulnerability scans, including CVE severity and affected images For more information, see [About the Security Center](/vendor/security-center-about). ## About the Enterprise Portal The Enterprise Portal is a customizable, web-based portal for your customers. From the Enterprise Portal, customers can: * View install and update instructions for Embedded Cluster and Helm CLI installations * Manage their team members and service accounts * Upload support bundles * View insights about their active and inactive instances The following shows an example of the Enterprise Portal dashboard: ![Enterprise Portal dashboard](/images/enterprise-portal-dashboard.png) [View a larger version of this image](/images/enterprise-portal-dashboard.png) ### Enterprise Portal access Customers access the Enterprise Portal outside their installation environment at a custom domain that you specify. The following diagram shows how customers use the Enterprise Portal to access release assets and installation instructions, and upload support bundles: ![Customer uses install instructions in enterprise portal to install a release](/images/enterprise-portal-overview.png) [View a larger version of this image](/images/enterprise-portal-overview.png) As shown in the diagram, licensed customers log in to the Enterprise Portal to access installation and update instructions. The Enterprise Portal tracks installation attempts and progress, then shares those insights to the Vendor Portal. Customers can also upload support bundles, which become available to you in the Vendor Portal. For more information, see [About the Enterprise Portal](enterprise-portal-v2-about). ## Preflight checks Define preflight checks that customers run before installing to validate that their environment meets your application's requirements. Preflight checks increase the success rate of installations and upgrades by catching issues before they cause failures. For more information, see [About Preflight Checks and Support Bundles](preflight-support-bundle-about). ## Guided installation experience [Embedded Cluster](/embedded-cluster/v3/embedded-overview) provides a guided installation experience through a web-based UI that walks end customers through configuration, preflight validation, and deployment. This makes it simpler for less technical customers to complete installation tasks, such as providing their license or configuring the deployment, without editing YAML files directly. This reduces installation errors and support issues related to installation. For Helm CLI installations, the [Enterprise Portal](/vendor/enterprise-portal-v2-about) provides install and update instructions with copy-paste commands tailored to the customer's environment and configuration. --- # About installation options Enterprise customers deploy software in a wide range of environments, from managed Kubernetes clusters to VMs and bare metal servers. These environments can be online or air-gapped. Vendors must support this spectrum without multiplying the release artifacts and install paths they maintain. Replicated supports two installation methods: the Helm CLI for existing Kubernetes clusters, and Embedded Cluster for VMs and bare metal servers. ## Installations with the Helm CLI in an existing cluster Helm is a popular open source package manager for Kubernetes applications. Many ISVs use Helm to configure and deploy Kubernetes applications because it provides a consistent, reusable, and sharable packaging format. For more information, see the [Helm documentation](https://helm.sh/docs). The following diagram shows how customers install Helm charts distributed with Replicated in online (internet-connected) environments: diagram of a helm chart in a custom environment [View a larger version of this image](/images/helm-install-diagram.png) As shown in the diagram, customers install your Helm chart by authenticating to the [Replicated proxy registry](/vendor/private-images-about) with their unique license ID. This ensures that every customer who installs your chart has a valid, unexpired license. After logging in, they run `helm install` to install the chart. For Helm CLI installations, customers can optionally run preflight checks before installing to verify that their cluster meets your application's requirements. For more information, see [Define Preflight Checks](preflight-defining). ## Installations with Embedded Cluster on a VM Replicated Embedded Cluster allows you to distribute a Kubernetes cluster and your application together as a single appliance. Enterprise users install, update, and manage the application and the cluster in tandem on a VM or bare metal server. Embedded Cluster uses the open source Kubernetes distribution [k0s](https://k0sproject.io/). Embedded Cluster provides a built-in UI that guides users through installation and upgrades. This includes license validation, preflight checks, and application configuration. Cluster infrastructure updates alongside application updates, so users do not need to manage Kubernetes separately. Vendors configure the [Embedded Cluster Config](/embedded-cluster/v3/embedded-config) to define the cluster and installation. This includes optional Helm extensions that deploy additional components before your application. For more information, see [Embedded Cluster Overview](/embedded-cluster/v3/embedded-overview). ## Supporting both installation methods from the same release With Replicated, you support both Helm CLI and Embedded Cluster installations from a single release. You package your application as Helm charts, and each release can include an Embedded Cluster Config for VM-based installations. You maintain one set of artifacts while giving customers the flexibility to choose the method that fits their environment. For more information about creating releases, see [About releasing your application](concepts-release). --- # About customer licensing Licensing codifies the agreements in the software contract between the vendor and the enterprise customer. It makes those agreements available to the application through a license server at installation and runtime. Licensing is a cross-functional concern: * **Sales teams** need license entitlements integrated with CRM tools like Salesforce so that entitlements can be updated when contracts change. * **Support teams** need the license as a unique customer identifier to get visibility into entitlements and product usage. * **Engineering teams** need application logic that controls access to features based on entitlements, without requiring code changes each time a license agreement changes. ## About customer records In the Replicated Vendor Portal, each licensed end customer has a customer record. The record includes the customer's license, which defines their entitlements, expiration date, release channel, and available installation methods. You can create and manage customer records in the Vendor Portal or with the Replicated CLI and Vendor API. For more information, see [Create and Manage Customers](releases-creating-customer). ## About custom license entitlements License agreements for enterprise software often include entitlements such as: * **Expiration dates** for trial or Proof-of-Concept licenses * **Feature-based entitlements** to control access to features available only under certain product plans * **Usage-based entitlements** to limit the number of instances, users, or nodes permitted * **Application-specific entitlements**, such as controlling which AI model images a customer can access Define custom license fields in the Vendor Portal to represent these entitlements. The [Replicated SDK](/vendor/replicated-sdk-overview) provides an in-cluster API that your application queries at runtime to retrieve the customer's current entitlements. For more information, see [About Customers and Licensing](licenses-about). ## Use license fields in custom metrics In most cases, vendors rely on the license agreement to enforce entitlements, as enterprise customers avoid violating a software contract. Rather than blocking usage in code, most vendors track usage that exceeds the contract and reconcile at renewal. The exception is expiration dates, which you can enforce directly and extend as needed. Measuring usage surfaces data to both the vendor and the customer. For vendors, it helps identify opportunities to expand the agreement. For customers, understanding their own usage helps them stay within contractual limits. For more information about custom metrics, see [Configure Custom Metrics](custom-metrics). ## Use license fields in preflight checks Reference license field values in preflight check specifications to validate that the customer's environment meets their license requirements. For example, write a preflight check that verifies the node count does not exceed the customer's licensed limit. For more information, see [Define Preflight Checks](preflight-defining). --- # About releasing your application Releasing refers to the process of delivering software to licensed users, ensuring that new features, improvements, and bug fixes get into the hands of the right customers at the right frequency. Key considerations for vendors when releasing modern enterprise software include: * Making application images available for customers to access securely * Packaging and publishing cryptographically signed release artifacts for different installation methods * Demonstrating the integrity of each release with supply chain metadata like SBOMs and provenance attestations * Managing release streams for different customers, including production (GA) and pre-release (alpha, beta) versions * Versioning releases with a consistent pattern so that customers understand backward compatibility ## About creating your application releases ### Packaging with Helm Replicated releases are built around Helm charts. You package your application as one or more Helm charts, which Replicated distributes through the proxy registry. Use standard Helm packaging practices and your existing CI/CD pipelines to build charts, then promote them as Replicated releases. For more information, see [Manage Releases with the CLI](releases-creating-cli). ### Release files for installers A release contains your application Helm charts and any additional manifests required for installation. For Embedded Cluster installations, releases also include an Embedded Cluster Config that defines the cluster, Helm extensions, and node roles. Replicated generates the appropriate installation assets for each method, including air gap bundles for disconnected environments. ### About iterating on releases with the Replicated platform Replicated supports a rapid iteration workflow where you create and test releases frequently. Use the Replicated CLI to create releases from your local environment or automate release creation in CI/CD. Promote releases to development channels and install them in test environments provisioned with Compatibility Matrix for fast feedback before promoting to customer-facing channels. ## About managing releases with channels Release management is important for ensuring that each release is made available to the right subset of users (including internal teams and customers). With Replicated, each release is promoted to one or more _channels_. Channels provide a way to progress releases through the software development lifecycle: from internal testing, to sharing with early-adopters, and finally to making the release generally available. Channels also control which customers are able to install a release. You assign each customer to a channel to define the releases that the customer can access. For more information, see [About Channels and Releases](releases-about). Channels create a logical separation between different types of releases. You can isolate releases intended for internal testing without manually granting or restricting access. Channels also provide flexibility in release frequency, letting you publish updates to internal channels more often while maintaining a different pace for GA releases. For example, vendors might keep separate channels for internal-only, experimental, beta, and generally available (GA) releases. Enterprise customers and internal users can then access the releases published to the channel where they are subscribed. ### Default unstable, beta, and stable channels Replicated includes the following channels by default: * **Unstable**: The Unstable channel is designed for internal testing and development. You can create and assign an internal test customer to the Unstable channel to install in a development environment. Replicated recommends that you do not license any of your external users against the Unstable channel. * **Beta**: The Beta channel is designed for release candidates and early-adopting customers. Replicated recommends that you promote a release to the Beta channel after it has passed automated testing in the Unstable channel. You can also choose to license early-adopting customers against this channel. * **Stable**: The Stable channel is designed for releases that are generally available. Replicated recommends that you assign most of your customers to the Stable channel. Customers licensed against the Stable channel only receive application updates when you promote a new release to the Stable channel. ## About testing your releases Testing ensures that enterprise software can be reliably distributed to current and future customer environments. Catching issues before the application reaches customers improves the customer experience and manages costs. Discovering and fixing a bug after the fact is more expensive than investing in testing up front. ### Customer-representative environments with compatibility matrix Testing self-hosted software presents a unique challenge: both the application and the customer’s environment can cause a failed deployment. The same application that installs successfully in one environment might fail in the next. Testing must go beyond unit and integration tests to verify functionality across different environments. Test on a variety of distributions representative of your customer base. For example, you might test on vanilla Kubernetes, a cloud provider (like GKE or AKS), and a more complex distribution like OpenShift. For more information, see [About Compatibility Matrix](testing-about). ## Provide secure access to images with the proxy registry A single release for an application contains all the artifacts required to install and run the application, such as container images or executables. When publishing a release for distribution to self-hosted environments, software vendors need to make images available to customers securely. For online (internet-connected) environments, proxy servers grant pull-through access to images. A proxy acts as an intermediary between your private image registry and the customer, so users access images without exposing registry credentials. Customers authenticate with credentials you determine, such as their unique license ID. For air gap environments, customers must have access to downloadable archives that contain the release images so they can push images to their own registry. For more information, see [About the Replicated Proxy Registry](/vendor/private-images-about). All image pull activity can be tracked for auditing and reporting. For more information, see [About Telemetry and Reporting](concepts-report). ## Release versioning Assign and increment version numbers using a consistent pattern, such as Semantic Versioning (SemVer). SemVer communicates backward compatibility using the format `MAJOR.MINOR.PATCH`. The versioning pattern should also dictate how you indicate pre-release versions. With SemVer, alpha or beta versions append a hyphen and label, such as `1.0.0-alpha` or `1.2.3-0.0.2`. A consistent pattern like SemVer is important because vendors often support multiple versions concurrently. Enterprise customers can understand that a patch release is backward compatible with the corresponding minor version. ## Automate releases with CI/CD Minimize manual intervention by automating release management and publishing in your CI/CD pipelines. For example, vendors can create workflows that run tests, publish releases to the right channel, and notify customers subscribed to the channel that a new version is available. For more information, see [About Integrating with CI/CD](ci-overview). --- # About telemetry and reporting With Replicated, you get out-of-the-box visibility into your application instances running in customer-controlled environments. For example: * Metadata about the environment where the application is running, such as the Kubernetes distribution, version, or cloud provider * Application uptime and service status * Adoption data such as the current application version Replicated also supports collecting custom metrics through the [Replicated SDK](/vendor/replicated-sdk-overview) for reporting on usage data such as daily or weekly active users. Unlike traditional observability with its firehose of logs, Replicated reporting focuses on application usage and functionality at a customer level. Access to reporting data empowers vendors to take more informed action: * **Feature prioritization**: Low feature usage can indicate the need to invest in usability, discoverability, or documentation. * **Security scoping**: Knowing which version each customer is running helps you scope and prioritize CVE disclosures and patches. * **Churn and growth signals**: Decreased usage for a customer can indicate churn risk, while increased usage can indicate expansion opportunities. * **Performance monitoring**: Uptime data helps troubleshoot issues and understand the resiliency of your software. ## Custom metrics with the SDK In addition to built-in insights like uptime and time to install, you can configure custom metrics to measure application instances in customer environments. Collect custom metrics from instances in both online and air gap environments. The following diagram demonstrates how a custom `activeUsers` metric is sent to the in-cluster API and displayed in the Vendor Portal: Custom metrics flowing from customer environment to Vendor Portal [View a larger version of this image](/images/custom-metrics-flow.png) For more information, see [Configure Custom Metrics](custom-metrics). ## Air gap telemetry Air gap instances run in environments without outbound internet access, so they cannot send telemetry to the Vendor Portal directly. Instead, the Replicated SDK collects and stores instance telemetry, including custom metrics, in a Kubernetes Secret in the customer environment. When a customer generates a support bundle, the stored telemetry is included automatically. When the bundle is uploaded to the Vendor Portal, the telemetry is associated with the correct customer and instance, and the Vendor Portal updates insights and event data accordingly. Replicated recommends collecting support bundles from air gap customers regularly (monthly or quarterly) to maintain complete telemetry data. The Vendor Portal handles overlapping event archives idempotently. For more information, see [Collect Telemetry for Air Gap Instances](telemetry-air-gap). ## Event notifications Define and subscribe to notifications in the Vendor Portal to receive alerts when specific events occur. Built-in event types and filters let you target the events that matter most. For example: * Customer Success Managers could get an email when a key customer uploads a support bundle * Support Engineers could get a Slack notification when a customer instance has been unhealthy for an extended period The following shows an example of the notifications **Overview** page: ![notifications overview page](/images/notifications-overview.png) [View a larger version of this image](/images/notifications-overview.png) For more information, see [Configure Event Notifications](/vendor/event-notifications). --- # About supporting your application Support refers to the services, tools, and documentation offered by a software vendor that help customers troubleshoot and resolve issues with their deployed instances. For enterprise software, a Service Level Agreement (SLA) typically defines support expectations: response times, standard support hours, and emergency support. Common expectations include 24/7 support hours and a response time under three hours for critical issues. Support teams aim to reduce the mean time to resolution (MTTR) while meeting SLA commitments. To do this, they need: * The training and expertise to address customer issues * Access to diagnostic information from the customer environment, such as logs, the Kubernetes distribution and version, and usage data ## The challenge of on-prem support Accessing diagnostic information is challenging for on-prem software because customer environments are often disconnected. Support engineers cannot SSH into machines or view observability data directly. Instead, vendors need tools that securely collect redacted information and run diagnostics. Replicated provides two tools for this: **preflight checks** and **support bundles**. ## Preflight checks Preflight checks run before or during installation to validate that the customer's environment meets application requirements. They catch issues like insufficient resources, missing dependencies, or incompatible Kubernetes versions before installation. For more information, see [Define Preflight Checks](preflight-defining). For example specs, see [Example Preflight Specs](preflight-examples). ## Support bundles Support bundles collect diagnostic information from a running instance: logs, cluster state, and application-specific data. Customers generate a bundle and upload it through the [Enterprise Portal](/vendor/enterprise-portal-v2-about) or share it with your support team. Uploaded bundles become available for analysis in the Vendor Portal. Support bundles are valuable beyond just your own troubleshooting. When you open a support request with Replicated, including a support bundle dramatically improves resolution time. Based on historical data, Severity 1 issues with an attached support bundle have been resolved up to three times faster. The Vendor Portal can also pre-populate support request details from the bundle, reducing the back-and-forth needed to get to a resolution. For more information, see [Add and Customize Support Bundles](support-bundle-customizing). For example specs, see [Example Support Bundle Specs](support-bundle-examples). ## Treating specs as living documents Preflight and support bundle specs should not be static. As customers deploy across diverse environments, you learn which checks matter and what diagnostic information helps most during escalations. Treat your specs as living documents that evolve over time: * **After support escalations**, add collectors or analyzers that capture what would have helped resolve the issue faster. If a ticket required manual root cause analysis, codify that investigation as a new analyzer. * **After installation failures**, add preflight checks that would have caught the issue. For example, if an install failed due to a missing storage class, add a check so the next customer gets a warning. * **As your application evolves**, update specs for new components and dependencies. A feature that adds a database dependency should include a preflight check for connectivity and a collector for database logs. The most effective vendors review specs regularly alongside support metrics, using ticket patterns to identify gaps in what they check and collect. ## Getting support from Replicated Replicated provides support to help you troubleshoot issues with the Replicated Platform and your application deployments. You can submit support requests and attach support bundles directly from the Vendor Portal. For more information, see [Submit a Support Request](support-submit-request). ## Documentation and self-service support High-quality documentation and community help articles help customers self-resolve issues. Keep documentation up to date with troubleshooting information for common issues to reduce repeat tickets. --- # About the configuration screen This topic describes the configuration screen on the Config tab in the Replicated Admin Console. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## About collecting configuration values When you distribute your application with Replicated KOTS, you can include a configuration screen in the Admin Console. This configuration screen is used to collect required or optional values from your users that are used to run your application. You can use regular expressions to validate user input for some fields, such as passwords and email addresses. For more information about how to add custom fields to the configuration screen, see [Create and Edit Configuration Fields](admin-console-customize-config-screen). If you use a Helm chart for your application, your users provide any values specific to their environment from the configuration screen, rather than in a Helm chart `values.yaml` file. This means that your users can provide configuration values through a user interface, rather than having to edit a YAML file or use `--set` CLI commands. The Admin Console configuration screen also allows you to control which options you expose to your users. For example, you can use the configuration screen to provide database configuration options for your application. Your users could connect your application to an external database by providing required values in the configuration screen, such as the host, port, and a username and password for the database. Or, you can also use the configuration screen to provide a database option that runs in the cluster as part of your application. For an example of this use case, see [Example: Adding Database Configuration Options](tutorial-adding-db-config). ## Viewing the configuration screen If you include a configuration screen with your application, users of your application can access the configuration screen from the Admin Console: * During application installation. * At any time after application installation on the Admin Console Config tab. ### Application installation The Admin Console displays the configuration screen when the user installs the application, after they upload their license file. The following shows an example of how the configuration screen displays during installation: ![configuration screen that displays during application install](/images/config-screen-sentry-enterprise-app-install.png) [View a larger version of this image](/images/config-screen-sentry-enterprise-app-install.png) ### Admin Console Config tab Users can access the configuration screen any time after they install the application by going to the Config tab in the Admin Console. The following shows an example of how the configuration screen displays in the Admin Console Config tab: ![configuration screen that displays in the Config tab](/images/config-screen-sentry-enterprise.png) [View a larger version of this image](/images/config-screen-sentry-enterprise.png) --- # Use conditional statements in configuration fields This topic describes how to use Replicated template functions in the Config custom resource to conditionally show or hide configuration fields for your application on the Replicated KOTS Admin Console **Config** page. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview The `when` property in the Config custom resource denotes configuration groups or items that are displayed on the Admin Console **Config** page only when a condition evaluates to true. When the condition evaluates to false, the group or item is not displayed. This lets you conditionally show or hide fields so your end customers only see the options that are relevant to them. You can use Go template functions to create conditional statements. Replicated provides a set of Go template functions that you can use to evaluate conditions like the user's environment, their license entitlements, and their previous configuration choices. For more information, see [About Replicated Template Functions](/reference/template-functions-about). For more information about the Config custom resource `when` property, see [when](/reference/custom-resource-config#when) in _Config_. ## Conditional statement examples This section includes examples of common types of conditional statements used in the `when` property of the Config custom resource. For additional examples of using conditional statements in the Config custom resource, see [Applications](https://github.com/replicatedhq/platform-examples/tree/main/applications) in the platform-examples repository in GitHub. ### Cluster distribution check It can be useful to show or hide configuration fields depending on the distribution of the cluster because different distributions often have unique requirements. In the following example, the `when` properties use the [Distribution](/reference/template-functions-static-context#distribution) template function to return the Kubernetes distribution of the cluster where Replicated KOTS is running. If the distribution of the cluster matches the specified distribution, then the `when` property evaluates to true. The following example uses: * Replicated [Distribution](/reference/template-functions-static-context#distribution) template function to return the Kubernetes distribution of the cluster * [eq](https://pkg.go.dev/text/template#hdr-Functions) (_equal_) Go binary operator to compare the rendered value of the Distribution template function to a string, then return the boolean truth of the comparison ```yaml # Replicated Config custom resource apiVersion: kots.io/v1beta1 kind: Config metadata: name: config-sample spec: groups: - name: example_settings title: My Example Config description: Example fields for using Distribution template function items: - name: gke_distribution type: label title: "You are deploying to GKE" # Use the eq binary operator to check if the rendered value # of the Distribution template function is equal to gke when: repl{{ eq Distribution "gke" }} - name: openshift_distribution type: label title: "You are deploying to OpenShift" when: repl{{ eq Distribution "openShift" }} - name: eks_distribution type: label title: "You are deploying to EKS" when: repl{{ eq Distribution "eks" }} ... ``` The following image shows how only the `gke_distribution` item appears on the app configuration screen: Config page with the text You are deploying to GKE ### Embedded Cluster distribution check It can be useful to show or hide configuration fields if the distribution of the cluster is [Replicated Embedded Cluster](/embedded-cluster/v3/embedded-overview) because you can include extensions in embedded cluster distributions to manage functionality such as ingress and storage. This means that embedded clusters frequently have fewer configuration options for the user. In the following example, the `ingress_type` field appears on the configuration page only when the distribution of the cluster is _not_ [Replicated Embedded Cluster](/embedded-cluster/v3/embedded-overview). This ensures that only users deploying to their own existing cluster are able to select the method for ingress. The following example uses: * Replicated [Distribution](/reference/template-functions-static-context#distribution) template function to return the Kubernetes distribution of the cluster * [ne](https://pkg.go.dev/text/template#hdr-Functions) (_not equal_) Go binary operator to compare the rendered value of the Distribution template function to a string, then return `true` if the values are not equal to one another ```yaml apiVersion: kots.io/v1beta1 kind: Config metadata: name: config spec: groups: # Ingress settings - name: ingress_settings title: Ingress Settings description: Configure Ingress items: - name: ingress_type title: Ingress Type help_text: | Select how traffic will ingress to the appliction. type: radio items: - name: ingress_controller title: Ingress Controller - name: load_balancer title: Load Balancer default: "ingress_controller" required: true when: 'repl{{ ne Distribution "embedded-cluster" }}' # Database settings - name: database_settings title: Database items: - name: postgres_type help_text: Would you like to use an embedded postgres instance, or connect to an external instance that you manage? type: radio title: Postgres default: embedded_postgres items: - name: embedded_postgres title: Embedded Postgres - name: external_postgres title: External Postgres ``` The following image shows how the `ingress_type` field does not appear when the distribution of the cluster is `embedded-cluster`. Only the `postgres_type` item appears: Config page with a Postgres field [View a larger version of this image](/images/config-example-distribution-not-ec.png) Conversely, when the distribution of the cluster is not `embedded-cluster`, both fields appear: Config page with Ingress and Postgres fields [View a larger version of this image](/images/config-example-distribution-not-ec-2.png) ### kURL distribution check It can be useful to show or hide configuration fields if the cluster was provisioned by Replicated kURL because kURL distributions often include add-ons to manage functionality such as ingress and storage. This means that kURL clusters frequently have fewer configuration options for the user. In the following example, the `when` property of the `not_kurl` group uses the IsKurl template function to evaluate if the cluster was provisioned by kURL. For more information about the IsKurl template function, see [IsKurl](/reference/template-functions-static-context#iskurl) in _Static Context_. ```yaml # Config custom resource apiVersion: kots.io/v1beta1 kind: Config metadata: name: config-sample spec: groups: - name: all_distributions title: Example Group description: This group always displays. items: - name: example_item title: This item always displays. type: text - name: not_kurl title: Non-kURL Cluster Group description: This group displays only if the cluster is not provisioned by kURL. when: 'repl{{ not IsKurl }}' items: - name: example_item_non_kurl title: The cluster is not provisioned by kURL. type: label ``` As shown in the image below, both the `all_distributions` and `non_kurl` groups are displayed on the **Config** page when KOTS is _not_ running in a kURL cluster: ![Config page displays both groups from the example](/images/config-example-iskurl-false.png) [View a larger version of this image](/images/config-example-iskurl-false.png) However, when KOTS is running in a kURL cluster, only the `all_distributions` group is displayed, as shown below: ![Config page displaying only the first group from the example](/images/config-example-iskurl-true.png) [View a larger version of this image](/images/config-example-iskurl-true.png) ### License field value equality check You can show or hide configuration fields based on the values in a license to ensure that users only see configuration options for the features and entitlements granted by their license. In the following example, the `when` property of the `new_feature_config` item uses the LicenseFieldValue template function to determine if the user's license contains a `newFeatureEntitlement` field that is set to `true`. For more information about the LicenseFieldValue template function, see [LicenseFieldValue](/reference/template-functions-license-context#licensefieldvalue) in _License Context_. ```yaml apiVersion: kots.io/v1beta1 kind: Config metadata: name: config-sample spec: groups: - name: example_settings title: My Example Config description: Example fields for using LicenseFieldValue template function items: - name: new_feature_config type: label title: "You have the new feature entitlement" when: '{{repl (LicenseFieldValue "newFeatureEntitlement") }}' ``` As shown in the image below, the **Config** page displays the `new_feature_config` item when the user's license contains `newFeatureEntitlement: true`: ![Config page displaying the text "You have the new feature entitlement"](/images/config-example-newfeature.png) [View a larger version of this image](/images/config-example-newfeature.png) ### Show messaging for unavailable features When all items in a group are hidden by `when` conditions, the entire group is hidden, including its title and description. To display a message to users when a feature is unavailable (for example, to inform them that they need to upgrade their license to access certain configuration options), add a `label` item to the group that is shown in the negated condition. In the following example, the `enterprise_features` group contains two items that are shown only when the user's license includes the `enterprise_features` field set to `true`. The `upgrade_notice` item uses `type: label` with a negated `when` condition so that it is displayed when the entitlement is missing, ensuring the group remains visible with an informational message. ```yaml apiVersion: kots.io/v1beta1 kind: Config metadata: name: config-sample spec: groups: - name: enterprise_features title: Enterprise Features description: Advanced configuration options. items: - name: advanced_setting title: Advanced Setting type: text when: '{{repl (LicenseFieldValue "enterprise_features" | ParseBool) }}' - name: another_advanced_setting title: Another Advanced Setting type: text when: '{{repl (LicenseFieldValue "enterprise_features" | ParseBool) }}' - name: upgrade_notice type: label title: "Upgrade your license to access these features." when: '{{repl not (LicenseFieldValue "enterprise_features" | ParseBool) }}' ``` In this example, when the `enterprise_features` license field is missing or false, only the `upgrade_notice` label is shown and the group remains visible. When the entitlement is present, the label is hidden and the actual configuration items are shown. ### License field value integer comparison You can show or hide configuration fields based on the values in a license to ensure that users only see configuration options for the features and entitlements granted by their license. You can also compare integer values from license fields to control the configuration experience for your users. The following example uses: * Replicated [LicenseFieldValue](/reference/template-functions-license-context#licensefieldvalue) template function to evaluate the number of seats permitted by the license * Sprig [atoi](https://masterminds.github.io/sprig/conversion.html) function to convert the string values returned by LicenseFieldValue to integers * [Go binary comparison operators](https://pkg.go.dev/text/template#hdr-Functions) `gt`, `lt`, `ge`, and `le` to compare the integers ```yaml # Replicated Config custom resource apiVersion: kots.io/v1beta1 kind: Config metadata: name: config-sample spec: groups: - name: example_group title: Example Config items: - name: small title: Small (100 or Fewer Seats) type: text default: Default for small teams # Use le and atoi functions to display this config item # only when the value of the numSeats entitlement is # less than or equal to 100 when: repl{{ le (atoi (LicenseFieldValue "numSeats")) 100 }} - name: medium title: Medium (101-1000 Seats) type: text default: Default for medium teams # Use ge, le, and atoi functions to display this config item # only when the value of the numSeats entitlement is # greater than or equal to 101 and less than or equal to 1000 when: repl{{ (and (ge (atoi (LicenseFieldValue "numSeats")) 101) (le (atoi (LicenseFieldValue "numSeats")) 1000)) }} - name: large title: Large (More Than 1000 Seats) type: text default: Default for large teams # Use gt and atoi functions to display this config item # only when the value of the numSeats entitlement is # greater than 1000 when: repl{{ gt (atoi (LicenseFieldValue "numSeats")) 1000 }} ``` As shown in the image below, if the user's license contains `numSeats: 150`, then the `medium` item is displayed on the **Config** page and the `small` and `large` items are not displayed: Config page displaying the Medium (101-1000 Seats) item [View a larger version of this image](/images/config-example-numseats.png) ### User-supplied value check You can show or hide configuration fields based on user-supplied values on the **Config** page to ensure that users only see options that are relevant to their selections. In the following example, the `database_host` and `database_passwords` items use the ConfigOptionEquals template function to evaluate if the user selected the `external` database option for the `db_type` item. For more information about the ConfigOptionEquals template function, see [ConfigOptionEquals](/reference/template-functions-config-context#configoptionequals) in _Config Context_. ```yaml apiVersion: kots.io/v1beta1 kind: Config metadata: name: config-sample spec: groups: - name: database_settings_group title: Database Settings items: - name: db_type title: Database Type type: radio default: external items: - name: external title: External Database - name: embedded title: Embedded Database - name: database_host title: Database Hostname type: text when: '{{repl (ConfigOptionEquals "db_type" "external")}}' - name: database_password title: Database Password type: password when: '{{repl (ConfigOptionEquals "db_type" "external")}}' ``` As shown in the images below, when the user selects the external database option, the `database_host` and `database_passwords` items are displayed. Alternatively, when the user selects the embedded database option, the items are _not_ displayed: ![Config page displaying the database host and password fields](/images/config-example-external-db.png) [View a larger version of this image](/images/config-example-external-db.png) ![Config page with embedded database option selected](/images/config-example-embedded-db.png) [View a larger version of this image](/images/config-example-embedded-db.png) ## Use multiple conditions in the `when` property You can use more than one template function in the `when` property to create more complex conditional statements. This allows you to show or hide configuration fields based on multiple conditions being true. The following example includes `when` properties that use both the ConfigOptionEquals and IsKurl template functions: ```yaml apiVersion: kots.io/v1beta1 kind: Config metadata: name: config-sample spec: groups: - name: ingress_settings title: Ingress Settings description: Configure Ingress items: - name: ingress_type title: Ingress Type help_text: | Select how traffic will ingress to the appliction. type: radio items: - name: ingress_controller title: Ingress Controller - name: load_balancer title: Load Balancer default: "ingress_controller" required: true when: 'repl{{ not IsKurl }}' - name: ingress_host title: Hostname help_text: Hostname used to access the application. type: text default: "hostname.example.com" required: true when: 'repl{{ and (not IsKurl) (ConfigOptionEquals "ingress_type" "ingress_controller") }}' - name: ingress_annotations type: textarea title: Ingress Annotations help_text: See your ingress controller’s documentation for the required annotations. when: 'repl{{ and (not IsKurl) (ConfigOptionEquals "ingress_type" "ingress_controller") }}' - name: ingress_tls_type title: Ingress TLS Type type: radio items: - name: self_signed title: Self Signed (Generate Self Signed Certificate) - name: user_provided title: User Provided (Upload a TLS Certificate and Key Pair) required: true default: self_signed when: 'repl{{ and (not IsKurl) (ConfigOptionEquals "ingress_type" "ingress_controller") }}' - name: ingress_tls_cert title: TLS Cert type: file when: '{{repl and (ConfigOptionEquals "ingress_type" "ingress_controller") (ConfigOptionEquals "ingress_tls_type" "user_provided") }}' required: true - name: ingress_tls_key title: TLS Key type: file when: '{{repl and (ConfigOptionEquals "ingress_type" "ingress_controller") (ConfigOptionEquals "ingress_tls_type" "user_provided") }}' required: true - name: load_balancer_port title: Load Balancer Port help_text: Port used to access the application through the Load Balancer. type: text default: "443" required: true when: 'repl{{ and (not IsKurl) (ConfigOptionEquals "ingress_type" "load_balancer") }}' - name: load_balancer_annotations type: textarea title: Load Balancer Annotations help_text: See your cloud provider’s documentation for the required annotations. when: 'repl{{ and (not IsKurl) (ConfigOptionEquals "ingress_type" "load_balancer") }}' ``` As shown in the image below, the configuration fields that are specific to the ingress controller display only when the user selects the ingress controller option and KOTS is _not_ running in a kURL cluster: ![Config page displaying the ingress controller options](/images/config-example-ingress-controller.png) [View a larger version of this image](/images/config-example-ingress-controller.png) Additionally, the options relevant to the load balancer display when the user selects the load balancer option and KOTS is _not_ running in a kURL cluster: ![Config page displaying the load balancer options](/images/config-example-ingress-load-balancer.png) [View a larger version of this image](/images/config-example-ingress-load-balancer.png) --- # Map user-supplied values This topic describes how to map the values that your users provide in the Replicated Admin Console configuration screen to your application. This topic assumes that you have already added custom fields to the Admin Console configuration screen by editing the Config custom resource. For more information, see [Create and Edit Configuration Fields](admin-console-customize-config-screen). :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Overview of mapping values You use the values that your users provide in the Admin Console configuration screen to render YAML in the manifest files for your application. For example, if you provide an embedded database with your application, you might add a field on the Admin Console configuration screen where users input a password for the embedded database. You can then map the password that your user supplies in this field to the Secret manifest file for the database in your application. For an example of mapping database configuration options in a sample application, see [Example: Adding Database Configuration Options](tutorial-adding-db-config). You can also conditionally deploy custom resources depending on the user input for a given field. For example, if a customer chooses to use their own database with your application rather than an embedded database option, it is not desirable to deploy the optional database resources such as a StatefulSet and a Service. For more information about including optional resources conditionally based on user-supplied values, see [Conditionally Including or Excluding Resources](packaging-include-resources). ## About mapping values with template functions To map user-supplied values, you use Replicated template functions. The template functions are based on the Go text/template libraries. To use template functions, you add them as strings in the custom resource manifest files in your application. For more information about template functions, including use cases and examples, see [About Replicated Template Functions](/reference/template-functions-about). For more information about the syntax of the template functions for mapping configuration values, see [Config Context](/reference/template-functions-config-context) in the _Template Functions_ section. ## Map user-supplied values Follow one of these procedures to map user inputs from the configuration screen, depending on if you use a Helm chart for your application: * **Without Helm**: See [Map Values to Manifest Files](#map-values-to-manifest-files). * **With Helm**: See [Map Values to a Helm Chart](#map-values-to-a-helm-chart). ### Map values to manifest files To map user-supplied values from the configuration screen to manifest files in your application: 1. In the [Vendor Portal](https://vendor.replicated.com/apps), click **Releases**. Then, click **View YAML** next to the desired release. 1. Open the Config custom resource manifest file that you created in the [Add Fields to the Configuration Screen](admin-console-customize-config-screen#add-fields-to-the-configuration-screen) procedure. The Config custom resource manifest file has `kind: Config`. 1. In the Config manifest file, locate the name of the user-input field that you want to map. **Example**: ```yaml apiVersion: kots.io/v1beta1 kind: Config metadata: name: my-application spec: groups: - name: smtp_settings title: SMTP Settings description: Configure SMTP Settings items: - name: smtp_host title: SMTP Hostname help_text: Set SMTP Hostname type: text ``` In the example above, the field name to map is `smtp_host`. 1. In the same release in the Vendor Portal, open the manifest file where you want to map the value for the field that you selected. 1. In the manifest file, use the ConfigOption template function to map the user-supplied value in a key value pair. For example: ```yaml hostname: '{{repl ConfigOption "smtp_host"}}' ``` For more information about the ConfigOption template function, see [Config Context](../reference/template-functions-config-context#configoption) in the _Template Functions_ section. **Example**: The following example shows mapping user-supplied TLS certificate and TLS private key files to the `tls.cert` and `tls.key` keys in a Secret custom resource manifest file. For more information about working with TLS secrets, including a strategy for re-using the certificates uploaded for the Admin Console itself, see the [Configuring Cluster Ingress](packaging-ingress) example. ```yaml apiVersion: v1 kind: Secret metadata: name: tls-secret type: kubernetes.io/tls data: tls.crt: '{{repl ConfigOption "tls_certificate_file" }}' tls.key: '{{repl ConfigOption "tls_private_key_file" }}' ``` 1. Save and promote the release to a development environment to test your changes. ### Map values to a Helm chart The `values.yaml` file in a Helm chart defines parameters that are specific to each environment in which the chart will be deployed. With Replicated KOTS, your users provide these values through the configuration screen in the Admin Console. You customize the configuration screen based on the required and optional configuration fields that you want to expose to your users. To map the values that your users provide in the Admin Console configuration screen to your Helm chart `values.yaml` file, you create a HelmChart custom resource. To map user inputs from the configuration screen to the `values.yaml` file: 1. In the [Vendor Portal](https://vendor.replicated.com/apps), click **Releases**. Then, click **View YAML** next to the desired release. 1. Open the Config custom resource manifest file that you created in the [Add Fields to the Configuration Screen](admin-console-customize-config-screen#add-fields-to-the-configuration-screen) procedure. The Config custom resource manifest file has `kind: Config`. 1. In the Config manifest file, locate the name of the user-input field that you want to map. **Example**: ```yaml apiVersion: kots.io/v1beta1 kind: Config metadata: name: my-application spec: groups: - name: smtp_settings title: SMTP Settings description: Configure SMTP Settings items: - name: smtp_host title: SMTP Hostname help_text: Set SMTP Hostname type: text ``` In the example above, the field name to map is `smtp_host`. 1. In the same release, create a HelmChart custom resource manifest file. A HelmChart custom resource manifest file has `kind: HelmChart`. For more information about the HelmChart custom resource, see [HelmChart](../reference/custom-resource-helmchart) in the _Custom Resources_ section. 1. In the HelmChart manifest file, copy and paste the name of the property from your `values.yaml` file that corresponds to the field that you selected from the Config manifest file under `values`: ```yaml values: HELM_VALUE_KEY: ``` Replace `HELM_VALUE_KEY` with the property name from the `values.yaml` file. 1. Use the ConfigOption template function to set the property from the `values.yaml` file equal to the corresponding configuration screen field: ```yaml values: HELM_VALUE_KEY: '{{repl ConfigOption "CONFIG_SCREEN_FIELD_NAME" }}' ``` Replace `CONFIG_SCREEN_FIELD_NAME` with the name of the field that you created in the Config custom resource. For more information about the KOTS ConfigOption template function, see [Config Context](../reference/template-functions-config-context#configoption) in the _Template Functions_ section. **Example:** ```yaml apiVersion: kots.io/v1beta1 kind: HelmChart metadata: name: samplechart spec: chart: name: samplechart chartVersion: 3.1.7 helmVersion: v3 useHelmInstall: true values: hostname: '{{repl ConfigOption "smtp_host" }}' ``` 1. Save and promote the release to a development environment to test your changes. --- # Use custom domains This topic describes how to use the Replicated Vendor Portal to add and manage custom domains to alias Replicated endpoints, including the Replicated registry, the Replicated proxy registry, the Replicated app service, the Replicated Enterprise Portal, and the Replicated Download Portal. For information about adding and managing custom domains with the Vendor API v3, see the [customHostnames](https://replicated-vendor-api.readme.io/reference/createcustomhostname) section in the Vendor API v3 documentation. For more information about custom domains, see [About Custom Domains](custom-domains). ## Add a custom domain in the Vendor Portal {#add-domain} To add and verify a custom domain: 1. In the [Vendor Portal](https://vendor.replicated.com), go to **Custom Domains**. 1. In the **Add custom domain** dropdown, select the target Replicated endpoint. :::note There is a known issue when using a custom domain for the Enterprise Portal if any of your customers use link transformers such as Microsoft Defender Safe Links. For more information, see [Known Issue](custom-domains#known-issue) in _About Custom Domains_. ::: The **Configure a custom domain** wizard opens. custom domain wizard [View a larger version of this image](/images/custom-domains-download-configure.png) 1. For **Domain**, enter the custom domain. Click **Save & continue**. 1. For **Create CNAME**, copy the text string and use it to create a CNAME record in your DNS account. Click **Continue**. 1. For **Verify ownership**, ownership will be validated automatically using an HTTP token when possible. If ownership cannot be validated automatically, copy the text string provided and use it to create a TXT record in your DNS account. Click **Validate & continue**. Your changes can take up to 24 hours to propagate. 1. For **TLS cert creation verification**, TLS verification will be performed automatically using an HTTP token when possible. If TLS verification cannot be performed automatically, copy the text string provided and use it to create a TXT record in your DNS account. Click **Validate & continue**. Your changes can take up to 24 hours to propagate. :::note If you set up a [CAA record](https://letsencrypt.org/docs/caa/) for this hostname, you must include all Certificate Authorities (CAs) that Cloudflare partners with. The following CAA records are required to ensure proper certificate issuance and renewal: ```dns @ IN CAA 0 issue "letsencrypt.org" @ IN CAA 0 issue "pki.goog; cansignhttpexchanges=yes" @ IN CAA 0 issue "ssl.com" @ IN CAA 0 issue "amazon.com" @ IN CAA 0 issue "cloudflare.com" @ IN CAA 0 issue "google.com" ``` Failing to include any of these CAs might prevent certificate issuance or renewal, which can result in downtime for your customers. For additional security, you can add an IODEF record to receive notifications about certificate requests: ```dns @ IN CAA 0 iodef "mailto:your-security-team@example.com" ``` ::: 1. For **Use Domain**, to set the new domain as the default, click **Yes, set as default**. Otherwise, click **Not now**. :::note Replicated recommends that you do _not_ set a domain as the default until you are ready for it to be used by customers. ::: After the verification checks for ownership and TLS certificate creation are complete, the Vendor Portal marks the domain as **Configured**. 1. (Optional) After a domain is marked as **Configured**, you can remove any TXT records that you created in your DNS account. ## Use custom domains After you add one or more custom domains in the Vendor Portal, you can configure your application to use the domains. ### Configure Enterprise Portal domains {#enterprise-portal} The New Enterprise Portal has its own domain settings. To add or manage a New Enterprise Portal custom domain, go to **Enterprise Portal > Domains**. Teams that use only the New Enterprise Portal do not see Download Portal domains on the **Custom Domains** page. In mixed mode, use **Custom Domains** for Classic Enterprise Portal and Download Portal domains. Use **Enterprise Portal > Domains** for New Enterprise Portal domains. ### Configure Embedded Cluster to use custom domains {#ec} You can configure Replicated Embedded Cluster to use your custom domains for the Replicated proxy registry and Replicated app service. For more information about Embedded Cluster, see [Embedded Cluster Overview](/embedded-cluster/v3/embedded-overview). To configure Embedded Cluster to use your custom domains for the proxy registry and app service: 1. In the [Embedded Cluster Config](/embedded-cluster/v3/embedded-config) spec for your application, add `domains.proxyRegistryDomain` and `domains.replicatedAppDomain`. Set each field to your custom domain for the given service. **Example:** ```yaml apiVersion: embeddedcluster.replicated.com/v1beta1 kind: Config spec: domains: # Your proxy registry custom domain proxyRegistryDomain: proxy.yourcompany.com # Your app service custom domain replicatedAppDomain: updates.yourcompany.com ``` For more information, see [domains](/embedded-cluster/v3/embedded-config#domains) in _Embedded Cluster Config_. 1. Add the Embedded Cluster Config to a new release. Promote the release to a channel that your team uses for testing, and install with Embedded Cluster in a development environment to test your changes. ### Set a default domain Setting a default domain is useful for ensuring that the same domain is used across channels for all your customers. When you set a custom domain as the default, it is used by default for all new releases promoted to any channel, as long as the channel does not have a different domain assigned in its channel settings. Only releases that are promoted to a channel _after_ you set a default domain use the new default domain. Any existing releases that were promoted before you set the default continue to use the same domain that they used previously. :::note In Embedded Cluster installations, the KOTS Admin Console will use the domains specified in the `domains.proxyRegistryDomain` and `domains.replicatedAppDomain` fields of the Embedded Cluster Config when making requests to the proxy registry and app service, regardless of the default domain or the domain assigned to the given release channel. For more information about using custom domains in Embedded Cluster installations, see [Configure Embedded Cluster to Use Custom Domains](#ec) above. ::: To set a custom domain as the default: 1. In the Vendor Portal, go to **Custom Domains**. 1. Next to the target domain, click **Set as default**. 1. In the confirmation dialog that opens, click **Yes, set as default**. ### Assign a domain to a channel {#channel-domain} You can assign a domain to an individual channel by editing the channel settings. When you specify a domain in the channel settings, new releases promoted to the channel use the selected domain even if there is a different domain set as the default on the **Custom Domains** page. Assigning a domain to a release channel is useful when you need to override either the default Replicated domain or a default custom domain for a specific channel. For example: * You need to use a different domain for releases promoted to your Beta and Stable channels. * You need to test a domain in a development environment before you set the domain as the default for all channels. :::note In Embedded Cluster installations, the KOTS Admin Console will use the domains specified in the `domains.proxyRegistryDomain` and `domains.replicatedAppDomain` fields of the Embedded Cluster Config when making requests to the proxy registry and app service, regardless of the default domain or the domain assigned to the given release channel. For more information about using custom domains in Embedded Cluster installations, see [Configure Embedded Cluster to Use Custom Domains](#ec) above. ::: To assign a custom domain to a channel: 1. In the Vendor Portal, go to **Channels** and click the settings icon for the target channel. 1. Under **Custom domains**, in the drop-down for the target Replicated endpoint, select the domain to use for the channel. For more information about channel settings, see [Channel Settings](releases-about#channel-settings) in _About Channels and Releases_. channel settings dialog [View a larger version of this image](/images/channel-settings.png) ## Reuse a custom domain for another application If you have configured a custom domain for one application, you can reuse the custom domain for another application in the same team without going through the ownership and TLS certificate verification process again. To reuse a custom domain for another application: 1. In the Vendor Portal, select the application from the dropdown list. 1. Click **Custom Domains**. 1. In the section for the target endpoint, click **Add your first custom domain** for your first domain, or click **Add new domain** for additional domains. The **Configure a custom domain** wizard opens. 1. In the text box, enter the custom domain name that you want to reuse. Click **Save & continue**. The last page of the wizard opens because the custom domain was verified previously. 1. Do one of the following: - Click **Set as default**. In the confirmation dialog that opens, click **Yes, set as default**. - Click **Not now**. You can come back later to set the domain as the default. The Vendor Portal shows shows that the domain has a Configured status because it was configured for a previous application, though it is not yet assigned as the default for this application. ## Remove a custom domain You can remove a custom domain at any time, but you should plan the transition so that you do not break any existing installations or documentation. Removing a custom domain for the Replicated registry, proxy registry, or Replicated app service will break existing installations that use the custom domain. Existing installations need to be upgraded to a version that does not use the custom domain before it can be removed safely. If you remove a custom domain for the download portal, it is no longer accessible using the custom URL. You will need to point customers to an updated URL. To remove a custom domain: 1. Log in to the [Vendor Portal](https://vendor.replicated.com) and click **Custom Domains**. 1. Verify that the domain is not set as the default nor in use on any channels. You can edit the domains in use on a channel in the channel settings. For more information, see [Channel Settings](releases-about#channel-settings) in _About Channels and Releases_. :::important When you remove a registry or Replicated app service custom domain, any installations that reference that custom domain will break. Ensure that the custom domain is no longer in use before you remove it from the Vendor Portal. ::: 1. Click **Remove** next to the unused domain in the list, and then click **Yes, remove domain**. --- # About custom domains This topic provides an overview and the limitations of using custom domains to alias the Replicated proxy registry, the Replicated app service, the Replicated Download Portal, and the Replicated registry. For information about adding and managing custom domains, see [Use Custom Domains](custom-domains-using). ## Overview You can use custom domains to alias Replicated endpoints by creating Canonical Name (CNAME) records for your domains. Replicated domains are external to your domain and can require additional security reviews by your customer. Using custom domains as aliases can bring the domains inside an existing security review and reduce your exposure. You can configure custom domains for the following services: - **Proxy registry:** Images can be proxied from external private registries using the Replicated proxy registry. By default, the proxy registry uses the domain `proxy.replicated.com`. Replicated recommends using a CNAME such as `proxy.{your app name}.com`. The image used by the [Replicated SDK](replicated-sdk-overview) Helm chart is automatically pulled through the Replicated proxy registry during deployment. This means that, when you add a custom domain for the proxy registry, the SDK image also uses that custom domain automatically. No additional configuration is required. For the default Replicated SDK image properties, see [values.yaml](https://github.com/replicatedhq/replicated-sdk/blob/main/chart/values.yaml#L52) in the replicated-sdk repository in GitHub. :::note If you use a custom domain for the proxy registry, you might see `/v2/token` authentication endpoints in logs or network traffic. These token requests are part of the standard Docker Registry v2 API and are expected behavior. For public images, these tokens are anonymous and do not contain sensitive information. ::: - **Replicated app service:** Upstream application YAML and metadata, including a license ID, are pulled from the app service. By default, this service uses the domain `replicated.app`. Replicated recommends using a CNAME such as `updates.{your app name}.com`. - **Enterprise Portal:** The Enterprise Portal is a web-based portal that provides end customers with a centralized location for managing their installation. By default, the Enterprise Portal uses the domain **`[DOMAIN].replicated.com`**. Replicated recommending using a CNAME such as `portal.{your app name}.com` or `enterprise.{your app name}.com`. - **Download Portal:** The Download Portal can be used to share customer license files, air gap bundles, and so on. By default, the Download Portal uses the domain `get.replicated.com`. Replicated recommends using a CNAME such as `portal.{your app name}.com` or `enterprise.{your app name}.com`. - **Replicated registry:** Images and Helm charts can be pulled from the Replicated registry. By default, the Replicated registry uses the domain `registry.replicated.com`. Replicated recommends using a CNAME such as `registry.{your app name}.com`. ## Limitations Using custom domains has the following limitations: - A single custom domain cannot be used for multiple endpoints. For example, a single domain can map to `registry.replicated.com` for any number of applications, but cannot map to both `registry.replicated.com` and `proxy.replicated.com`, even if the applications are different. - Custom domains cannot be used to alias `api.replicated.com` (legacy customer-facing APIs) or kURL. - Multiple custom domains can be configured, but only one custom domain can be the default for each Replicated endpoint. All configured custom domains work whether or not they are the default. - Each custom domain can only be used by one team. - For [Replicated Embedded Cluster](/embedded-cluster/v3/embedded-overview) installations, any Helm [`extensions`](/embedded-cluster/v3/embedded-config) that you add in the Embedded Cluster Config do not use custom domains. During deployment, Embedded Cluster pulls both the repo for the given chart and any images in the chart as written. Embedded Cluster does not rewrite image names to use custom domains. ## Known issue If you use a custom domain for the Replicated [Enterprise Portal](/vendor/enterprise-portal-about) and any of your customers use link transformers such as Microsoft Defender Safe Links, then there is a known issue where legitimate URLs in emails generated by the Enterprise Portal can break due to rewrapping. To avoid this issue, request a "Do not rewrite the following URLs" exclusion policy for your custom Enterprise Portal domain. --- # Configure custom metrics This topic describes how to configure an application to send custom metrics to the Replicated Vendor Portal. ## Overview In addition to the built-in insights displayed in the Vendor Portal by default (such as uptime and time to install), you can also configure custom metrics to measure instances of your application running customer environments. Custom metrics can be collected for application instances running in online or air gap environments. Custom metrics can be used to generate insights on customer usage and adoption of new features, which can help your team to make more informed prioritization decisions. For example: * Decreased or plateaued usage for a customer can indicate a potential churn risk * Increased usage for a customer can indicate the opportunity to invest in growth, co-marketing, and upsell efforts * Low feature usage and adoption overall can indicate the need to invest in usability, discoverability, documentation, education, or in-product onboarding * High usage volume for a customer can indicate that the customer might need help in scaling their instance infrastructure to keep up with projected usage ## How the SDK sends custom metrics to the Vendor Portal The Vendor Portal receives custom metrics from the Replicated SDK, which is installed in the cluster alongside the application. The SDK exposes an in-cluster API where you can configure your application to PATCH and POST metric payloads. When an application sends data to the API, the SDK sends the data (including any custom and built-in metrics) to the Replicated app service. The app service is located at `replicated.app` or at your custom domain. If any values in the metric payload are different from the current values for the instance, then a new event is generated and displayed in the Vendor Portal. This design reduces noise and helps you focus on actual changes in your customer deployments. For more information about how the Vendor Portal generates events, see [How the Vendor Portal Generates Events and Insights](/vendor/instance-insights-event-data#about-events) in _About Instance and Event Data_. The following diagram demonstrates how a custom `activeUsers` metric is sent to the in-cluster API and ultimately displayed in the Vendor Portal, as described above: Custom metrics flowing from customer environment to Vendor Portal [View a larger version of this image](/images/custom-metrics-flow.png) ## Requirements * To support the collection of custom metrics in online and air gap environments, the Replicated SDK version 1.0.0-beta.12 or later must be running in the cluster alongside the application instance. If you have any customers running earlier versions of the SDK, Replicated recommends that you add logic to your application to gracefully handle a 404 from the in-cluster APIs. For more information about the Replicated SDK, see [About the Replicated SDK](/vendor/replicated-sdk-overview). * The `PATCH` and `DELETE` methods described on this page require the Replicated SDK version 1.0.0-beta.23 or later. ## Limitations * The label that is used to display metrics in the Vendor Portal cannot be customized. Metrics are sent to the Vendor Portal with the same name used in the `POST` or `PATCH` payload. The Vendor Portal automatically converts camel case or snake case to title case: for example, `activeUsers` or `active_users` is displayed as Active Users. * The SDK API accepts only JSON scalar values for metrics. Any requests containing nested objects or arrays are rejected. ## Define custom metrics in JSON payload You can define the custom metrics for your application as a set of key value pairs in a JSON metric payload. The payload must be valid JSON with proper content type headers. **Example:** ```json { "data": { "active_users": 150, // Number "cpu_usage_percent": 75.5, // Number "sso_enabled": true, // Boolean "deployment_region": "us-east-1", // String } } ``` ### Supported data types Custom metric names (keys) must be strings. Custom metric values support these JSON types: - Numbers (integers or decimals) - Strings - Booleans - Null The JSON payload must contain only scalar values. Nested objects or arrays are not supported. ### Best practices for naming custom metrics Metrics are displayed in the Vendor Portal with the same name that is used in the JSON payload. The Vendor Portal automatically converts camel case or snake case to title case: for example, `activeUsers` or `active_users` is displayed as Active Users. To make it easier for team members to understand the instance reporting data for your application, Replicated recommends that you follow these best practices when naming custom metrics: * Use descriptive names like `active_users`. Avoid abbreviations like `au`, vague names like `user_metric`, or overly verbose names like `current_active_users`. * Use camel case or snake case. Don't use hyphenated names like `active-users`. * Use camel or snake case consistently across all of your custom metrics. ## Send custom metrics You can configure your application to `PATCH` or `POST` a JSON metric payload to the SDK in-cluster API. For information about when to use `PATCH` or `POST`, see [PATCH vs POST](#patch-vs-post) on this page. The SDK API custom metrics endpoint is available at `http://replicated:3000/api/v1/app/custom-metrics`. ### Nodejs example The following example shows a NodeJS application that sends metrics on a weekly interval to the in-cluster API exposed by the SDK: ```javascript async function sendMetrics(db) { const projectsQuery = "SELECT COUNT(*) as num_projects from projects"; const numProjects = (await db.getConnection().queryOne(projectsQuery)).num_projects; const usersQuery = "SELECT COUNT(*) as active_users from users where DATEDIFF('day', last_active, CURRENT_TIMESTAMP) < 7"; const activeUsers = (await db.getConnection().queryOne(usersQuery)).active_users; const metrics = { data: { numProjects, activeUsers }}; const res = await fetch('https://replicated:3000/api/v1/app/custom-metrics', { method: 'POST', headers: { "Content-Type": "application/json", }, body: JSON.stringify(metrics), }); if (res.status !== 200) { throw new Error(`Failed to send metrics: ${res.statusText}`); } } async function startMetricsLoop(db) { const ONE_DAY_IN_MS = 1000 * 60 * 60 * 24 // send metrics once on startup await sendMetrics(db) .catch((e) => { console.log("error sending metrics: ", e) }); // schedule weekly metrics payload setInterval( () => { sendMetrics(db, licenseId) .catch((e) => { console.log("error sending metrics: ", e) }); }, ONE_DAY_IN_MS); } startMetricsLoop(getDatabase()); ``` ### Patch vs post Both the `PATCH` and `POST` methods record metrics with a timestamp, but they differ in how they handle your current metric state: * **`PATCH`:** Updates only the fields included in the JSON payload. Any other existing fields are unchanged. Use `PATCH` unless you need to explicitly remove metrics from the instance summary. * **`POST`:** Replaces the current metric state. Any existing metrics that are not included in the JSON payload are removed from the instance summary. Use `POST` only when sending your complete metric set each time. For example, if a component of your application initially sends the following with the `POST` method: ```json { "numProjects": 5, "activeUsers": 10, } ``` Then, the component later sends the following with the `PATCH` method: ```json { "usingCustomReports": false } ``` Then the instance detail will show `Num Projects: 5`, `Active Users: 10`, `Using Custom Reports: false`, which represents the merged and upserted payload: ```json { "numProjects": 5, "activeUsers": 10, "usingCustomReports": false } ``` However, if you use `POST` for the second call instead of `PATCH`, then the instance detail will show only `Active Users: 10` and `Using Custom Reports: false`: ```json { "activeUsers": 10, "usingCustomReports": false } ``` In this case, the previously-sent `numProjects` value is removed from the instance summary (though it remains accessible in the instance events history). ### How often to send custom metrics Replicated recommends that you add logic to your application to send metrics at regular intervals, such as daily or weekly. Avoid sending metrics too frequently as it creates unnecessary noise. Custom metrics are best for periodic product statistics reporting rather than real-time monitoring. For an example of application logic that sends custom metrics on a weekly interval, see [NodeJS Example](#nodejs-example) on this page. ## Remove a custom metric To remove an existing custom metric, use `DELETE` with the custom metric name. For example: ```bash DELETE http://replicated:3000/api/v1/app/custom-metrics/num_projects ``` ## View custom metrics You can view the custom metrics that you configure for each active instance of your application on the **Instance Details** page in the Vendor Portal. The following shows an example of an instance with custom metrics: Custom Metrics section of Instance details page [View a larger version of this image](/images/instance-custom-metrics.png) As shown in the image above, the **Custom Metrics** section of the **Instance Details** page includes the following information: * The timestamp when the custom metric data was last updated. * Each custom metric that you configured, along with the most recent value for the metric. * A time-series graph depicting the historical data trends for the selected metric. Custom metrics are also included in the **Instance activity** stream of the **Instance Details** page. For more information, see [Instance Activity](/vendor/instance-insights-details#instance-activity) in _Instance Details_. ## Export custom metrics You can use the Vendor API v3 `/app/{app_id}/events` endpoint to programmatically access historical timeseries data containing instance level events, including any custom metrics that you have defined. For more information about the endpoint, see [Export Customer and Instance Data](/vendor/instance-data-export). ## Troubleshoot custom metrics ### Custom metrics not showing up in the Vendor Portal #### Symptom After your application sends a custom metric payload to the SDK API, one or more custom metrics are not displayed in the instance details in the Vendor Portal. #### Cause There are several possible reasons why a custom metric might not be showing up in the Vendor Portal, such as using an unsupported version of the SDK, invalid JSON, using POST rather than PATCH, or network connectivity issues. #### Solution To troubleshoot this issue: - Ensure that the application instance is using the Replicated SDK version 1.0.0-beta.12 or later. If your application is using the `PATCH` and `DELETE` methods, version 1.0.0-beta.23 or later of the SDK is required. - Verify that your payload only contains scalar values (no nested objects or arrays), and is valid JSON with proper content type headers - Test network connectivity by confirming that the application can reach `http://replicated:3000` - Check that your application is using the intended method (PATCH or POST). If a metric payload is sent using the POST method, any existing metrics that are not included in the payload are removed from the instance summary. For more information, see [PATCH vs POST](#patch-vs-post). ### Duplicate events for unchanged values #### Symptom Instance reporting in the Vendor Portal displays duplicate events for one of your custom metrics, even though the metric's value was unchanged. #### Cause Your application logic might be computing values differently between calls. #### Solution To troubleshoot this issue: - Review your metric collection logic to ensure consistent value calculation - Check for floating-point precision issues with numeric values - Verify that boolean values are consistently true or false and are not truthy or falsy conversions --- # Adoption report This topic describes the insights in the **Adoption** section on the Replicated Vendor Portal **Dashboard** page. ## About adoption rate The **Adoption** section on the **Dashboard** provides insights about the rate at which your customers upgrade their instances and adopt the latest versions of your application. As an application vendor, you can use these adoption rate metrics to learn if your customers are completing upgrades regularly, which is a key indicator of the discoverability and ease of application upgrades. The Vendor Portal generates adoption rate data from all your customer's application instances that have checked-in during the selected time period. For more information about instance check-ins, see [How the Vendor Portal Collects Instance Data](instance-insights-event-data#about-reporting) in _About Instance and Event Data_. The following screenshot shows an example of the **Adoption** section on the **Dashboard**: ![Adoption report section on dashboard](/images/customer_adoption_rates.png) [View a larger version of this image](/images/customer_adoption_rates.png) As shown in the screenshot above, the **Adoption** report includes a graph and key adoption rate metrics. For more information about how to interpret this data, see [Adoption Graph](#graph) and [Adoption Metrics](#metrics) below. The **Adoption** report also displays the number of customers assigned to the selected channel and a link to the report that you can share with other members of your team. You can filter the graph and metrics in the **Adoption** report by: * License type (Paid, Trial, Dev, or Community) * Time period (the previous month, three months, six months, or twelve months) * Release channel to which instance licenses are assigned, such as Stable or Beta ## Adoption graph {#graph} The **Adoption** report includes a graph that shows the percent of active instances that are running different versions of your application within the selected time period. The following shows an example of an adoption rate graph with three months of data: ![Adoption report graph showing three months of data](/images/adoption_rate_graph.png) [View a larger version of this image](/images/adoption_rate_graph.png) As shown in the image above, the graph plots the number of active instances in each week in the selected time period, grouped by the version each instance is running. The key to the left of the graph shows the unique color that is assigned to each application version. You can use this color-coding to see at a glance the percent of active instances that were running different versions of your application across the selected time period. Newer versions will enter at the bottom of the area chart, with older versions shown higher up. You can also hover over a color-coded section in the graph to view the number and percentage of active instances that were running the version in a given period. If there are no active instances of your application, then the adoption rate graph displays a "No Instances" message. ## Adoption metrics {#metrics} The **Adoption** section includes metrics that show how frequently your customers discover and complete upgrades to new versions of your application. It is important that your users adopt new versions of your application so that they have access to the latest features and bug fixes. Additionally, when most of your users are on the latest versions, you can also reduce the number of versions for which you provide support and maintain documentation. The following shows an example of the metrics in the **Adoption** section: ![Adoption rate metrics showing](/images/adoption_rate_metrics.png) [View a larger version of this image](/images/adoption_rate_metrics.png) As shown in the image above, the **Adoption** section displays the following metrics: * Instances on last three versions * Unique versions * Median relative age * Upgrades completed Based on the time period selected, each metric includes an arrow that shows the change in value compared to the previous period. For example, if the median relative age today is 68 days, the selected time period is three months, and three months ago the median relative age was 55 days, then the metric would show an upward-facing arrow with an increase of 13 days. The following table describes each metric in the **Adoption** section, including the formula used to calculate its value and the recommended trend for the metric over time:
Metric Description Target Trend
Instances on last three versions

Percent of active instances that are running one the latest three versions of your application.

Formula: count(instances on last 3 versions) / count(instances)

 Increase towards 100%
Unique versions

Number of unique versions of your application running in active instances.

Formula: count(distinct instance_version)

 Decrease towards less than or equal to three
Median relative age

The relative age of a single instance is the number of days between the date that the instance's version was promoted to the channel and the date when the latest available application version was promoted to the channel.

Median relative age is the median value across all active instances for the selected time period and channel.

Formula: median(relative_age(instance_version))

Depends on release cadence. For vendors who ship every four to eight weeks, decrease the median relative age towards 60 days or fewer.
Upgrades completed

Total number of completed upgrades across active instances for the selected time period and channel.

An upgrade is a single version change for an instance. An upgrade is considered complete when the instance deploys the new application version.

The instance does not need to become available (as indicated by reaching a Ready state) after deploying the new version for the upgrade to be counted as complete.

Formula: sum(instance.upgrade_count) across all instances

 Increase compared to any previous period, unless you reduce your total number of live instances.
--- # Customer reporting This topic describes the customer and instance data displayed in the customer **Reporting** page in the Replicated Vendor Portal. ## About the customer reporting page {#reporting-page} The **Customers > [Customer Name] > Reporting** page displays data about the active application instances associated with each customer. The following shows an example of the **Reporting** page: ![Customer reporting page showing two active instances](/images/customer-reporting-page.png) [View a larger version of this image](/images/customer-reporting-page.png) As shown in the image above, the **Reporting** page has the following main sections: * [Manage Customer](#manage-customer) * [Time to Install](#time-to-install) * [Download Portal](#download-portal) * [Enterprise Portal](#enterprise-portal) * [Instances](#instances) * [Install Attempts](#install-attempts-beta) ### Manage customer The manage customer section displays the following information about the customer: * The customer name * The channel the customer is assigned * Details about the customer license: * The license type * The date the license was created * The expiration date of the license * The features the customer has enabled, including: * GitOps * Air gap * Identity * Snapshots In this section, you can also view the Helm CLI installation instructions for the customer and download the customer license. ### Time to install If the customer has one or more application instances that have reached a Ready status at least one time, then the **Time to install** section displays _License time to install_ and _Instance time to install_ metrics: * **License time to install**: The time between when you create the customer license in the Vendor Portal, and when the application instance reaches a Ready status in the customer environment. * **Instance time to install**: The time between when the Vendor Portal records the first event for the application instance in the customer environment, and when the instance reaches a Ready status. A _Ready_ status indicates that all Kubernetes resources for the application are Ready. For example, a Deployment resource is considered Ready when the number of Ready replicas equals the total desired number of replicas. For more information, see [Enabling and Understanding Application Status](insights-app-status). If the customer has no application instances that have ever reported a Ready status, or if you have not configured your application to deliver status data to the Vendor Portal, then the **Time to install** section displays a **No Ready Instances** message. If the customer has more than one application instance that has previously reported a Ready status, then the **Time to install** section displays metrics for the instance that most recently reported a Ready status for the first time. For example, Instance A reported its first Ready status at 9:00 AM today. Instance B reported its first Ready status at 8:00 AM today, moved to a Degraded status, then reported a Ready status again at 10:00 AM today. In this case, the Vendor Portal displays the time to install metrics for Instance A, which reported its _first_ Ready status most recently. For more information about how to interpret the time to install metrics, see [Time to Install](instance-insights-details#time-to-install) in _Instance Details_. ### Download Portal :::note If the Replicated Enterprise Portal is enabled for the customer, then an **Enterprise Portal** section is displayed instead of the **Download Portal** section. For more information, see [Enterprise Portal](#enterprise-portal) below. ::: From the **Download portal** section, you can: * 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 [Access a Customer's Download Portal](releases-share-download-portal). ### Enterprise Portal :::note The **Enterprise Portal** section is available only for customers with the Enterprise Portal enabled. For more information about how to enable the Enterprise Portal for a customer, see [Manage Customer Access to the Enterprise Portal](/vendor/enterprise-portal-invite). ::: The following shows an example of the **Enterprise Portal** section: ![Enterprise Portal section of customer reporting page](/images/customer-reporting-enterprise-portal.png) [View a larger version of this image](/images/customer-reporting-enterprise-portal.png) From the **Enterprise Portal** section, you can: * Click **View** to access the unique Enterprise Portal for the customer * View the status of the customer's access to the Enterprise Portal * View the timestamp when the Enterprise Portal was most recently accessed by the customer * View the number of users with Enterprise Portal accounts * Click **Invite user** to invite a new user to the Enterprise Portal * View the number of install attempts made by the customer. The **Customer Reporting > Install Attempts** section includes additional details about install attempts. For more information, see [Install Attempts](#install-attempts-beta) below. * View the number of service accounts created in the Enterprise Portal * View the number of support bundles uploaded to the Enterprise Portal * Open the **Delivery** row to see when the customer first accessed the Enterprise Portal and the timestamps of their first and most recent software pulls For more information about the Enterprise Portal, see [About the Enterprise Portal](/vendor/enterprise-portal-about). ### Instances The **Instances** section displays details about the active application instances associated with the customer. You can also enable the **Show archived instances** and **Show inactive instances** checkboxes to view archived and inactive instances. From the **Instances** section, you can: * Click any of the instances to open its **Instance details** page. For more information, see [Instance Details](instance-insights-details). * Bulk archive instances. For more information, see [Bulk archive instances](/vendor/releases-creating-customers#bulk-archive-instances) in _Create and manage customers_. * View instances details, including: * The first seven characters of the instance ID * The instance's status. See [Enabling and Understanding Application Status](insights-app-status). * The application version * Details about the cluster where the instance is installed * Instance uptime data. For more information, see [Instance Uptime](instance-insights-details#instance-uptime) in _Instance Details_. The following shows an example of a row for an active instance in the **Instances** section: ![Row in the Instances section](/images/instance-row.png) [View a larger version of this image](/images/instance-row.png) ### Install attempts (Beta) :::note The **Install Attempts** section is available only for customers with the Replicated Enterprise Portal enabled. For more information about how to enable the Enterprise Portal for a customer, see [Manage Enterprise Portal Access](/vendor/enterprise-portal-invite). ::: The **Install Attempts** section includes details about the installation attempts made by users. These insights are based on the customer's activity in the Enterprise Portal. To track install attempts, the Enterprise Portal creates a unique, _just-in-time_ service account that sends data back to the Vendor Portal when the user starts and completes the installation or takes other actions that are specific to the installation type. These service accounts also provide realtime feedback to the user on their installation progress using checkboxes and status indicators, and allow users to pause and return to an installation attempt. The following shows an example of the **Install Attempts** section: Install attempts section of customer reporting page [View a larger version of this image](/images/customer-reporting-install-attempts-expanded.png) The **Install Attempts** section includes the following details about each installation attempt: * The installation status (succeeded, stalled, or failed) * The date and time when the installation attempt was started * The email address of the user that initiated the installation attempt * Installation environment details: * **OS** or **K8s**: The operating system of the VM or bare metal server. Or, the distribution of Kubernetes running in the installation environment. * **Mode**: If the installation is online (internet-connected) or air gap (offline). * **Registry**: If the image registry used is online (accessed over the internet) or offline (a local registry is used). For air gap installations, the registry is always offline. Users can also optionally use a local image registry in online installations. * Installation progress details, including when the installation was started and completed as well as other progress indicators that are specific to the installation type. For example: * For installations with Helm, the Enterprise Portal reports when your image registry was accessed and when application images were pulled, as shown below: ![Helm install attempt progress details](/images/customer-reporting-install-attempts-helm.png) [View a larger version of this image](/images/customer-reporting-install-attempts-helm.png) * For installations with Replicated Embedded Cluster on VMs or bare metal servers, the Enterprise Portal reports when the installation assets were downloaded, as shown below: ![VM-based install attempt progress details](/images/customer-reporting-install-attempts-vm.png) [View a larger version of this image](/images/customer-reporting-install-attempts-vm.png) --- # Data availability and continuity Replicated uses redundancy and a cloud-native architecture in support of availability and continuity of vendor data. ## Data storage architecture To ensure availability and continuity of necessary vendor data, Replicated uses a cloud-native architecture. This cloud-native architecture includes clustering and network redundancies to eliminate single point of failure. Replicated stores vendor data in various Amazon Web Services (AWS) S3 buckets and multiple databases. Data stored in the AWS S3 buckets includes registry images and air gap build data. The following diagram shows the flow of air gap build data and registry images from vendors to enterprise customers. ![Architecture diagram of Replicated vendor data storage](/images/data-storage.png) [View a larger version of this image](/images/data-storage.png) As shown in the diagram above, vendors push application images to an image registry. Replicated stores this registry image data in AWS S3 buckets, which are logically isolated by vendor portal Team. Instances of the vendor's application that are installed by enterprise customers pull data from the image registry. For more information about how Replicated secures images pushed to the Replicated registry, see [Replicated Registry Security](packaging-private-registry-security). The diagram also shows how enterprise customers access air gap build data from the customer download portal. Replicated stores this air gap build data in AWS S3 buckets. ## Data recovery Our service provider's platform automatically restores customer applications and databases in the case of an outage. The provider's platform is designed to dynamically deploy applications within its cloud, monitor for failures, and recover failed platform components including customer applications and databases. For more information, see the [Replicated Trust Center](https://trust.replicated.com/). ## Data availability Replicated availability is continuously monitored. For availability reports, see https://status.replicated.com. --- # About managing stateful services This topic provides recommendations for managing stateful services that you install into existing clusters. :::note Replicated KOTS is available only for existing customers. For supporting installations into customer managed clusters, we recommend Helm. For more information, see [About Helm Installations with Replicated](/vendor/helm-install-overview). KOTS is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see [Support Lifecycle Policy](/vendor/policies-support-lifecycle). ::: ## Preflight checks for stateful services If you expect to also install stateful services into existing clusters, you will likely want to expose [preflight analyzers that check for the existence of a storage class](https://troubleshoot.sh/reference/analyzers/storage-class/). If you are allowing end users to provide connection details for external databases, you can often use a troubleshoot.sh built-in [collector](https://troubleshoot.sh/docs/collect/) and [analyzer](https://troubleshoot.sh/docs/analyze/) to validate the connection details for [Postgres](https://troubleshoot.sh/docs/analyze/postgresql/), [Redis](https://troubleshoot.sh/docs/collect/redis/), and many other common datastores. These can be included in both `Preflight` and `SupportBundle` specifications. ## About adding persistent datastores You can integrate persistent stores, such as databases, queues, and caches. There are options to give an end user, such as embedding an instance alongside the application or connecting an application to an external instance that they will manage. For an example of integrating persistent datastores, see [Example: Adding Database Configuration Options](tutorial-adding-db-config). --- # About the Enterprise Portal This topic provides an overview of the Replicated Enterprise Portal. :::note Looking for the new Enterprise Portal? See [About the Enterprise Portal](/vendor/enterprise-portal-v2-about) in the Enterprise Portal (New) section. ::: ## Overview The Enterprise Portal is a customizable, web-based portal for customers that install using either Replicated Embedded Cluster or the Helm CLI. From the Enterprise Portal, your customers can: * View application install and update instructions for Embedded Cluster and Helm CLI installations * Manage their team members and service accounts * Upload support bundles * View insights about their active and inactive instances * And more The following shows an example of the Enterprise Portal dashboard: ![Enterprise Portal dashboard](/images/enterprise-portal-dashboard.png) [View a larger version of this image](/images/enterprise-portal-dashboard.png) Your customers can access the Enterprise Portal outside their application installation environment at a custom domain that you specify, making it easier for teams to manage instances and get support. The following diagram shows how customers can use the Enterprise Portal to access release assets and installation instructions, as well as upload support bundles: ![Customer uses install instructions in enterprise portal to install a release](/images/enterprise-portal-overview.png) [View a larger version of this image](/images/enterprise-portal-overview.png) As shown in the diagram above, your licensed customers can access the installation and update instructions for one or more application releases by logging in to the Enterprise Portal. The Enterprise Portal tracks the customer's installation attempts and progress, and shares those insights back to the Vendor Portal. After installing, customers can also upload support bundles in the Enterprise Portal. Support bundles uploaded to the Enterprise Portal are automatically made available to you in the Vendor Portal. You can enable and disable access to the Enterprise Portal for all customers, or on a per-customer basis. For more information about how to enable access, see [Manage Customer Access](/vendor/enterprise-portal-invite#manage-ep-access). For information about using the Enterprise Portal, see [Access and Use the Enterprise Portal](enterprise-portal-use). ## Limitations * Installation and upgrade instructions are available only for Embedded Cluster and Helm CLI installations. The Enterprise Portal does not provide instructions for installing and upgrading with KOTS in existing clusters or with kURL. * Air gap instance records do not appear in the Enterprise Portal until the end customer creates an air gap instance record by either uploading a support bundle for that instance or manually entering instance information. For more information, see [View Active and Inactive Instances](/vendor/enterprise-portal-use#view-active-and-inactive-instances) in _Access and Use the Enterprise Portal_. * The Enterprise Portal limits support bundle uploads to 500 MB. For larger bundles, use the [Replicated SDK API](/reference/replicated-sdk-apis#post-supportbundle) upload endpoint, which has no size restriction. * There is a known issue when using a custom domain for the Enterprise Portal if any of your customers use link transformers such as Microsoft Defender Safe Links. For more information, see [Known Issue](custom-domains#known-issue) in _About Custom Domains_. ## Comparison to the Download Portal The Enterprise Portal is the next generation version of the Replicated Download Portal. Compared to the Download Portal, the Enterprise Portal not only provides access to installation assets and instructions, but also allows users to track available updates, manage their team and service accounts, view the status of their instances, view license details, and more. These features are designed to make it easier for your customers to manage their instances of your application from a centralized location outside of the installation environment. For more information about enabling Enterprise Portal access for your customers that install using either Embedded Cluster or the Helm CLI, see [Manage Customer Access to the Enterprise Portal](enterprise-portal-invite). :::note The Entprise Portal supports Embedded Cluster and Helm CLI installation methods only. Customers that use KOTS in an existing cluster or kURL can continue to use the Download Portal. ::: For more information about the Download Portal, see [Access a Customer's Download Portal](/vendor/releases-share-download-portal). ## About customizing the Enterprise Portal You can configure the Enterprise Portal to use a custom domain, add links and contact information, customize the look and feel of the Enterprise Portal, edit the content of invitation and notification emails, and more. Customizing the Enterprise Portal helps ensure that your customers have a consistent branding experience and can access application- and vendor-specific information. For more information about customizing the Enterprise Portal, see [Customize the Enterprise Portal](enterprise-portal-configure). For information about how to set a custom domain for the Enterprise Portal, see [Use Custom Domains](/vendor/custom-domains-using). ## About instance reporting with the Enterprise Portal This section describes the instance reporting functionality of the Enterprise Portal. ### Active and inactive instances The Enterprise Portal provides insights to end users about their active and inactive instances, including the application version installed, the instance status, computed metrics like the first and most recent times the instance sent data to the Vendor Portal, and more. For more information about the instance insights available in the Enterprise Portal, see [View Active and Inactive Instances](/vendor/enterprise-portal-use#view-active-and-inactive-instances) in _Access and Use the Enterprise Portal_. ![active and inactive instances](/images/enterprise-portal-instance-status-details.png) [View a larger version of this image](/images/enterprise-portal-instance-status-details.png) ### Customer reporting The Enterprise Portal sends insights back to the Vendor Portal, which are surfaced on the **Customer Reporting** page. For more information, see [Enterprise Portal](/vendor/customer-reporting#enterprise-portal) in _Customer Reporting_. These insights include details about the customer's install attempts. The Enterprise Portal tracks and reports on install attempts by creating unique, _just-in-time_ service accounts. These service accounts allow the Enterprise Portal to send data back to the Vendor Portal when the user starts and completes the installation or takes other actions that are specific to the installation type. The service accounts also provide realtime feedback to the user on their installation progress using checkboxes and status indicators, and allow users to pause and return to an installation attempt. For more information, see [Install Attempts](/vendor/customer-reporting#install-attempts-beta) in _Customer Reporting_. The following shows an example of the **Install Attempts** section: Install attempts section of customer reporting page [View a larger version of this image](/images/customer-reporting-install-attempts-expanded.png) --- # View a customer's Enterprise Portal This topic describes how you can log in to the Enterprise Portal for a customer from the Vendor Portal. This is useful when testing your application installation and upgrade instructions, previewing customizations that you made to the Enterprise Portal, or managing Enterprise Portal users on behalf of one of your customers. :::note Looking for the new Enterprise Portal? See [View a customer's Enterprise Portal](/vendor/enterprise-portal-v2-access) in the Enterprise Portal (New) section. ::: For information about how end users can sign up for an account and log in to the Enterprise Portal, see [Log In To and Use the Enterprise Portal](enterprise-portal-use). ## Log in using a one-time link You can access the Enterprise Portal for a customer using a one-time login. This is useful for quickly accessing the Enteprise Portal, or if you must not create an account in the customer's Enterprise Portal. To access the Enterprise Portal for a customer with a one-time login: 1. In the Vendor Portal, go to **Customers > [Customer Name] > Enterprise Portal Access**. 1. In the **Login to portal** section, click **Login to portal**. This generates a one-time login and opens the Enterprise Portal for the customer. ![Login to portal section](/images/enterprise-portal-one-time-login.png) [View a larger version of this image](/images/enterprise-portal-one-time-login.png) ## Log in with an account :::note If your email address is not yet added to the customer's Enterprise Portal team, send an invitation before attempting to log in. For information about how to add users to a customer's Enterprise Portal from the Vendor Portal, see [Invite Users](enterprise-portal-invite#invite-users) in _Manage Customer Access to the Enterprise Portal_. ::: To access the Enterprise Portal for a customer by logging in with an account: 1. In the Vendor Portal, do one of the following to get the unique Enterprise Portal link for the customer: * Go to **Customers > [Customer Name] > Enterprise Portal Access**. Click **View customer's portal link**. ![customer-specific enterprise portal access toggle](/images/customer-enterprise-portal-access-toggle.png) [View a larger version of this image](/images/customer-enterprise-portal-access-toggle.png) * Go to **Customers > [Customer Name] > Reporting** and click **View** in the **Enterprise Portal** section. ![Enterprise Portal section of customer reporting page](/images/customer-reporting-enterprise-portal.png) [View a larger version of this image](/images/customer-reporting-enterprise-portal.png) 1. In the dialog, enter the email address for the existing Enterprise Portal user and click **Continue with email**. The Vendor Portal generates a verification code and sends it to the email address. --- # Customize the Enterprise Portal This topic describes how to customize the Enterprise Portal, including using a custom domain, changing the branding, editing the content of invitation and notification emails, and adding custom documentation. :::note Looking for the new Enterprise Portal? The new portal uses a GitHub content repo and `theme.yaml` for customization. See [Customize Portal Content](/vendor/enterprise-portal-v2-content) and [Customize Portal Branding](/vendor/enterprise-portal-v2-branding) in the Enterprise Portal (New) section. ::: ## Manage Enterprise Portal settings You can edit the settings for the Enterprise Portal to use a custom domain, provide custom links and contact information, customize the look and feel of the Enterprise Portal, and more. To manage Enterprise Portal settings: 1. In the Vendor Portal, go to **Enterprise Portal > Portal Settings**. ![Enterprise Portal settings page](/images/enterprise-portal-settings.png) [View a larger version of this image](/images/enterprise-portal-settings.png) 1. Edit the settings as desired:
Field Description
URL The URL where customers can access the Enterprise Portal. You can change the URL to use a custom domain. For information, see [Use Custom Domains](custom-domains-using).
Title The title of the Enterprise Portal. The title is displayed at the top of each page in the Enterprise Portal and is also used in email notifications.
Page overview An overview of the Enterprise Portal.
Support portal link The URL for the portal that your customers can use to get support. This link is provided on the Enterprise Portal **Support** page.
Contact email The email address that customers can use to contact you. This email address is provided on the Enterprise Portal **Support** page.
Logo Upload a custom PNG logo for the Enterprise Portal. The minimum size for the logo is 160px by 160px.
Favicon Upload a custom favicon for the Enterprise Portal. The favicon is displayed in the browser tab.
Background Select or customize the background for the Enterprise Portal.
Colors Set the primary and secondary colors for the Enterprise Portal.
1. Click **Save**. ## Customize emails {#configure-customer-emails} This section describes options for customizing the emails sent to customers through the Enteprise Portal. For information about how to view the delivery status of all emails sent to customers, see [View Email History and Delivery Status](/vendor/enterprise-portal-invite#email-history) in _Manage Enterprise Portal Customer Access_. ### Configure email sender Adding a sender address helps ensure that your emails are delivered and are not marked as spam. To configure customer emails: 1. In the Vendor Portal, go to **Enterprise Portal > Customer Emails**. ![Enterprise Portal customer emails page](/images/enterprise-portal-customer-emails.png) [View a larger version of this image](/images/enterprise-portal-customer-emails.png) 1. For **Email Sender Verification**, in **From email address**, add the email address that you want to use as the sender for all system notifications sent to your customers, then click **Continue**. 1. Follow the steps in the wizard to verify the domain by adding the DKIM and Return-Path to your domain registrar. After the domain is verified automatically, the email address is displayed under **Verified Sender Address**. ### Customize email templates You can customize the subject line, content, and styling of the emails that are sent to your customers. To customize email templates: 1. In the Vendor Portal, go to **Enterprise Portal > Customer Emails**. ![Enterprise Portal customer emails page](/images/enterprise-portal-customer-emails.png) [View a larger version of this image](/images/enterprise-portal-customer-emails.png) 1. For **Customer Emails**, first select the email category (such as **Access & Authentication** or **Update Notifications**). Then, select the name of the email template that you want to customize. The template editor opens. The following shows an example of the editor for the **Temporary Login Link** email template: ![Enterprise Portal edit emails pane](/images/enterprise-portal-customer-emails-edit.png) [View a larger version of this image](/images/enterprise-portal-customer-emails-edit.png) 1. In the editor, modify the subject line and body as desired. Note the following options: * You can customize the default style component to change things like color and font. * You can use template variables to insert dynamic content in the subject or body. For example, `Welcome to {{app_name}}!` or `Click here to join {{team_name}}: {{invite_url}}`. Template variables are automatically populated with relevant data when emails are sent. :::note The specific template variables that are available for use depend on the type of email template that you are editing. You can see all available variables in the **Available Variables** section of the editor. For a list of the common template variables that are available across multiple email templates, see [Common Template Variables](#common-template-variables) below. ::: 1. Click the **Preview** tab to see how your email will look with sample data. 1. Click **Save changes** when finished. ### Common template variables The following template variables are available across multiple email types: | Variable | Description | Example Output | |----------|-------------|----------------| | `{{app_name}}` | Your application name | "Acme Application" | | `{{team_name}}` | Customer team name | "Acme Corp" | | `{{customer_name}}` | Customer organization name | "Acme Corporation" | | `{{login_url}}` | Link to login page | https://portal.example.com/acme/login | | `{{invite_url}}` | Link to accept invitation | https://portal.example.com/acme/invite#token | | `{{verification_code}}` | Temporary verification code | "ABC123" | | `{{version_label}}` | Software version number | "1.2.3" | | `{{release_notes}}` | Release notes content | "New features and bug fixes" | | `{{update_url}}` | Link to update/release page | https://portal.example.com/acme/releases | ## Customize user instructions ### Add a link to documentation For each of your supported install types, you can add a link your installation documentation. The link you provide is displayed on the Enterprise Portal **Install** page. To add a link to your documentation in the Enterprise Portal: 1. In the Vendor Portal, go to **Enterprise Portal > Installation Instructions**. ![Enterprise Portal knowledge base page](/images/enterprise-portal-knowledge-base.png) [View a larger version of this image](/images/enterprise-portal-knowledge-base.png) 1. In the panel on the left, select the installation type. 1. In the documentation links section, add a link to your application install documentation. 1. Click **Save changes**. ### Add pre- and post-install instructions For each of your supported install types, you can add custom pre- and post-install instructions for users. This is useful if there are additional prerequisites or follow-up steps that users need to complete in addition to the primary installation instructions. :::note The same pre- and post- instructions are shown for all your release channels. To add channel-specific instructions, see [Customize Channel-Specific Install Instructions](#customize-channel-install-instructions). ::: To customize the pre- and post-install instructions for your application: 1. In the Vendor Portal, go to **Enterprise Portal > Installation Instructions**. ![Enterprise Portal knowledge base page](/images/enterprise-portal-knowledge-base.png) [View a larger version of this image](/images/enterprise-portal-knowledge-base.png) 1. In the panel on the left, select the installation type. 1. In the documentation content section, add pre- and post-installation instructions in markdown format. Click **Preview** to see a preview of your changes. 1. Click **Save changes**. ### Exclude certain images from Helm CLI install instructions {#installer-only} You can use the `kots.io/installer-only` annotation to exclude the images for an entire Helm chart or for one or more resoures in a Helm chart's templates from the Helm CLI installation instructions displayed in the Enterprise Portal. This annotation is useful for charts or resources that are required for deployments with a Replicated installer (KOTS, Embedded Cluster, kURL) but should not be visible or deployed when customers install with the Helm CLI. #### Exclude an entire Helm chart from Helm CLI installations ```yaml apiVersion: kots.io/v1beta2 kind: HelmChart metadata: name: installers-only-chart annotations: kots.io/installer-only: "true" spec: chart: name: installers-only-chart chartVersion: 1.0.0 ``` #### Exclude resources inside a chart's templates from Helm CLI installations The following example shows a Kubernetes Job inside a Helm chart's templates that should only run during Replicated installer deployments: ```yaml # example-chart/templates/preflight-job.yaml apiVersion: batch/v1 kind: Job metadata: name: {{ .Release.Name }}-preflight annotations: kots.io/installer-only: "true" spec: template: spec: containers: - name: preflight-checks image: replicated/preflight:latest command: ["/bin/sh"] args: ["-c", "echo Running installer-specific preflight checks"] restartPolicy: Never ``` ### Customize channel-specific install instructions (Alpha) {#customize-channel-install-instructions} :::note Custom install instructions are Alpha and subject to change. To access this feature, a feature flag must be enabled for your team. For more information, reach out to your Replicated account representative. ::: By default, the installation instructions available in the Enterprise Portal are automatically generated based on the install types and options enabled in the customer's license. These default installation instructions are the same across all release channels. For more information about managing the install types and options, see [Manage Install Types for a License](/vendor/licenses-install-types). You can also write custom, channel-specific instructions. This is useful if you need to provide unique installation steps for any of your release channels. For example, you can add custom steps, rename steps or sections to match your documentation, include videos or diagrams, and more. These custom installation instructions support MDX. MDX is a format that combines Markdown with JSX, allowing you to use components and template variables in your instructions. MDX templates support the following: - **Template variables**: Access dynamic data like application name, release version, registry settings, and customer inputs - **Built-in UI components**: Use UI components like code blocks, alerts, tabs, and progress indicators - **Conditional rendering**: Conditionally show or hide content. For example, show or hide certain steps based on the installation options supported by the customer's license #### Add channel-specific instructions To add custom, channel-specific installation instructions: 1. In the Vendor Portal, go to **Enterprise Portal > Installation Instructions**. 1. Scroll to the **Channel customizations** section. 1. For the channel where you want to customize instructions, click **Enable**. ![Enable button](/images/vendor-portal-custom-instructions-enable.png) [View a larger version of this image](/images/vendor-portal-custom-instructions-enable.png) 1. In the MDX template editor, write your custom installation instructions using Markdown, template variables, and MDX components. The editor provides autocomplete for available template variables and components. Start typing `{` for template variables or `<` for MDX components to see suggestions. For more information about the available variables and components, see [Supported MDX Template Variables](#vars) and [Supported MDX Components](#components) below. ![MDX template editor](/images/vendor-portal-custom-instructions-editing.png) [View a larger version of this image](/images/vendor-portal-custom-instructions-editing.png) 1. Click **Save changes** to save your custom installation instructions. #### Revert to default instructions To disable custom instructions for a channel and revert to the default automatically-generated instructions: 1. In the **Channel customizations** section, select the channel. 1. For the target channel, click **Disable**. When channel customizations are disabled, the Enterprise Portal shows the default installation instructions for the channel. :::note Your custom documentation is saved in the **Channel customizations** MDX template editor. You can enable the custom instructions again by clicking **Enable** for the channel. ::: #### Supported MDX template variables {#vars} :::note For a complete list of available variables, use the autocomplete feature in the editor. ::: The following describes some of the supported MDX template variables:
Variable Description Example
{`{app.name}`} Application name `My Application`
{`{app.slug}`} Application slug (identifier) `my-app`
{`{channel.channelName}`} Channel name `Stable`
{`{channel.channelSlug}`} Channel slug `stable`
{`{release.versionLabel}`} Release version number `1.2.3`
{`{release.releaseSequence}`} Release sequence number `42`
{`{release.releaseNotes}`} Release notes in markdown `Review the release notes above before proceeding with installation.`
{`{release.isRequired}`} Boolean: is this a required release Add a ConditionalRender when={`{release.isRequired}`} to generate a special message
{`{installOptions.isAirgap}`} Boolean: air gap installation Add a ConditionalRender when={`{!installOptions.isAirgap}`} to add an extra Pull Images step
{`{installOptions.installType}`} Installation type (helm, linux, embedded) Add a ConditionalRender when={`{installOptions.installType === 'helm'}`} to generate different cluster preparation instructions
{`{installOptions.adminConsoleUrl}`} Admin Console URL (user input, dynamic) `https://admin.example.com`
{`{installOptions.proxyUrl}`} HTTP/HTTPS proxy URL (user input, dynamic) `https://proxy.example.com:8080`
{`{installOptions.privateRegistryUrl}`} Private registry hostname (user input, dynamic) `registry.example.com:5000`
{`{branding?.title}`} Enterprise Portal title (optional) `MyApp Enterprise Portal`
{`{branding?.logo}`} Custom logo URL (optional) `www.mycompany.com/logo`
{`{branding?.primaryColor}`} Primary brand color (optional) `#4a53b0`
{`{branding?.secondaryColor}`} Primary brand color (optional) `#0066cc`
{`{branding?.supportPortalLink}`} Support portal URL (optional) `https://support.example.com`
{`{installation.licenseId}`} Unique Customer license ID `2cHXb1RCttzpR0xvnNWyaZCgDBP`
{`{installation.serviceAccountId}`} Service account identifier `2cHXb1RCttzpR0xvnNWyaZCgDBP`
{`{installation.customerEmail}`} Email address associated with the customer installation. Used for registry authentication as the username in Helm CLI installation instructions. `customer@example.com`
{`{installation.serviceAccountToken}`} Authentication token for the service account. Used for registry authentication as the password in Helm CLI installation instructions. `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
{`{images.raw}`} Array of image names without registry (Helm only) `["nginx:1.19", "postgres:13"]`
{`{images.full}`} Array of complete image references (Helm only) `["registry.replicated.com/..."]`
#### Supported MDX components {#components} The following components are available in MDX templates. For examples of each component, see [Example](#example) below. ##### Text and Formatting
Name Description Props
``, ``, ``, `` Display callout boxes with different styles. `icon` (boolean, optional): Show or hide the icon in the callout.
`` General purpose alert with customizable type
  • `kind` ("info" | "warning" | "error" | "success", optional)
  • `icon` (boolean, optional): Show or hide the icon in the callout.
``

Display inline code.

To use template variables inside CodeBlock, wrap them in template literals using curly braces: `{`...`}`. For example, ```{`${app.slug}`}```.

Limitation: Dynamic user input variables (like `installOptions.privateRegistryUrl`, `installOptions.proxyUrl`, `installOptions.adminConsoleUrl`) are not supported in code components. Use placeholders like `` instead.

 None
``

Display multi-line code blocks with syntax highlighting.

To use template variables inside CodeBlock, wrap them in template literals using curly braces: `{`...`}`. For examples of this, see [Example](#example).

Limitation: Dynamic user input variables (like `installOptions.privateRegistryUrl`, `installOptions.proxyUrl`, `installOptions.adminConsoleUrl`) are not supported in code components. Use placeholders like `` instead.
  • `language` (string, optional)
  • `maxHeight` (number | string, optional)
  • `showCopyButton` (boolean, optional)
  • `disabled` (boolean, optional)
``

Display shell commands with copy functionality.

To use template variables inside CommandBlock, wrap them in template literals using curly braces: `{`...`}`. For examples of this, see [Example](#example).

Limitation: Dynamic user input variables (like `installOptions.privateRegistryUrl`, `installOptions.proxyUrl`, `installOptions.adminConsoleUrl`) are not supported in code components. Use placeholders like `` instead.
  • `language` (string, optional)
  • `maxHeight` (number | string, optional)
  • `showCopyButton` (boolean, optional)
  • `disabled` (boolean, optional)
##### Layout
Name Description Props
`` Create tabbed content sections `defaultActiveTab` (number, optional): Index of initially active tab
`` Individual tab within a Tabs container `title` (string, required): Tab label text
`` Create collapsible content sections `title` (string, required), `defaultOpen` (boolean, optional)
`` Show or hide content based on conditions `when` (string, required): JavaScript expression to evaluate
##### Installation Components
Name Description Props
`` Numbered installation step
  • `title` (string, required)
  • `stepNumber` (number, optional)
  • `completed` (boolean, optional)
  • `optional` (boolean, optional)
`` Display prerequisites section `title` (string, optional): Custom title for the section
`` Display troubleshooting section `title` (string, optional): Custom title for the section
##### Input Components
Name Description Props
`` Collect proxy URL from user
  • `placeholder` (string, optional)
  • `disabled` (boolean, optional)
`` Collect registry credentials
  • `placeholder` (string, optional)
  • `disabled` (boolean, optional)
`` Collect Admin Console URL
  • `placeholder` (string, optional)
  • `disabled` (boolean, optional)
##### Display Components
Name Description Props
`` Link to support resources
  • `href` (string, optional): Link URL. If not set, uses `branding.supportPortalLink`.
  • `showIcon` (boolean, optional, default: true)
  • `target` ("_blank" | "_self", optional, default: "_blank")
#### MDX template restrictions MDX templates are validated for security before being saved. The following restrictions apply: - Only approved MDX components can be used - JavaScript code execution is not allowed - External script imports are blocked - Dangerous HTML elements (script, iframe, embed) are not allowed - Template size is limited to 1MB #### Example The following is an example of custom installation instructions that use MDX with conditional rendering based on installation type:
MDX Example ```mdx # Install \{app.name\} ## Helm Installation - Kubernetes cluster version 1.24 or later - Helm 3.8 or later installed - kubectl configured to access your cluster Save your registry credentials to a Kubernetes secret: {`kubectl create secret docker-registry ${app.slug}-registry \\ --docker-server= \\ --docker-username= \\ --docker-password= \\ --namespace default`} {`helm install ${app.slug} oci:///${app.slug} \\ --version ${release.versionLabel} \\ --namespace default`} {`kubectl get pods -n default`}

All pods should be in the Running state within 5 minutes. ### Pods are not starting If your pods are not starting, check the pod logs: {`kubectl logs -n default -l app=${app.slug}`}

### Need help? Contact our support team: Get Support ## Embedded Cluster Installation - Linux server (Ubuntu 20.04+, RHEL 8+, or equivalent) - Root or sudo access - Minimum 4 CPU cores and 8GB RAM Download the air gap bundle to your server: {`curl -f "https://replicated.app/embedded/${app.slug}/${channel.channelSlug}/${release.versionLabel}?airgap=true" \\ -H "Authorization: YOUR_LICENSE" \\ -o ${app.slug}-${channel.channelSlug}.tgz`} Download the installation assets via proxy: {`curl -f "https://replicated.app/embedded/${app.slug}/${channel.channelSlug}/${release.versionLabel}" \\ -H "Authorization: YOUR_LICENSE" \\ --proxy \\ -o ${app.slug}-${channel.channelSlug}.tgz`} Download the installation assets: {`curl -f "https://replicated.app/embedded/${app.slug}/${channel.channelSlug}/${release.versionLabel}" \\ -H "Authorization: YOUR_LICENSE" \\ -o ${app.slug}-${channel.channelSlug}.tgz`} {`tar -xvzf ${app.slug}-${channel.channelSlug}.tgz`} {`sudo ./${app.slug} install --license license.yaml --airgap-bundle ${app.slug}.airgap`} {`sudo ./${app.slug} install --license license.yaml --https-proxy=`} {`sudo ./${app.slug} install --license license.yaml`}

The installer will provision a Kubernetes cluster and deploy \{app.name\}. ### Installation fails Check the installation logs: {`sudo journalctl -u ${app.slug}`}

### Need help? Visit our support portal or email support@example.com. ```
Given the MDX example above, the following show previews of how the Helm online install and Linux (Embedded Cluster) online install instructions would appear in the Enterprise Portal:
Helm Online Install Preview ![Helm online install instructions example](/images/enterprise-portal-custom-instructions-helm-online.png) [View a larger version of this image](/images/enterprise-portal-custom-instructions-helm-online.png)
Linux (Embedded Cluster) Online Install Preview ![Linux online install instructions example](/images/enterprise-portal-custom-instructions-linux-online.png) [View a larger version of this image](/images/enterprise-portal-custom-instructions-linux-online.png)
--- # Manage Enterprise Portal customer access This topic describes how to manage customer access to the Enterprise Portal from the Replicated Vendor Portal. It includes information about enabling the Enterprise Portal, managing user invitations, enabling SAML authentication for Enterprise Portal logins, and more. :::note Looking for the new Enterprise Portal? See [Manage customer access](/vendor/enterprise-portal-v2-invite) in the Enterprise Portal (New) section. ::: For information about how your end customers can manage, invite, and remove team members in their Enterprise Portal, see [Log In To and Use the Enterprise Portal](enterprise-portal-use). ## Manage access to the Enterprise Portal {#manage-ep-access} You can enable the Enterprise Portal globally for all customers, or on a per-customer basis. When the Enterprise Portal is disabled for a customer, they have access to the Replicated Download Portal instead. :::note The Enterprise Portal supports Embedded Cluster and Helm CLI installation methods only. Customers that use KOTS in an existing cluster or kURL can continue to use the Download Portal. ::: ### Enable the Enterprise Portal globally {#enable-global} To enable the Enterprise Portal globally for all customers: * Go to **Enterprise Portal > Customer Access**. In the **Portal Access** section, enable the **Enable Enterprise Portal for all customers** toggle. ![enterprise portal access toggle](/images/enterprise-portal-access-toggle.png) [View a larger version of this image](/images/enterprise-portal-access-toggle.png) ### Enable the Enterprise Portal per customer To enable the Enterprise Portal on a per-customer basis: * Go to **Customers** and select the target customer. On the customer's page, go to **Enterprise Portal access** and enable the **Enable Enterprise Portal for this customer** toggle. ![customer-specific enterprise portal access toggle](/images/customer-enterprise-portal-access-toggle.png) [View a larger version of this image](/images/customer-enterprise-portal-access-toggle.png) :::note When the global **Enable Enterprise Portal for all customers** setting is on, the per-customer toggle is disabled. To manage Enterprise Portal access on a per-customer basis, disable the global setting. See [Enable the Enterprise Portal Globally](#enable-global). ::: ### Automatically invite customers on creation {#auto-invite} You can enable automatic invitations so that each new customer automatically receives an Enterprise Portal invitation on creation. You can also override this global automatic invitation setting for individual customers. For more information, see [Create a customer](releases-creating-customer#create-a-customer). #### Requirements * Enable the **Enterprise Portal > Customer Access > Enable Enterprise Portal for all customers** setting. Disabling this setting automatically turns off automatic invitations. See [Enable the Enterprise Portal globally](#enable-global) on this page. #### Enable automatic Enterprise Portal invitations To enable automatic invitations: * In the Vendor Portal, go to **Enterprise Portal > Customer Access**. In the **Portal Access** section, enable the **Automatically invite customer email to Enterprise Portal on creation** toggle. ## Configure allowed domains for user invitations You can restrict user invitations for a customer's Enterprise Portal to specific email domains. When you add allowed domains for a customer, only users with allowed email domains can be invited to the Enterprise Portal. To configure allowed domains for a customer's Enterprise Portal invitations: 1. In the Vendor Portal, go to **Customers** and select the target customer. 1. On the customer's page, go to **Enterprise Portal access**. In the **Authentication** section, enable the **Domain Restrictions** toggle. ![Enterprise Portal domain restrictions](/images/enterprise-portal-domain-restrictions.png) [View a larger version of this image](/images/enterprise-portal-domain-restrictions.png) 1. In the text box, enter a domain to add to the allowlist. Click **Add domain**. Add more domains as needed. ## View email history and delivery status {#email-history} To view Enterprise Portal email history and delivery status, do one of the following: * To view email history for a specific customer: In the Vendor Portal, go to **Customer > Enterprise Portal Access > Email History**. * To view email history for all customers: In the Vendor Portal, go to **Enterprise Portal > Customer Access > Email History**. ## Invite users This section describes how to invite users to the Enterprise Portal from the Vendor Portal. Your customers can also invite users to the Enterprise Portal from the Enterprise Portal **Team settings** page. For more information about using the **Team settings** page, see [Manage Team Settings](/vendor/enterprise-portal-use#manage-team-settings) in _Log In To and Use the Enterprise Portal_. :::note You can also configure automatic invitations so that new customers receive an Enterprise Portal invite when you create them. See [Automatically Invite Customers on Creation](#auto-invite). ::: To invite users to the Enterprise Portal: 1. Enable access to the Enterprise Portal for the customer. See [Manage Access to the Enterprise Portal](#manage-ep-access) above. 1. (Optional) Customize the Enterprise Portal invitation email. For more information, see [Configure Invitation and Notification Emails](enterprise-portal-configure#configure-customer-emails) in _Customize the Enterprise Portal_. 1. In the Vendor Portal, go to either **Customers > [Customer Name] > Enterprise Portal access** or **Enterprise Portal > Access**. Then, click **Invite user**. ![invite user button](/images/vendor-portal-enterprise-portal-invite-user.png) [View a larger version of this image](/images/vendor-portal-enterprise-portal-invite-user.png) 1. In the **Invite user** dialog, for **Email**, enter the user's email address. If the dialog includes a **Customer** dropdown, select the name of the customer where the user is associated. ![invite user dialog](/images/enterprise-portal-invite-user-dialog.png) [View a larger version of this image](/images/enterprise-portal-invite-user-dialog.png) 1. Click **Send invite**. ## Delete users To delete users from the Enterprise Portal: 1. In the Vendor Portal, go to **Customers > [Customer Name] > Enterprise Portal access**. 1. In the **Customer users** table, find the target customer and open the dot menu. Click **Delete**. ![Delete user button](/images/enterprise-portal-delete-user.png) [View a larger version of this image](/images/enterprise-portal-delete-user.png) ## Enable SAML authentication (Alpha) {#enable-saml} :::note SAML Authentication to the Enterprise Portal is Alpha and subject to change. To access this feature, a feature flag must be enabled for your team. For more information, reach out to your Replicated account representative. ::: You can enable and disable SAML authentication for the Enterprise Portal on a per customer basis. When SAML authentication is enabled, the customer can set up SAML SSO logins for the Enterprise Portal using their identity provider (IdP). When SAML authentication is disabled, Enterprise Portal users are not able to log in using SAML, even if the customer had already configured SAML for their Enterprise Portal previously. For more information, see [About SAML Logins (Alpha)](enterprise-portal-use#about-saml) in _Log In and Use the Enterprise Portal_. To enable SAML authentication: 1. In the Vendor Portal, go to **Customers** and select the target customer. 1. On the customer's page, go to **Enterprise Portal access**. In the **Authentication** section, enable the **SAML Authentication** toggle. ![Enterprise Portal SAML authentication](/images/enterprise-portal-saml-authentication.png) [View a larger version of this image](/images/enterprise-portal-saml-authentication.png) After you enable SAML authentication, the customer can configure SAML in the Enterprise Portal using their IdP. For more information, see [Configure SAML Authentication (Alpha)](/vendor/enterprise-portal-use#saml) in _Log In and Use the Enterprise Portal_. --- # Enable self-service sign-ups This topic describes how to enable Enterprise Portal self-service sign-ups. This allows users to access your application by signing up for Trial or Community licenses through the Enterprise Portal. :::note Looking for the new Enterprise Portal? See [Enable self-service sign-ups](/vendor/enterprise-portal-v2-self-serve-signup) in the Enterprise Portal (New) section. ::: For information about how your future and prospective customers can sign up for an account after self-service sign-ups are enabled, see [Log In To and Use the Enterprise Portal](enterprise-portal-use). ## Overview You can enable self-service sign-ups through the Enterprise Portal for your application. When self-service sign-ups are enabled, current and potential customers can access your application by signing up for a trial or community license. All licenses issued through self-service sign-ups are automatically configured based on the default license policy that you configure in the Vendor Portal. ## Enable self-service sign-ups {#enable-self-service-signup} To enable Enterprise Portal self-service sign-ups: 1. In the Vendor Portal, go to **Enterprise Portal > Self Serve Signup**. ![Self-Service Sign-Up Configuration Screen](/images/self-serve-configure.png) [View a larger version of this image](/images/self-serve-configure.png) 1. (Optional) For **Terms and Conditions URL**, enter a URL to the terms and conditions that the user must acknowlwedge before proceeding with signup. 1. For **License Configuration**, configure the default settings for licenses created through self-service signups, including the default channel, expiration date, license type (trial or community), supported installation types, and other support features. For information about customizing the Trial Signup invitation email, see [Customize the Enterprise Portal](enterprise-portal-configure). 1. Click **Save**. ## Add custom signup fields {#custom-signup-fields} You can add custom fields to the self-service sign-up form to collect additional information from users, such as job title, company size, or use case. Custom fields help you qualify leads and prioritize outreach without custom integrations. To add custom signup fields: 1. In the Vendor Portal, go to **Enterprise Portal > Self Serve Signup**. 1. In the **Custom Signup Fields** section, click **Add** to add a new field. 1. For each field, configure the following: - **Label**: The name of the field displayed to the user on the sign-up form (for example, "Job Title"). - **Placeholder**: (Optional) Hint text displayed inside the field before the user enters a value. - **Required**: Select this option to require users to fill in the field before submitting the sign-up form. :::note Each field is automatically assigned a unique **Key** based on the label (for example, "Job Title" becomes `job_title`). The key is a stable identifier used in webhook payloads for your custom event notifications. Renaming a field's label does not change its key. To change a key, delete the field and create a new one. For more information about configuring webhook notifications, see [About event notifications](/vendor/event-notifications). ::: 1. Click **Save**. When users sign up through the Enterprise Portal, you can view both the built-in and custom field values in the **Pending Trials** list in the Vendor Portal. ## Configure email domain filtering {#email-domain-filtering} You can restrict which email domains are allowed to sign up through the Enterprise Portal. This helps ensure that only users with work email addresses can create trial accounts. To configure email domain filtering: 1. In the Vendor Portal, go to **Enterprise Portal > Self Serve Signup**. 1. In the **Email Domain Filtering** section, select one of the following modes: - **No filtering**: Any email address can sign up (default). - **Block specific domains**: Block signups from specific email domains. When this option is selected: - (Optional) Select **Block common consumer email domains** to automatically block signups from popular consumer email providers such as gmail.com, yahoo.com, hotmail.com, outlook.com, and others. - (Optional) Enter additional domains to block in the **Additional domains to block** field. Use the format `example.com` (no `https://` or paths). Press Enter or comma to add each domain. - **Allow only specific domains**: Only allow signups from the domains you specify. Enter at least one domain in the **Allowed domains** field. 1. Click **Save**. When a user tries to sign up with a blocked email domain, they receive an error message asking them to use a work email address. Domain filtering is applied during signup only and does not affect existing customers. ## Share your sign-up URL {#share-trial-url} Each application has a dedicated sign-up URL where users can access the self-servive sign up. When a new user naviagtes to the sign-up page and clicks **Create account**, they receive an email with a 12-digit verification code. The following shows an example of a self-service sign-up page for an application: Self-Service Sign-Up Interaction [View a larger version of this image](/images/self-serve-signup-screen.png) To get the sign-up URL for your application: 1. In the Vendor Portal, go to **Enterprise Portal > Self Serve Signup**. 1. Under **Enable self-service sign-ups**, copy the **Sign-Up URL**. ## View pending trials {#pending-user} When users request access to your application through a self-service sign-up, they are added to a list of **Pending Trials**. After the user confirms their account through the automated confirmation email, an active customer record is created for the user on the **Customers** page. To view pending trials: 1. In the Vendor Portal, go to **Enterprise Portal > Self Serve Signup**. 1. Under **Pending Trials**, review details about any pending self-service sign-ups, including the user's email address, company, sign-up date and time, and more. ![Pending Trials List View](/images/pending-trial-user.png) [View a larger version of this image](/images/pending-trial-user.png) --- # Log in to and use the Enterprise Portal This topic describes how to log in to the Replicated Enterprise Portal as a user, and how to use the features in the Enterprise Portal. :::note Looking for the new Enterprise Portal? See [Log in to and use the Enterprise Portal](/vendor/enterprise-portal-v2-use) in the Enterprise Portal (New) section. ::: ## Log in to the Enterprise Portal :::note If SAML authentication has been enabled and configured for the Enterprise Portal it will be the preferred login method and attempted automatically. See [Configure SAML Authentication (Alpha)](#saml) below. ::: This section describes how end customers can log in to their Enterprise Portal. Vendors can also log in to the Enterprise Portal for a customer from the Vendor Portal. For more information, see [View a Customer's Enterprise Portal](enterprise-portal-access). ### Log in from the invitation email Users can log in to the Enterprise Portal after they are invited to join a team. See [Invite or Delete Users](#invite-or-delete-users) below. * Go to your email account and open the automated invitation email. Click **Activate your account** to log in. enterprise portal invitation email [View a larger version of this image](/images/enterprise-portal-invitation-email.png) ### Sign up for a self-service account If self-service sign-ups are enabled for the application, users can create an account in the Enterprise Portal without being invited. The primary use case for self-service account creation is to sign up for a trial or community version of the software. :::note For information about how to enable self-service sign-ups from the Vendor Portal, see [Enable Self-Service Sign-Ups](/vendor/enterprise-portal-self-serve-signup). ::: To sign up for a self-service account and log in to the Enteprise Portal: 1. Go to the sign-up page URL. :::note For information about how to find the unique sign-up URL in the Vendor Portal, see [Share Your Sign-Up URL](/vendor/enterprise-portal-self-serve-signup#share-trial-url) in _Enable Self-Service Sign-Ups_. ::: 1. Enter your company name and email address, agree to the terms and conditions, and click **Create account**. The following shows an example of a self-service sign-up page for an application: Self-Service Sign-Up Interaction [View a larger version of this image](/images/self-serve-signup-screen.png) 1. Go to your email account and open the automated account creation email. Follow the link provided in the email to log in. ### About SAML logins (Alpha) {#about-saml} :::note SAML Authentication to the Enterprise Portal is Alpha and subject to change. To access this feature, a feature flag must be enabled for your team. For more information, reach out to your Replicated account representative. ::: When SAML authentication is enabled and configured for your Enterprise Portal team, you can log in with your single sign-on (SSO) credentials either through your SAML Identity Provider (IdP) or the Enterprise Portal. For more information about how to configure SAML, see [Configure SAML Authentication (Alpha)](#saml) below. #### Just-in-time user provisioning The first time that you attempt to log in with SAML using your SSO credentials, if you do not already have an Enterprise Portal account, then your account is automatically created using just-in-time (JIT) user provisioning. JIT is handled differently depending on if you attempt to log in through your IdP or the Enterprise Portal: * IdP-initiated SAML login attempts always allow for JIT user provisioning * Enterprise Portal-initiated SAML login attempts allow for JIT user provisioning if your email address has already been invited to the team. See [Invite or Delete Users](#invite-or-delete-users) below. ## Access with multiple teams If your email address has been invited to more than one customer team, you can switch between teams in the Enterprise Portal. To switch teams, click your name in the top right of the page and select a different team from the list. Each team has its own license, pull tokens, and portal content based on its assigned channel. All users invited to the same customer team share access to the same pull tokens, license credentials, and portal content. ## View install and update instructions This section describes how to view install and update instructions in the Enterprise Portal. The install and update instructions available in the Enterprise Portal are automatically generated based on the install types and options enabled in the customer's license. For more information about managing the installation types and options, see [Manage Install Types for a License](/vendor/licenses-install-types). ### View install instructions To view install instructions in the Enterprise Portal: 1. Log in to the Enterprise Portal and go to **Install**. 1. On the panel on the left, if there are multiple installation types available for the customer's license, select the installation type to use (Helm or Embedded Cluster). The installation options displayed in the Enterprise Portal are based on the customer's license. For more information, see [Manage Install Types for a License](/vendor/licenses-install-types). 1. Follow the instructions provided to install. Status indicators track your progress throughout the installation. If you exit the Enterprise Portal before completing the installation, you can resume the installation process by clicking **Continue installation** on the **Install** page, as shown below: ![Enterprise Portal continue installation button](/images/enterprise-portal-continue-install.png) [View a larger version of this image](/images/enterprise-portal-continue-install.png) ### View update instructions To view update instructions in the Enterprise Portal: 1. Log in to the Enterprise Portal and go to **Update**. For any online instances, the Enterprise Portal displays an **Update available** button when a new version is available. 1. If an **Update available** button is displayed, click it to view and follow the update instructions for the given instance. ## View instance records Users can view their active and inactive instances in the Enterprise Portal, including the instance status and other details. :::note Air gap instance records do not appear in the Enterprise Portal until the user adds a record by either uploading a support bundle for the instance or manually entering instance information. See [Create an Air Gap Instance Record](#create-an-air-gap-instance-record) below. ::: ### View active and inactive instances To view instances in the Enterprise Portal: 1. In the Enterprise Portal, go to **Updates**. 1. Under **Active Instances**, view details about the active instances. Select **View inactive instances** to view details about inactive instances. ![enterprise portal instance details](/images/enterprise-portal-instance-details.png) [View a larger version of this image](/images/enterprise-portal-instance-details.png) The following table describes the instance details available on the **Updates** page:
Field Description
Instance ID The unique identifier for the instance.
Version The application version installed.
Instance status The status of the instance, based on the status informers configured for the application. For more information, see [Enable and Understand Application Status](/vendor/insights-app-status).
First check-in The timestamp when the instance first sent data to the Vendor Portal.
Last check-in The timestamp when the instance most recently sent data to the Vendor Portal.
First ready The timestamp when the instance first reached a ready state. For more information about the ready state, see [About Resource Statuses](/vendor/insights-app-status#resource-statuses) in Enable and Understand Application Status.
Instance labels Any labels applied to the instance.
### Create an air gap instance record Air gap instance records do not appear in the Enterprise Portal until the end customer creates an air gap instance record by either uploading a support bundle for that instance or manually entering instance information. :::note To create an air gap instance record in the Enterprise Portal, the customer license must have the **Helm CLI Air Gap Instructions (Helm CLI only)** or **Air Gap Installation Option (Replicated Installers only)** option enabled. For more information, see [Create and Manage Customers](/vendor/releases-creating-customer). ::: #### Upload a support bundle for the air gap instance To create an air gap instance record by extracting instance details from a support bundle: 1. On the **Update** page, under **Air gap instances**, click **Create air gap instance record > Upload support bundle**. create air gap instance button [View a larger version of this image](/images/enterprise-portal-create-air-gap-instance.png) 1. In the **Extract instance info from a support bundle** dialog, upload the support bundle and click **Upload bundle**: manually create air gap instance dialog [View a larger version of this image](/images/enterprise-portal-extract-air-gap-instance-bundle.png) #### Manually create an air gap instance record To create an air gap instance record manually: 1. On the **Update** page, under **Air gap instances**, click **Create air gap instance record > Enter information manually**. create air gap instance button [View a larger version of this image](/images/enterprise-portal-create-air-gap-instance.png) 1. In the **Manually create air gap instance record** dialog, complete the fields and click **Create instance**. manually create air gap instance dialog [View a larger version of this image](/images/enterprise-portal-manually-create-air-gap-instance.png) ## View release history To view the release history in the Enterprise Portal: 1. In the Enterprise Portal, go to **Release History**. 1. In the **Version History** panel on the left, select a version to view details about the given release. ## View license details Customers can view license information, including expiration dates and available features. To manage licenses in the Enterprise Portal: 1. In the Enterprise Portal, go to **License**. 1. Under **License Details**, view license information including the expiration date, status, associated release channels, custom license fields, and more. ![enterprise portal license details](/images/enterprise-portal-license-details.png) [View a larger version of this image](/images/enterprise-portal-license-details.png) ## Manage team settings This section includes information about how to manage users, service accounts, and SAML authentication in the Enterprise Portal. ### Invite or delete users Customers can invite additional users to the portal and manage their access. To manage invite and manage users in the Enterprise Portal: 1. In the Enterprise Portal, open the user account dropdown in the top right of the page and select **Team settings**. ![enterprise portal team settings](/images/enterprise-portal-user-account.png) [View a larger version of this image](/images/enterprise-portal-user-account.png) 1. Click **Users**. 1. Manage users as desired: * To invite a new user, click **Invite user**. * To delete a user, find the target user in the table and open the menu. Select **Delete user**. ### Manage service accounts To manage service accounts in the Enterprise Portal: 1. In the Enterprise Portal, open the user account dropdown in the top right of the page and select **Team settings**. ![enterprise portal team settings](/images/enterprise-portal-user-account.png) [View a larger version of this image](/images/enterprise-portal-user-account.png) 1. Click **Service accounts**. 1. Manage service accounts as desired: * To create a new service account, click **Create Service Account**. * To view a service account token, find the target service account in the table and click **View** under **Token**. * The revoke a service account's token, find the target service account in the table and open the menu under **Actions**. Select **Revoke**. ### Configure SAML authentication (Alpha) {#saml} :::note SAML Authentication to the Enterprise Portal is Alpha and subject to change. To access this feature, a feature flag must be enabled for your team. For more information, reach out to your Replicated account representative. ::: :::note SAML authentication must be enabled for the customer in the Vendor Portal before they can configure SAML for their Enterprise Portal team. For more information, see [Enable SAML Authentication (Alpha)](enterprise-portal-invite#enable-saml). ::: To configure SAML authentication for your account: 1. In the Enterprise Portal, open the user account dropdown in the top right of the page and select **Team settings**. ![enterprise portal team settings](/images/enterprise-portal-user-account.png) [View a larger version of this image](/images/enterprise-portal-user-account.png) 1. Click **SAML Authentication**. 1. For **Service provider information**, copy the values provided and use them to configure your identity provider (IdP). ![enterprise portal SAML service provider information](/images/enterprise-portal-saml-sp-info.png) [View a larger version of this image](/images/enterprise-portal-saml-sp-info.png) 1. Upload the required metadata XML and public certificate from your IdP. ![enterprise portal SAML configuration](/images/enterprise-portal-saml-config.png) [View a larger version of this image](/images/enterprise-portal-saml-config.png) 1. After the file upload is complete, the **Enable SAML authentication** toggle is automatically enabled. ![enterprise portal SAML enablement](/images/enterprise-portal-saml-enable.png) [View a larger version of this image](/images/enterprise-portal-saml-enable.png) :::note If you disable SAML authentication, the SAML configuration details that you added to the Enterprise Portal are saved. ::: ## Manage user settings Each user can manage their settings in the Enterprise Portal, including enabling and disabling email notifications for various system events. To manage user settings in the Enterprise Portal: 1. In the Enterprise Portal, open the user account dropdown in the top right of the page and select **User settings**. ![enterprise portal team settings](/images/enterprise-portal-user-account.png) [View a larger version of this image](/images/enterprise-portal-user-account.png) 1. Edit the user settings as desired: * Edit profile information * Manage email notification preferences ## Collect, upload, and manage support bundles End customers can use the portal to collect, upload, and manage support bundles. The Enterprise Portal limits support bundle uploads to 500 MB. If your support bundle is larger than 500 MB, use the Replicated SDK API `POST /supportbundle` endpoint instead. This endpoint has no size limit because it uploads the bundle directly to cloud storage. For more information, see [supportbundle](/reference/replicated-sdk-apis) in _Replicated SDK API_. To manage support bundles in the Enterprise Portal: 1. In the Enterprise Portal, go to **Support**. ![enterprise portal support](/images/enterprise-portal-support.png) [View a larger version of this image](/images/enterprise-portal-support.png) 1. Manage support bundles as desired: * For **Support Bundle Collection**, follow the instructions provided to collect a support bundle based on the environment. * To upload a support bundle, click **Upload support bundle**. * To view, download, or delete previous support bundles, select **Download** or **Delete** in the **Support Bundles** table. --- # About the Enterprise Portal :::important Alpha Feature Features described on this page are in alpha and subject to change. Some capabilities might require additional access. ::: The Enterprise Portal gives your customers one central place to view their install and upgrade instructions for each version of your software, set up their environment, manage their team, and get troubleshooting support by uploading support bundles. By connecting your own GitHub repo, you control the content your customers see. You can serve versioned documentation tied to your releases, auto-generate Helm chart reference docs, customize branding, and distribute Terraform modules through a license-gated proxy registry. Content is driven by entitlements and channel assignment, so each customer sees only what applies to them. ## What your customers can do - **Install and upgrade**: Step-by-step installation instructions for Helm and Embedded Cluster (Linux), with per-instance commands personalized to each customer's license and environment - **Manage instances**: View all deployed instances, check for available updates, and follow inline upgrade instructions - **Download install artifacts**: Download air gap bundles, Helm chart tarballs, and CLI tools directly from the portal. Available artifacts vary by install method and license entitlements - **Access security data**: Review CVE reports, filter to fixable vulnerabilities, view per-instance upgrade recommendations, and download SBOMs for each release. Available for Helm and Embedded Cluster installs when Security Center is enabled - **View release history**: Browse release notes and track what's changed between versions - **Upload support bundles**: Generate and upload diagnostic bundles for faster troubleshooting - **Manage their team**: Invite users, create service accounts, and configure SAML SSO - **Download assets**: Access vendor-provided files (scripts, checklists, configuration templates) gated by entitlements ## What's new The new Enterprise Portal is a complete rebuild of the customer portal experience. Key differences from the Classic Enterprise Portal: - **Content repo driven**: All portal content (pages, navigation, branding) is managed through a GitHub repo you control, not through Vendor Portal UI forms - **MDX components**: Interactive, customer-aware components (install commands, version selectors, upgrade paths) that adapt to each customer's license and instance state - **Versioned docs**: Each Git branch becomes a version in the customer's portal, with smart resolution that automatically finds the right content for any release - **Local preview**: `replicated enterprise-portal preview` lets you preview the full portal locally with live reload - **Helm chart reference**: Auto-generated from your promoted releases with AI-enhanced descriptions - **Terraform module distribution**: License-gated module registry with native `terraform init` integration (premium feature) ## Current limitations {#current-limitations} - Installation and upgrade instructions are available only for Embedded Cluster and Helm CLI installations. The Enterprise Portal does not provide instructions for KOTS or kURL. - Air gap instance records do not appear until the customer creates one from the Instances & Updates page, either by manually entering instance information or by extracting details from an uploaded support bundle. - Security Center data (CVE reports and SBOMs) is available for Helm and Embedded Cluster installations only. Security data is not displayed for KOTS or kURL installations. - If you have many version branches and need to make a change across all versions, you must update each branch individually. ## Requirements Enterprise Portal uses a GitHub App integration to sync content from your repo. The App has read-only access and never writes to or modifies your repositories. You must have a GitHub organization. GitLab, Bitbucket, and other git providers are not supported. Replicated enables the New Enterprise Portal by default for new teams. If your existing team uses the Classic Enterprise Portal, check the Vendor Portal for New Enterprise Portal pages. Contact your Replicated account representative if you do not see them. Some Enterprise Portal capabilities require additional access: * Customer email customization * Security Center * Terraform module distribution, available to teams on the Business or Enterprise pricing plan ## For vendors already using the Classic Enterprise Portal If your team already uses the Classic Enterprise Portal, you can adopt the New Enterprise Portal incrementally. To avoid disrupting existing customers, run both portal versions in mixed mode. The new Enterprise Portal runs at a different domain (`{appSlug}.enterpriseportal.app`) than Classic (`get.replicated.com/{appSlug}/...`). Both portals share the same backend, so customer data, licenses, and instance information are consistent across both. ### How to get started 1. **Enable mixed mode.** Contact Replicated to run the New Enterprise Portal alongside the Classic Enterprise Portal. Customers continue using their current portal until you move them to the new version. 1. **Connect a content repo.** Follow the setup steps in [Connect a Git Repo](/vendor/enterprise-portal-v2-connect-repo). Connecting a repo has zero effect on any customer's portal version. No customer sees the new portal until you explicitly switch them. 1. **Test it yourself.** Use the local CLI preview (`replicated enterprise-portal preview`) or open the new portal URL directly to see how your content renders. The Vendor Portal also has a "Login as customer" button on each customer's EP access tab. 1. **Move individual customers.** On the customer's **Enterprise Portal access** tab in Vendor Portal, set the **Portal Version** toggle to use the new Enterprise Portal. Only that customer is affected. 1. **Move customers back if needed.** Set the Portal Version toggle back to Classic at any time. The customer immediately returns to the Classic experience. ### Vendor Portal view vs. customer portal version The **New Portal** / **Classic Portal** toggle appears only in mixed mode. It controls the Vendor Portal view that you see. It does not change which portal your customers see. Use the Portal Version toggle on each customer's EP access tab to change their portal. --- # Test and Preview the Enterprise Portal :::important Alpha Feature Features described on this page are in alpha and subject to change. For access, contact your Replicated account representative. ::: This topic describes how to preview and test the Enterprise Portal before and after inviting customers, including local preview for content development and logging in as a specific customer for production checks. ## Local preview Run the Enterprise Portal locally using the Replicated CLI. This is the fastest way to iterate on content because you see changes on browser refresh without committing or pushing. **Prerequisites:** Docker running, the `replicated` CLI installed, and your content repo checked out locally. From anywhere on your machine: ```shell replicated enterprise-portal preview /path/to/your-content-repo --app ``` The CLI pulls a preview container (first run only), starts a local server, and opens the full Enterprise Portal experience at `http://localhost:3000` (auto-increments if the port is busy). If you are authenticated with the CLI (`replicated login`, `REPLICATED_API_TOKEN`, or `--token`), a customer switcher dropdown appears in the preview toolbar. Switching customers re-renders the page with that customer's entitlements, channel, and license data applied. Without a token, the preview runs with mock customer data. **Editing content:** The preview reads from your local repo on every request. Edit any file (`theme.yaml`, a markdown page, `toc.yaml`, etc.), save, then refresh the browser. No restart needed. **Version / branch selector:** The preview lists your local git branches (minus `main`) in the version dropdown. Switching versions renders content from that branch. If your repo isn't a git checkout, you get a single synthetic "local" version that reads the working tree. ### Common options ```shell --port 4000 # choose a specific host port --app # app to resolve customers + branding against --token # override token (else: REPLICATED_API_TOKEN / stored profile) ``` :::note The local preview mocks some backend endpoints locally. Install flows, instance dashboards, and anything outside of docs content will render mostly empty or log benign errors. This is expected. Content changes must still be committed and pushed through your normal release flow to be visible to real customers. ::: ## Login as customer To view the production Enterprise Portal as a specific customer, use the **Login as customer** button on the customer's **Enterprise Portal access** tab (or the EP card on the customer's Reporting page). This generates a one-time login link and opens the portal in a new tab. This is useful for verifying that a customer sees the correct content, entitlements, and branding without creating a permanent user account in their portal team. The system creates a temporary system user scoped to that customer and generates a magic link nonce that expires after 10 minutes. The login routes to the correct portal version automatically. If the customer is on the new Enterprise Portal, the link opens `{appSlug}.enterpriseportal.app` (or your custom domain). If the customer is on Classic, the link opens `get.replicated.com`. --- # Customize Portal Branding :::important Alpha Feature Features described on this page are in alpha and subject to change. For access, contact your Replicated account representative. ::: Branding for the new Enterprise Portal is configured entirely through your content repo. There is no branding UI in the Vendor Portal. Include a `theme.yaml` file in your repo to override branding for any version of your docs. For content customization (pages, navigation, MDX components), see [Customize Portal Content](/vendor/enterprise-portal-v2-content). ## theme.yaml reference :::note All branding fields must be nested under the `branding:` key. Placing fields like `primaryColor` at the root level will cause a sync error. Only `customCSS` and `customCSSFile` go at the root level. ::: **Example:** ```yaml # theme.yaml branding: title: "Acme Portal" primaryColor: "#4f46e5" secondaryColor: "#6366f1" logo: assets/logo.png favicon: assets/favicon.ico contact: "support@acme.com" supportPortalLink: "https://support.acme.com" background: minimal # defaultTheme: dark # set to "light" if your branding is designed for light mode # Login page footer. Customize or remove these to brand your login page. # Warning: removing the login footer without a custom domain may cause # your portal to be flagged by Google Safe Browsing. loginFooterText: "Secured by Acme Corp" loginFooterLinks: - label: Privacy url: https://acme.com/privacy - label: Terms url: https://acme.com/terms # Optional: custom CSS (inline or file reference) customCSS: | .portal-header { border-bottom: 2px solid #4f46e5; } # customCSSFile: assets/custom.css ``` ## Branding fields | Field | Type | Notes | | :--- | :--- | :--- | | `title` | string | Portal title override, max 255 chars | | `overview` | string | Portal description, max 2000 chars | | `logo` | file path | Logo image, max 2MB (resolved to data URI) | | `favicon` | file path | Favicon, max 500KB | | `primaryColor` | hex | Primary brand color (`#RGB` or `#RRGGBB`) | | `secondaryColor` | hex | Secondary brand color | | `linkColor` | hex | Link color | | `linkHoverColor` | hex | Link hover color | | `background` | enum | `minimal`, `custom`, or `image` | | `backgroundImage` | file path | Background image, max 5MB (requires `background: image`) | | `customColor1` / `customColor2` | hex | Custom gradient colors (required when `background: custom`) | | `headerColor` / `headerGradientEnd` | hex | Header gradient | | `sidebarColor` / `sidebarGradientEnd` | hex | Sidebar gradient | | `contentBackgroundColor` / `contentBackgroundGradientEnd` | hex | Content area gradient | | `customCSS` | inline string | Inline CSS overrides, max 50KB | | `customCSSFile` | file path | Path to external CSS file, max 50KB | | `contact` | string | Support contact info, max 255 chars | | `supportPortalLink` | URL | External support link, max 2048 chars (http/https only) | | `loginFooterText` | string | Login page footer text, max 255 chars. Omit to use defaults. Set to empty string to hide. | | `loginFooterLinks` | list | Login page footer links. Each item has `label` (string, max 255 chars) and `url` (http/https, max 2048 chars). Omit to use defaults. Set to empty list to hide. | | `defaultTheme` | enum | Default color mode for new visitors: `light` or `dark`. When not set, defaults to `dark`. Customers can still toggle between light and dark mode; this setting controls the initial experience before they choose. | ## Login page footer By default, the login page shows a footer with "Secured by Enterprise Portal" and links to Privacy, Terms, and Contact pages on `enterpriseportal.app`. You can customize the text and links via `loginFooterText` and `loginFooterLinks` to point to your own pages. On a custom domain, you can remove the footer entirely by omitting these fields or setting `loginFooterText` to an empty string. :::caution On `*.enterpriseportal.app` domains (no custom domain), keeping the footer is recommended to avoid Google Safe Browsing flagging. ::: --- # Connect a Git Repo :::important Alpha Feature Features described on this page are in alpha and subject to change. Some capabilities might require additional access. ::: :::note Enterprise Portal requires a GitHub organization. The content repo integration uses the Replicated GitHub App for syncing and webhooks. GitLab, Bitbucket, and other git providers are not supported. ::: Enterprise Portal content is driven by a GitHub repo you control. Connecting a repo is a prerequisite to offer versioned docs, advanced theming, and Terraform module delivery. The Content tab appears when your team has the New Enterprise Portal. The same setting enables the GitHub App workflow for content repositories. Use this workflow to create, authorize, and link repos. The Vendor Portal walks you through setup in three steps: ## Step 1: Create from template Go to **Enterprise Portal** in Vendor Portal. The **Content** tab is the default landing page. Click **Create Repo from Template** to generate a new content repository from Replicated's template. This opens GitHub's "Create a new repository" flow, pre-configured with the `replicatedhq/enterprise-portal-content` template. The repository name is pre-filled as `-enterprise-portal-content` and visibility defaults to **private**. Choose an owner, adjust the name if needed, and click **Create repository** on GitHub. The template includes a working `toc.yaml`, example pages for installation (Linux and Helm), operations, updates, and support, along with built-in MDX components for interactive install instructions. See [Content Template Structure](/vendor/enterprise-portal-v2-content#content-template-structure) for what's included out of the box. If you already have a content repository (or prefer to create one from scratch), click **Continue** to skip this step. ## Step 2: Connect GitHub Click **Connect GitHub** and authorize the Replicated GitHub App on your GitHub organization. The App requests read-only access to sync content from your repo into Replicated. It does not write to or modify your repositories. Creating the repo first (Step 1) ensures it's available to grant access to during this step. To change the linked GitHub account later (for example, if you move your content repo to a different organization), go to **[Team > GitHub Integration](https://vendor.replicated.com/team/github-integration)** and connect the new account. :::note When installing the Replicated GitHub App, grant access to all repositories you plan to use with Enterprise Portal (content repos AND Terraform module repos). If you need to add access to additional repos later, update the GitHub App's repository permissions in your GitHub org settings (Settings > Integrations > Applications > Replicated > Configure > Repository access). ::: ## Step 3: Link repository Select your GitHub organization and the repository containing your Enterprise Portal content, then click **Link Repository**. When only one GitHub organization or repository is available, it is auto-selected for you. :::note The selected repository must contain a `toc.yaml` file at the root of its default branch. If none is found, you'll see a warning and won't be able to link the repo. Use the content template (Step 2) or add a `toc.yaml` manually before linking. ::: All branches are synced automatically. Pushes trigger automatic syncs via webhook. Once linked, the Content tab shows sync status for each branch. A branch labeled **Fallback** means it doesn't match any release `version_label` on the customer's channel. Fallback content is shown when no version-matched branch is available for a customer. See [Naming Your Branches](/vendor/enterprise-portal-v2-versioned-docs#naming-your-branches) for how to set up version gating. You can also trigger a manual sync from the **Content** tab. Via API: ``` # Your APP_ID is visible in the Vendor Portal URL when viewing your app, # or via: replicated api get /v3/apps | jq '.apps[] | {id, name}' # List your content repos to get the REPO_ID: replicated api get /v3/app//enterprise-portal/content-repos # Trigger a sync: replicated api post /v3/app//enterprise-portal/content-repos//sync ``` :::important Content branches must be named with semver versions (e.g., 1.0.0) that match your release version_label values. The main branch is synced but never shown to customers directly. See [Naming Your Branches](/vendor/enterprise-portal-v2-versioned-docs#naming-your-branches) for details. ::: ## Adopting template updates You create your content repo from the [replicatedhq/enterprise-portal-content](https://github.com/replicatedhq/enterprise-portal-content) template. Because you clone the template rather than fork it, your repo diverges as soon as you start customizing content, branding, and navigation. When Replicated publishes improvements to the template (new MDX components, updated default pages, navigation changes), the Vendor Portal shows a banner on the **Content** tab with the number of updates available since your last review. ### Reviewing updates Click **Review** on the Content tab banner to open the template updates modal. Each update includes: - **Title and date**: What changed and when - **Impact level**: `required`, `recommended`, or `optional`, indicating how important the update is for your portal - **Summary**: A brief description of the change and its effect on your customers' portal experience - **Affected areas**: Tags showing which parts of the template the update touches (for example, installation instructions, navigation, troubleshooting content) - **Guide link**: Opens the full adoption guide on GitHub with step-by-step instructions for applying the change to your repo ### Applying an update Template updates do not apply automatically. Each update's guide describes what files to copy or modify and what to verify after making the change. Because your repo has diverged from the template, each guide provides targeted adoption steps rather than a wholesale merge. After reviewing the available updates, click **Mark reviewed** to acknowledge them. The banner clears until Replicated publishes the next template update. Marking updates as reviewed is per-user, so other team members continue to see the banner until they review it themselves. --- # Customize Portal Content :::important Alpha Feature Features described on this page are in alpha and subject to change. For access, contact your Replicated account representative. ::: This topic describes how to customize the content in the new Enterprise Portal, including the content template structure, table of contents configuration, MDX components, template variables, visibility rules, and downloadable assets. For branding and theme customization, see [Customize Portal Branding](/vendor/enterprise-portal-v2-branding). To serve different content for different release versions, see [Manage Content Versions](/vendor/enterprise-portal-v2-versioned-docs). ## Content template structure {#content-template-structure} The default content template ([replicatedhq/enterprise-portal-content](https://github.com/replicatedhq/enterprise-portal-content)) provides a working portal out of the box with the following structure: ``` your-content-repo/ ├── pages/ │ ├── home.md │ ├── installation/ │ │ ├── requirements.md │ │ ├── release-history.md │ │ ├── linux.md │ │ └── helm.md │ ├── operations/ │ │ ├── security.md │ │ └── bundles/ │ │ ├── bundles.md │ │ ├── helm.md │ │ ├── linux.md │ │ └── uploaded.md │ ├── updates/ │ │ └── checking.md │ └── support/ │ ├── faq.md │ └── contact.md └── toc.yaml ``` The template's `toc.yaml` organizes content into four sections: ```yaml navigation: - title: Installation icon: rocket items: - title: Requirements page: pages/installation/requirements.md visible_when: entitlements: - isEmbeddedClusterDownloadEnabled - title: Release History page: pages/installation/release-history.md - title: Linux page: pages/installation/linux.md visible_when: entitlements: - isEmbeddedClusterDownloadEnabled - title: Helm page: pages/installation/helm.md visible_when: entitlements: - isHelmInstallEnabled - title: Operations icon: wrench items: - title: Security page: pages/operations/security.md - title: Support Bundles page: pages/operations/bundles/bundles.md - title: Upload Bundles page: pages/operations/bundles/uploaded.md - title: Updates icon: refresh-cw items: - title: Checking for Updates page: pages/updates/checking.md - title: Support icon: life-buoy items: - title: FAQ page: pages/support/faq.md - title: Contact Support page: pages/support/contact.md overrides: home: pages/home.md ``` The template pages use built-in MDX components (see [MDX Components](#mdx-components)) to render interactive installation instructions, version selectors, support bundle uploads, and more. You can customize any page by editing the markdown and MDX, or replace the entire structure with your own. ## Table of contents The `toc.yaml` file at the root of your repo defines the sidebar navigation. Each navigation item has a `title` and one of the following content types: | Key | What it does | | :--- | :--- | | `page` | Renders a markdown file from your repo (e.g. `pages/getting-started.md`) | | `terraform_module` | Generates docs from a Terraform module source URI (see [Terraform Modules](/vendor/enterprise-portal-v2-terraform)) | | `helm_chart` | Generates reference docs from a Helm chart in your promoted release (see [Helm Reference Docs](/vendor/enterprise-portal-v2-helm-reference)) | | `items` | Nests child navigation items to create expandable sections. Items can nest to any depth, with each child following the same structure | Every item also supports `icon` and `visible_when` (see [Visibility](#visibility) below). The `toc.yaml` acts as an allowlist: pages that exist in your repo but are not listed in `toc.yaml` are not reachable through the portal navigation or direct URL. This means you can hide a page by simply omitting it from `toc.yaml`. :::note The `overrides.home` page bypasses the TOC allowlist and remains accessible even if it is not listed in `toc.yaml`. If you need to hide the home page, use `visible_when` in its frontmatter instead. ::: Supported icon values: `rocket`, `download`, `cloud`, `settings`, `wrench`, `life-buoy`, `file-text`, `star`, `book`, `shield`, `package`, `refresh-cw`, `database`, `key`. If omitted, defaults to `book`. ### Complete example Here's a `toc.yaml` showing all content types together: ```yaml navigation: - title: Getting Started icon: rocket page: pages/getting-started.md - title: Installation icon: download items: - title: Requirements page: pages/installation/requirements.md - title: Helm Installation page: pages/installation/helm.md visible_when: entitlements: - isHelmInstallEnabled - title: Air Gap Installation page: pages/installation/airgap.md visible_when: entitlements: - isAirgapSupported - title: Infrastructure icon: database items: - title: AWS Module terraform_module: github.com/your-org/your-terraform//modules/aws?ref=v1.0.0 visible_when: entitlements: - isAWSEnabled - title: Reference icon: book items: - title: My App Chart helm_chart: name: my-app overrides: home: pages/getting-started.md ``` ### Nested navigation Navigation items can nest to any depth. Each child item follows the same structure and can contain its own `items` array: ```yaml navigation: - title: Configuration icon: settings items: - title: Required Values page: pages/configuration/required-values.md items: - title: Authentication page: pages/configuration/auth.md - title: Networking page: pages/configuration/networking.md - title: Optional Values page: pages/configuration/optional-values.md ``` In this example, **Configuration** expands to show **Required Values** and **Optional Values**. **Required Values** further expands to show **Authentication** and **Networking**. Each level is collapsible in the sidebar. Any item with `items` can also have its own `page`, `visible_when`, and `icon`. If all children of a parent are hidden by `visible_when`, the parent is also hidden automatically. ## MDX components {#mdx-components} Enterprise Portal content supports MDX, which is markdown with embedded React components. These components render interactive UI elements that adapt to each customer's license, entitlements, and instance state. ### Layout and callouts **``**: Informational callout box. ```markdown Run `kubectl get sc` to confirm a default StorageClass is available. ``` **``**: Highlighted tip or best practice. ```markdown Start with the Installation Guide for your deployment method. ``` **``**: Warning callout for important caveats. ```markdown Always create a backup before applying updates. ``` **`` / ``**: Tabbed content sections. ```markdown Linux-specific instructions here... Helm-specific instructions here... ``` Props: `` accepts `defaultActiveTab`. `` requires `title`. **``**: Collapsible content section. ```markdown Detailed configuration options... ``` Props: `title` (required), `defaultOpen` (optional, defaults to false). **`` / `