The KOTS Existing Cluster Guide is one of our simplest guides.
We’ll get running quickly with a simple Nginx application on an existing cluster in GKE (or another cluster you have handy).
It is broken into four sections:
Creating a Release
When getting started with the KOTS platform, the Vendor Portal will be the place you spend a lot of time.
This guide is designed to help you get familiar with the concepts and ideas that are important to successfully deploy your application with KOTS.
If you get stuck or need help, head to our community.
This guide will deploy a basic application using KOTS, and show you how to deliver an update to that application.
The guide isn’t going to teach Kubernetes, rather it will start with a minimal Kubernetes application that deploys a single replica of nginx.
Create a New Application
To start, log in (or create a new team) on vendor.replicated.com and create a new application.
After signing up and activating your account, you will be prompted to create a new application.
Give it a name like “Starter KOTS application” or “Nginx Example” and click the “Create Application” button.
You should be at the channels page now.
This is a list of your release channels, which are logical stacks for you to stage and promote releases to your customers.
We’ll explore this in more detail later.
For now, click on the “Releases” item on the left menu and then click the “Create a release” button.
Create a Release
You should now see a YAML editor where you can define how your application will work and the integration with KOTS functionality.
Once you are familiar with these concepts, you’ll probably use our CLI and API to automate this rather than manually edit YAML on this page (although if you’re itching to hit the command line, rather than editing YAML in the browser, you can always run through the CLI setup guide before coming back to complete this guide).
Since this guide is intended as a “Hello, World” example, we’ll skip editing the YAML right now and just proceed with the defaults.
We’ll make some changes later on in this guide.
The default YAML documents above the white line contains information for KOTS, preflight checks, customer configuration screen options, and support bundle analyzers for troubleshooting installs.
You can learn about those in the reference docs but for now, let’s click the “Save release” button in the bottom right.
Once the release is saved, go ahead and promote it to the “Unstable” channel to make this release available for installation.
To do this, click the “Releases” link in the top left and then click the “Promote” button on the row we just created.
In this popup, choose the “Unstable” channel and click the “Promote” button.
Now that we’ve got a release promoted, we can walk through creating a license and installing our basic nginx application on a test server.
Installing and Testing
This guide will give you first-hand experience installing a KOTS application using an existing Kubernetes cluster.
If you haven’t yet created a release, head back to the Create and Promote a Release guide and complete that first.
Now that we’ve created a release and promoted it to the “Unstable” channel, the next step is to create a customer license and use this license to install the application in a namespace in our test cluster.
A customer license (downloadable as a
.yaml file) is required to install any KOTS application.
To create a customer license, log in to the Vendor Portal and select the Customers link on the left.
Click the “Create your first customer” button to continue.
On the “Create a new customer” page, fill in your name for the “Customer name” field, select the “Unstable” channel on the right hand side, and click “Save Changes”.
The defaults in all other fields will be fine.
After creating the customer, click the “Download license” link in the upper right corner.
This will download the file with your customer name and a
This is the license file your customer will need to install your application.
When a customer is installing your software you need to send them two things: the KOTS install script and the license file.
Create Kubernetes Cluster and Install KOTS
KOTS can be installed either into an existing Kubernetes cluster, or as an embedded cluster.
You can see the installation options at the bottom of each channel on the Channels page.
Installing KOTS on existing clusters is very similar to using an embedded cluster, except instead of bringing a plain VM, we will use a pre-built Kubernetes cluster and deploy your KOTS app into a namespace.
In this example, we will launch a GKE cluster using
gcloud CLI, but you can use any cluster for which you have
gcloud container clusters create kots-app --preemptible --no-enable-ip-alias
Once the cluster is launched set the local
gcloud container clusters get-credentials kots-app
Install latest KOTS version as
curl https://kots.io/install | bash
Install your KOTS app
kubectl kots install <your-app-name-and-channel>
Enter the namespace to deploy to: <your-app-name-and-channel>
• Deploying Admin Console
• Creating namespace ✓
• Waiting for datastore to be ready ✓
Enter a new password to be used for the Admin Console: ••••••••
• Waiting for Admin Console to be ready ✓
• Press Ctrl+C to exit
• Go to http://localhost:8800 to access the Admin Console
At this point, the Admin Console and Kubernetes are running, but the application isn’t yet.
This is also what your customer would be experiencing when installing your application.
To complete the installation, visit the URL
http://localhost:8800 where you’ll be required to enter the password set earlier.
Now the installation needs a license file to continue.
Until this point, this cluster is just running Kubernetes and the Admin Console containers.
Once we upload a license file, kotsadm will have access to pull the application YAML and containers.
Click the Upload button and select your
.yaml file to continue.
The settings page is here with default configuration items.
The appearance of this page can be configured in the
For now we can proceed with the defaults.
Preflight checks are designed to ensure this server has the minimum system and software requirements to run the application.
By default, we include some preflight checks that are expected to fail so that we can see what failing checks might look like for a customer.
If you click continue it will warn you but you can still continue.
Click the “Application” link on the top to see the application running.
If you are still connected to this server over ssh,
kubectl get pods will now show the example nginx service we just deployed.
On the nav bar, there’s a link to the application page.
Clicking that will show you the Kubernetes services that we just deployed.
View the application
To view the running Nginx Application, port-forward the Nginx service port to localhost
kubectl port-forward service/<service-name> 8080:80
You can also add a link on the admin dashboard and port-forward the nginx port to your localhost as part of the kots application spec.
Then head to
http://localhost:8080/, and you should see a basic (perhaps familiar) nginx server running.
Next, we’ll walk through creating and delivering an update to the application we just installed.
Iterating and Updating
This guide will walk you through making a change and delivering an update to an application after it’s been deployed.
It’s assumed you have the environment from parts 1 and 2 of this guide (creating a release and installing).
If you haven’t completed these guides, head back and finish them first.
Now that we have a KOTS application running, a common task is to deliver updates.
Let’s change the number of nginx replicas to show how to deliver an update.
Create a New Release
On the Releases page of the Vendor Portal, click the “Create Release” link on top.
Once again, you’ll be taken to a YAML editor that shows the contents of the most recently created release.
This gives us everything we’ve done so far, and our task now is to only write the changes needed to increase the number of nginx replicas.
In the release YAML, find the nginx image to change.
The line is in the
deployment.yaml file and looks like:
Change the number to
2 or more.
Note: If you’ve worked ahead and already completed the CLI setup guide, you can make this
replicas change in your locally checked-out git repo, and publish them with
replicated release create --auto, then skip to Update the Test Server.
Following the same process we did before, click the “Save Release” button, go back one screen and click “Promote” next to the newly created Sequence 2.
Choose the “Unstable” channel again to promote this new release.
Now, any license installed from the “Unstable” channel will start with this new release, and any installation already running will be prompted to update to the new release.
Update the Test Server
To install and test this new release, we need to connect to the Admin Console dashboard on port :8800 using a web browser.
At this point, it will likely show that our test application is “Up To Date” and that “No Updates Are Available”.
The Admin Console will check for new updates about every five hours but we can force it to check now.
In the “Application” or “Version History” tab click on the “Check For Updates” button.
On the version history page the faded “Deployed” button should become active and say “Deploy.”
In addition, it should say how many files were changed and how many lines are different.
You can click on that to view what has changed in the yaml.
Clicking the “Deploy” button will apply the new YAML which will change the number of nginx replicas.
This should only take a few seconds to deploy.
Next Steps: Manage YAML in your Git Repo
Now that you’re familiar with the basics, you should run through the CLI Quickstart so you can start managing your release YAML in a git repo.
You can also head over to KOTS Documentation to learn how to integrate your application with other KOTS features.