This tutorial demonstrates packaging and installing a sample NGINX application in Kubernetes on an existing cluster in GKE (or another cluster that you have available).
The tutorial is broken into four sections:
Creating a Release
When you work with the Replicated platform, the Replicated vendor portal is the primary user interface (UI) that you use to package and distribute your application. This tutorial is designed to help you get familiar with the concepts and ideas that are important to successfully deploy your application with the Replicated app manager.
This tutorial shows you how to deploy a sample application using the app manager, and how to deliver an update to that application. The tutorial does not teach Kubernetes, rather it starts with a minimal Kubernetes application that deploys a single replica of NGINX.
Create a New Application
To create a new application:
Log in (or create a new team) to the vendor portal.
After signing up and activating your account, the Create a new application page opens.
Enter a name for the new application, such as Starter Application or NGINX Example.
Click Create Application.
The Channels page opens and displays a list of your release channels that are logical stacks for you to stage and promote releases to your customers. We will explore this in more detail later.
Create a Release
To create a release:
Click Releases from the left menu, and click Create a release.
A YAML editor opens, where you can define how your application will work and the integration with the app manager functionality. The default YAML documents above the white line contain information for the app manager, preflight checks, customer configuration screen options, and support bundle analyzers for troubleshooting installations. For more information, see the custom resources reference docs.
Click Save release to proceed using the default values. For this example, you can skip editing the YAML. (You will make some changes later in this tutorial.)
Promote a Release
After the release is saved, promote it to the Unstable channel to make this release available for installation.
To promote the release:
Click Releases from the top left menu.
Click Promote on the row for the release that you just created.
The Promote Release dialog opens.
Choose the Unstable channel, and click Promote.
Now that you have a release promoted, you can create a license and install the sample NGINX application on a test server.
Installing and Testing
This section gives you experience installing an application using an existing Kubernetes cluster.
After you create and promote a release, create a customer license and use this license to install the application in a namespace in your test cluster.
Create a License
A customer license, downloadable as a YAML file, is required to install any application.
To create a customer license:
From the vendor portal, select Customers from the left menu.
Click Create your first customer.
The Create a new customer page opens.
Edit the following fields, leaving the rest of the fields set to the default values:
- Enter your name for the Customer Name field.
- Select the Unstable channel on the right hand side.
Click Create Customer.
Click Download license in the upper right corner for the newly created customer.
This downloads the file with your customer name and a
.yamlextension. This is the license file your customer needs to install your application. When a customer is installing your software you need to send them two things: the app manager installation script and the license file.
You will also use this license file to install and test the application on the test server.
Create a Kubernetes Cluster and Install the App Manager
The app manager can be installed either into an existing Kubernetes cluster, or as a Kubernetes installer-created cluster (embedded cluster). You can see the installation options at the bottom of each channel on the Channels page.
Installing the app manager on existing clusters is similar to using a Kubernetes installer-created cluster, except instead of bringing a plain virtual machine (VM), you will use a pre-built Kubernetes cluster and deploy your application into a namespace.
To install the app manager:
Run the following command to launch a GKE cluster using the
gcloudCLI. (You can use any cluster for which you have
kubectlaccess instead of a GKE cluster.)
gcloud container clusters create kots-app --preemptible --no-enable-ip-alias
Run the following command to set the local
gcloud container clusters get-credentials kots-app
Run the following command to install the latest app manager version as a
curl https://kots.io/install | bash
Install your application using the kots CLI. For more information about installing an application with the kots CLI, see install in the kots CLI documentation.
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
Note the URL and password that you will use to access the Replicated admin console.
Install the Application
At this point, the admin console and Kubernetes are running, but the application is not deployed yet. This is also what your customer would be experiencing when installing your application.
To install the application:
In a browser, enter the URL
http://localhost:8800and password to access the admin console.
The Upload license page opens.
Click Upload. Select your customer license YAML file to continue, or drag and drop the license file from your desktop. The admin console can pull the application YAML and containers now.
The Settings page opens with the default configuration items.
The appearance of this page can be configured in the
Proceed with the default settings.
The Preflight page opens.
Click Continue and ignore the warnings. Preflight checks are designed to ensure this server has the minimum system and software requirements to run the application. By default, we included some preflight checks that are expected to fail so that you can see what failing checks might look like for a customer.
Vendors can optionally configure
strictpreflight checks that cause the application deployment to fail if specific requirements are not met. For more information about preflight checks, see Creating Preflight Checks and Support Bundles.
Additionally, when installing with minimal role-based access control (RBAC), the preflight checks can fail due to insufficient privileges.
When this occurs, a
kubectl preflightcommand is displayed that lets the end user manually run the preflight checks and upload the results automatically to the app manager. For more information about configuring RBAC privileges, see
supportMinimalRBACPrivilegesin the Application custom resource.
Click Application on the top to see the application running. If you are still connected to this server using SSH,
kubectl get podsshows the example NGINX service that you just deployed.
View the Deployed 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 console dashboard and port-forward the NGINX port to your localhost as part of the Application custom resource manifest.
From your browser, go to
http://localhost:8080/, and you should see a basic NGINX server running.
Next, you will create and deliver an update to the sample application.
Iterating and Updating
Now that you have an application running, a common task is to deliver updates. You will change the number of NGINX replicas to learn how to deliver an update.
Create a New Release
From the vendor portal, click Releases > Create Release.
The YAML editor opens and shows the contents of the most recently created release. This gives you everything that you have done so far, and the next task is to increase the number of NGINX replicas.
In the release YAML, find the NGINX image to change. The line is in the
deployment.yamlfile and looks like:
Change the number to
Click Save Release.
Promote the Release
Following the same process you before, promote the release to a channel.
To promote the release:
Click Promote next to the newly created Sequence 2.
Choose the Unstable channel, and click Promote.
Any license installed from the Unstable channel will start with this new release, and any installation already running is prompted to update to the new release.
Update the Test Server
To install and test this new release, you must connect to the admin console on port :8800 using a web browser. At this point, the UI likely shows that your test application is up-to-date and that no updates are available. The admin console checks for new updates approximately every five hours, but for now you will trigger a check manually.
To check for updates manually:
Click Check for Updates on the Version History tab. You should see a new release in the history now. You can click Diff versions to review the differences in the YAML files.
Click Deploy to apply the new YAML, which changes the number of NGINX replicas. The deployment takes only a few seconds.
Now that you are familiar with the basics, we recommend that you run through the CLI Quickstart Tutorial to start managing your release YAML in a git repository.
You can also head over to How to Distribute a Production Application to learn how to integrate your application with other app manager features.