This morning I was helping someone evaluation Replicated and they mentioned they’d upgrade their laptop since our last session. This meant they’d lost all of the tools we’d set up for interacting with the Replicated Platform. I dropped them some very terse instructions in Slack, but realized I share this info in Slack or Zoom chat all the time. Rather than ahve them continue to disappear into chat histories, I thought I’d document the process here.
Working with the Replicated Platform requires a specific toolkit that builds on the foundational tools you use with Kubernetes. The foundation starts with kubectl and helm, then expands to include five specialized Replicated tools that handle everything from CLI operations to troubleshooting workflows.
Foundation Tools
Odds are, if you’re here, you already have the Kubernetes essentials. But just in case, here’s how you get kubectl and helm installed.
If you’re on a Mac, Homebrew makes this all pretty straightforward:
brew install kubectl
brew install helm
If you prefer direct downloads, you can fetch kubectl using curl from the official Kubernetes release endpoint:
# macOS
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 users have similar options, whether through package managers or direct downloads:
# 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
# Or using package manager (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y kubectl
# Or using package manager (CentOS/RHEL/Fedora)
sudo yum install -y kubectl
Helm follows the same pattern, with Homebrew installation on macOS:
brew install helm
Or the official installation script that works across platforms:
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
For manual installation 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
The Replicated Toolkit
The Replicated Platform ecosystem centers around four essential tools (and one helpful supporting tool) that work together to create a complete development and troubleshooting environment.
The Replicated CLI serves as your primary interface to the platform. On macOS, it’s available through a dedicated Homebrew tap:
brew install replicatedhq/replicated/cli
Linux users can grab the latest release directly from GitHub:
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 \" \
| wget -O replicated.tar.gz -qi -
tar xf replicated.tar.gz replicated && rm replicated.tar.gz
sudo mv replicated /usr/local/bin/
For Windows developers, I strongly recommend using WSL2 and following the Linux installation path. None of the Replicated tools are built for Windows, so it’s either WSL2 or Docker. For WSL2 installation instructions, visit: Install WSL | Microsoft Learn
Krew makes it easy to install plugins for kubectl. It’s by far the easiest way to install two critical plugins: preflights and support-bundle.
Like our other tools, macOS users can install it via Homebrew:
brew install krew
The manual installation script works reliably across platforms and gives you more control over the process:
(
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
)
After installation, remember to add the krew binary directory to your PATH—this step often gets forgotten but is essential for the subsequent plugin installations:
echo 'export PATH="${KREW_ROOT:-$HOME/.krew}/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
The Preflight and Support Bundle plugins work as a pair to keep your customer on track and help you support them. You’ll use them a ton during development. Preflight runs checks before installation to catch pitfalls before they happen, while Support Bundle collects what you need to help your customer when things go wrong. Both install through krew:
kubectl krew install preflight
kubectl krew install support-bundle
Finally, sbctl provides a command-line tools that makes a support bundles look like a running cluster. The installation varies by architecture—Intel Macs, Apple Silicon Macs, x86_64 Linux, and ARM64 Linux each have their own binary packages.
For 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/
For 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/
For 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/
For 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/
Essential Data Processing Tools
While working with Kubernetes and Replicated configurations, you’ll frequently need to parse and manipulate JSON and YAML data. Two tools become indispensable for this work: jq for JSON processing and yq for YAML manipulation.
# macOS
brew install jq
# Ubuntu/Debian
sudo apt-get install jq
# CentOS/RHEL/Fedora
sudo yum install jq
# Or download directly
curl -LO https://github.com/stedolan/jq/releases/latest/download/jq-linux64
chmod +x jq-linux64
sudo mv jq-linux64 /usr/local/bin/jq
For yq:
# 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
# Or using go install
go install github.com/mikefarah/yq/v4@latest
These tools transform complex data manipulation tasks from multi-step processes into single commands, making your development workflow significantly more efficient.
Organizing Your Development Workspace
A well-structured project layout prevents confusion and makes automation easier. I organize Replicated projects with a clear separation between build artifacts, Helm charts, and Replicated-specific configurations:
.
├── build
├── charts
│ └── hello
│ ├── Chart.lock
│ ├── Chart.yaml
│ ├── charts
│ ├── README.md
│ ├── templates
│ │ ├── _helpers.tpl
│ │ ├── deployment.yaml
│ │ ├── ingress.yaml
│ │ ├── NOTES.txt
│ │ ├── secret.yaml
│ │ ├── service.yaml
│ │ ├── serviceaccount.yaml
│ │ ├── tests
│ │ │ └── test-connection.yaml
│ │ └── troubleshoot
│ │ ├── _shared.tpl
│ │ ├── preflights.yaml
│ │ ├── secrets.yaml
│ │ └── support-bundle.yaml
│ └── values.yaml
├── LICENSE
├── Makefile
├── README.md
└── replicated
├── config.yaml
├── embedded-cluster.yaml
├── replicated-app.yaml
└── hello-chart.yaml
The charts directory contains your Helm charts, each in its own subdirectory with the standard Helm structure. Within each chart, I include a troubleshoot directory under templates to house preflight checks and support bundle configurations alongside the main application templates.
The replicated directory holds platform-specific configuration files: application definitions, embedded cluster configurations, and chart references. The build directory serves as a staging area for packaged charts and manifest files before release.
This structure supports a Makefile-driven workflow that automatically discovers charts, packages them with proper versioning, and handles Replicated release operations. The Makefile includes dynamic targets that adapt to your chart structure, parallel builds for efficiency, and integrated linting to catch issues before release:
PROJECTDIR := .
# Set default parallelism
MAKEFLAGS += -j$(shell nproc)
CHARTDIR := $(PROJECTDIR)/charts
CHARTS := $(shell find $(CHARTDIR) -mindepth 1 -maxdepth 1 -type d -exec basename {} \;)
MANIFESTDIR := $(PROJECTDIR)/replicated
MANIFESTS := $(shell find $(MANIFESTDIR) -name '*.yaml' -o -name '*.yml')
# Cache chart versions
define cache-chart-version
$(eval CHART_$(1)_VERSION := $(shell yq .version $(CHARTDIR)/$(1)/Chart.yaml))
endef
$(foreach chart,$(CHARTS),$(eval $(call cache-chart-version,$(chart))))
VERSION ?= $(CHART_hello_VERSION)
CHANNEL := $(shell git branch --show-current)
ifeq ($(CHANNEL), master)
CHANNEL=Unstable
endif
BUILDDIR := $(PROJECTDIR)/build
RELEASE_FILES :=
# Group all .PHONY targets
.PHONY: charts manifests clean lint release
define make-manifest-target
$(BUILDDIR)/$(notdir $1): $1 | $(BUILDDIR)
cp $1 $(BUILDDIR)/$(notdir $1)
RELEASE_FILES := $(RELEASE_FILES) $(BUILDDIR)/$(notdir $1)
manifests:: $(BUILDDIR)/$(notdir $1)
endef
$(foreach element,$(MANIFESTS),$(eval $(call make-manifest-target,$(element))))
define make-chart-target
$(BUILDDIR)/$1-$(CHART_$1_VERSION).tgz : $(shell find $(CHARTDIR)/$1 -name '*.yaml' -o -name '*.yml' -o -name "*.tpl" -o -name "NOTES.txt" -o -name "values.schema.json") | $(BUILDDIR)
helm package -u $(CHARTDIR)/$1 -d $(BUILDDIR)/
RELEASE_FILES := $(RELEASE_FILES) $(BUILDDIR)/$1-$(CHART_$1_VERSION).tgz
charts:: $(BUILDDIR)/$1-$(CHART_$1_VERSION).tgz
endef
$(foreach element,$(CHARTS),$(eval $(call make-chart-target,$(element))))
$(BUILDDIR):
mkdir -p $(BUILDDIR)
clean:
rm -rf $(BUILDDIR)
lint: $(RELEASE_FILES)
replicated release lint --yaml-dir $(BUILDDIR)
release: $(RELEASE_FILES) lint
replicated release create \
--app ${REPLICATED_APP} \
--version $(VERSION) \
--yaml-dir $(BUILDDIR) \
--ensure-channel \
--promote $(CHANNEL)
Streamlining Your Workflow
The included Makefile demonstrates how to automate the entire build and release process. It dynamically discovers charts in your project, caches version information to avoid repeated file reads, and creates release artifacts in a staging directory. The lint target validates your configuration before release, while the release target handles the complete publish workflow including channel promotion.
This automation becomes invaluable when working with multiple charts or frequent releases. The Makefile handles dependency updates, proper versioning, and ensures consistent release processes across team members.
Setting up this environment takes some initial effort, but it creates a foundation that makes Replicated Platform development significantly more productive. Each tool serves a specific purpose in the workflow, from initial development through troubleshooting production deployments.