Skip to main content

Replicated Quick Start

Welcome! This topic provides an onboarding workflow and a feature checklist to help you get started with Replicated. For more information about Replicated, see Introduction to 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 or 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.

  • Ask for help from the Replicated community. For more information, see 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:

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 to create a new replicated-onboarding folder with a basic NGINX deployment:

    helm create replicated-onboarding

    For more information, see Helm Create in the Helm documentation.

    Alternatively, more advanced users can also use one of the following open source Helm charts:

    • Gitea

      helm pull --untar oci://registry-1.docker.io/bitnamicharts/gitea

    • MediaWiki 

      helm pull --untar oci://registry-1.docker.io/bitnamicharts/mediawiki

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

  2. Create a new application:

    1. In the vendor portal, from the application drop down, click Create new app...

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

  3. In the Helm chart Chart.yaml, add the Replicated SDK as a dependency:

    # Chart.yaml
    dependencies:
    - name: replicated
      repository: oci://registry.replicated.com/library
      version: 1.0.0-beta.8

    For the latest version information for the Replicated SDK, see the replicated-sdk repository in GitHub.

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

    note

    If your chart uses the Chart API version 1 (v1), then add the dependency to the requirements.yaml file rather than the Chart.yaml file. For more information, see Consolidation of requirements.yaml into Chart.yaml in the Helm documentation.

  4. Update dependencies then package the Helm chart to a .tgz file:

    helm package . --dependency-update

    For more information, see Packaging a Helm Chart for a Release.

  5. Create a release with the Helm chart:

    1. In the vendor portal, click Releases > Create release.

      note

      If a drop down is displayed, click Create Helm-only release.

    2. In the Upload Helm chart dialog, drag and drop the Helm chart .tgz package. Click Upload chart.

      Upload Helm chart dialog

      View a larger image

    3. On the release page, click Promote.

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

    5. Click Promote.

      note

      You can ignore any error messages in the Promote Release dialog.

  6. Create a customer so that you can install the release in your cluster:

    1. Click Customer > Create customer.

    2. For Customer name, add a name.

    3. For Channel, select Unstable. This allows the customer to install releases promoted to the Unstable channel.

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

    5. Click Save Changes.

    For more information, see Creating and Managing Customers.

  7. Install the application:

    1. On the Customers page for the customer that you created, click Helm install instructions.

      Helm install instructions button

      View a larger image

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

      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.

    3. 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 View a larger image

      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 Customer Reporting and Instance Insights in About the Replicated SDK.

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

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

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

    3. 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 in the Helm documentation.

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

      View a larger version

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

  10. (Recommended) Finish setting up your vendor portal account and team:

    1. If you are an admin, invite and manage team members. See Invite Members in Managing Team Members.

    2. 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 (Alpha)

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 order of less challenging to more challenging, though you can configure and test the features in any order.

FeatureDescriptionHow to
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 1 hour to create and test each entitlement

Replicated SDK API

Embed Replicated functionality like licensing and update checks into your Helm-based application.

To get started, use 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 features with your application

Proxy service

Allow customer licenses to grant proxy access to your application's private images.

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

Proxying Images for Helm Installations
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
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 for Helm Installations
Compatibility matrix

Quickly create ephemeral clusters for development, support, and testing.

Estimated time: Minutes to create a cluster with the replicated CLI, plus time for developing or testing on the cluster. Optionally, an additional 2 hours to configure GitHub Actions in your CI pipeline to automatically test releases with the compatibility matrix.

Using the Compatibility Matrix
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.

Onboarding with KOTS

Get Help from the Community​

The Replicated community site 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/.