Skip to main content

Set Up Your Environment

This topic describes how to set up your environment to get started with the Replicated Platform. It includes information about installing the required tools on your local workstation as well as creating development environments for testing installation and upgrade scenarios for your application.

Set Up Your Local Workstation​

This section lists the tools that you need to install on your local workstation to manage applications, releases, customers, and more with the Replicated Platform.

Install kubectl​

kubectl is the Kubernetes command line tool. You will use kubectl to communicate with the clusters that you create with the Replicated Compatibility Matrix, and when testing and troubleshooting installations in existing clusters. For more information about kubectl, see Command line tool (kubectl) in the Kubernetes documentation.

Mac​

To install kubectl on Mac, do one of the following:

  • Install with Homebrew:

    brew install kubectl

  • Install using curl:

    curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"
    chmod +x ./kubectl
    sudo mv ./kubectl /usr/local/bin/kubectl

Linux​

To install kubectl on Linux, do one of the following:

  • Install using curl:

    curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
    chmod +x ./kubectl
    sudo mv ./kubectl /usr/local/bin/kubectl

  • Install with a package manager (Ubuntu/Debain):

    sudo apt-get update
    sudo apt-get install -y kubectl

  • Install with a package manager (CentOS/RHEL/Fedora):

    sudo yum install -y kubectl

Install Helm​

The Helm CLI is the tool for interacting with Helm and managing charts. Replicated recommends that all applications distributed with the Replicated Platform are packaged with Helm. Helm charts distributed with Replicated can also be installed in customer environments using Helm. Installing the Helm CLI on your workstation is important for being able to test and troubleshoot installations with Helm.

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

Mac​

To install the Helm CLI on Mac, do one of the following:

  • Install with Homebrew:

    brew install helm

  • Install using curl:

    curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Linux​

To install the Helm CLI on Linux:

curl -LO https://get.helm.sh/helm-v3.12.0-linux-amd64.tar.gz
tar -zxvf helm-v3.12.0-linux-amd64.tar.gz
sudo mv linux-amd64/helm /usr/local/bin/helm

Install and Authorize the Replicated CLI​

The Replicated CLI is the primary interface for the Replicated Platform. With the Replicated CLI, you can create and manage applications, releases, channels, customers, and more. You also use the Replicated CLI to create clusters with the Compatibility Matrix.

After installing, you can authorize the Replicated CLI by logging in to your Replicated vendor account through the replicated login command.

For more information about installing and authorizing the Replicated CLI, see Install the Replicated CLI.

Mac​

