diff --git a/docs/intro.md b/docs/intro.md index 4faad5eef1..316bc2acbb 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -46,13 +46,13 @@ pagination_next: null Introduction to Replicated
  • - About Distributing Applications with Replicated + Quick Start
  • - Replicated Quick Start + Replicated Onboarding
  • - Tutorials + Getting Started Tutorials
  • Getting Started Lab in Instruqt @@ -60,49 +60,43 @@ pagination_next: null
    -
    +
    -
    +
    -
    diff --git a/docs/partials/embedded-cluster/_default-config.mdx b/docs/partials/embedded-cluster/_default-config.mdx new file mode 100644 index 0000000000..4ef9974f42 --- /dev/null +++ b/docs/partials/embedded-cluster/_default-config.mdx @@ -0,0 +1,7 @@ +```yaml +apiVersion: embeddedcluster.replicated.com/v1beta1 +kind: Config +spec: + version: 1.10.0+k8s-1.29 +``` +See the Embedded Cluster [GitHub repo](https://github.com/replicatedhq/embedded-cluster/releases) to find the latest version. \ No newline at end of file diff --git a/docs/partials/getting-started/_add-license-entitlements.mdx b/docs/partials/getting-started/_add-license-entitlements.mdx new file mode 100644 index 0000000000..4a6c871633 --- /dev/null +++ b/docs/partials/getting-started/_add-license-entitlements.mdx @@ -0,0 +1,3 @@ +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 create a custom license field to limit the number of active users permitted. Or, you can create a field that limits the number of nodes a customer is permitted on their cluster. + +After you add custom entitlements, you can also add logic to your application to query license entitlements both before deployment and at runtime. \ No newline at end of file diff --git a/docs/partials/getting-started/_best-practices.mdx b/docs/partials/getting-started/_best-practices.mdx new file mode 100644 index 0000000000..5fc75f2048 --- /dev/null +++ b/docs/partials/getting-started/_best-practices.mdx @@ -0,0 +1,7 @@ +The following are some best practices and recommendations for successfully onboarding with Replicated: + +* 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. + +* Use the Replicated CLI to create and manage your application and releases. Getting familiar with the Replicated CLI will 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). \ No newline at end of file diff --git a/docs/partials/getting-started/_ci-cd.mdx b/docs/partials/getting-started/_ci-cd.mdx new file mode 100644 index 0000000000..8a90ca6e93 --- /dev/null +++ b/docs/partials/getting-started/_ci-cd.mdx @@ -0,0 +1,6 @@ +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) \ No newline at end of file diff --git a/docs/partials/getting-started/_community.mdx b/docs/partials/getting-started/_community.mdx new file mode 100644 index 0000000000..744f7158c2 --- /dev/null +++ b/docs/partials/getting-started/_community.mdx @@ -0,0 +1,5 @@ +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/. \ No newline at end of file diff --git a/docs/partials/getting-started/_connect-image-registry.mdx b/docs/partials/getting-started/_connect-image-registry.mdx new file mode 100644 index 0000000000..907bb141de --- /dev/null +++ b/docs/partials/getting-started/_connect-image-registry.mdx @@ -0,0 +1,3 @@ +Add credentials for your image registry to the Vendor Portal. This will allow you to enable the Replicated proxy service 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). \ No newline at end of file diff --git a/docs/partials/getting-started/_create-app.mdx b/docs/partials/getting-started/_create-app.mdx new file mode 100644 index 0000000000..38228ca146 --- /dev/null +++ b/docs/partials/getting-started/_create-app.mdx @@ -0,0 +1,9 @@ +To create an application: + +1. Create a new application using the Replicated CLI or the Vendor Portal. For the application name, use an official name for your application. You will not be able to modify the name. See [Create an Application](/vendor/vendor-portal-manage-app#create-an-application). + +1. Set the `REPLICATED_APP` environment variable to the unique slug of the application that you created. See [Set Environment Variables](/reference/replicated-cli-installing#replicated_app) in _Installing the Replicated CLI_. For example: + + ```bash + export REPLICATED_APP=my-app + ``` \ No newline at end of file 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/_custom-channels.mdx b/docs/partials/getting-started/_custom-channels.mdx new file mode 100644 index 0000000000..de6be3442b --- /dev/null +++ b/docs/partials/getting-started/_custom-channels.mdx @@ -0,0 +1,11 @@ +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](releases-about-releases) +* [Creating and Editing Channels](/vendor/releases-creating-channels) \ No newline at end of file diff --git a/docs/partials/getting-started/_custom-domains.mdx b/docs/partials/getting-started/_custom-domains.mdx new file mode 100644 index 0000000000..636b648924 --- /dev/null +++ b/docs/partials/getting-started/_custom-domains.mdx @@ -0,0 +1,3 @@ +Replicated recommends that you use custom domains to alias Replicated endpoints. 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. + +For more information, see [Using Custom Domains](/vendor/custom-domains-using). \ No newline at end of file diff --git a/docs/partials/getting-started/_custom-metrics.mdx b/docs/partials/getting-started/_custom-metrics.mdx new file mode 100644 index 0000000000..6e01f5bf68 --- /dev/null +++ b/docs/partials/getting-started/_custom-metrics.mdx @@ -0,0 +1,3 @@ +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 using the Replicated SDK. + +For more information, see [Configuring Custom Metrics](/vendor/custom-metrics). \ No newline at end of file diff --git a/docs/partials/getting-started/_customize-support-bundles.mdx b/docs/partials/getting-started/_customize-support-bundles.mdx new file mode 100644 index 0000000000..594784f5cd --- /dev/null +++ b/docs/partials/getting-started/_customize-support-bundles.mdx @@ -0,0 +1,13 @@ +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. + +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). \ No newline at end of file diff --git a/docs/partials/getting-started/_enable-proxy-service.mdx b/docs/partials/getting-started/_enable-proxy-service.mdx new file mode 100644 index 0000000000..650c88f34b --- /dev/null +++ b/docs/partials/getting-started/_enable-proxy-service.mdx @@ -0,0 +1,11 @@ +import HelmPackage from "../helm/_helm-package.mdx" + +1. Follow the steps in [Using the Proxy Service with Helm Installations](/vendor/helm-image-registry) to authenticate with the Replicated proxy service 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 with the Helm CLI to test your changes. For more information, see [Installing with Helm](/vendor/install-with-helm). \ No newline at end of file diff --git a/docs/partials/getting-started/_onboard-intro.mdx b/docs/partials/getting-started/_onboard-intro.mdx new file mode 100644 index 0000000000..c526078ddf --- /dev/null +++ b/docs/partials/getting-started/_onboard-intro.mdx @@ -0,0 +1 @@ +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. \ No newline at end of file diff --git a/docs/partials/getting-started/_package-sdk.mdx b/docs/partials/getting-started/_package-sdk.mdx new file mode 100644 index 0000000000..f3b8c087b6 --- /dev/null +++ b/docs/partials/getting-started/_package-sdk.mdx @@ -0,0 +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). \ No newline at end of file diff --git a/docs/partials/getting-started/_preflights.mdx b/docs/partials/getting-started/_preflights.mdx new file mode 100644 index 0000000000..6d4e62239e --- /dev/null +++ b/docs/partials/getting-started/_preflights.mdx @@ -0,0 +1,27 @@ +import HelmPackage from "../helm/_helm-package.mdx" +import CreateRelease from "../getting-started/_create-promote-release.mdx" + +:::note +Before you begin this task, Replicated recommends that you 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, then 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). + :::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. Install the release to test your changes. + + 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. \ No newline at end of file diff --git a/docs/partials/getting-started/_prerequisites.mdx b/docs/partials/getting-started/_prerequisites.mdx new file mode 100644 index 0000000000..870a1a9cd6 --- /dev/null +++ b/docs/partials/getting-started/_prerequisites.mdx @@ -0,0 +1,5 @@ +* 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). + +* 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-embedded). \ No newline at end of file diff --git a/docs/partials/getting-started/_quick-start-create-account.mdx b/docs/partials/getting-started/_quick-start-create-account.mdx new file mode 100644 index 0000000000..0a91be631b --- /dev/null +++ b/docs/partials/getting-started/_quick-start-create-account.mdx @@ -0,0 +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). \ No newline at end of file diff --git a/docs/partials/getting-started/_quick-start-create-app.mdx b/docs/partials/getting-started/_quick-start-create-app.mdx new file mode 100644 index 0000000000..0d9b464fcd --- /dev/null +++ b/docs/partials/getting-started/_quick-start-create-app.mdx @@ -0,0 +1,43 @@ +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. 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 slug for the application that you created: + + ```bash + replicated app ls + ``` + **Example output**: + ```bash + ID NAME SLUG SCHEDULER + 2WthxUIfGT13RlrsUx9HR7So8bR Gitea gitea-kite kots + ``` + In the example above, the application slug is `gitea-kite`. + + 1. Set the `REPLICATED_APP` environment variable to the application slug. + + **Example:** + + ```bash + export REPLICATED_APP=gitea-kite + ``` \ No newline at end of file diff --git a/docs/partials/getting-started/_quick-start-instance-insights.mdx b/docs/partials/getting-started/_quick-start-instance-insights.mdx new file mode 100644 index 0000000000..5dbc942ff0 --- /dev/null +++ b/docs/partials/getting-started/_quick-start-instance-insights.mdx @@ -0,0 +1,5 @@ +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 when the Replicated SDK is installed alongside the application. 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). \ No newline at end of file diff --git a/docs/partials/getting-started/_quick-start-intro.mdx b/docs/partials/getting-started/_quick-start-intro.mdx new file mode 100644 index 0000000000..23aaf6c309 --- /dev/null +++ b/docs/partials/getting-started/_quick-start-intro.mdx @@ -0,0 +1 @@ +This workflow 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. \ No newline at end of file diff --git a/docs/partials/getting-started/_quick-start-next-steps.mdx b/docs/partials/getting-started/_quick-start-next-steps.mdx new file mode 100644 index 0000000000..6ab8058f4a --- /dev/null +++ b/docs/partials/getting-started/_quick-start-next-steps.mdx @@ -0,0 +1 @@ +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. \ No newline at end of file diff --git a/docs/partials/getting-started/_quick-start-objectives.mdx b/docs/partials/getting-started/_quick-start-objectives.mdx new file mode 100644 index 0000000000..0cd12d27fb --- /dev/null +++ b/docs/partials/getting-started/_quick-start-objectives.mdx @@ -0,0 +1,5 @@ +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 \ No newline at end of file diff --git a/docs/partials/getting-started/_quick-start-preflights.mdx b/docs/partials/getting-started/_quick-start-preflights.mdx new file mode 100644 index 0000000000..4886863d8f --- /dev/null +++ b/docs/partials/getting-started/_quick-start-preflights.mdx @@ -0,0 +1,59 @@ +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 . --dependency-update + ``` \ No newline at end of file diff --git a/docs/partials/getting-started/_quick-start-welcome.mdx b/docs/partials/getting-started/_quick-start-welcome.mdx new file mode 100644 index 0000000000..f8f111841e --- /dev/null +++ b/docs/partials/getting-started/_quick-start-welcome.mdx @@ -0,0 +1 @@ +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. \ No newline at end of file diff --git a/docs/partials/getting-started/_sdk-api-update-checks.mdx b/docs/partials/getting-started/_sdk-api-update-checks.mdx new file mode 100644 index 0000000000..db284e9cf8 --- /dev/null +++ b/docs/partials/getting-started/_sdk-api-update-checks.mdx @@ -0,0 +1,9 @@ +The Replicated SDK provides an in-cluster API that can be used to integrate Replicated functionality with your application. + +The Replicated SDK API `api/v1/app/updates` endpoint returns details about new releases that are available to an instance for upgrade. You can use the `api/v1/app/updates` endpoint to allow users to easily check for available updates for your application. + +To do so, you can use the Replicated SDK in integration mode to develop locally against the SDK API without needing to make real changes in the Vendor Portal or in your environment. + +For more information, see: +* [Support Update Checks in your Application](/reference/replicated-sdk-apis#support-update-checks-in-your-application) in _Replicated SDK API_ +* [Developing Against the SDK API](/vendor/replicated-sdk-development) \ No newline at end of file diff --git a/docs/partials/getting-started/_setup-cluster.mdx b/docs/partials/getting-started/_setup-cluster.mdx new file mode 100644 index 0000000000..74df7fee35 --- /dev/null +++ b/docs/partials/getting-started/_setup-cluster.mdx @@ -0,0 +1 @@ +Ensure that you have kubectl access to a Kubernetes cluster. 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. \ No newline at end of file diff --git a/docs/partials/getting-started/_support-bundles.mdx b/docs/partials/getting-started/_support-bundles.mdx new file mode 100644 index 0000000000..8c76e13f21 --- /dev/null +++ b/docs/partials/getting-started/_support-bundles.mdx @@ -0,0 +1,69 @@ +import HelmPackage from "../helm/_helm-package.mdx" +import TestYourChanges from "../getting-started/_test-your-changes.mdx" +import CreateRelease from "../getting-started/_create-promote-release.mdx" + +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: [] + ``` + +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. + + ```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 + * [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. Install the release to test your changes. For information about how to create support bundles, see [Generating Support Bundles](/vendor/support-bundle-generating). + +1. (Optional) Customize the support bundle spec by adding additional collectors and analyzers. You can do this step later. See [(Optional) Customize the Specification](/vendor/support-bundle-customizing#optional-customize-the-specification) in _Adding and Customizing Support Bundles_. \ 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..5503cd77ca --- /dev/null +++ b/docs/partials/getting-started/_test-your-changes.mdx @@ -0,0 +1 @@ +Install the release to test your changes. See [Performing Udpates in Embedded Clusters](/enterprise/updating-embedded) and [Performing Updates in Existing Clusters](/enterprise/updating-app-manager). \ No newline at end of file diff --git a/docs/partials/preflights/_overview.mdx b/docs/partials/preflights/_overview.mdx new file mode 100644 index 0000000000..f899f05d24 --- /dev/null +++ b/docs/partials/preflights/_overview.mdx @@ -0,0 +1,5 @@ +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. \ No newline at end of file diff --git a/docs/vendor/distributing-workflow.md b/docs/vendor/distributing-workflow.md deleted file mode 100644 index ed7638d6e4..0000000000 --- a/docs/vendor/distributing-workflow.md +++ /dev/null @@ -1,136 +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). - -* Complete a basic Replicated onboarding workflow to create an application and then promote and install initial releases in a development environment: - * (Recommended) For Helm chart-based applications, Replicated recommends that you complete the [Replicated Quick Start](/vendor/replicated-onboarding) workflow before getting started with KOTS. The workflow in _Replicated Quick Start_ demonstrates how to add a Helm chart to a release in the vendor platform and then install with the Helm CLI. - - :::note - Packaging your application with Helm is recommended because it allows you to support both installations with the Helm CLI and with KOTS from the same release, without having to maintain separate sets of Helm charts or application manifests. - ::: - - * Alternatively, if you do _not_ intend to distribute a Helm chart-based application with Replicated, see [KOTS Tutorial (UI)](tutorial-ui-setup) for a workflow that uses a sample application with standard Kubernetes manifests. - -## 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. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    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 Config (Beta)Create an embedded cluster config to support installations in VMs or bare metal servers with Replicated Embedded Cluster.Using Embedded Cluster (Beta)
    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 - -Review the [Features Checklist](/vendor/replicated-onboarding#features-checklist) in _Replicated Quick Start_ 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/distributing-workflow.mdx b/docs/vendor/distributing-workflow.mdx new file mode 100644 index 0000000000..afd76e5c9b --- /dev/null +++ b/docs/vendor/distributing-workflow.mdx @@ -0,0 +1,316 @@ +import SDKOverview from "../partials/replicated-sdk/_overview.mdx" +import BestPractices from "../partials/getting-started/_best-practices.mdx" +import Community from "../partials/getting-started/_community.mdx" +import Prerequisites from "../partials/getting-started/_prerequisites.mdx" +import PackageSdk from "../partials/getting-started/_package-sdk.mdx" +import Preflights from "../partials/getting-started/_preflights.mdx" +import SupportBundles from "../partials/getting-started/_support-bundles.mdx" +import DependencyYaml from "../partials/replicated-sdk/_dependency-yaml.mdx" +import CiCd from "../partials/getting-started/_ci-cd.mdx" +import CustomMetrics from "../partials/getting-started/_custom-metrics.mdx" +import CustomChannels from "../partials/getting-started/_custom-channels.mdx" +import CustomDomains from "../partials/getting-started/_custom-domains.mdx" +import HelmPackage from "../partials/helm/_helm-package.mdx" +import UnauthorizedError from "../partials/replicated-sdk/_401-unauthorized.mdx" +import TestYourChanges from "../partials/getting-started/_test-your-changes.mdx" +import CreateRelease from "../partials/getting-started/_create-promote-release.mdx" +import EmbeddedConfig from "../partials/embedded-cluster/_default-config.mdx" +import Requirements from "../partials/embedded-cluster/_requirements.mdx" +import Cluster from "../partials/getting-started/_setup-cluster.mdx" +import ImageRegistry from "../partials/getting-started/_connect-image-registry.mdx" +import CustomizeSupportBundles from "../partials/getting-started/_customize-support-bundles.mdx" +import AboutPreflightsSupportBundles from "../partials/preflights/_overview.mdx" +import CustomEntitlements from "../partials/getting-started/_add-license-entitlements.mdx" +import CreateApp from "../partials/getting-started/_create-app.mdx" +import EnableProxyService from "../partials/getting-started/_enable-proxy-service.mdx" +import Intro from "../partials/getting-started/_onboard-intro.mdx" +import UpdateChecks from "../partials/getting-started/_sdk-api-update-checks.mdx" + +# Replicated Onboarding + +This topic describes how to onboard applications to support installation with both the Replicated Embedded Cluster installer and the Helm CLI. + +## Before You Begin + +This section includes guidance and prerequisites to review before you begin onboarding your application. + +### Prerequisites + + + +* + +* Ensure that you have access to a VM that meets the requirements for Embedded Cluster: + + + +### Best Practices and Recommendations + + + +### Getting Help from the Community + + + +## Onboard + + + +### 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. + + + +### Task 2: Connect Your Image Registry + + + +### Task 3: Add the Replicated SDK and Package your Chart + +Next, add the Replicated SDK as a dependency of your Helm chart then 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. + + + +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 and Install the Initial Release {#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 Embedded Cluster: +* 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. + +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: + + + + 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). + + 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 enable the Replicated proxy service. + + 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. 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 [Download the Embedded Cluster Binary](/vendor/embedded-overview#download-the-embedded-cluster-binary) and [Install](/vendor/embedded-overview#install) in _Using Embedded Cluster_. + + 1. Install in an existing cluster with KOTS. See [Online Installation in Existing Clusters](/enterprise/installing-existing-cluster). + +After successfully installing the initial release both on a VM and in an existing cluster, 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 + icon: https://raw.githubusercontent.com/cncf/artwork/master/projects/kubernetes/icon/color/kubernetes-icon-color.png + 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) + +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. + +:::note +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. +::: + +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) + +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) + * [`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_. + + + + + +### Task 8: Add a Support Bundle Spec + + + +### Task 9: Alias Replicated Endpoints with Your Own Domains + + + +## 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. + +### 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 service. + +:::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: + + + +### Add Support for Air Gap Installations + +KOTS and Embedded Cluster support installations in _air gap_ environments with no outbound internet access. Users can install in air gap environments by providing air gap bundles that contain the required images. + +You can use the Vendor Portal to build and download the air gap bundles needed to install in an air gap existing cluster with KOTS or in an air gap VM or bare metal server with Embedded Cluster. + +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 `.airgap` bundle for the release. See [Define Additional Images](/vendor/operator-defining-additional-images). + +1. If you have any Helm values that determine whether or not an application image is included in an installation, then configure the `builder` key in the KOTS HelmChart custom resource to enable those values. The Vendor Portal uses the values provided in the `builder` key to build the `.airgap` bundle for the release. 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 the chart, then you do not need to configure the `builder` key. + ::: + +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. See [Rewrite Image Names](/vendor/helm-native-v2-using#rewrite-image-names) in _Configuring the HelmChart Custom Resource v2_. + +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 release artifacts for air gap installations, 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. 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. See [Building Air Gap Bundles](/vendor/releases-download-airgap-bundles). Then, install in an air gap existing cluster to test. See [Air Gap Installation in Existing Clusters](/enterprise/installing-existing-cluster-airgapped). + +### Add Application Links to the Admin Console Dashboard + +You can add the Kubernetes SIG Application custom resource in order to add a link to your application from the Admin Console dashboard. This makes it easier for users to access your application after installation. + +For more information, see [Adding Application Links to the Dashboard](/vendor/admin-console-adding-buttons-links). + +### Update the Preflight and Support Bundles Specs + + + +### Add and Query Custom License Entitlements + + + +For more information, see: +* [Managing Custom License Fields](/vendor/licenses-adding-custom-fields) +* [Querying Entitlements with the Replicated SDK API](/vendor/licenses-reference-sdk) +* [Checking Entitlements in Preflights with KOTS Template Functions](/vendor/licenses-referencing-fields) +* [Verifying License Field Signatures with the Replicated SDK API](/vendor/licenses-verify-fields-sdk-api) +* [Creating and Managing Customers](/vendor/releases-creating-customer) +* [Developing Against the SDK API](/vendor/replicated-sdk-development) + +### 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 + + + +### Integrate with CI/CD + + + +### Customize Release Channels + + \ 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..ea3a7973ab 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -271,6 +271,10 @@ spec: ### Add Backup Labels for Snapshots +:::note +The snapshots feature for backup and restore is supported for existing cluster installations with KOTS only. Snapshots is not supported for installations with [Replicated Embedded Cluster](/vendor/embedded-overview). +::: + The Replicated 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. diff --git a/docs/vendor/quick-start-embedded.mdx b/docs/vendor/quick-start-embedded.mdx new file mode 100644 index 0000000000..137f4a7fd1 --- /dev/null +++ b/docs/vendor/quick-start-embedded.mdx @@ -0,0 +1,337 @@ +--- +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/getting-started/_gitea-ec-config.mdx" +import Requirements from "../partials/embedded-cluster/_requirements.mdx" +import Welcome from "../partials/getting-started/_quick-start-welcome.mdx" +import Objectives from "../partials/getting-started/_quick-start-objectives.mdx" +import Intro from "../partials/getting-started/_quick-start-intro.mdx" +import NextSteps from "../partials/getting-started/_quick-start-next-steps.mdx" +import CreateAccount from "../partials/getting-started/_quick-start-create-account.mdx" +import CreateApp from "../partials/getting-started/_quick-start-create-app.mdx" +import Preflights from "../partials/getting-started/_quick-start-preflights.mdx" + +# Replicated Quick Start + + + +## Introduction + + + +* Working with the KOTS Admin Console + +* Installing and updating applications on a VM with Embedded Cluster + +## 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. + +1. + +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: + + + +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 YAML manifests required to install the chart with Embedded Cluster: + ``` + 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 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 in your VM with Embedded Cluster: + + 1. In the [Vendor Portal](https://vendor.replicated.com), 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 (Beta)** + + 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. In the **Embedded cluster install instructions** dialog, for the **Select a version** dropdown, select **latest**. + + 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 artifacts, and install. + + embedded cluster install instructions dialog + + [View a larger version of this image](/images/embedded-cluster-install-dialog.png) + + 1. When prompted, enter a password for accessing the KOTS 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 KOTS 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, for version `0.1.0`, click **Deploy** 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: + + ![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. + + 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 and update the `chartVersion`: + + ```yaml + # KOTS HelmChart + chartVersion: 1.0.7 + ``` + + 1. Create and promote the new release: + + ```bash + replicated release create --yaml-dir manifests --promote Unstable + ``` + **Example output**: + ```bash + • Reading manifests from manifests ✓ + • 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. + + 1. Click **Check for update**. + + 1. Click **Deploy** next to the new version. Then, **Yes, Deploy**. + + The preflight check that you added runs automatically during deployment. + + 1. Next to the newly deployed version, click the **View preflight checks** icon to see the result of the "Slack Accessible" preflight check that you added: + + ![View preflights icon](/images/quick-start-ec-view-preflight.png) + + [View a larger version of this image](/images/quick-start-ec-view-preflight.png) + + ![Pass result for Slack Accessible preflight check](/images/quick-start-ec-slack-preflight.png) + + [View a larger version of this image](/images/quick-start-ec-slack-preflight.png) + +1. Reset and reboot the VM to remove the installation: + + ```bash + sudo ./APP_SLUG reset --reboot + ``` + +## 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 + + + +To get started, see [Replicated Onboarding](distributing-workflow). + +## 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 deleted file mode 100644 index ed46f3fe5a..0000000000 --- a/docs/vendor/replicated-onboarding.mdx +++ /dev/null @@ -1,361 +0,0 @@ ---- -pagination_next: null ---- - -import DependencyYaml from "../partials/replicated-sdk/_dependency-yaml.mdx" -import HelmPackage from "../partials/helm/_helm-package.mdx" - -# Replicated Quick Start - -Welcome! This topic provides an onboarding workflow and a feature checklist to help you get started with the Replicated Platform. For more information about Replicated, see [Introduction to Replicated](../intro-replicated). - -The goals of this topic are to introduce new Replicated users to the following common tasks so that they can successfully onboard their application to the Replicated Platform: -* Working with applications, channels, releases, and customers in the Replicated Vendor Portal and Replicated CLI -* Testing and iterating on releases by installing in a development environment -* Integrating key Replicated features and functionality with an application - -## Best Practices and Recommendations - -The following are Replicated's best practices and recommendations for successfully onboarding: - -* 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. - -* 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. - -* Try creating and managing releases with both the Vendor Portal and the Replicated CLI. 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). - -* 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. - -## Prerequisites - -Before you begin, complete the following prerequisites: - -* This workflow assumes that you have a Helm chart that you can install and develop against. Replicated strongly recommends that all vendors distribute their application as a Helm chart because many enterprise users expect to be able to install using Helm. - - You can use your own application chart or a sample chart. If you want to use a sample chart, Replicated recommends that you run the following Helm CLI command to create a new `replicated-onboarding` folder with a basic NGINX deployment: - ```bash - helm create replicated-onboarding - ``` - For more information, see [Helm Create](https://helm.sh/docs/helm/helm_create/) in the Helm documentation. - - Alternatively, more advanced users can also use one of the following open source Helm charts: - * [Gitea](https://github.com/bitnami/charts/tree/main/bitnami/gitea) - - ``` - helm pull --untar oci://registry-1.docker.io/bitnamicharts/gitea - ``` - - * [MediaWiki](https://github.com/bitnami/charts/tree/main/bitnami/mediawiki) - - ``` - helm pull --untar oci://registry-1.docker.io/bitnamicharts/mediawiki - ``` - - * [WordPress](https://github.com/bitnami/charts/tree/main/bitnami/wordpress) - - ``` - helm pull --untar oci://registry-1.docker.io/bitnamicharts/wordpress - ``` - - :::note - If you do not intend to distribute a Helm chart-based application with Replicated, see [KOTS Tutorial (UI)](tutorial-ui-setup) to follow an onboarding workflow that uses a sample application with standard Kubernetes manifests and demonstrates installing with Replicated KOTS. - ::: - -* You must have kubectl access to a cluster where you can develop against the Helm chart. Replicated recommends that you confirm that you can successfully install the chart in the cluster and also log in to the application UI. After you confirm that you can install and access the application, uninstall it before proceeding to the onboarding workflow. For more information, see [Helm Install](https://helm.sh/docs/helm/helm_install/) and [Helm Uninstall](https://helm.sh/docs/helm/helm_uninstall/) in the Helm documentation. - -## Workflow - -This onboarding workflow provides steps for using the Replicated Platform to create releases for a Helm chart-based application, then using the Helm CLI to install in a development environment. - -You will repeat these same basic steps to create and test releases throughout the onboarding process to test Replicated features. You will also repeat these steps after onboarding whenever you need to integrate new Replicated features with your application. - -To begin onboarding to the Replicated Platform with a Helm chart: - -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 a new application: - - 1. In the [Vendor Portal](https://vendor.replicated.com/), from the application drop down, click **Create new app..**. - - 1. In the **Name your application** field, enter a name based on the Helm chart that you will use for onboarding. For example, "Wordpress Test" or "MediaWiki Onboarding". - -1. Create a release for the application: - - 1. In the Vendor Portal, click **Releases > Create release**. - - :::note - If a drop down is displayed, click **Create Helm-only release**. - ::: - - 1. In the **Add the Replicated SDK to your Helm chart** dialog, click **Yes, I have a Helm chart for my app that I'd like to use**, and then click **Next**. - - Add the SDK dialog - [View a larger version of this image](/images/do-you-have-a-helm-chart-modal.png) - - 1. Follow the steps in the dialog to add the Replicated SDK, package the chart to a `.tgz`, and then upload the `.tgz`: - - Upload Helm chart dialog - [View a larger version of this image](/images/upload-helm-chart-modal.png) - - The following describes the steps in the dialog: - - 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 (Beta)](/vendor/replicated-sdk-overview). - - 1. Update dependencies and package the chart as a `.tgz` file: - - - - 1. Under **Upload your Helm chart**, drag and drop the Helm chart `.tgz` file that you created. Click **Upload chart**. - - 1. On the release page, click **Promote**. - - 1. In the dialog, for **Which channels you would like to promote this release to?** select **Unstable**. Unstable is a default channel that is intended for use with internal testing. - - Promote release dialog - - [View a larger image](/images/release-promote.png) - - 1. Click **Promote**. - - :::note - You can ignore any error messages in the **Promote Release** dialog. - ::: - -1. Create a customer so that you can install the release in your cluster: - - 1. Click **Customer > Create customer**. - - 1. For **Customer name**, add a name. - - 1. For **Channel**, select **Unstable**. This allows the customer to install releases promoted to the Unstable channel. - - 1. For **Customer email**, enter an email address. An email address is required for Helm installations to authenticate with the Replicated registry. This email address is never used to send emails to customers. - - 1. Click **Save Changes**. - - For more information, see [Creating and Managing Customers](/vendor/releases-creating-customer). - -1. Install the application: - 1. On the **Customers** page for the customer that you created, click **Helm install instructions**. - - ![Helm install instructions button](/images/helm-install-button.png) - - [View a larger image](/images/helm-install-button.png) - - 1. Run the commands in the **Helm install instructions** dialog to log in to the registry and install the Helm chart. Skip the step to run preflight checks. - - Helm install instructions dialog - - [View a larger image](/images/helm-install-instructions-no-preflights.png) - - :::note - Ignore the **No preflight checks found** warning, if one is displayed in the dialog. This warning appears because there are no specifications for preflight checks in the Helm chart archive. You will add preflight checks later in the onboarding process. - ::: - - 1. After you install, in the Vendor Portal, go to **Customers**. Under the name of the customer, confirm that you can see an active instance. - - **Example**: - - ![Customers page with one customer that has an active isntance](/images/onboarding-view-telemetry.png) - - [View a larger image](/images/onboarding-view-telemetry.png) - - This instance telemetry is automatically collected and sent back to the Vendor Portal when the Replicated SDK is installed alongside the application. 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 in the Vendor Portal and then upgrade the instance in the cluster: - - 1. Make a small change in the chart, such as incrementing the semantic version in the `Chart.yaml` to a new version. Then, package the chart again. - - 1. In the Vendor Portal, create a new release (**Releases > Create release**). Drag and drop the new chart `.tgz` and then promote the new release to the Unstable channel. - - 1. In your cluster, run `helm upgrade` to upgrade the instance to the new release that you just promoted. The `helm upgrade` command is the same as the command you used for `helm install` in a previous step, replacing `install` with `upgrade`. - - **Example**: - - ``` - helm upgrade wordpress oci://registry.replicated.com/my-app/unstable/wordpress - ``` - - See [Helm Upgrade](https://helm.sh/docs/helm/helm_upgrade/) in the Helm documentation. - - 1. After the upgrade completes, return to the **Instance details** page in the Vendor Portal and confirm that you can see the new application version. - - **Example**: - - ![Instance details page](/images/onboarding-instance-details-new-version.png) - - [View a larger version](/images/onboarding-instance-details-new-version.png) - -1. Now that you are familiar with the workflow of creating and installing releases, repeat step 8 to integrate and test new Replicated features with the application. Integrate one feature at a time by creating a release and then upgrading in a development environment to test. For the list of recommended features to integrate, see [Features Checklist](#features-checklist) below. - -1. (Recommended) Finish setting up your Vendor Portal account and team: - - 1. If you are an admin, invite and manage team members. See [Invite Members](/vendor/team-management#invite-members) in _Managing Team Members_. - - 1. Set up Slack or email notifications to be notified when there are changes in the installed instances of your application. Notifications can help catch problems before they happen and let you proactively contact customers to prevent support cases. See [Configuring Instance Notifications](/vendor/instance-notifications-config). - -## Features Checklist - -This section provides a checklist of key Replicated features to integrate with your application to fully onboard onto the Replicated Platform. These features are provided in a suggested order, though you can configure and test the features in any order. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    FeatureDescriptionHow to
    Proxy registry -

    Allow customer licenses to grant proxy access to your application's private images. Configuring the proxy registry allows you to pull your images so that you can test your deployment.

    -

    Estimated time: 1 to 2 hours to connect your external registry and update your Helm chart to deliver image pull secrets for the proxy registry

    -     		- Proxying Images for Helm Installations -
    Preflight checks -

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

    -

    Estimated time: 30 minutes to define and test one or more collectors and analyzers for your application

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

    -

    Estimated time: 30 minutes to define and test one or more collectors and analyzers for your application

    -     		- -
    Custom license entitlements -

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

    -

    Estimated time: 30 minutes to create and test each entitlement

    -     		- Managing Custom License Fields -
    Pre-installation license entitlement checks -

    Add checks for customer license entitlements before installation.

    -

    Estimated time: 1 hour to integrate pre-installation license checks into your application, plus more time to test and iterate

    -     		Checking Entitlements in Helm Charts Before Deployment
    Runtime license entitlement checks with the SDK API -

    Use the SDK API to add checks for customer license entitlements during runtime.

    -

    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.

    -

    Estimated time: 1 hour to integrate pre-installation license checks into your application, plus more time to test and iterate

    -     		- -
    License field signature validation

    Verify the signatures of license fields when you check customer entitlements in your application.

    -

    Estimated time: 2 hours, including time to add entitlement checks in your application if you have not already

    		Verifying License Field Signatures with the Replicated SDK API
    Custom metrics with the SDK API -

    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.

    -

    Estimated time: 30 minutes to create mock data and test the endpoints locally with integration mode, plus more time to integrate with your application

    -     		- Configuring Custom Metrics -
    Custom domains -

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

    -

    Estimated time: 30 minutes, plus up to 24 hours to create and verify the CNAME record in your DNS account.

    -     		Using Custom Domains
    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.

    -

    Estimated time: 1 to 2 hours to configure your CI pipeline using Replicated CLI commands or Replicated GitHub Actions.

    -     		- -
    Application update checks with the SDK API -

    Use the SDK API to allow your users to easily check for available updates from your application..

    -

    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.

    -

    Estimated time: 1 hour to mock endpoints locally with integration mode, plus more time to optionally integrate with your application

    -     		- -
    Replicated KOTS -

    For vendors with access to the KOTS installer, add custom resources to your release to support KOTS installations.

    -

    Estimated time: 1 to 2 hours to configure and test each custom resource.

    -     		- -
    - -## Get Help from the 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/. diff --git a/docs/vendor/tutorial-embedded-cluster-install.mdx b/docs/vendor/tutorial-embedded-cluster-install.mdx index c336234ef9..04c077238c 100644 --- a/docs/vendor/tutorial-embedded-cluster-install.mdx +++ b/docs/vendor/tutorial-embedded-cluster-install.mdx @@ -101,7 +101,7 @@ To install the release with Embedded Cluster: ## Next Step -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). To learn more about how to iterate on releases to add more functionality, such as defining preflight checks or custom license entitlements, see [Replicated Quick Start](replicated-onboarding). +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). ## Related Topics diff --git a/docs/vendor/tutorial-kots-helm-install-helm.md b/docs/vendor/tutorial-kots-helm-install-helm.md index 579ecd0517..a0a29c94cf 100644 --- a/docs/vendor/tutorial-kots-helm-install-helm.md +++ b/docs/vendor/tutorial-kots-helm-install-helm.md @@ -108,7 +108,7 @@ To install the release with the Helm CLI: ## Next Step -Congratulations! As part of this tutorial, you created a release in the Replicated Vendor Portal and installed the release with both KOTS and the Helm CLI. To learn more about how to iterate on releases to add more functionality, such as defining preflight checks or custom license entitlements, see [Replicated Quick Start](replicated-onboarding). +Congratulations! As part of this tutorial, you created a release in the Replicated Vendor Portal and installed the release with both KOTS and the Helm CLI. ## Related Topics diff --git a/docs/vendor/tutorial-kots-helm-setup.md b/docs/vendor/tutorial-kots-helm-setup.md index 0e44ff392f..7599bc5852 100644 --- a/docs/vendor/tutorial-kots-helm-setup.md +++ b/docs/vendor/tutorial-kots-helm-setup.md @@ -1,3 +1,5 @@ +import Cluster from "../partials/getting-started/_setup-cluster.mdx" + # Introduction and Setup This topic provides a summary of the goals and outcomes for the tutorial and also lists the prerequisites to set up your environment before you begin. @@ -18,7 +20,7 @@ In this tutorial, you use a sample Helm chart to learn how to: Before you begin, do the following to set up your environment: -* Ensure that you have kubectl access to a Kubernetes cluster. You can use any cloud provider or tool that you prefer to create a cluster, such as Google Kubernetes Engine (GKE), Amazon Web Services (AWS), or minikube. +* For information about installing kubectl and configuring kubectl access to a cluster, see the following in the Kubernetes documentation: * [Install Tools](https://kubernetes.io/docs/tasks/tools/) diff --git a/docs/vendor/vendor-portal-creating-account.md b/docs/vendor/vendor-portal-creating-account.md index dd51125cb1..99ff18b0e7 100644 --- a/docs/vendor/vendor-portal-creating-account.md +++ b/docs/vendor/vendor-portal-creating-account.md @@ -42,5 +42,5 @@ To create a vendor account: ::: ## Next Steps -* Invite team members to collaborate with you in Vendor Portal. See [Invite Members](team-management#invite-members). -* Learn about how to get started with Replicated. See [Replicated Quick Start](replicated-onboarding). + +Invite team members to collaborate with you in Vendor Portal. See [Invite Members](team-management#invite-members). diff --git a/docusaurus.config.js b/docusaurus.config.js index 8d03563578..6a65b7b36f 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -183,7 +183,7 @@ const config = { }, { label: 'Replicated Quick Start', - to: 'vendor/replicated-onboarding', + to: 'vendor/distributing-workflow', }, ], }, diff --git a/netlify.toml b/netlify.toml index 80b0270ed0..27c66f114f 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/replicated-onboarding" + to="https://docs.replicated.com/vendor/distributing-workflow" ################################################### # Redirects To the Enterprise Section diff --git a/sidebars.js b/sidebars.js index 2e97f66e0a..48dd76ef02 100644 --- a/sidebars.js +++ b/sidebars.js @@ -36,7 +36,9 @@ const sidebars = { //GET STARTED {type: 'html', value: '
    getting started
    ', defaultStyle: true}, 'intro-replicated', - 'vendor/replicated-onboarding', + 'vendor/distributing-overview', + 'vendor/quick-start-embedded', + 'vendor/distributing-workflow', // { // type: 'category', // label: 'Planning', @@ -45,22 +47,22 @@ 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/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', items: [ + { + type: 'category', + label: 'Deploy a Helm Chart on a VM with Embedded Cluster (Beta)', + items: [ + 'vendor/tutorial-embedded-cluster-setup', + 'vendor/tutorial-embedded-cluster-create-app', + 'vendor/tutorial-embedded-cluster-package-chart', + 'vendor/tutorial-embedded-cluster-create-release', + 'vendor/tutorial-embedded-cluster-create-customer', + 'vendor/tutorial-embedded-cluster-install', + ], + }, { type: 'category', label: 'Deploy a Helm Chart with KOTS and the Helm CLI', @@ -77,19 +79,7 @@ const sidebars = { }, { type: 'category', - label: 'Deploy a Helm Chart on a VM with Embedded Cluster (Beta)', - items: [ - 'vendor/tutorial-embedded-cluster-setup', - 'vendor/tutorial-embedded-cluster-create-app', - 'vendor/tutorial-embedded-cluster-package-chart', - 'vendor/tutorial-embedded-cluster-create-release', - 'vendor/tutorial-embedded-cluster-create-customer', - 'vendor/tutorial-embedded-cluster-install', - ], - }, - { - type: 'category', - label: 'KOTS Tutorial (UI)', + label: 'Installing with KOTS in an Existing Cluster (UI)', items: [ 'vendor/tutorial-ui-setup', 'vendor/tutorial-ui-create-app', @@ -103,7 +93,7 @@ const sidebars = { }, { type: 'category', - label: 'KOTS Tutorial (CLI)', + label: 'Installing with KOTS in an Existing Cluster (CLI)', items: [ 'vendor/tutorial-cli-setup', 'vendor/tutorial-cli-install-cli', @@ -119,7 +109,17 @@ 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/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}, { @@ -200,7 +200,6 @@ const sidebars = { items: [ 'intro-kots', 'vendor/kots-faq', - 'vendor/distributing-workflow', { type: 'category', label: 'Packaging KOTS Releases', @@ -243,15 +242,6 @@ const sidebars = { }, ], }, - { - type: 'category', - label: 'Admin Console and Download Portal Customization', - items: [ - 'vendor/admin-console-customize-app-icon', - 'vendor/admin-console-adding-buttons-links', - 'vendor/admin-console-prometheus-monitoring', - ], - }, { type: 'category', label: 'Admin Console Config Screen', @@ -275,6 +265,15 @@ const sidebars = { }, ], }, + { + type: 'category', + label: 'Admin Console and Download Portal Customization', + items: [ + 'vendor/admin-console-customize-app-icon', + 'vendor/admin-console-adding-buttons-links', + 'vendor/admin-console-prometheus-monitoring', + ], + }, { type: 'category', label: 'Configuring Backup and Restore', @@ -333,6 +332,31 @@ const sidebars = { 'vendor/operator-defining-additional-namespaces', ], }, + { + type: 'category', + label: 'KOTS Custom Resources', + items: [ + 'reference/custom-resource-about', + 'reference/custom-resource-application', + 'reference/custom-resource-config', + 'reference/custom-resource-helmchart-v2', + 'reference/custom-resource-helmchart', + 'reference/custom-resource-lintconfig', + ], + }, + { + type: 'category', + label: 'KOTS Template Functions', + items: [ + 'reference/template-functions-about', + 'reference/template-functions-examples', + 'reference/template-functions-config-context', + 'reference/template-functions-identity-context', + 'reference/template-functions-kurl-context', + 'reference/template-functions-license-context', + 'reference/template-functions-static-context', + ], + }, { type: 'category', label: 'Downloading and Sharing Assets for KOTS Releases', @@ -342,7 +366,7 @@ const sidebars = { 'vendor/releases-share-download-portal', 'vendor/releases-configvalues', ], - }, + }, ], }, // KOTS ENTERPRISE USER DOCS @@ -473,31 +497,6 @@ const sidebars = { }, ], }, - { - type: 'category', - label: 'KOTS Custom Resources', - items: [ - 'reference/custom-resource-about', - 'reference/custom-resource-application', - 'reference/custom-resource-config', - 'reference/custom-resource-helmchart-v2', - 'reference/custom-resource-helmchart', - 'reference/custom-resource-lintconfig', - ], - }, - { - type: 'category', - label: 'KOTS Template Functions', - items: [ - 'reference/template-functions-about', - 'reference/template-functions-examples', - 'reference/template-functions-config-context', - 'reference/template-functions-identity-context', - 'reference/template-functions-kurl-context', - 'reference/template-functions-license-context', - 'reference/template-functions-static-context', - ], - }, ], }, 'vendor/install-with-helm', diff --git a/static/images/helm-install-instructions-no-preflights.png b/static/images/helm-install-instructions-no-preflights.png index 7ba16b6636..d53feef086 100644 Binary files a/static/images/helm-install-instructions-no-preflights.png and b/static/images/helm-install-instructions-no-preflights.png differ diff --git a/static/images/helm-install-instructions-preflights.png b/static/images/helm-install-instructions-preflights.png new file mode 100644 index 0000000000..cc4739aab6 Binary files /dev/null and b/static/images/helm-install-instructions-preflights.png differ diff --git a/static/images/quick-start-ec-slack-preflight.png b/static/images/quick-start-ec-slack-preflight.png new file mode 100644 index 0000000000..2759cc0ee9 Binary files /dev/null and b/static/images/quick-start-ec-slack-preflight.png differ diff --git a/static/images/quick-start-ec-view-preflight.png b/static/images/quick-start-ec-view-preflight.png new file mode 100644 index 0000000000..00a6cfe672 Binary files /dev/null and b/static/images/quick-start-ec-view-preflight.png differ