Skip to main content

Replicated Quick Start

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 demonstrates 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 through the Replicated Admin Console UI.

Set Up Your Environment​

To complete this quick start, you need access to a VM that meets the requirements for Embedded Cluster:

  • Option 1: Use Compatibility Matrix. To use Replicated Compatibility Matrix to create a VM, do the following before proceeding:

    • Request Compatibility Matrix credits. You can request credits by creating a Vendor Portal account and then going to Compatibility Matrix > Request more credits in the Vendor Portal. For more information about creating an account, see Create a Vendor Account. For more information about Compatibility Matrix credits, see Billing and Credits.

    • Ensure that you have an SSH key in your GitHub account. Then, add your GitHub username to your Vendor Portal Account Settings. This will provide SSH access to VMs that you create with Compatibility Matrix. For more information, see Set Up SSH Access in Create VMs.

    After you complete the prerequisites above, continue to the Quick Start. You will create the VM with Compatibility Matrix as part of the tutorial.

  • Option 2: Bring your own VM. Your VM must meet these requirements:

    • Firewalls must allow HTTP and HTTPS traffic.

    • 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 data directory used by Embedded Cluster must have 40Gi or more of total space and be less than 80% full. By default, the data directory is /var/lib/embedded-cluster. The directory can be changed by passing the --data-dir flag with the Embedded Cluster install command. For more information, see install.

      Note that in addition to the primary data directory, Embedded Cluster creates directories and files in the following locations:

      • /etc/cni
      • /etc/k0s
      • /opt/cni
      • /opt/containerd
      • /run/calico
      • /run/containerd
      • /run/k0s
      • /sys/fs/cgroup/kubepods
      • /sys/fs/cgroup/system.slice/containerd.service
      • /sys/fs/cgroup/system.slice/k0scontroller.service
      • /usr/libexec/k0s
      • /var/lib/calico
      • /var/lib/cni
      • /var/lib/containers
      • /var/lib/kubelet
      • /var/log/calico
      • /var/log/containers
      • /var/log/embedded-cluster
      • /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.

For more information about setting up your environment to work with the Replicated Platform, see Set Up Your Environment.

