Running your application in a production environment like Kubernetes is the best way to automate the deployment, scaling and management of the operations of the application containers. To deploy and manage the application containers in a Kubernetes cluster, you can use Helm charts.
This guide walks you through the process of running an example MEAN application on a Kubernetes cluster. It uses a simple MEAN application which exploits HTML5 geo-location features to show your location on a map. This location can be saved in a MongoDB database, and you can see other people's locations too. The first step is to create a Dockerfile and use it as the starting point for creating a custom Helm chart to automate the application deployment in a Kubernetes cluster. Once the application is deployed and working, it will also explore how to modify the source code for publishing a new application release and how to perform rolling updates in Kubernetes using the Helm CLI.
Assumptions and prerequisites
This guide focuses on deploying an example MEAN application in a Kubernetes cluster running on Minikube. The example application is an application comprising MongoDB, ExpressJS, AngularJS and NodeJS which uses HTML5 geo-location features to locate users on a map.
This guide makes the following assumptions:
- You have basic knowledge of how to build Docker images.
- You have basic knowledge of Helm charts and how to create them.
- You have a Docker environment running.
- You have an account in a container registry (this tutorial assumes that you are using Docker Hub).
- You have Minikube installed on your local computer.
- You have a Kubernetes cluster running.
- You have the kubectl command line (kubectl CLI) installed.
- You have Helm and Tiller installed.
To create your own application in MEAN and deploy it in a Kubernetes using custom Helm charts you will typically follow these steps:
- Step 1: Obtain the application source code
- Step 2: Build the Docker image
- Step 3: Publish the Docker image
- Step 4: Create the Helm Chart
- Step 5: Deploy the example application in Kubernetes
- Step 6: Update the source code and the Helm chart
Step 1: Obtain the application source code
To begin the process you'll need to clone the bitnami/tutorials repository, as shown below:
$ git clone https://github.com/bitnami/tutorials $ cd tutorials/mean-k8s
This will clone the entire tutorials repository. In the mean-k8s directory, you will find the following:
- Dockerfile: a text file that contains instructions on how to build a Docker image. Each line indicates an instruction and a command for assembling all the pieces that comprise the image.
- app-code directory: a folder that contains the application source code.
- helm-chart directory: a folder that contains the Helm chart for this tutorial.
|IMPORTANT: The following steps must be executed within the tutorials/mean-k8s directory.|
The sample code is based on the Create a MEAN Stack Google Map App tutorial, but it has been adapted to the needs of this current tutorial by changing the MongoDB connection string to make it configurable using environment variables. Take a look at the app-code/app/config.js file in the repository, which defines MongoDB parameters through environment variables.
Step 2: Build the Docker image
Once the Dockerfile has been created, you can build the Docker image. Here's how:
Run the docker run command in the directory containing the Dockerfile. Add a tag to identify the current version of the application: 0.1.0. Remember to replace the USERNAME placeholder with your Docker ID.
$ docker build -t USERNAME/mean-k8s:0.1.0 .
You will see output like this during the build process:
Check that the image has been created in your local repository by executing the command below:
$ docker images | grep mean-k8s
Step 3: Publish the Docker image
Now that you've created a Docker image which contains your application code, you can upload it into a public registry. This tutorial uses Docker Hub, but you can select one of your own, such as:
To upload the image to Docker Hub, follow the steps below:
Log in to Docker Hub:
$ docker login
Push the image to your Docker Hub account. Replace the USERNAME placeholder with your Docker ID:
$ docker push USERNAME/mean-k8s:0.1.0
You will see output like this during the build process:
You should now see the new image in your Docker Hub repositories dashboard.
Step 4: Create the Helm Chart
|IMPORTANT: The bitnami/tutorials repository you have cloned in step 1, contains all the files you need with the required changes already made. The only step you must perform is to edit the values.yaml file in order to update the image repository field.|
To create a brand new chart, you just need to run the helm create command. This creates a scaffold with sample files that you can modify to build your custom chart. For this tutorial, we'll provide you with a ready-made Helm chart. If you examine the repository you just downloaded, there is a directory named helm-chart that already contains the files you need. Check out the chart's file structure:
helm-chart/ |-- Chart.yaml |-- requirements.lock |-- requirements.yaml |-- templates | |-- NOTES.txt | |-- _helpers.tpl | |-- deployment.yaml | `-- service.yaml `-- values.yaml
For a more in-depth look at chart creation, we recommend reading our Helm Chart tutorial.
With the scaffolding in place, we'll perform the following steps:
- Edit the values.yaml file (mandatory)
- Edit the templates/_helpers.tpl file
- Edit the requirements.yaml file
- Edit the templates/deployment.yaml file
- Install the missing database dependencies
|NOTE: The current example works with a MongoDB-based application. The database values added to the files mentioned above come from the existing Bitnami MongoDB chart.|
Edit the values.yaml file (mandatory)
Edit the values.yaml file to replace the current image repository name with the name given in step 2 as follows:
Edit the templates/_helpers.tpl file
The templates/_helpers.tpl file will help you deal with Helm chart values easily. In this file, some lines have been added to allow you to access MongoDB's resources, such as the database Secrets. To do so, a Go template has been specified under the tag mongodb.fullname as shown below. It will be used to populate text values in other files.
Edit the requirements.yaml file
In this second step, we edit the requirements.yaml file to specify the database dependencies. Your file should look like this:
Edit the templates/deployment.yaml file
The templates/deployment.yaml file contains the instructions to launch the application container. For a successful launch, you need to specify the database values in the current application chart. You can find the database values in the values.yaml file included in the Bitnami MongoDB chart. These values are:
MONGODB_PASSWORD: Since you want to store your database password as a Kubernetes Secret, the secretKeyRef value has been added to the current file. Learn about about Secrets in Kubernetes.
Open the templates/deployment.yaml file to see how these values have been added to the current mean-k8s chart:
That's the beauty of Helm charts: it's very easy to use building blocks to deploy, operate and upgrade applications on Kubernetes!
Install missing dependencies
The final step consists of installing missing database dependencies. To do this, execute the following commands:
$ helm dep list $ helm dep update helm-chart/
As you can see in the image above, Helm has downloaded and stored database dependencies under the charts directory, using the database version (0.4.10) which has been indicated in the requirements.yaml file.
Step 5: Deploy the example application in Kubernetes
|NOTE: Before performing the following steps, make sure you have a Kubernetes cluster running, and that Helm and Tiller are installed correctly. For detailed instructions, refer to our starter tutorial.|
At this point, you have built a Docker image, published it in a Container Registry and created your custom Helm chart. It's now time to deploy the example MEAN application within a Kubernetes cluster. To deploy the example application using the current Helm chart, follow these steps:
Make sure that you can to connect to your Kubernetes cluster by executing the command below:
$ kubectl cluster-info
Deploy the Helm chart by executing the following (my-mean-app is an example name, replace it with the name you want to give to your application):
$ helm install --name my-mean-app helm-chart/
This will create two pods within the cluster, one for the MongoDB service and the other for the application itself.
NOTE: Please be aware that we have defined passwords and users in the values.yaml file to make it easy for everyone to understand where the environment variables come from. In general, you need to avoid writing passwords and other sensitive data in the chart. You can override the default values in values.yaml passing the --set option while installing the chart (DB_PASSWORD is a placeholder, remember to replace it with the right value):
$ helm install helm-chart/ --name my-mean-app --set mongodb.mongodbRootPassword=DB_PASSWORD
Once the chart has been installed, you will see a lot of useful information about the deployment. The application won't be available until database configuration is complete. Follow these instructions to check the database status:
Run the kubectl get pods command to get a list of running pods:
$ kubectl get pods
Check the logs of the application pod. APP-POD-NAME is a placeholder; remember to replace it with the right value:
$ kubectl logs -f APP-POD-NAME
Once you've configured the database, you can access the application. To obtain the application URL, run the commands shown in the "Notes" section below.
If you're using Minikube, you can also check the application service to get the application's URL. You have two ways to do this:
Option 1: List the services by executing the minikube service list command. You'll notice two service names:
$ minikube service list
Option 2: Check the application service using the minikube service SERVICE command (SERVICE is a placeholder. Remember to replace it with the name of the service you want to check):
$ minikube service my-mean-app-mean-k8s --url
Enter the resulting URL in your default browser to access the application.
Congratulations! You've successfully deployed your MEAN application on Kubernetes.
|IMPORTANT: HTML5 Geolocation is a technology that offers location services for web applications. It's included by default on all major browsers, but for security reasons, it may require user action to work. Select the option "Always allow on this site" in Chrome or click "Allow Location Access" if you are using Firefox as default browser.|
Step 6: Update the source code and the Helm chart
To release a new Docker image, you just need to carry out a few basic steps: change your application source code, and rebuild and republish the image in your selected container registry. To illustrate the process, let's perform a change to the title of the application homepage, and then release a fresh Docker image with the updated code, using the following steps:
Edit the file app-code/public/index.html and in the Header-Title section, change the page title
<title>The Scotch MEAN MapApp running on Kubernetes</title>
<title>My new MEAN MapApp</title>
|IMPORTANT: Remember to replace the USERNAME placeholder with your Docker ID when executing the commands below.|
Build your container again, changing the tag from 0.1.0 to 0.2.0:
$ docker build -t USERNAME/mean-k8s:0.2.0 .
|NOTE: Before performing the next step, make sure you're logged in to Docker Hub. Run the docker login command to access your account (if applicable).|
Push the new image to Docker Hub using the same commands as in step 3. Remember to change the tag version from 0.1.0 to 0.2.0:
$ docker push USERNAME/mean-k8s:0.2.0
You should see the new image in your Docker Hub repositories dashboard. Find the application releases listed in the "Tags" section. You can also see the new image by executing the following:
$ docker images | grep mean-k8s
In the helm-chart/values.yaml file, change the tag: 0.1.0 to tag: 0.2.0:
In the helm-chart/Chart.yaml file, change the tag: 0.1.0 to tag: 0.2.0:
Execute the helm upgrade command to update your Helm Chart:
$ helm upgrade my-mean-app helm-chart/
Follow these steps every time you want to update your Docker image and Helm chart.
|IMPORTANT: To rollback your application chart, refer to our how-to tutorial for deploying, scaling and upgrading an application on Kubernetes with Helm. Remember to replace my-todo-app with the name of your Helm chart when you work through the example provided in the above-mentioned tutorial.|
To learn more about the topics discussed in this guide, use the links below: