This tutorial demonstrates packaging and installing a sample NGINX application in Kubernetes using a single virtual machine (VM).
It 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 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 your 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 the Replicated Kubernetes installer for an embedded Kubernetes cluster. For more information, see Kubernetes installer.
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 a new 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.
- Set the Customer Type to Development.
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 Test Server 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. For this tutorial, you will use the Kubernetes installer, or embedded cluster, option.
To create the test server and install the app manager:
Create a server using any cloud provider (such as GCP or AWS). Or, use a local virtual machine. The server must meet the following criteria:
- Ubuntu 18.04
- At least 8 GB of RAM
- 4 CPU cores
- At least 50GB of disk space
If you use a virtual machine that is behind a firewall, make sure that port 8800 (and any other ports you attempt to access through the internet) are allowed to accept traffic. GCP and AWS typically require firewall rule creation to expose ports.
Use SSH to access the server you just created.
Run the installation script:
curl -sSL https://k8s.kurl.sh/<your-app-name-and-channel> | sudo bash
This script installs Docker, Kubernetes, and the Replicated admin console containers (kotsadm).
Installation takes approximately 5-10 minutes.
After the installation script completes the initial installation, the output displays the connection URL and password that you must use in a later step of the installation process:
Login with password (will not be shown again): [password]
The login password displayed in the CLI output of the installation command is not shown again. Copy this password so that you can log in to the admin console in a later step of the installation process.
Reload your shell to access the cluster with
kubectlcommand to test that
kubectl get pods
NAME READY STATUS RESTARTS AGE
kotsadm-79dcb4dc7d-2xh85 1/1 Running 0 60m
kotsadm-postgres-0 1/1 Running 0 60m
kurl-proxy-kotsadm-5f7fb75f47-b7jbz 1/1 Running 0 60m
Install the Application
At this point, Kubernetes and the Replicated admin console are running, but the application is not deployed yet.
To install the application:
In a browser, enter the URL from the
Kotsadm:field in the CLI output of the installation script. For more information about the installation script, see Create a Test Server and Install the App Manager above. Notice that the Kubernetes installer cluster has provisioned a self-signed certificate.
If your virtual machine is behind a firewall, make sure that port 8800 (and any other ports you attempt to access through the internet) are allowed to accept traffic. GCP and AWS typically require firewall rule creation to expose ports.
Bypass the insecure certificate warning. You have the option of uploading a trusted certificate and key. For production installations, we recommend using a trusted certificate. For this tutorial, use the self-signed certificate.
You are prompted for a password.
Enter the password from the
Login with password (will not be shown again):field in the CLI output of the installation script to log in to the admin console. For more information about the installation script, see Create a Test Server and Install the App Manager above.
The Upload license page opens. Until this point, this server is running only Docker, Kubernetes, and the admin console containers.
Click Upload. Select your customer license YAML file to continue, or drag and drop the license file from your desktop. The app manager can pull containers and run your application now.
The Settings page opens with the default configuration items.
There are some example configuration options on this page. Feel free to explore and toggle some of the options. You can see the results of your changes later.
For production, you can customize what appears on this screen to collect the configuration that your application needs from the customer. Values are available to your app as text templates or input values to Helm Charts.
The Preflight page opens.
Click Continue. If you have failing checks, dismiss the warning to continue. Preflight checks are designed to help ensure that this server has the minimum system and software requirements to run the application. Depending on your YAML configuration in the
preflight.yamlfile, you can see some of the example preflight checks fail.
The Version History page opens and displays the initial version that was deployed. Later, you will come back to this page to deploy an update to the application.
Click Application on the top to see the status of the application and some basic monitoring statistics (such as CPU, memory, and disk space). 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 default NGINX application, click Open App on the Dashboard page.
You should see a simple web page.
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 make a change to the number of NGINX replicas to learn how to deliver an update.
Create a New Release
To 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 write the changes needed to increase the number of NGINX replicas.
In the release YAML, find the NGINX deployment to change. Add a
replicasline in the
--- example-deployment.yaml 2022-08-23 16:54:45.000000000 -0500
+++ example-deployment-2.yaml 2022-08-23 19:30:47.000000000 -0500
@@ -6,6 +6,7 @@
Change the number of replicas to
Click Save Release.
Save and Promote the Release
Following the same process as you did before, promote the release to the 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 about 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 page. You should see a new release in the history now. You can click Diff versions to review the differences.
Click Deploy to apply the new YAML, which changes the number of NGINX replicas. The deployment takes only a few seconds.
Run the following command to verify the deployment on the server:
kubectl get pod -l app=nginx
You should see two pods running.