Quick Start​

  1. If you have not done so already, create an account in the Vendor Portal. You can either create a new team or join an existing team. For more information, see Create a Vendor Account.

  2. Create an application using the Replicated CLI:

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

      • MacOS

        brew install replicatedhq/replicated/cli

      • Linux / Windows Subsystem for Linux (WSL)

        version=$(curl -s https://api.github.com/repos/replicatedhq/replicated/releases/latest \
          | grep -m1 -Po '"tag_name":\s*"v\K[^"]+')
        curl -Ls \
          "https://github.com/replicatedhq/replicated/releases/download/v${version}/replicated_${version}_linux_amd64.tar.gz" \
          -o replicated.tar.gz
        tar xf replicated.tar.gz replicated && rm replicated.tar.gz
        mv replicated /usr/local/bin/replicated

      For more information and additional installation options, see Install the Replicated CLI.

    2. Authorize the Replicated CLI:

      replicated login

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

    3. Create an application named SlackerNews:

      replicated app create SlackerNews

    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.

      Setting the REPLICATED_APP environment variable 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 SlackerNews Helm chart:

    1. Run the following command to download version 1.0.0 of the sample SlackerNews Helm chart to a new quick-start directory:

      curl -O --create-dirs --output-dir quick-start https://docs.replicated.com/slackernews-1.0.0.tar.gz

    2. Untar the chart:

      tar -xzf quick-start/slackernews-1.0.0.tar.gz -C quick-start/ && rm quick-start/slackernews-1.0.0.tar.gz

    3. Change to the slackernews chart directory:

      cd quick-start/chart/slackernews

    4. List the files in the slackernews directory to view the contents of the Helm chart:

      ls
      Chart.lock  Chart.yaml  NOTES.txt   README.md   templates   values.yaml

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

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

      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.

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

      helm package --dependency-update .

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

      The output of this command is a file named slackernews-1.0.0.tgz.

  4. Add the slackernews-1.0.0.tgz chart archive to a release in the Replicated Platform:

    1. Change to the quick-start directory:

      cd ../..

    2. In the quick-start directory, create a directory named manifests:

      mkdir manifests

      You will add the files required to support installation with Embedded Cluster to this subdirectory.

    3. Move the slackernews-1.0.0.tgz chart archive that you created to manifests:

      mv chart/slackernews/slackernews-1.0.0.tgz manifests

    4. In manifests, create the following YAML files:

      cd manifests
      touch slackernews.yaml replicated-app.yaml k8s-app.yaml embedded-cluster.yaml config.yaml

      These manifests will be used by Embedded Cluster to install SlackerNews.

    5. In each of the files that you created, paste the corresponding YAML provided in the tabs below:

      Description

      The HelmChart custom resource provides instructions to the installer 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. This HelmChart resource includes several values and conditional optionalValues that are supplied to helm template during deployment.

      YAML
      apiVersion: kots.io/v1beta2
      kind: HelmChart
      metadata:
        name: slackernews
      spec:
        # chart identifies a matching chart from a .tgz
        chart:
          name: slackernews
          chartVersion: 1.0.0
        namespace: slackernews

        # values are used in the customer environment, as a pre-render step
        # these values will be supplied to helm template
        values:
          postgres:
            enabled: true
            deploy_postgres: repl{{ ConfigOption "deploy_postgres" | ParseBool }}
          slack:
            botToken: repl{{ ConfigOption "slack_bot_token" | quote }}
            userToken: repl{{ ConfigOption "slack_user_token" | quote }}
            clientId: repl{{ ConfigOption "slack_clientid" | quote }}
            clientSecret: repl{{ ConfigOption "slack_clientsecret" | quote }}
          slackernews:
            domain: repl{{ ConfigOption "slackernews_domain" }}
            adminUserEmails: repl{{ ConfigOption "slackernews_admin_user_emails" | quote }}
          admin-console:
            enabled: false
          replicated:
            isEmbeddedCluster: repl{{ eq Distribution "embedded-cluster"}}
            isKOTSManaged: true
            imagePullSecrets:
              - name: '{{repl ImagePullSecretName }}'
          service:
            tls:
              enabled: true
          nginx:
            enabled: true
          images:
            pullSecrets:
              - name: '{{repl ImagePullSecretName }}'

        optionalValues:
          # load images from the local registry in an air-gapped environment
          - when: '{{repl HasLocalRegistry }}'
            recursiveMerge: true
            values:
              replicated:
                isAirgap: true
                image:
                  registry: '{{repl LocalRegistryHost }}'
                  repository: '{{repl LocalRegistryNamespace }}/replicated-sdk-image'
              slackernews:
                registry: '{{repl LocalRegistryHost}}'
                repository: '{{LocalRegistryNamespace}}/slackernews-web'
              nginx:
                registry: '{{repl LocalRegistryHost}}'
                repository: '{{LocalRegistryNamespace}}/nginx'
              postgres:
                registry: '{{repl LocalRegistryHost}}'
                repository: '{{LocalRegistryNamespace}}/postgres'

          # the user wants us to deploy a local Postgres instance
          - when: '{{repl ConfigOptionEquals "deploy_postgres" "1"}}'
            recursiveMerge: true
            values:
              postgres:
                password: '{{repl ConfigOption "postgres_password" }}'

          # the user provided their own Postgres instance
          - when: '{{repl ConfigOptionEquals "deploy_postgres" "0"}}'
            recursiveMerge: true
            values:
              postgres:
                uri: '{{repl ConfigOption "postgres_external_uri" }}'

          # use the user-provided certificates 
          - when: '{{repl ConfigOptionEquals "certificate_source" "upload_existing"}}'
            recursiveMerge: true
            values:
              service:
                tls:
                  enabled: true
                  cert: repl{{ ConfigOptionData "tls_cert" | nindent 14 }}
                  key: repl{{ ConfigOptionData "tls_key" | nindent 14 }}
                  ca: repl{{ ConfigOptionData "tls_ca" | nindent 14 }}
                
          # or generate our own
          - when: '{{repl ConfigOptionEquals "certificate_source" "generate_internal"}}'
            recursiveMerge: true
            values:
              service:
                tls:
                  enabled: true
                  ca: |-
                    {{repl $ca := genCA (LicenseFieldValue "customerName") 365 }}
                    {{repl $ca.Cert | Base64Encode}}
                  cert: |-
                    {{repl $cert := genSignedCert (ConfigOption "slackernews_domain") nil (list (ConfigOption "slackernews_domain")) 365 $ca }}
                    {{repl $cert.Cert | nindent 14 }}
                  key: |-
                    {{repl $cert.Key | nindent 14 }}
                   
          # handle different service types
          - when: '{{repl ConfigOptionEquals "service_type" "cluster_ip"}}'
            recursiveMerge: true
            values:
              nginx:
                service:
                  type: ClusterIP

          - when: '{{repl ConfigOptionEquals "service_type" "load_balancer"}}'
            recursiveMerge: true
            values:
              nginx:
                service:
                  type: LoadBalancer

          - when: '{{repl ConfigOptionEquals "service_type" "node_port"}}'
            recursiveMerge: true
            values:
              nginx:
                service:
                  type: NodePort
                  nodePort:
                    port: repl{{ ConfigOption "node_port_port" }}



        # builder values provide a way to render the chart with all images
        # and manifests. this is used in Replicated to create airgap packages
        builder:
          postgres:
            password: this-is-not-used-but-needed-for-builder
            deploy_postgres: true
            enabled: true

    6. Lint the YAML files in the manifests directory:

      replicated release lint --yaml-dir .

      Example output:

      RULE                                TYPE   FILENAME             LINE   MESSAGE
      may-contain-secrets                 info   slackernews.yaml     142    It looks like there might be secrets in this file
      preflight-spec                      warn                               Missing preflight spec
      troubleshoot-spec                   warn                               Missing troubleshoot spec
      nonexistent-status-informer-object  warn   replicated-app.yaml  14     Status informer points to a nonexistent kubernetes object. If this is a Helm resource, this warning can be ignored.
      nonexistent-status-informer-object  warn   replicated-app.yaml  15     Status informer points to a nonexistent kubernetes object. If this is a Helm resource, this warning can be ignored.
      nonexistent-status-informer-object  warn   replicated-app.yaml  16     Status informer points to a nonexistent kubernetes object. If this is a Helm resource, this warning can be ignored.
      note

      You can ignore info or warn messages for the purpose of this quick start.

    7. From the manifests directory, create a 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 test customer so that you can install the release in your VM with Embedded Cluster:

    1. Log in to the Vendor Portal.

    2. Under the application drop down, select the SlackerNews application that you created.

      App drop down

      View a larger version of this image

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

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

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

    6. For Customer type, select Development.

    7. For Install types, enable Embedded Cluster (current generation product) and disable the other install type options.

    8. Click Save Changes.

  6. If you brought your own VM, SSH onto your VM. Otherwise, follow these steps to create and SSH onto a VM with Compatibility Matrix:

    1. Create an Ubuntu VM that expires after two hours:

      replicated vm create --distribution ubuntu --version 24.04 --instance-type r1.small --disk 50 --ttl 2h

      Example output:

      ID        NAME             DISTRIBUTION  VERSION  STATUS  NETWORK   CREATED               EXPIRES   COST
      97940819  practical_black  ubuntu        24.04    queued  c726ffff  2025-08-20 14:32 MDT  -         $0.69

    2. After a few minutes, check the status of the VM to see when it is running:

      replicated vm ls

      Example output:

      ID        NAME             DISTRIBUTION  VERSION  STATUS   NETWORK   CREATED               EXPIRES                COST
      97940819  practical_black  ubuntu        24.04    running  c726ffff  2025-08-20 14:32 MDT  2025-08-20 16:33 MDT   $0.69

    3. Run the following command to use the Compatibility Matrix Forwarder to SSH onto the VM:

      ssh VM_ID@replicatedvm.com

      Where VM_ID is the ID from the output of the replicated vm ls command.

      note

      If you are prompted to add the fingerprint for replicatedvm.com, type yes and press Enter.

    4. When prompted, provide the passphrase for the SSH key in your linked GitHub account. Compatibility Matrix uses GitHub SSH to provide access to the VM.

  7. Install the application with Embedded Cluster:

    1. In the Vendor Portal, on the page for the customer that you created, click Embedded Cluster install instructions.

      Customer install instructions

      View a larger version of this image

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

      embedded cluster install instructions dialog

      View a larger version of this image

    3. When prompted by the install command, set a password for accessing the Admin Console. You will use this password to log in to the Admin Console in a later step.

      The installation command takes a few minutes to complete.

      Example output:

      ? Set the Admin Console password (minimum 6 characters): ********
      ? Confirm the Admin Console password: ********

      ✔  Initialization complete
      ✔  Host preflights passed
      ✔  Node is ready
      ✔  Storage is ready
      ✔  Runtime Operator is ready
      ✔  Admin Console is ready
      ✔  Additional components are ready

      -----------------------------------------------------------------
      Visit the Admin Console to configure and install slackernews-gnu:

      http://10.0.0.11:30000
      -----------------------------------------------------------------

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

    4. Do one of the following to access the Admin Console:

      • If you brought your own VM, go to the URL provided in the output of the install command.
        note

        The IP address in the provided URL might be the private IP address of your VM. You might need to edit the URL to use the public IP address.

      • If you created the VM with Compatibility Matrix:

        1. In the Vendor Portal, go to Compatibility Matrix.

        2. Open the dot menu for your VM and click Edit VM.

          Edit VM in the dot menu

          View a larger version of this image

        3. Under Ingress & Ports, for Add DNS record, click Add to create a DNS record using the default settings. This will provide a hostname where you can access the Admin Console.

        4. Add another DNS record with a Target Port of 443. This will provide a hostname where you can access SlackerNews after it's installed.

          The following shows an example of both of these DNS records added to a VM:

          DNS record for a VM View a larger version of this image

        5. (Optional) Copy the URL for the DNS record with a target port of 443 and save it somewhere on your local machine. You will be asked to provide this hostname in the Admin Console as part of the installation process for SlackerNews.

        6. In a browser, navigate to the URL for the DNS record with a target port of 30000.

          The Admin Console opens.

    5. If you are directed to the Admin Console landing page:

      1. Click Start.
      2. 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.
      3. 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.
      note

      If you created the VM with Compatibility Matrix, you might not see these pages. Instead, your browser might automatically redirect to the Admin Console login screen.

    6. On the login screen, enter the Admin Console password that you set and click Log in.

      Admin console login screen

      View a larger version of this image

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

      Admin console login screen

      View a larger version of this image

    8. On the Configure SlackerNews screen, complete the following fields:

      • For Hostname:

        • If you created the VM with Compatibility Matrix, enter the URL that you copied for the DNS record with a target port of 443. For example, pensive-keldysh.ingress.replicatedcluster.com.

        • If you are using your own VM, provide the public IP address for your VM. You can copy the IP address from your browser's address bar where you are currently accessing the Admin Console. Alternatively, if you have a hostname for your VM's IP address, you can provide that instead.

      • For Application Access > Service Type, select NodePort. Leave the Node Port field blank to use the default port of 443.

      • For Postgresql, ensure that Deploy Postgresql Database is enabled to deploy the built-in Postgresql database.

      Leave the other fields on the Configure SlackerNews screen empty. They are not applicable for this quick start.

      Configure slackernews screen

      View a larger version of this image

    9. Click Continue.

      The Admin Console dashboard opens. The application status changes from Missing to Unavailable while the application is being deployed. You can click Details next to the status for more information about the status of specific application resources.

      After a few minutes, the status changes to Ready when the application is deployed:

      Slackernews with ready status on admin console dashboard

      View a larger version of this image

    10. After a few minutes when the application status is Ready, click Open SlackerNews to view SlackerNews in a browser.

      Slackernews landing page

      View a larger version of this image

  8. View telemetry for the instance that you just deployed:

    1. Return to the Vendor Portal, select the SlackerNews application, and go to Customers. Under the name of the customer, confirm that you can see an active instance.

      Slackernews instance on customers page

      View a larger version of this image

      This instance telemetry is automatically collected and sent back to the Vendor Portal by Embedded Cluster and the Replicated SDK. For more information, see About Instance and Event Data.

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

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

    1. In your local filesystem, go to the quick-start/chart/slackernews directory.

    2. Create a preflights.yaml file in the templates directory for the chart:

      touch templates/preflights.yaml

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

      apiVersion: v1
      kind: Secret
      metadata:
        name: slackernews-preflight
        labels:
          troubleshoot.sh/kind: preflight
      stringData:
        preflight.yaml: |-
          apiVersion: troubleshoot.sh/v1beta2
          kind: Preflight
          metadata:
            name: slackernews-preflight
          spec:
            collectors:
              - clusterInfo: {}
              - clusterResources: {}
              - http:
                  collectorName: slack
                  get:
                    url: https://api.slack.com/methods/api.test
                    timeout: 20s
            analyzers:
              # verify that slack is accessible
              - 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.1:

      # Chart.yaml
      version: 1.0.1

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

      helm package --dependency-update .

    6. Move the slackernews-1.0.1.tgz chart archive to the manifests directory:

      mv slackernews-1.0.1.tgz ../../manifests

    7. Change to the manifests directory.

    8. In the manifests directory, open the HelmChart custom resource (slackernews.yaml) and update the chartVersion to match the new archive:

      # slackernews.yaml HelmChart
      chartVersion: 1.0.1

    9. Remove the unused chart archive for version 1.0.0 from the manifests directory:

      rm slackernews-1.0.0.tgz

    10. From the manifests directory, lint the release manifests:

      replicated release lint --yaml-dir .
      note

      If you see a helm-archive-missing error, confirm that you have only one chart archive in manifests for version 1.0.1, and that the chartVersion in the HelmChart resource is also set to 1.0.1. If you notice that any of the errors are from files in your .history/ directory, run rm -rf .history and then lint the files again.

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

      Admin console version history tab

      View a larger version of this image

    2. Click Deploy next to the new version.

      The Embedded Cluster upgrade wizard opens. Follow the steps until you see the Preflight checks screen.

    3. On the Preflight checks screen, note that the "Slack Accessible" preflight check that you added was successful. Click Next: Confirm and deploy.

      preflights screen in the upgrade wizard

      View a larger version of this image

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

  11. Clean up the installation:

    • If you created the VM with Compatibility Matrix, delete the VM:

      replicated vm rm VM_ID

      Where VM_ID is the ID of the VM. You can run replicated vm ls to get the ID.

    • If you brought your own VM, use Embedded Cluster to 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 to the new version using Embedded Cluster

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 Onboard to the Replicated Platform.

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