To install and run the latest Replicated CLI on MacOS:

  1. Run one of the following commands:

    • With Brew:

      brew install replicatedhq/replicated/cli

    • Without Brew:

      curl -Ls $(curl -s https://api.github.com/repos/replicatedhq/replicated/releases/latest \
        | grep "browser_download_url.*darwin_all.tar.gz" \
        | cut -d : -f 2,3 \
        | tr -d \") -o replicated.tar.gz
      tar xf replicated.tar.gz replicated && rm replicated.tar.gz
      mv replicated /usr/local/bin/replicated
    note

    If you do not have root access to the /usr/local/bin directory, you can install with sudo by running sudo mv replicated /usr/local/bin/replicated instead of mv replicated /usr/local/bin/replicated.

  2. Verify that the installation was successful:

    replicated --help

  3. Authorize the Replicated CLI:

    replicated login

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

    Authorize replicated cli web page

    View a larger version of this image

    note

    The replicated login command creates a token after you log in to your vendor account in a browser and saves it to a config file. Alteratively, if you do not have access to a browser, you can set the REPLICATED_API_TOKEN environment variable to authenticate. For more information, see (Optional) Set Environment Variables below.

  4. (Optional) When you are done using the Replicated CLI, remove any stored credentials created by the replicated login command:

    replicated logout

Linux / Windows Subsystem for Linux (WSL2)​

To install and run the latest Replicated CLI on Linux or Windows Subsystem for Linux (WSL2):

  1. For Windows users, first install Linux on Windows using WSL2. See How to install Linux on Windows with WSL.

  2. Run the following command:

    curl -Ls $(curl -s https://api.github.com/repos/replicatedhq/replicated/releases/latest \
      | grep "browser_download_url.*linux_amd64.tar.gz" \
      | cut -d : -f 2,3 \
      | tr -d \") -o replicated.tar.gz
    tar xf replicated.tar.gz replicated && rm replicated.tar.gz
    mv replicated /usr/local/bin/replicated
    note

    If you do not have root access to the /usr/local/bin directory, you can install with sudo by running sudo mv replicated /usr/local/bin/replicated instead of mv replicated /usr/local/bin/replicated.

  3. Verify that the installation was successful:

    replicated --help

  4. Authorize the Replicated CLI:

    replicated login

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

    Authorize replicated cli web page

    View a larger version of this image

    note

    The replicated login command creates a token after you log in to your vendor account in a browser and saves it to a config file. Alteratively, if you do not have access to a browser, you can set the REPLICATED_API_TOKEN environment variable to authenticate. For more information, see (Optional) Set Environment Variables below.

  5. (Optional) When you are done using the Replicated CLI, remove any stored credentials created by the replicated login command:

    replicated logout

Docker / Windows​

note

For Windows users, Replicated recommends using Windows Subsystem for Linux (WSL2) and installing the Replicated using the Linux installations above. See Linux / Windows Subsystem for Linux (WSL2).

Installing in Docker environments requires that you set the REPLICATED_API_TOKEN environment variable to authorize the Replicated CLI with an API token. For more information, see (Optional) Set Environment Variables below.

To install and run the latest Replicated CLI in Docker environments:

  1. Generate a service account or user API token in the vendor portal. To create new releases, the token must have Read/Write access. See Generating API Tokens.

  2. Get the latest Replicated CLI installation files from the replicatedhq/replicated repository on GitHub.

    Download and install the files. For simplicity, the usage in the next step is represented assuming that the CLI is downloaded and installed to the desktop.

  3. Authorize the Replicated CLI:

    • Through a Docker container:

      docker run \
        -e REPLICATED_API_TOKEN=$TOKEN \
        replicated/vendor-cli --help

      Replace TOKEN with your API token.

    • On Windows:

      docker.exe run \
        -e REPLICATED_API_TOKEN=%TOKEN% \
        replicated/vendor-cli --help

      Replace TOKEN with your API token.

For more information about the docker run command, see docker run in the Docker documentation.

Install the Preflight and Support Bundle Plugins​

The preflight and support-bundle plugins available through the open source Troubleshoot project provide important troubleshooting tools for your customers, allowing them to run preflight checks and collect support bundles. For more information, see About Preflight Checks and Support Bundles.

These instructions show you how to install the Troubleshoot plugins using Krew. For more information about installing the preflight and support-bundle plugins, including other installation options, see Getting Started in the Troubleshoot documentation.

To install the preflight and support-bundle plugins:

  1. Install Krew:

    • Mac: 
      brew install krew
    • Other operating systems: 
      (
        set -x; cd "$(mktemp -d)" &&
        OS="$(uname | tr '[:upper:]' '[:lower:]')" &&
        ARCH="$(uname -m | sed -e 's/x86_64/amd64/' -e 's/\(arm\)\(64\)\?.*/\1\2/' -e 's/aarch64$/arm64/')" &&
        KREW="krew-${OS}_${ARCH}" &&
        curl -fsSLO "https://github.com/kubernetes-sigs/krew/releases/latest/download/${KREW}.tar.gz" &&
        tar zxvf "${KREW}.tar.gz" &&
        ./"${KREW}" install krew
      )

  2. After installing, add the krew binary directory to your PATH:

    echo 'export PATH="${KREW_ROOT:-$HOME/.krew}/bin:$PATH"' >> ~/.bashrc
    source ~/.bashrc

  3. Run the following commands:

    kubectl krew install preflight
    kubectl krew install support-bundle

Install sbctl​

sbctl is a command-line tool that you can use to examine Kubernetes resources in support bundles. With sbctl, you can interact with the support bundle in a shell using kubectl commands to view and inspect resources.

For more information, see the sbctl repository in GitHub.

To install sbctl, run one of the following commands:

  • macOS Intel systems:

    curl -LO https://github.com/replicatedhq/sbctl/releases/latest/download/sbctl_darwin_amd64.tar.gz
    tar -xzf sbctl_darwin_amd64.tar.gz -C /tmp sbctl
    rm -f sbctl_darwin_amd64.tar.gz
    sudo mv /tmp/sbctl /usr/local/bin/

  • macOS Apple Silicon:

    curl -LO https://github.com/replicatedhq/sbctl/releases/latest/download/sbctl_darwin_arm64.tar.gz
    tar -xzf sbctl_darwin_arm64.tar.gz -C /tmp sbctl
    rm -f sbctl_darwin_arm64.tar.gz
    sudo mv /tmp/sbctl /usr/local/bin/

  • Linux x86_64:

    curl -LO https://github.com/replicatedhq/sbctl/releases/latest/download/sbctl_linux_amd64.tar.gz
    tar -xzf sbctl_linux_amd64.tar.gz -C /tmp sbctl
    rm -f sbctl_linux_amd64.tar.gz
    sudo mv /tmp/sbctl /usr/local/bin/

  • Linux ARM64:

    curl -LO https://github.com/replicatedhq/sbctl/releases/latest/download/sbctl_linux_arm64.tar.gz
    tar -xzf sbctl_linux_arm64.tar.gz -C /tmp sbctl
    rm -f sbctl_linux_arm64.tar.gz
    sudo mv /tmp/sbctl /usr/local/bin/

Replicated recommends that you install the following tools for parsing and manipulating JSON and YAML data:

  • jq for JSON processing
  • yq for YAML manipulation

These tools are useful when working with Kubernetes and Replicated configurations to reduce complex data manipulation tasks from multi-step processes into single commands, simplifying your development workflow.

  • To install jq, run one of the following commands:

    • macOS: 
      brew install jq
    • Ubuntu/Debian: 
      sudo apt-get install jq
    • CentOS/RHEL/Fedora" 
      sudo yum install jq
    • Direct download: 
      curl -LO https://github.com/stedolan/jq/releases/latest/download/jq-linux64
      chmod +x jq-linux64
      sudo mv jq-linux64 /usr/local/bin/jq

  • To install yq, run one of the following commands:

    • macOS: 
      brew install yq
    • Linux: 
      curl -LO https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
      chmod +x yq_linux_amd64
      sudo mv yq_linux_amd64 /usr/local/bin/yq
    • Go install: 
      go install github.com/mikefarah/yq/v4@latest

Set Up Development Environments for Testing​

Testing your releases is an important part of the commercial software distribution lifecycle. Replicated recommends that you have access to a virtual machine (VM) and a cluster where you can install your application releases for testing.

About Creating a VM​

You need access to a VM to test installations and updates with the Replicated Embedded Cluster installer. For more information about Embedded Cluster, see Embedded Cluster Overview.

Your VM must meet the following requirements to install with 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 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 Embedded Cluster Install Command Options.

    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.

About Creating a Cluster​

To test installations with Helm, you need kubectl access to a cluster.

You can use any cloud provider or tool that you prefer to create a cluster, such as Replicated Compatibility Matrix, Google Kubernetes Engine (GKE), or minikube.

For information about how to create a cluster with Compatibility Matrix, see Prerequisites and Create Clusters in Use Compatibility Matrix.