Skip to main content

Replicated Quick Start

Welcome! This topic provides a quick start workflow to help new users learn about the Replicated Platform. Complete this quick start before you onboard your application to the platform.

Introduction​

This quick start shows how to create, install, and update releases for a sample Helm chart in the Replicated Platform. You will repeat these same basic steps to create and test releases throughout the onboarding process to integrate Replicated features with your own application.

The goals of this quick start are to introduce new Replicated users to the following common tasks for the purpose of preparing to onboard to the Replicated Platform:

  • Working with applications, channels, releases, and customers in the Replicated Vendor Portal

  • Working with the Replicated CLI

  • Installing and updating applications on a VM with Replicated Embedded Cluster

  • Managing an installation with the Replicated KOTS Admin Console

Set Up the Environment​

Before you begin, ensure that you have access to a VM that meets the requirements for Embedded Cluster:

  • Linux operating system

  • x86-64 architecture

  • systemd

  • At least 2GB of memory and 2 CPU cores

  • The disk on the host must have a maximum P99 write latency of 10 ms. This supports etcd performance and stability. For more information about the disk write latency requirements for etcd, see Disks in Hardware recommendations and What does the etcd warning “failed to send out heartbeat on time” mean? in the etcd documentation.

  • The filesystem at /var/lib/embedded-cluster has 40Gi or more of total space and must be less than 80% full

    note

    The directory used for data storage can be changed by passing the --data-dir flag with the Embedded Cluster install command. For more information, see Embedded Cluster Install Command Options.

    Note that in addition to the primary /var/lib/embedded-cluster directory, Embedded Cluster creates directories and files in the following locations:

    • /etc/cni
    • /etc/k0s
    • /opt/cni
    • /opt/containerd
    • /run/calico
    • /run/containerd
    • /run/k0s
    • /sys/fs/cgroup/kubepods
    • /sys/fs/cgroup/system.slice/containerd.service
    • /sys/fs/cgroup/system.slice/k0scontroller.service
    • /usr/libexec/k0s
    • /var/lib/calico
    • /var/lib/cni
    • /var/lib/containers
    • /var/lib/kubelet
    • /var/log/calico
    • /var/log/containers
    • /var/log/pods
    • /usr/local/bin/k0s

  • (Online installations only) Access to replicated.app and proxy.replicated.com or your custom domain for each

  • Embedded Cluster is based on k0s, so all k0s system requirements and external runtime dependencies apply. See System requirements and External runtime dependencies in the k0s documentation.

