diff --git a/docs/intro.md b/docs/intro.md index 357b8d9687..c7a5160c4a 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -49,13 +49,10 @@ pagination_next: null Replicated FAQs
  • - Replicated Quick Start + Replicated Onboarding
  • - Tutorials -
    • -
  • - Getting Started Lab in Instruqt + Tutorials
    • @@ -141,9 +138,6 @@ pagination_next: null
  • Introduction to KOTS
    • -
  • - Onboarding with KOTS -
  • About Distributing Helm Charts with KOTS
    • @@ -151,19 +145,19 @@ pagination_next: null diff --git a/docs/partials/getting-started/_create-promote-release.mdx b/docs/partials/getting-started/_create-promote-release.mdx new file mode 100644 index 0000000000..5eb72800f9 --- /dev/null +++ b/docs/partials/getting-started/_create-promote-release.mdx @@ -0,0 +1 @@ +Create a new release and promote it to the Unstable channel. For more information, see [Managing Releases with the Vendor Portal](releases-creating-releases) or [Managing Releases with the CLI](releases-creating-cli). \ No newline at end of file diff --git a/docs/partials/getting-started/_test-your-changes.mdx b/docs/partials/getting-started/_test-your-changes.mdx new file mode 100644 index 0000000000..ab570b4fbe --- /dev/null +++ b/docs/partials/getting-started/_test-your-changes.mdx @@ -0,0 +1 @@ +Install the release to test your changes. For Embedded Cluster installations, see [Performing Udpates in Embedded Clusters](/enterprise/updating-embedded). For existing cluster installations with KOTS, see [Performing Updates in Existing Clusters](/enterprise/updating-app-manager). \ No newline at end of file diff --git a/docs/partials/replicated-sdk/_dependency-yaml.mdx b/docs/partials/replicated-sdk/_dependency-yaml.mdx index 6c57134e9b..116eeb4138 100644 --- a/docs/partials/replicated-sdk/_dependency-yaml.mdx +++ b/docs/partials/replicated-sdk/_dependency-yaml.mdx @@ -6,4 +6,4 @@ dependencies: version: 1.0.0-beta.25 ``` -For the latest version information for the Replicated SDK, see the [replicated-sdk repository](https://github.com/replicatedhq/replicated-sdk/tags) in GitHub. +For the latest version information for the Replicated SDK, see the [replicated-sdk repository](https://github.com/replicatedhq/replicated-sdk/releases) in GitHub. diff --git a/docs/reference/custom-resource-application.mdx b/docs/reference/custom-resource-application.mdx index 5ed15c20e6..e6027b9a6c 100644 --- a/docs/reference/custom-resource-application.mdx +++ b/docs/reference/custom-resource-application.mdx @@ -85,7 +85,7 @@ spec: - + diff --git a/docs/vendor/distributing-workflow.md b/docs/vendor/distributing-workflow.md deleted file mode 100644 index 3b10aebc71..0000000000 --- a/docs/vendor/distributing-workflow.md +++ /dev/null @@ -1,129 +0,0 @@ -import SDKOverview from "../partials/replicated-sdk/_overview.mdx" - -# Onboarding with KOTS - -This topic describes how to onboard with Replicated KOTS, including prerequisites and the list of custom resources to add to your releases in order to support KOTS installations. - -## Prerequisites - -If you are new to Replicated, complete the following prerequisites before you get started with KOTS: - -* Create an account in the Vendor Portal. You can either create a new team or join an existing team. For more information, see [Creating a Vendor Account](vendor-portal-creating-account). - -* Review [Replicated Onboarding](/vendor/replicated-onboarding) for more information about onboarding an application to the Replicated Platform before you get started with KOTS. - -## Add Custom Resources - -You can add custom resources to your releases to support installations with KOTS. The custom resources are consumed by KOTS and are not deployed to the cluster. This section provides a checklist of the custom resources to add as well as information about how to add and test custom resources. - -### How to Add Custom Resources - -Replicated recommends that you configure and add one custom resource at a time by creating a release and then upgrading in a development environment to test. You can add these custom resources to releases in any order that you prefer. - -For more information about creating releases, see [Managing Releases with the Vendor Portal](releases-creating-releases). For more information about installing and upgrading with KOTS, see [About Installing an Application](/enterprise/installing-overview) and [Performing Updates in Existing Clusters](/enterprise/updating-app-manager). - -### Custom Resource Checklist - -This section lists the required and recommended custom resources to add to your releases to enable KOTS installations for your application. The custom resources are grouped in the following categories: - -* [KOTS Admin Console](#admin-console) -* [Helm Chart Installations](#helm-chart-installations) -* [Embedded Kubernetes](#embedded-kubernetes) - -#### KOTS Admin Console {#admin-console} - -The following custom resources can be added to customize the Admin Console experience for your application and enable recommended features for KOTS. - -
    DescriptionThe icon file for the application. Used on the license upload and in various places in the Admin Console.The icon file for the application. Used on the license upload, in various places in the Admin Console, and in the Download Portal. The icon can be a remote URL or a Base64 encoded image. Base64 encoded images are required to display the image in air gap installations with no outbound internet access.
    Example
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Custom ResourceDescriptionHow To
    KOTS Application

    Control the KOTS Admin Console experience for your application.

    		 - Application -
    Kubernetes SIG Application

    Add links to the Admin Console dashboard. A common use case for the Kubernetes Application custom resource is adding a button to the dashboard that users can click to navigate to port forwarded services for your application.

    		Adding Application Links to the Dashboard
    Config -

    Create a configuration screen in the Admin Console to collect required and optional configuration values from your users.

    -

    Note: This feature does not apply to Kubernetes Operators.

    -     		Creating and Editing Configuration Fields
    Preflight

    Define preflight checks to test for system compliance during installation and upgrade to reduce the number of support escalations.

    		Defining Preflight Checks
    SupportBundle

    Enable customers to quickly collect and analyze troubleshooting data from their clusters to help you diagnose problems with application deployments.

    		Adding and Customizing Support Bundles
    BackupEnable snapshots with Velero so that end users can back up and restore their application data.Configuring Backup and Restore
    - -#### Helm Chart Installations - -The HelmChart custom resource is required to install Helm charts with KOTS. - - - - - - - - - - - - -
    Custom ResourceDescriptionHow To
    HelmChart

    Provides instructions for KOTS about how to deploy a given Helm chart.

    		Configuring the HelmChart Custom Resource
    - -#### Embedded Kubernetes - -The following custom resources can be added to embed Kubernetes with your application to support KOTS installations in VMs or bare metal servers. - -You can choose to use either Replicated Embedded Cluster or Replicated kURL to embed Kubernetes. For more information, see [About Embedded Kubernetes](/vendor/embedded-kubernetes-overview). - - - - - - - - - - - - - - - - - -
    Custom ResourceDescriptionHow To
    Embedded Cluster ConfigCreate an embedded cluster config to support installations in VMs or bare metal servers with Replicated Embedded Cluster.Using Embedded Cluster
    InstallerCreate an Installer spec to support installations in VMs or bare metal servers with Replicated kURL.Creating a kURL Installer
    - -## Distribute the SDK with your Application - - - -## Configure Additional Replicated Features - -See [Replicated Onboarding](/vendor/replicated-onboarding) for a list of features to integrate with your application to fully onboard onto the Replicated platform. - -For example, you can add custom domains for the Replicated registry and app service, configure checks in your application for custom license entitlements, collect custom metrics using the Replicated SDK API, and more. \ No newline at end of file diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index d9e7af0dcf..3134d26738 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -12,38 +12,6 @@ For more information about the HelmChart custom resource, including the unique r After you complete the tasks in this topic to configure the `kots.io/v1beta2` HelmChart custom resource, you can migrate any existing installations that were deployed with `kots.io/v1beta1` with `useHelmInstall: true` to use `kots.io/v1beta2` instead. For more information, see [Migrating Existing Installations to HelmChart v2](helm-v2-migrate). -## HelmChart v1 and v2 Differences - -The `kots.io/v1beta2` HelmChart custom resource has the following differences from `kots.io/v1beta1`: - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    HelmChart v1beta2HelmChart v1beta1Description
    apiVersion: kots.io/v1beta2apiVersion: kots.io/v1beta1apiVersion is updated to kots.io/v1beta2
    releaseNamechart.releaseNamereleaseName is a top level field under spec
    N/AhelmVersionhelmVersion field is removed
    N/AuseHelmInstalluseHelmInstall field is removed
    - ## Workflow To support installations with the `kots.io/v1beta2` HelmChart custom resource, do the following: @@ -271,7 +239,11 @@ spec: ### Add Backup Labels for Snapshots -The Replicated snapshots feature requires the following labels on all resources in your Helm chart that you want to be included in the backup: +:::note +The Replicated [snapshots](snapshots-overview) feature for backup and restsore is supported only for existing cluster installations with KOTS. Snapshots are not support for installations with Embedded Cluster. For more information about disaster recovery for installations with Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery.mdx). +::: + +The snapshots feature requires the following labels on all resources in your Helm chart that you want to be included in the backup: * `kots.io/backup: velero` * `kots.io/app-slug: APP_SLUG`, where `APP_SLUG` is the slug of your Replicated application. @@ -308,14 +280,42 @@ spec: kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }} ``` -### Support Local Image Registries for Online Installations {#local-registries} +### Support Local Image Registries {#local-registries} Local image registries are required for KOTS installations in air gapped environments. Also, users in online environments can optionally push images to a local registry. For more information about how users configure a local image registry with KOTS, see [Using Private Registries](/enterprise/image-registry-settings). -To support the use of local registries for online installations with version `kots.io/v1beta2` of the HelmChart custom resource, you must provide the necessary values in the builder field to render the Helm chart with all of the necessary images so that KOTS knows where to pull the images from to push them into the local registry. +To support the use of local registries with version `kots.io/v1beta2` of the HelmChart custom resource, provide the necessary values in the builder field to render the Helm chart with all of the necessary images so that KOTS knows where to pull the images from to push them into the local registry. -For more information about how to configure the `builder` key, see [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. +For more information about how to configure the `builder` key, see [Packaging Air Gap Bundles for Helm Charts](/vendor/helm-packaging-airgap-bundles) and [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. -:::note -If you already configured the `builder` key previously to support air gap installations, then you can use the same configuration in your HelmChart custom resource to support the use of local registries for online installations. No additional configuration is required. -::: \ No newline at end of file +## HelmChart v1 and v2 Differences + +The `kots.io/v1beta2` HelmChart custom resource has the following differences from `kots.io/v1beta1`: + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    HelmChart v1beta2HelmChart v1beta1Description
    apiVersion: kots.io/v1beta2apiVersion: kots.io/v1beta1apiVersion is updated to kots.io/v1beta2
    releaseNamechart.releaseNamereleaseName is a top level field under spec
    N/AhelmVersionhelmVersion field is removed
    N/AuseHelmInstalluseHelmInstall field is removed
    \ No newline at end of file diff --git a/docs/vendor/kots-faq.mdx b/docs/vendor/kots-faq.mdx index 846df867dd..4f974b05ff 100644 --- a/docs/vendor/kots-faq.mdx +++ b/docs/vendor/kots-faq.mdx @@ -129,7 +129,7 @@ Releases that support installation with KOTS include the manifests required by K In addition to the KOTS manifests, releases that support installation with Embedded Cluster also include the Embedded Cluster Config. The Embedded Cluster Config defines aspects of the cluster that will be provisioned and also sets the version of KOTS that will be installed. -For more information, see [Onboarding with KOTS](/vendor/distributing-workflow) and [Using Embedded Cluster](/vendor/embedded-overview). +For more information, see [Using Embedded Cluster](/vendor/embedded-overview). ### Can I use my own branding? diff --git a/docs/vendor/quick-start.mdx b/docs/vendor/quick-start.mdx new file mode 100644 index 0000000000..530dda5633 --- /dev/null +++ b/docs/vendor/quick-start.mdx @@ -0,0 +1,436 @@ +--- +pagination_next: null +--- + +import DependencyYaml from "../partials/replicated-sdk/_dependency-yaml.mdx" +import HelmPackage from "../partials/helm/_helm-package.mdx" +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import HelmChartCr from "../partials/getting-started/_gitea-helmchart-cr-ec.mdx" +import KotsCr from "../partials/getting-started/_gitea-kots-app-cr-ec.mdx" +import K8sCr from "../partials/getting-started/_gitea-k8s-app-cr.mdx" +import EcCr from "../partials/embedded-cluster/_ec-config.mdx" +import Requirements from "../partials/embedded-cluster/_requirements.mdx" + +# Replicated Quick Start + +Welcome! This topic provides a quick start workflow to help new users learn about the Replicated Platform. Complete this quick start before you onboard your application to the platform. + +## Introduction + +This quick start shows how to create, install, and update releases for a sample Helm chart in the Replicated Platform. You will repeat these same basic steps to create and test releases throughout the onboarding process to integrate Replicated features with your own application. + +The goals of this quick start are to introduce new Replicated users to the following common tasks for the purpose of preparing to onboard to the Replicated Platform: + +* Working with _applications_, _channels_, _releases_, and _customers_ in the Replicated Vendor Portal + +* Working with the Replicated CLI + +* Installing and updating applications on a VM with Replicated Embedded Cluster + +* Managing an installation with the Replicated KOTS Admin Console + +## Set Up the Environment + +Before you begin, ensure that you have access to a VM that meets the requirements for Embedded Cluster: + + + +## Quick Start + +1. Create an account in the Vendor Portal. You can either create a new team or join an existing team. For more information, see [Creating a Vendor Account](vendor-portal-creating-account). + +1. Create an application using the Replicated CLI: + + 1. On your local machine, install the Replicated CLI: + + ```bash + brew install replicatedhq/replicated/cli + ``` + For more installation options, see [Installing the Replicated CLI](/reference/replicated-cli-installing). + + 1. Authorize the Replicated CLI: + + ```bash + replicated login + ``` + In the browser window that opens, complete the prompts to log in to your Vendor Portal account and authorize the CLI. + + 1. Create an application named `Gitea`: + + ```bash + replicated app create Gitea + ``` + + 1. Set the `REPLICATED_APP` environment variable to the application that you created: + + ```bash + export REPLICATED_APP=APP_SLUG + ``` + Where `APP_SLUG` is the unique application slug provided in the output of the `app create` command. For example, `export REPLICATED_APP=gitea-kite`. + + This allows you to interact with the application using the Replicated CLI without needing to use the `--app` flag with every command. + +1. Get the sample Bitnami Gitea Helm chart and add the Replicated SDK as a dependency: + + 1. Run the following command to pull and untar version 1.0.6 of the Bitnami Gitea Helm chart: + + ``` + helm pull --untar oci://registry-1.docker.io/bitnamicharts/gitea --version 1.0.6 + ``` + For more information about this chart, see the [bitnami/gitea](https://github.com/bitnami/charts/tree/main/bitnami/gitea) repository in GitHub. + + 1. Change to the new `gitea` directory that was created: + + ```bash + cd gitea + ``` + + 1. In the Helm chart `Chart.yaml`, add the Replicated SDK as a dependency: + + + + The Replicated SDK is a Helm chart that provides access to Replicated features and can be installed as a small service alongside your application. For more information, see [About the Replicated SDK](/vendor/replicated-sdk-overview). + + 1. Update dependencies and package the Helm chart to a `.tgz` chart archive: + + ```bash + helm package -u . + ``` + Where `-u` or `--dependency-update` is an option for the helm package command that updates chart dependencies before packaging. For more information, see [Helm Package](https://helm.sh/docs/helm/helm_package/) in the Helm documentation. + +1. Add the chart archive to a release: + + 1. In the `gitea` directory, create a subdirectory named `manifests`: + + ``` + mkdir manifests + ``` + + You will add the files required to support installation with Replicated KOTS and Replicated Embedded Cluster to this subdirectory. + + 1. Move the Helm chart archive that you created to `manifests`: + + ``` + mv gitea-1.0.6.tgz manifests + ``` + + 1. In `manifests`, create the following YAML files: + ``` + cd manifests + ``` + ``` + touch gitea.yaml kots-app.yaml k8s-app.yaml embedded-cluster.yaml + ``` + + 1. In each of the files that you created, paste the corresponding YAML provided in the tabs below: + + + +
    Description
    +

    The KOTS HelmChart custom resource provides instructions to KOTS about how to deploy the Helm chart. The name and chartVersion listed in the HelmChart custom resource must match the name and version of a Helm chart archive in the release. The optionalValues field sets the specified Helm values when a given conditional statement evaluates to true. In this case, if the application is installed with Embedded Cluster, then the Gitea service type is set to `NodePort` and the node port is set to `"32000"`. This will allow Gitea to be accessed from the local machine after deployment for the purpose of this quick start.

    +
    YAML
    + +     + +
    Description
    +

    The KOTS Application custom resource enables features in the Replicated Admin Console such as branding, release notes, application status indicators, and custom graphs.

    The YAML below provides a name for the application to display in the Admin Console, adds a custom status informer that displays the status of the gitea Deployment resource in the Admin Console dashboard, adds a custom application icon, and adds the port where the Gitea service can be accessed so that the user can open the application after installation.

    +
    YAML
    + +     + +
    Description
    +

    The Kubernetes SIG Application custom resource supports functionality such as including buttons and links on the Replicated Admin Console dashboard. The YAML below adds an Open App button to the Admin Console dashboard that opens the application using the service port defined in the KOTS Application custom resource.

    +
    YAML
    + +     + +
    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
    + +     +     + + 1. Lint the YAML files: + + ```bash + replicated release lint --yaml-dir . + ``` + **Example output:** + ```bash + RULE TYPE FILENAME LINE MESSAGE + config-spec warn Missing config spec + preflight-spec warn Missing preflight spec + troubleshoot-spec warn Missing troubleshoot spec + nonexistent-status-informer-object warn kots-app.yaml 8 Status informer points to a nonexistent kubernetes object. If this is a Helm resource, this warning can be ignored. + ``` + :::note + You can ignore any warning messages for the purpose of this quick start. + ::: + + 1. Create the release and promote it to the Unstable channel: + + ```bash + replicated release create --yaml-dir . --promote Unstable + ``` + **Example output**: + ```bash + • Reading manifests from . ✓ + • Creating Release ✓ + • SEQUENCE: 1 + • Promoting ✓ + • Channel 2kvjwEj4uBaCMoTigW5xty1iiw6 successfully set to release 1 + ``` + +1. Create a customer so that you can install the release on your VM with Embedded Cluster: + + 1. In the [Vendor Portal](https://vendor.replicated.com), select the Gitea application and then click **Customers > Create customer**. + + The **Create a new customer** page opens: + + ![Customer a new customer page in the Vendor Portal](/images/create-customer.png) + + [View a larger version of this image](/images/create-customer.png) + + 1. For **Customer name**, enter a name for the customer. For example, `Example Customer`. + + 1. For **Channel**, select **Unstable**. This allows the customer to install releases promoted to the Unstable channel. + + 1. For **License type**, select **Development**. + + 1. For **License options**, enable the following entitlements: + * **KOTS Install Enabled** + * **Embedded Cluster Enabled** + + 1. Click **Save Changes**. + +1. Install the application with Embedded Cluster: + + 1. On the page for the customer that you created, click **Install instructions > Embedded Cluster**. + + ![Customer install instructions dropdown](/images/customer-install-instructions-dropdown.png) + + [View a larger image](/images/customer-install-instructions-dropdown.png) + + 1. On the command line, SSH onto your VM and run the commands in the **Embedded cluster install instructions** dialog to download the latest release, extract the installation assets, and install. + + embedded cluster install instructions dialog + + [View a larger version of this image](/images/embedded-cluster-install-dialog-latest.png) + + 1. When prompted, enter a password for accessing the Admin Console. + + The installation command takes a few minutes to complete. + + **Example output:** + + ```bash + ? Enter an Admin Console password: ******** + ? Confirm password: ******** + ✔ Host files materialized! + ✔ Running host preflights + ✔ Node installation finished! + ✔ Storage is ready! + ✔ Embedded Cluster Operator is ready! + ✔ Admin Console is ready! + ✔ Additional components are ready! + Visit the Admin Console to configure and install gitea-kite: http://104.155.145.60:30000 + ``` + + At this point, the cluster is provisioned and the Admin Console is deployed, but the application is not yet installed. + + 1. Go to the URL provided in the output to access to the Admin Console. + + 1. Bypass the browser TLS warning by clicking **Continue to Setup**. + + 1. Click **Advanced > Proceed**. + + 1. On the **HTTPS for the Gitea Admin Console** page, select **Self-signed** and click **Continue**. + + 1. On the login page, enter the Admin Console password that you created during installation and click **Log In**. + + 1. On the **Nodes** page, you can view details about the VM where you installed, including its node role, status, CPU, and memory. Users can also optionally add additional nodes on this page before deploying the application. Click **Continue**. + + The Admin Console dashboard opens. + + 1. In the **Version** section, next to the new version, click **Deploy** and then **Yes, Deploy**. + + The application status changes from Missing to Unavailable while the `gitea` Deployment is being created. + + 1. After a few minutes when the application status is Ready, click **Open App** to view the Gitea application in a browser. + + For example: + + ![Admin console dashboard showing ready status](/images/gitea-ec-ready.png) + + [View a larger version of this image](/images/gitea-ec-ready.png) + + Gitea app landing page + + [View a larger version of this image](/images/gitea-app.png) + +1. Return to the Vendor Portal and go to **Customers**. Under the name of the customer, confirm that you can see an active instance. + + This instance telemetry is automatically collected and sent back to the Vendor Portal by both KOTS and the Replicated SDK. For more information, see [About Instance and Event Data](/vendor/instance-insights-event-data). + +1. Under **Instance ID**, click on the ID to view additional insights including the versions of Kubernetes and the Replicated SDK running in the cluster where you installed the application. For more information, see [Instance Details](/vendor/instance-insights-details). + +1. Create a new release that adds preflight checks to the application: + + 1. In your local filesystem, go to the `gitea` directory. + + 1. Create a `gitea-preflights.yaml` file in the `templates` directory: + + ``` + touch templates/gitea-preflights.yaml + ``` + + 1. In the `gitea-preflights.yaml` file, add the following YAML to create a Kubernetes Secret with a simple preflight spec: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + labels: + troubleshoot.sh/kind: preflight + name: "{{ .Release.Name }}-preflight-config" + stringData: + preflight.yaml: | + apiVersion: troubleshoot.sh/v1beta2 + kind: Preflight + metadata: + name: preflight-sample + spec: + collectors: + - http: + collectorName: slack + get: + url: https://api.slack.com/methods/api.test + analyzers: + - textAnalyze: + checkName: Slack Accessible + fileName: slack.json + regex: '"status": 200,' + outcomes: + - pass: + when: "true" + message: "Can access the Slack API" + - fail: + when: "false" + message: "Cannot access the Slack API. Check that the server can reach the internet and check [status.slack.com](https://status.slack.com)." + ``` + The YAML above defines a preflight check that confirms that an HTTP request to the Slack API at `https://api.slack.com/methods/api.test` made from the cluster returns a successful response of `"status": 200,`. + + 1. In the `Chart.yaml` file, increment the version to 1.0.7: + + ```yaml + # Chart.yaml + version: 1.0.7 + ``` + + 1. Update dependencies and package the chart to a `.tgz` chart archive: + + ```bash + helm package -u . + ``` + + 1. Move the chart archive to the `manifests` directory: + + ```bash + mv gitea-1.0.7.tgz manifests + ``` + + 1. In the `manifests` directory, open the KOTS HelmChart custom resource (`gitea.yaml`) and update the `chartVersion`: + + ```yaml + # gitea.yaml KOTS HelmChart + chartVersion: 1.0.7 + ``` + + 1. Remove the chart archive for version 1.0.6 of the Gitea chart from the `manifests` directory: + + ``` + rm gitea-1.0.6.tgz + ``` + + 1. From the `manifests` directory, create and promote a new release, setting the version label of the release to `0.0.2`: + + ```bash + replicated release create --yaml-dir . --promote Unstable --version 0.0.2 + ``` + **Example output**: + ```bash + • Reading manifests from . ✓ + • Creating Release ✓ + • SEQUENCE: 2 + • Promoting ✓ + • Channel 2kvjwEj4uBaCMoTigW5xty1iiw6 successfully set to release 2 + ``` + +1. On your VM, update the application instance to the new version that you just promoted: + + 1. In the Admin Console, go to the **Version history** tab. + + The new version is displayed automatically. + + 1. Click **Deploy** next to the new version. + + The Embedded Cluster upgrade wizard opens. + + 1. In the Embedded Cluster upgrade wizard, on the **Preflight checks** screen, note that the "Slack Accessible" preflight check that you added was successful. Click **Next: Confirm and deploy**. + + ![preflight page of the embedded cluster upgrade wizard](/images/quick-start-ec-upgrade-wizard-preflight.png) + + [View a larger version of this image](/images/quick-start-ec-upgrade-wizard-preflight.png) + + :::note + The **Config** screen in the upgrade wizard is bypassed because this release does not contain a KOTS Config custom resource. The KOTS Config custom resource is used to set up the Config screen in the KOTS Admin Console. + ::: + + 1. On the **Confirm and Deploy** page, click **Deploy**. + +1. Reset and reboot the VM to remove the installation: + + ```bash + sudo ./APP_SLUG reset + ``` + Where `APP_SLUG` is the unique slug for the application. + + :::note + You can find the application slug by running `replicated app ls` on your local machine. + ::: + +## Next Steps + +Congratulations! As part of this quick start, you: +* Added the Replicated SDK to a Helm chart +* Created a release with the Helm chart +* Installed the release on a VM with Embedded Cluster +* Viewed telemetry for the installed instance in the Vendor Portal +* Created a new release to add preflight checks to the application +* Updated the application from the Admin Console + +Now that you are familiar with the workflow of creating, installing, and updating releases, you can begin onboarding your own application to the Replicated Platform. + +To get started, see [Replicated Onboarding](replicated-onboarding). + +## Related Topics + +For more information about the Replicated Platform features mentioned in this quick start, see: + +* [About Distributing Helm Charts with KOTS](/vendor/helm-native-about) +* [About Preflight Checks and Support Bundles](/vendor/preflight-support-bundle-about) +* [About the Replicated SDK](/vendor/replicated-sdk-overview) +* [Introduction to KOTS](/intro-kots) +* [Managing Releases with the CLI](/vendor/releases-creating-cli) +* [Packaging a Helm Chart for a Release](/vendor/helm-install-release) +* [Using Embedded Cluster](/vendor/embedded-overview) + +## Related Tutorials + +For additional tutorials related to this quick start, see: + +* [Deploying a Helm Chart on a VM with Embedded Cluster](/vendor/tutorial-embedded-cluster-setup) +* [Adding Preflight Checks to a Helm Chart](/vendor/tutorial-preflight-helm-setup) +* [Deploying a Helm Chart with KOTS and the Helm CLI](/vendor/tutorial-kots-helm-setup) \ No newline at end of file diff --git a/docs/vendor/replicated-onboarding.mdx b/docs/vendor/replicated-onboarding.mdx index 3db3560477..362b420b70 100644 --- a/docs/vendor/replicated-onboarding.mdx +++ b/docs/vendor/replicated-onboarding.mdx @@ -1,171 +1,583 @@ ---- -pagination_next: null ---- +import CreateRelease from "../partials/getting-started/_create-promote-release.mdx" +import DependencyYaml from "../partials/replicated-sdk/_dependency-yaml.mdx" +import EcCr from "../partials/embedded-cluster/_ec-config.mdx" +import HelmPackage from "../partials/helm/_helm-package.mdx" +import Requirements from "../partials/embedded-cluster/_requirements.mdx" +import SDKOverview from "../partials/replicated-sdk/_overview.mdx" +import TestYourChanges from "../partials/getting-started/_test-your-changes.mdx" +import UnauthorizedError from "../partials/replicated-sdk/_401-unauthorized.mdx" -# Replicated Onboarding +# Replicated Onboarding -Welcome! This topic provides a checklist to help you onboard to the Replicated Platform. For more information about Replicated, see [Introduction to Replicated](../intro-replicated). +This topic describes how to onboard applications to the Replicated Platform. -## Best Practices and Recommendations +## Before You Begin -The following are Replicated's best practices and recommendations for successfully onboarding: +This section includes guidance and prerequisites to review before you begin onboarding your application. -* Replicated recommends that all applications are packaged with Helm. If you are relatively new to Kubernetes or Helm, start with a basic tutorial. For example, see [10 Helm Tutorials to Start your Kubernetes Journey](https://jfrog.com/blog/10-helm-tutorials-to-start-your-kubernetes-journey/) or [Tutorials](https://kubernetes.io/docs/tutorials/) in the Kubernetes documentation. +### Best Practices and Recommendations -* When integrating new Replicated features with an application, make changes in small iterations and test frequently by installing or upgrading the application in a development environment. This will help you to more easily identify issues and troubleshoot. +The following are some best practices and recommendations for successfully onboarding with Replicated: - For information about how to install, see: - * [Installing with Embedded Cluster](/enterprise/installing-embedded) - * [Installing with Helm](/vendor/install-with-helm) - * [Installing with KOTS in Existing Clusters](/enterprise/installing-existing-cluster) - - For information about how to perform updates, see: - * [Performing Updates in Embedded Clusters](/enterprise/updating-embedded) - * [Performing Updates in Existing Clusters](/enterprise/updating-app-manager) +* When integrating new Replicated features with an application, make changes in small iterations and test frequently by installing or upgrading the application in a development environment. This will help you to more easily identify issues and troubleshoot. This onboarding workflow will guide you through the process of integrating features in small iterations. -* Create and manage releases with the Replicated CLI. For more information, see [Installing the Replicated CLI](/reference/replicated-cli-installing). +* Use the Replicated CLI to create and manage your application and releases. Getting familiar with the Replicated CLI will also help later on when integrating Replicated workflows into your CI/CD pipelines. For more information, see [Installing the Replicated CLI](/reference/replicated-cli-installing). -* Ask for help from the Replicated community. For more information, see [Get Help from the Community](#get-help-from-the-community). +* These onboarding tasks assume that you will test the installation of each release on a VM with the Replicated Embedded Cluster installer _and_ in a cluster with the Replicated KOTS installer. If you do not intend to offer existing cluster installations with KOTS (for example, if you intend to support only Embedded Cluster and Helm installations for your users), then can choose to test with Embedded Cluster only. -* Replicated also offers labs in Instruqt that provide a hands-on introduction to working with Replicated features, without needing your own sample application or development environment. To complete one or more labs before you begin the onboarding workflow, see: - * [Distributing Your Application with Replicated](https://play.instruqt.com/embed/replicated/tracks/distributing-with-replicated?token=em_VHOEfNnBgU3auAnN): Learn how to quickly get value from the Replicated Platform for your application. - * [Avoiding Installation Pitfalls](https://play.instruqt.com/embed/replicated/tracks/avoiding-installation-pitfalls?token=em_gJjtIzzTTtdd5RFG): Learn how to use preflight checks to avoid common installation issues and assure your customer is installing into a supported environment. - * [Closing the Support Information Gap](https://play.instruqt.com/embed/replicated/tracks/closing-information-gap?token=em_MO2XXCz3bAgwtEca): Learn how to use support bundles to close the information gap between your customers and your support team. +* Ask for help from the Replicated community. For more information, see [Getting Help from the Community](#community) below. -## Get Help from the Community +### Getting Help from the Community {#community} The [Replicated community site](https://community.replicated.com/) is a forum where Replicated team members and users can post questions and answers related to working with the Replicated Platform. It is designed to help Replicated users troubleshoot and learn more about common tasks involved with distributing, installing, observing, and supporting their application. Before posting in the community site, use the search to find existing knowledge base articles related to your question. If you are not able to find an existing article that addresses your question, create a new topic or add a reply to an existing topic so that a member of the Replicated community or team can respond. -To search and participate in the Replicated community, see https://community.replicated.com/. +To search and participate in the Replicated community, see https://community.replicated.com/. -## Prerequisites +### Prerequisites -* Create an account in the Vendor Portal. You can either create a new team or join an existing team. For more information, see [Creating a Vendor Account](/vendor/vendor-portal-creating-account). +* Create an account in the Vendor Portal. You can either create a new team or join an existing team. For more information, see [Creating a Vendor Account](vendor-portal-creating-account). * Install the Replicated CLI. See [Installing the Replicated CLI](/reference/replicated-cli-installing). -* Create an application in the Vendor Portal. This will be the official Vendor Portal application used by your team to create and promote both internal and customer-facing releases. See [Create an Application](/vendor/vendor-portal-manage-app#create-an-application). - -* Ensure that you have development environments available to test installation and upgrades with Replicated KOTS, Replicated Embedded Cluster, and Helm. For more information about the installation requirements for the Replicated installers, see [Installation Requirements](/enterprise/installing-general-requirements). - -* Complete a getting started tutorial to get familiar with the process of creating, installing, and iterating on releases in the Replicated Platform using a sample Helm chart. You will use this same basic workflow throughout the onboarding process to integrate and test new features with your own application. - * [Tutorial: Deploy a Helm Chart on a VM with Embedded Cluster](/vendor/tutorial-embedded-cluster-setup) - * [Tutorial: Deploy a Helm Chart with KOTS and the Helm CLI](/vendor/tutorial-kots-helm-setup) - -## Onboarding Checklist - -This checklist includes key Replicated Platform features to integrate with your application to onboard to the Replicated Platform. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FeatureDescriptionHow to
    Replicated SDK -

    Add the Replicated SDK as a dependency of your Helm chart. The Replicated SDK is a Helm chart that can be installed as a small service alongside your application. The SDK provides access to key Replicated functionality, including an in-cluster API and automatic access to insights and operational telemetry for instances running in customer environments.

    -     		Packaging a Helm Chart for a Release
    Replicated proxy registry -

    Connect your image registry to allow customer licenses to grant proxy access to your application's private images using the Replicated proxy registry.

    -

    To support the use of the proxy registry in Helm installations, there is an additional step to add a Kubernetes Secret to your Helm chart.

    -     		- -
    Replicated KOTS and Replicated Embedded Cluster -

    Add custom resources to a release to support installations with the Replicated KOTS and Replicated Embedded Cluster installers.

    -     		Onboarding with KOTS
    Preflight checks -

    Define preflight checks to test for system compliance during the installation process and reduce the number of support escalations.

    -     		- -
    Support bundles -

    Add a support bundle spec to enable customers to quickly collect and analyze troubleshooting data from their clusters to help you diagnose problems with application deployments.

    -     		- -
    License entitlement checks -

    Add checks for customer license entitlements before installation and during runtime.

    -     		- -
    Alias Replicated endpoints -

    Configure custom domains to alias the Replicated endpoints that are used for customer-facing URLs, such as registry.replicated.com and proxy.replicated.com.

    -     		Using Custom Domains
    Custom license entitlements -

    Configure custom license fields that are specific to a customer, such as limiting the number of active users permitted.

    -     		- Managing Custom License Fields -
    Custom metrics -

    Use the SDK API to send custom metrics that measure instances of your application running in online or air gap environments.

    -

    To get started, use the SDK in integration mode to develop locally without needing to make real changes in the Vendor Portal or in your environment.

    -     		- Configuring Custom Metrics -
    Integrate with CI/CD -

    Update your existing development and release CI/CD pipelines to automatically complete tasks such as creating and promoting releases, provisioning clusters to test installation with the Replicated Compatibility Matrix, installing releases in test environments, and more.

    -     		- -
    +* Complete a basic quick start workflow to create an application with a sample Helm chart and then promote and install releases in a development environment. This helps you get familiar with the process of creating, installing, and updating releases in the Replicated Platform. See [Replicated Quick Start](/vendor/quick-start). + +* Ensure that you have access to a VM that meets the requirements for the Replicated Embedded Cluster installer. You will use this VM to test installation with Embedded Cluster. + + Embedded Cluster has the following requirements: + + + +* (Optional) Ensure that you have kubectl access to a Kubernetes cluster. You will use this cluster to test installation with KOTS. If you do not intend to offer existing cluster installations with KOTS (for example, if you intend to support only Embedded Cluster and Helm installations for your users), then you do not need access to a cluster for the main onboarding tasks. + + You can use any cloud provider or tool that you prefer to create a cluster, such as [Replicated Compatibility Matrix](/vendor/testing-how-to), Google Kubernetes Engine (GKE), or minikube. + +## Onboard + +Complete the tasks in this section to onboard your application. When you are done, you can continue to [Next Steps](#next-steps) to integrate other Replicated features with your application. + +### Task 1: Create An Application + +To get started with onboarding, first create a new application. This will be the official Vendor Portal application used by your team to create and promote both internal and customer-facing releases. + +To create an application: + +1. Create a new application using the Replicated CLI or the Vendor Portal. Use an official name for your application. See [Create an Application](/vendor/vendor-portal-manage-app#create-an-application). + +
    + Can I change the application name in the future? + + You can change the application name, but you cannot change the application _slug_. + + The Vendor Portal automatically generates and assigns a unique slug for each application based on the application's name. For example, the slug for "Example App" would be `example-app`. + + Application slugs are unique across all of Replicated. This means that, if necessary, the Vendor Portal will append a random word to the end of slug to ensure uniqueness. For example, `example-app-flowers`. +
    + +1. Set the `REPLICATED_APP` environment variable to the unique slug of the application that you created. This will allow you to interact with the application from the Replicated CLI throughout onboarding. See [Set Environment Variables](/reference/replicated-cli-installing#replicated_app) in _Installing the Replicated CLI_. + + For example: + + ```bash + export REPLICATED_APP=my-app + ``` + +### Task 2: Connect Your Image Registry + +Add credentials for your image registry to the Vendor Portal. This will allow you to use the Replicated proxy registry in a later step so that you can grant proxy access to application images without exposing registry credentials to your customers. + +For more information, see [Connecting to an External Registry](/vendor/packaging-private-images). + +### Task 3: Add the Replicated SDK and Package your Chart + +Next, add the Replicated SDK as a dependency of your Helm chart and package the chart as a `.tgz` archive. + +The Replicated SDK is a Helm chart that can be installed as a small service alongside your application. The SDK provides access to key Replicated functionality, including an in-cluster API and automatic access to insights and operational telemetry for instances running in customer environments. For more information, see [About the Replicated SDK](/vendor/replicated-sdk-overview). + +To package your Helm chart with the Replicated SDK: + +1. Go to the local directory where your Helm chart is. + +1. In your application Helm chart `Chart.yaml` file, add the YAML below to declare the SDK as a dependency. + + If your application is installed as multiple charts, declare the SDK as a dependency of the chart that customers install first. Do not declare the SDK in more than one chart. For more information, see [Packaging a Helm Chart for a Release](helm-install-release). + + + +1. Update dependencies and package the chart as a `.tgz` file: + + + + + +1. If your application is deployed as multiple Helm charts, package each chart as a separate `.tgz` archive using the `helm package -u PATH_TO_CHART` command. Do not declare the SDK in more than one chart. + +### Task 4: Create the Initial Release with KOTS HelmChart and Embedded Cluster Config {#first-release} + +After packaging your Helm chart, you can create a release. The initial release for your application will include the minimum files required to install a Helm chart with the Embedded Cluster installer: +* The Helm chart `.tgz` archive +* [KOTS HelmChart custom resource](/reference/custom-resource-helmchart-v2) +* [Embedded Cluster Config](/reference/embedded-config) + +If you have multiple charts, you will add each chart archive to the release, plus a corresponding KOTS HelmChart custom resource for each archive. + +:::note +Configuring the KOTS HelmChart custom resource includes several tasks, and involves the use of KOTS template functions. Depending on how many Helm charts your application uses, Replicated recommends that you allow about two to three hours for configuring the HelmChart custom resource and creating and testing your initial release. +::: + +To create the first release for your application: + +1. In the local directory for your Helm chart, create a subdirectory named `manifests` where you will add the files for the release. + +1. In the `manifests` directory: + + 1. Move the `.tgz` chart archive that you packaged. If your application is deployed as multiple Helm charts, move each `.tgz` archive to `manifests`. + + 1. Create an `embedded-cluster.yaml` file with the following default Embedded Cluster Config: + + + +
    + What is the Embedded Cluster Config? + + The Embedded Cluster Config is required to install with Embedded Cluster. +
    + + For more information, see [Using Embedded Cluster](/vendor/embedded-overview). + + 1. Create a new YAML file. In this file, configure the KOTS HelmChart custom resource by completing the workflow in [Configuring the HelmChart Custom Resource](helm-native-v2-using). + +
    + What is the KOTS HelmChart custom resource? + + The KOTS HelmChart custom resource is required to install Helm charts with KOTS and Embedded Cluster. As part of configuring the KOTS HelmChart custom resource, you will rewrite image names and add image pull secrets to allow your application images to be accessed through the Replicated proxy registry. +
    + + 1. If your application is deployed as multiple Helm charts, repeat the step above to add a separate HelmChart custom resource for each Helm chart archive in the release. + + 1. If there are values in any of your Helm charts that need to be set for the installation to succeed, you can set those values using the `values` key in the corresponding HelmChart custom resource. See [Setting Helm Values with KOTS](/vendor/helm-optional-value-keys). + + This is a temporary measure to ensure the values get passed to the Helm chart during installation until you configure the Admin Console Config screen in a later onboarding task. If your default Helm values are sufficient for installation, you can skip this step. + + 1. If your application requires that certain components are deployed before the application and as part of the Embedded Cluster itself, then update the Embedded Cluster Config to add [extensions](/reference/embedded-config#extensions). Extensions allow you to provide Helm charts that are deployed before your application. For example, one situation where this is useful is if you want to ship an ingress controller because Embedded Cluster does not include one. + + For more information, see [extensions](/reference/embedded-config#extensions) in _Embedded Cluster Config_. + +1. From the `manifests` directory, create a release and promote it to the Unstable channel. For more information, see [Managing Releases with the Vendor Portal](releases-creating-releases) or [Managing Releases with the CLI](releases-creating-cli). + + ```bash + replicated release create --yaml-dir . --promote Unstable + ``` + +1. Install the release in your development environment to test: + + 1. Install with Embedded Cluster on a VM. See [Online Installation with Embedded Cluster](/enterprise/installing-embedded). + + 1. (Optional) Install in an existing cluster with KOTS. See [Online Installation in Existing Clusters](/enterprise/installing-existing-cluster). + +After successfully installing the initial release on a VM with Embedded Cluster (and optionally in an existing cluster with KOTS), go to the next task. You will continue to iterate throughout the rest of the onboarding process by creating and promoting new releases, then upgrading to the new version in your development environment. + +### Task 5: Customize the KOTS Admin Console {#admin-console} + +Configure the KOTS Application custom resource to add an application name, icon, and status informers. The name and icon will be displayed in the Admin Console and the Replicated Download Portal. The status informers will be used to display the application status on the Admin Console dashboard. + +To configure the KOTS Application custom resource: + +1. In your `manifests` directory, create a new `kots-app.yaml` file. + +1. In the `kots-app.yaml` file, add the [KOTS Application](/reference/custom-resource-application) custom resource YAML and set the `title`, `icon`, and `statusInformers` fields. + + **Example:** + + ```yaml + apiVersion: kots.io/v1beta1 + kind: Application + metadata: + name: gitea + spec: + title: Gitea + # Base64 encoded image string + icon: fyJINrigNkt5VsRiub9nXICdsYyVd2NcVvA3ScE5t2rb5JuEeyZnAhmLt9NK63vX1O + statusInformers: + - deployment/gitea + ``` + For more information, see: + * [Customizing the Application Icon](/vendor/admin-console-customize-app-icon) + * [Enabling and Understanding Application Status](/vendor/insights-app-status) + * [Application](/reference/custom-resource-application) +
    +
    + Can I preview the icon before installing the release? + + Yes. The Vendor Portal includes a **Application icon preview** in the **Help** pane on the **Edit release** page. + + ![Icon preview](/images/icon-preview.png) + + [View a larger version of this image](/images/icon-preview.png) + +
    + +1. + +1. + +### Task 6: Set Up the Admin Console Config Screen and Map to Helm Values + +The KOTS Admin Console Config screen is used to collect required and optional application configuration values from your users. User-supplied values provided on the Config screen can be mapped to your Helm values. + +Before you begin this task, you can complete the [Set Helm Values with KOTS](/vendor/tutorial-config-setup) tutorial to learn how to map user-supplied values from the Admin Console Config screen to a Helm chart. + +:::note +Setting up the Admin Console config screen can include the use of various types of input fields, conditional statements, and KOTS template functions. Depending on your application's configuration options, Replicated recommends that you allow about two to three hours for configuring the Config custom resource and testing the Admin Console config screen. +::: + +To set up the Admin Console Config screen for your application: + +1. In your `manifests` directory, create a new file named `kots-config.yaml`. + +1. In `kots-config.yaml`, add the KOTS Config custom resource. Configure the KOTS Config custom resource based on the values that you need to collect from users. + + **Example:** + + ```yaml + apiVersion: kots.io/v1beta1 + kind: Config + metadata: + name: my-application + spec: + groups: + - name: example_group + title: Example Group + items: + - name: example_item + title: Example Item + type: text + default: "Hello World" + ``` + + For more information, see: + * [Creating and Editing Configuration Fields](/vendor/admin-console-customize-config-screen) + * [Using Conditional Statements in Configuration Fields](/vendor/config-screen-conditional) + * [Config](/reference/custom-resource-config) + +
    + +
    + Can I preview the Admin Console config screen before installing the release? + + Yes. The Vendor Portal includes a **Config preview** in the **Help** pane on the **Edit release** page. + + For example: + + ![Config preview](/images/config-preview.png) + + [View a larger version of this image](/images/config-preview.png) +
    + +1. + +1. + +1. In `manifests`, open the KOTS HelmChart custom resource that you configured in a previous step. Configure the `values` key of the HelmChart custom resource to map the fields in the KOTS Config custom resource to your Helm values. + + For more information, see: + * [Mapping User-Supplied Values](/vendor/config-screen-map-inputs) + * [Tutorial: Set Helm Chart Values with KOTS](/vendor/tutorial-config-setup) + * [Setting Helm Values with KOTS](/vendor/helm-optional-value-keys) + * [`values`](/reference/custom-resource-helmchart-v2#values) in _HelmChart v2_ + +1. + +1. + +1. Continue to create and test new releases with new config fields until you are ready to move on to the next task. + +### Task 7: Define Preflight Checks + +In the next two tasks, you will add specs for _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/) 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. + +:::note +Before you begin this task, you can complete the [Add Preflight Checks to a Helm Chart](/vendor/tutorial-preflight-helm-setup) tutorial to learn how to add a preflight spec to a Helm chart in a Kubernetes secret and run the preflight checks before installation. +::: + +To define preflight checks for your application: + +1. In your Helm chart `templates` directory, add a Kubernetes Secret that includes a preflight spec. For more information, see [Defining Preflight Checks](/vendor/preflight-defining). For examples, see [Example Preflight Specs](/vendor/preflight-examples). + :::note + If your application is deployed as multiple Helm charts, add the Secret to the `templates` directory for the chart that is installed first. + ::: + +1. Update dependencies and package the chart as a `.tgz` file: + + + +1. Move the `.tgz` file to the `manifests` directory. + +1. + +1. + + Preflight checks run automatically during installation. + +1. Continue to create and test new releases with additional preflight checks until you are ready to move on to the next task. + +### Task 8: Add a Support Bundle Spec + +To add the default support bundle spec to your application: + +1. In your Helm chart `templates` directory, add the following YAML to a Kubernetes Secret to enable the default support bundle spec for your application: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + labels: + troubleshoot.sh/kind: support-bundle + name: example + stringData: + support-bundle-spec: | + apiVersion: troubleshoot.sh/v1beta2 + kind: SupportBundle + metadata: + name: support-bundle + spec: + collectors: [] + analyzers: [] + ``` + :::note + If your application is installed as multiple Helm charts, you can optionally create separate support bundle specs in each chart. The specs are automatically merged when a support bundle is generated. Alternatively, continue with a single support bundle spec and then optionally revisit how you organize your support bundle specs after you finish onboarding. + ::: + +1. (Recommended) At a minimum, Replicated recommends that all support bundle specs include the `logs` collector. This collects logs from running Pods in the cluster. + + **Example:** + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: example + labels: + troubleshoot.sh/kind: support-bundle + stringData: + support-bundle-spec: |- + apiVersion: troubleshoot.sh/v1beta2 + kind: SupportBundle + metadata: + name: example + spec: + collectors: + - logs: + selector: + - app.kubernetes.io/name=myapp + namespace: {{ .Release.Namespace }} + limits: + maxAge: 720h + maxLines: 10000 + ``` + + For more information, see: + * [Adding and Customizing Support Bundles](/vendor/support-bundle-customizing) + * [Example Support Bundle Specs](/vendor/support-bundle-examples) + * [Pod Logs](https://troubleshoot.sh/docs/collect/logs/) in the Troubleshoot documentation. + +1. (Recommended) Ensure that any preflight checks that you added are also include in your support bundle spec. This ensures that support bundles collect at least the same information collected when running preflight checks. + +1. Update dependencies and package the chart as a `.tgz` file: + + + +1. Move the `.tgz` file to the `manifests` directory. + +1. + +1. + + For information about how to generate support bundles, see [Generating Support Bundles](/vendor/support-bundle-generating). + +1. (Optional) Customize the support bundle spec by adding additional collectors and analyzers. + +### Task 9: Alias Replicated Endpoints with Your Own Domains + +Your customers are exposed to several Replicated domains by default. Replicated recommends you use custom domains to unify the customer's experience with your brand and simplify security reviews. + +For more information, see [Using Custom Domains](/vendor/custom-domains-using). + +## Next Steps + +After completing the main onboarding tasks, Replicated recommends that you also complete the following additional tasks to integrate other Replicated features with your application. You can complete these next recommended tasks in any order and at your own pace. + +### Add Support for Helm Installations + +Existing KOTS releases that include one or more Helm charts can be installed with the Helm CLI; it is not necessary to create and manage separate releases or channels for each installation method. + +To enable Helm installations for Helm charts distributed with Replicated, the only extra step is to add a Secret to your chart to authenticate with the Replicated proxy registry. + +This is the same secret that is passed to KOTS in the HelmChart custom resource using `'{{repl ImagePullSecretName }}'`, which you did as part of [Task 4: Create and Install the Initial Release](#first-release). So, whereas this Secret is created automatically for KOTS and Embedded Cluster installations, you need to create it and add it to your Helm chart for Helm installations. + +:::note +Before you test Helm installations for your application, you can complete the [Deploy a Helm Chart with KOTS and the Helm CLI](tutorial-kots-helm-setup) tutorial to learn how to install a single release with both KOTS and Helm. +::: + +To support and test Helm installations: + +1. Follow the steps in [Using the Proxy Registry with Helm Installations](/vendor/helm-image-registry) to authenticate with the Replicated proxy registry by creating a Secret with `type: kubernetes.io/dockerconfigjson` in your Helm chart. + +1. Update dependencies and package the chart as a `.tgz` file: + + + +1. Add the `.tgz` file to a release. For more information, see [Managing Releases with the Vendor Portal](releases-creating-releases) or [Managing Releases with the CLI](releases-creating-cli). + +1. Install the release in a cluster with the Helm CLI to test your changes. For more information, see [Installing with Helm](/vendor/install-with-helm). + +### Add Support for Air Gap Installations + +Replicated Embedded Cluster and KOTS support installations in _air gap_ environments with no outbound internet access. Users can install with Embedded Cluster and KOTS in air gap environments by providing air gap bundles that contain the required images for the installers and for your application. + +:::note +Replicated also offers Alpha support for air gap installations with Helm. If you are interested in trying Helm air gap installations and providing feedback, please reach out to your account rep to enable this feature. +::: + +To add support for air gap installations: + +1. If there are any images for your application that are not listed in your Helm chart, list these images in the `additionalImages` attribute of the KOTS Application custom resource. This ensures that the images are included in the air gap bundle for the release. One common use case for this is applications that use Kubernetes Operators. See [Define Additional Images](/vendor/operator-defining-additional-images). + +1. In the KOTS HelmChart custom resource `builder` key, pass any values that are required in order for `helm template` to yield all the images needed to successfully install your application. See [Packaging Air Gap Bundles for Helm Charts](/vendor/helm-packaging-airgap-bundles). + + :::note + If the default values in your Helm chart already enable all the images needed to successfully deploy, then you do not need to configure the `builder` key. + ::: + +
    + How do I know if I need to configure the `builder` key? + + When building an air gap bundle, the Vendor Portal templates the Helm charts in a release with `helm template` in order to detect the images that need to be included in the bundle. Images yielded by `helm template` are included in the bundle for the release. + + For many applications, running `helm template` with the default values would not yield all the images required to install. In these cases, vendors can pass the additional values in the `builder` key to ensure that the air gap bundle includes all the necessary images. +
    + +1. If you have not done so already as part of [Task 4: Create and Install the Initial Release](#first-release), ensure that the `values` key in the KOTS HelmChart custom resource correctly rewrites image names for air gap installations. This is done using the KOTS HasLocalRegistry, LocalRegistryHost, and LocalRegistryNamespace template functions to render the location of the given image in the user's own local registry. + + For more information, see [Rewrite Image Names](/vendor/helm-native-v2-using#rewrite-image-names) in _Configuring the HelmChart Custom Resource v2_. + +1. Create and promote a new release with your changes. For more information, see [Managing Releases with the Vendor Portal](releases-creating-releases) or [Managing Releases with the CLI](releases-creating-cli). + +1. In the [Vendor Portal](https://vendor.replicated.com), go the channel where the release was promoted to build the air gap bundle. Do one of the following: + * 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. + +1. Create a customer with the **Airgap Download Enabled** entitlement enabled so that you can test air gap installations. See [Creating and Managing Customers](/vendor/releases-creating-customer). + +1. Download the Embedded Cluster air gap installation assets, then install with Embedded Cluster on an air gap VM to test. See [Installing in Air Gap Environments with Embedded Cluster](/enterprise/installing-embedded-air-gap). + +1. (Optional) Download the `.airgap` bundle for the release and the air gap bundle for the KOTS Admin Console. You can also download both bundles from the Download Portal for the target customer. Then, install in an air gap existing cluster to test. See [Air Gap Installation in Existing Clusters](/enterprise/installing-existing-cluster-airgapped). + +1. (Optional) Follow the steps in [Installing and Updating with Helm in Air Gap Environments (Alpha)](/vendor/helm-install-airgap) to test air gap installation with Helm. + + :::note + Air gap Helm installations are an Alpha feature. If you are interested in trying Helm air gap installations and providing feedback, please reach out to your account rep to enable this feature. + ::: + +### Add Roles for Multi-Node Clusters in Embedded Cluster Installations + +The Embedded Cluster Config supports roles for multi-node clusters. One or more roles can be selected and assigned to a node when it is joined to the cluster. Node roles can be used to determine which nodes run the Kubernetes control plane, and to assign application workloads to particular nodes. + +For more information, see [roles](/reference/embedded-config#roles) in _Embedded Cluster Config_. + +### Add and Map License Entitlements + +You can add custom license entitlements for your application in the Vendor Portal. Custom license fields are useful when there is entitlement information that applies to a subset of customers. For example, you can use entitlements to: +* Limit the number of active users permitted +* Limit the number of nodes a customer is permitted on their cluster +* Identify a customer on a "Premium" plan that has access to additional features or functionality not available with your base plan + +For more information about how to create and assign custom entitlements in the Vendor Portal, see [Managing Custom License Fields](/vendor/licenses-adding-custom-fields) and [Creating and Managing Customers](/vendor/releases-creating-customer). + +#### Map Entitlements to Helm Values + +You can map license entitlements to your Helm values using KOTS template functions. This can be useful when you need to set certain values based on the user's license information. For more information, see [Using KOTS Template Functions](/vendor/helm-optional-value-keys#using-kots-template-functions) in _Setting Helm Values with KOTS_. + +#### Query Entitlements Before Installation and at Runtime + +You can add logic to your application to query license entitlements both before deployment and at runtime. For example, you might want to add preflight checks that verify a user's entitlements before installing. Or, you can expose additional product functionality dynamically at runtime based on a customer's entitlements. + +For more information, see: +* [Querying Entitlements with the Replicated SDK API](/vendor/licenses-reference-sdk) +* [Checking Entitlements in Preflights with KOTS Template Functions](/vendor/licenses-referencing-fields) + +### Add Application Links to the Admin Console Dashboard + +You can add the Kubernetes SIG Application custom resource to your release to add a link to your application from the Admin Console dashboard. This makes it easier for users to access your application after installation. + +You can also configure the Kubernetes SIG Application resource add links to other resources like documentation or dashboards. + +For more information, see [Adding Application Links to the Dashboard](/vendor/admin-console-adding-buttons-links). + +### Update the Preflight and Support Bundles Specs + +After adding basic specs for preflights and support bundles, you can continue to add more collectors and analyzers as needed. + +Consider the following recommendations and best practices: + +* Revisit your preflight and support bundle specs when new support issues arise that are not covered by your existing specs. + +* Your support bundles should include all of the same collectors and analyzers that are in your preflight checks. This ensures that support bundles include all the necessary troubleshooting information, including any failures in preflight checks. + +* Your support bundles will most likely need to include other collectors and analyzers that are not in your preflight checks. This is because some of the information used for troubleshooting (such as logs) is not necessary when running preflight checks before installation. + +* If your application is installed as multiple Helm charts, you can optionally add separate support bundle specs in each chart. This can make it easier to keep the specs up-to-date and to avoid merge conflicts that can be caused when multiple team members contribute to a single, large support bundle spec. When an application has multiple support bundle specs, the specs are automatically merged when generating a support bundle so that only a single support bundle is provided to the user. + +The documentation for the open-source Troubleshoot project includes the full list of available collectors and analyzers that you can use. See [All Collectors](https://troubleshoot.sh/docs/collect/all/) and the [Analyze](https://troubleshoot.sh/docs/analyze/) section in the Troubleshoot documentation. + +You can also view common examples of collectors and analyzers used in preflight checks and support bundles in [Preflight Spec Examples](preflight-examples) and [Support Bundle Spec Examples](support-bundle-examples). + +### Configure Backup and Restore + +Enable backup and restore with Velero for your application so that users can back up and restore their KOTS Admin Console and application data. + +There are different steps to configure backup and restore for Embedded Cluster and for existing cluster installations with KOTS: +* To configure the disaster recovery feature for Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery) +* To configure the snapshots feature for existing cluster KOTS installations, see [Configuring Backup and Restore](snapshots-configuring-backups). + +### Add Custom Metrics + +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 in customer environments. Custom metrics can be collected for application instances running in online or air gap environments using the Replicated SDK. + +For more information, see [Configuring Custom Metrics](/vendor/custom-metrics). + +### Integrate with CI/CD + +Replicated recommends that teams integrate the Replicated Platform into their existing develeopment and production CI/CD workflows. This can be useful for automating the processes of creating new releases, promoting releases, and testing releases with the Replicated Compatibility Matrix. + +For more information, see: +* [About Integrating with CI/CD](/vendor/ci-overview) +* [About Compatibility Matrix](/vendor/testing-about) +* [Recommended CI/CD Workflows](/vendor/ci-workflows) + +### Customize Release Channels + +By default, the Vendor Portal includes Unstable, Beta, and Stable channels. You can customize the channels in the Vendor Portal based on your application needs. + +Consider the following recommendations: +* Use the Stable channel for your primary release cadence. Releases should be promoted to the Stable channel only as frequently as your average customer can consume new releases. Typically, this is no more than monthly. However, this cadence varies depending on the customer base. +* If you have a SaaS product, you might want to create an "Edge" channel where you promote the latest SaaS releases. +* You can consider a “Long Term Support” channel where you promote new releases less frequently and support those releases for longer. +* It can be useful to create channels for each feature branch so that internal teams reviewing a PR can easily get the installation artifacts as well as review the code. You can automate channel creation as part of a pipeline or Makefile. + +For more information, see: +* [About Channels and Releases](/vendor/releases-about) +* [Creating and Editing Channels](/vendor/releases-creating-channels) + +### Write Your Documentation + +Before distributing your application to customers, ensure that your documentation is up-to-date. In particular, be sure to update the installation documentation to include the procedures and requirements for installing with Embedded Cluster, Helm, and any other installation methods that you support. + +For guidance on how to get started with documentation for applications distributed with Replicated, including key considerations, examples, and templates, see [Writing Great Documentation for On-Prem Software Distributed with Replicated](https://www.replicated.com/blog/writing-great-documentation-for-on-prem-software-distributed-with-replicated) in the Replicated blog. \ No newline at end of file diff --git a/docs/vendor/tutorial-cli-update-app.mdx b/docs/vendor/tutorial-cli-update-app.mdx index 9751c3cf05..55ed306dc1 100644 --- a/docs/vendor/tutorial-cli-update-app.mdx +++ b/docs/vendor/tutorial-cli-update-app.mdx @@ -48,7 +48,7 @@ To update the application: If you do not see the new text, refresh your browser. ::: -## Next Step +## Summary Congratulations! As part of this tutorial, you: * Created and promoted a release for a Kubernetes application using the Replicated CLI @@ -56,5 +56,3 @@ Congratulations! As part of this tutorial, you: * Edited the manifest files for the application, adding a new configuration field and using template functions to reference the field * Promoted a new release with your changes * Used the Admin Console to update the application to the latest version - -As a next step, you can continue to iterate on your application, using `replicated release create --auto` to promote each new release. For a list of KOTS features to integrate with your application, see [Onboarding with KOTS](/vendor/distributing-workflow). diff --git a/docs/vendor/tutorial-embedded-cluster-install.mdx b/docs/vendor/tutorial-embedded-cluster-install.mdx index 04c077238c..013ad55008 100644 --- a/docs/vendor/tutorial-embedded-cluster-install.mdx +++ b/docs/vendor/tutorial-embedded-cluster-install.mdx @@ -99,7 +99,7 @@ To install the release with Embedded Cluster: ``` Where `APP_SLUG` is the unique slug for the application that you created. You can find the appication slug by running `replicated app ls` on the command line on your local machine. -## Next Step +## Summary Congratulations! As part of this tutorial, you created a release in the Replicated Vendor Portal and installed the release with Replicated Embedded Cluster in a VM. To learn more about Embedded Cluster, see [Using Embedded Cluster](embedded-overview). diff --git a/docs/vendor/vendor-portal-manage-app.md b/docs/vendor/vendor-portal-manage-app.md index bf8a98700c..b5e87243d7 100644 --- a/docs/vendor/vendor-portal-manage-app.md +++ b/docs/vendor/vendor-portal-manage-app.md @@ -29,7 +29,7 @@ To create a new application: :::important If you intend to use the application for testing purposes, Replicated recommends that you use a temporary name such as `My Application Demo` or `My Application Test`. - You are not able to restore or modify previously-used application names or application slugs. Only use an official name for your application when you have completed testing and are ready to distribute the application to your customers. + You are not able to restore or modify previously-used application names or application slugs. ::: 1. Click **Create application**. diff --git a/docusaurus.config.js b/docusaurus.config.js index cdb7015fba..e6e6239a49 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -208,7 +208,7 @@ const config = { to: 'release-notes/rn-whats-new', }, { - label: 'Replicated Quick Start', + label: 'Replicated Onboarding', to: 'vendor/replicated-onboarding', }, ], diff --git a/netlify.toml b/netlify.toml index ccaafdccde..fe216c2b65 100644 --- a/netlify.toml +++ b/netlify.toml @@ -170,7 +170,11 @@ [[redirects]] from="https://docs.replicated.com/vendor/support-bundle-helm-customizing" - to="https://docs.replicated.com/vendor/support-bundle-customizing" + to="https://docs.replicated.com/vendor/support-bundle-customizing" + +[[redirects]] + from="https://docs.replicated.com/vendor/distributing-workflow" + to="https://docs.replicated.com/vendor/replicated-onboarding" ################################################### # Redirects To the Enterprise Section diff --git a/sidebars.js b/sidebars.js index 0ff0d94682..691db4ef84 100644 --- a/sidebars.js +++ b/sidebars.js @@ -37,6 +37,7 @@ const sidebars = { {type: 'html', value: '
    getting started
    ', defaultStyle: true}, 'intro-replicated', 'vendor/kots-faq', + 'vendor/quick-start', 'vendor/replicated-onboarding', // { // type: 'category', @@ -46,19 +47,6 @@ const sidebars = { // 'vendor/namespaces', // ], // }, - { - type: 'category', - label: 'Labs', - items: - [ - {type: 'link', href: 'https://play.instruqt.com/embed/replicated/tracks/distributing-with-replicated?token=em_VHOEfNnBgU3auAnN', label: 'Distributing Your Application with Replicated'}, - {type: 'link', href: 'https://play.instruqt.com/embed/replicated/tracks/delivering-as-an-appliance?token=em_lUZdcv0LrF6alIa3', label: 'Delivering Your Application as a Kubernetes Appliance'}, - {type: 'link', href: 'https://play.instruqt.com/embed/replicated/tracks/avoiding-installation-pitfalls?token=em_gJjtIzzTTtdd5RFG', label: 'Avoiding Installation Pitfalls'}, - {type: 'link', href: 'https://play.instruqt.com/embed/replicated/tracks/closing-information-gap?token=em_MO2XXCz3bAgwtEca', label: 'Closing the Support Information Gap'}, - {type: 'link', href: 'https://play.instruqt.com/embed/replicated/tracks/protecting-your-assets?token=em_7QjY34G_UHKoREBd', label: 'Protecting Your Assets'}, - ], - - }, { type: 'category', label: 'Tutorials', @@ -107,7 +95,18 @@ const sidebars = { }, ], }, - 'vendor/distributing-overview', + { + type: 'category', + label: 'Labs', + items: + [ + {type: 'link', href: 'https://play.instruqt.com/embed/replicated/tracks/distributing-with-replicated?token=em_VHOEfNnBgU3auAnN', label: 'Distributing Your Application with Replicated'}, + {type: 'link', href: 'https://play.instruqt.com/embed/replicated/tracks/delivering-as-an-appliance?token=em_lUZdcv0LrF6alIa3', label: 'Delivering Your Application as a Kubernetes Appliance'}, + {type: 'link', href: 'https://play.instruqt.com/embed/replicated/tracks/avoiding-installation-pitfalls?token=em_gJjtIzzTTtdd5RFG', label: 'Avoiding Installation Pitfalls'}, + {type: 'link', href: 'https://play.instruqt.com/embed/replicated/tracks/closing-information-gap?token=em_MO2XXCz3bAgwtEca', label: 'Closing the Support Information Gap'}, + {type: 'link', href: 'https://play.instruqt.com/embed/replicated/tracks/protecting-your-assets?token=em_7QjY34G_UHKoREBd', label: 'Protecting Your Assets'}, + ], + }, // PRODUCT DOCS {type: 'html', value: '
    product docs
    ', defaultStyle: true}, { @@ -187,7 +186,6 @@ const sidebars = { label: 'Distributing and Installing with KOTS', items: [ 'intro-kots', - 'vendor/distributing-workflow', { type: 'category', label: 'Packaging KOTS Releases', diff --git a/static/images/config-preview.png b/static/images/config-preview.png new file mode 100644 index 0000000000..e605c31710 Binary files /dev/null and b/static/images/config-preview.png differ diff --git a/static/images/gitea-ec-ready.png b/static/images/gitea-ec-ready.png index ed304c5314..40291ed191 100644 Binary files a/static/images/gitea-ec-ready.png and b/static/images/gitea-ec-ready.png differ diff --git a/static/images/icon-preview.png b/static/images/icon-preview.png new file mode 100644 index 0000000000..37a4fbf24c Binary files /dev/null and b/static/images/icon-preview.png differ diff --git a/static/images/quick-start-ec-upgrade-wizard-preflight.png b/static/images/quick-start-ec-upgrade-wizard-preflight.png new file mode 100644 index 0000000000..9dac140ad3 Binary files /dev/null and b/static/images/quick-start-ec-upgrade-wizard-preflight.png differ