Quick Start​

  1. Create an account in the Vendor Portal. You can either create a new team or join an existing team. For more information, see Creating a Vendor Account.

  2. Create an application using the Replicated CLI:

    1. On your local machine, install the Replicated CLI:

      brew install replicatedhq/replicated/cli

      For more installation options, see Installing the Replicated CLI.

    2. Authorize the Replicated CLI:

      replicated login

      In the browser window that opens, complete the prompts to log in to your Vendor Portal account and authorize the CLI.

    3. Create an application named Gitea:

      replicated app create Gitea

    4. Set the REPLICATED_APP environment variable to the application that you created:

      export REPLICATED_APP=APP_SLUG

      Where APP_SLUG is the unique application slug provided in the output of the app create command. For example, export REPLICATED_APP=gitea-kite.

      This allows you to interact with the application using the Replicated CLI without needing to use the --app flag with every command.

  3. 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 repository in GitHub.

    2. Change to the new gitea directory that was created:

      cd gitea

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

      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.

    4. Update dependencies and package the Helm chart to a .tgz chart archive:

      helm package -u .

      Where -u or --dependency-update is an option for the helm package command that updates chart dependencies before packaging. For more information, see Helm Package in the Helm documentation.

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

    2. Move the Helm chart archive that you created to manifests:

      mv gitea-1.0.6.tgz manifests

    3. In manifests, create the following YAML files:

      cd manifests
      touch gitea.yaml kots-app.yaml k8s-app.yaml embedded-cluster.yaml

    4. 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
      apiVersion: kots.io/v1beta2
      kind: HelmChart
      metadata:
        name: gitea
      spec:
        # chart identifies a matching chart from a .tgz
        chart:
          name: gitea
          chartVersion: 1.0.6
        optionalValues:
        - when: 'repl{{ eq Distribution "embedded-cluster" }}'
          recursiveMerge: false
          values:
            service:
              type: NodePort
              nodePorts:
                http: "32000"

    5. Lint the YAML files:

      replicated release lint --yaml-dir .

      Example output:

      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.

    6. Create the release and promote it to the Unstable channel:

      replicated release create --yaml-dir . --promote Unstable

      Example output:

        • Reading manifests from . ✓
        • Creating Release ✓
          • SEQUENCE: 1
        • Promoting ✓
          • Channel 2kvjwEj4uBaCMoTigW5xty1iiw6 successfully set to release 1

  5. Create a customer so that you can install the release on your VM with Embedded Cluster:

    1. In the Vendor Portal, select the Gitea application and then click Customers > Create customer.

      The Create a new customer page opens:

      Customer a new customer page in the Vendor Portal

      View a larger version of this image

    2. For Customer name, enter a name for the customer. For example, Example Customer.

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

    4. For License type, select Development.

    5. For License options, enable the following entitlements:

      • KOTS Install Enabled
      • Embedded Cluster Enabled

    6. Click Save Changes.

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

      View a larger image

    2. On the command line, SSH onto your VM and run the commands in the Embedded cluster install instructions dialog to download the latest release, extract the installation assets, and install.

      embedded cluster install instructions dialog

      View a larger version of this image

    3. When prompted, enter a password for accessing the Admin Console.

      The installation command takes a few minutes to complete.

      Example output:

      ? Enter an Admin Console password: ********
      ? Confirm password: ********
      ✔  Host files materialized!
      ✔  Running host preflights
      ✔  Node installation finished!
      ✔  Storage is ready!
      ✔  Embedded Cluster Operator is ready!
      ✔  Admin Console is ready!
      ✔  Additional components are ready!
      Visit the Admin Console to configure and install gitea-kite: http://104.155.145.60:30000

      At this point, the cluster is provisioned and the Admin Console is deployed, but the application is not yet installed.

    4. Go to the URL provided in the output to access to the Admin Console.

    5. On the Admin Console landing page, click Start.

    6. On the Secure the Admin Console screen, review the instructions and click Continue. In your browser, follow the instructions that were provided on the Secure the Admin Console screen to bypass the warning.

    7. On the Certificate type screen, either select Self-signed to continue using the self-signed Admin Console certificate or click Upload your own to upload your own private key and certificacte.

      By default, a self-signed TLS certificate is used to secure communication between your browser and the Admin Console. You will see a warning in your browser every time you access the Admin Console unless you upload your own certificate.

    8. On the login page, enter the Admin Console password that you created during installation and click Log in.

    9. On the Configure the cluster screen, 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.

    10. On the Admin Console dashboard, next to the version, click Deploy and then Yes, Deploy.

      The application status changes from Missing to Unavailable while the gitea Deployment is being created.

    11. After a few minutes when the application status is Ready, click Open App to view the Gitea application in a browser.

      For example:

      Admin console dashboard showing ready status

      View a larger version of this image

      Gitea app landing page

      View a larger version of this image

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

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

  9. Create a new release that adds preflight checks to the application:

    1. In your local filesystem, go to the gitea directory.

    2. Create a gitea-preflights.yaml file in the templates directory:

      touch templates/gitea-preflights.yaml

    3. In the gitea-preflights.yaml file, add the following YAML to create a Kubernetes Secret with a simple preflight spec:

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

    4. In the Chart.yaml file, increment the version to 1.0.7:

      # Chart.yaml
      version: 1.0.7

    5. Update dependencies and package the chart to a .tgz chart archive:

      helm package -u .

    6. Move the chart archive to the manifests directory:

      mv gitea-1.0.7.tgz manifests

    7. In the manifests directory, open the KOTS HelmChart custom resource (gitea.yaml) and update the chartVersion:

      # gitea.yaml KOTS HelmChart
      chartVersion: 1.0.7

    8. Remove the chart archive for version 1.0.6 of the Gitea chart from the manifests directory:

      rm gitea-1.0.6.tgz

    9. From the manifests directory, create and promote a new release, setting the version label of the release to 0.0.2:

      replicated release create --yaml-dir . --promote Unstable --version 0.0.2

      Example output:

        • Reading manifests from . ✓
        • Creating Release ✓
          • SEQUENCE: 2
        • Promoting ✓
          • Channel 2kvjwEj4uBaCMoTigW5xty1iiw6 successfully set to release 2

  10. On your VM, update the application instance to the new version that you just promoted:

    1. In the Admin Console, go to the Version history tab.

      The new version is displayed automatically.

    2. Click Deploy next to the new version.

      The Embedded Cluster upgrade wizard opens.

    3. In the Embedded Cluster upgrade wizard, on the Preflight checks screen, note that the "Slack Accessible" preflight check that you added was successful. Click Next: Confirm and deploy.

      preflight page of the embedded cluster upgrade wizard

      View a larger version of this image

      note

      The Config screen in the upgrade wizard is bypassed because this release does not contain a KOTS Config custom resource. The KOTS Config custom resource is used to set up the Config screen in the KOTS Admin Console.

    4. On the Confirm and Deploy page, click Deploy.

  11. Reset and reboot the VM to remove the installation:

    sudo ./APP_SLUG reset

    Where APP_SLUG is the unique slug for the application.

    note

    You can find the application slug by running replicated app ls on your local machine.

Next Steps​

Congratulations! As part of this quick start, you:

  • Added the Replicated SDK to a Helm chart
  • Created a release with the Helm chart
  • Installed the release on a VM with Embedded Cluster
  • Viewed telemetry for the installed instance in the Vendor Portal
  • Created a new release to add preflight checks to the application
  • Updated the application from the Admin Console

Now that you are familiar with the workflow of creating, installing, and updating releases, you can begin onboarding your own application to the Replicated Platform.

To get started, see Replicated Onboarding.

For more information about the Replicated Platform features mentioned in this quick start, see:

For additional tutorials related to this quick start, see: