Installing Mattermost using the Azure CNAB Quickstart Library
TL;DR – Get started with Mattermost on Azure using the Mattermost on AKS quickstart from the Azure CNAB Quickstart Library.
The quickstart provides a fast and simple way to get running with Mattermost, without the need to learn or install any new tooling. By using Azure Kubernetes Service (AKS), the infrastructure is fully managed for you, and the quickstart handles configuring networking and SSL certificates so you can instantly access the Mattermost application after installation.
Read on to find out more about CNAB and the Azure CNAB quickstarts library, plus a step-by-step guide to installing Mattermost on AKS using the quickstart.
What is CNAB?
CNAB is the abbreviation for Cloud Native Application Bundles. It's a specification designed for facilitating the bundling, installing, and managing of cloud-native or distributed apps. The specification was developed by a consortium of companies, including Microsoft and Docker.
A CNAB (or a bundle, for short) is made up of three components:
- Application images – these are the application artifacts, typical Docker images (although the specification is technology-agnostic)
- Invocation image – this is the installer for the application, an image containing all tools and scripts necessary to perform the installation
- Bundle descriptor – this is the metadata for bundle, which defines properties like the bundle name and version and well-known actions you can invoke for the bundle (such as install, upgrade, and uninstall)
The benefit of all this is that it gives you a bundle format where you can package up your application along with everything necessary to install it. What may have previously been written as a complex series of steps in an instructional readme—or just knowledge inside an engineer's head—can be captured in the invocation container image and installed using any of the tools that understand the CNAB specification.
As CNAB is only the specification, tooling is required to both build and run bundles. Popular tools include Porter, Duffle, and Docker App.
What is the Azure CNAB Quickstarts Library?
The Quickstarts Library is designed to be a collection of bundles that can be used to easily deploy applications, solutions, and samples. It is not limited to Azure, but bundles that make use of Azure resources can be highly optimised.
The library enables authors to build bundles for sharing (currently using Porter as the tooling). It also enables consumers to easily install the bundles, either via one-click button deployments or from the command line in Azure Cloud Shell. More information about how to author and consume the bundles can be found in the repo documentation, and specific guidance to installing the Mattermost on AKS can be found in the section below.
It is hoped that the library will not only offer bundles for users to quickly get started with application, but also provide a way to learn about CNAB and Porter and an opportunity for the community to contribute and share their own quickstarts.
Step-by-step guide to using the Mattermost on AKS quickstart
One of the quickstarts available in the library is 'Mattermost on AKS'. This bundle installs Mattermost on an Azure Kubernetes Service (AKS) cluster.
The bundle does the following:
- Deploys AKS cluster
- Installs NGINX ingress controller and configures to use public DNS name
- Installs cert-manager and configures to use Let's Encrypt to issue free SSL certificates
- Installs Mattermost (Enterprise Edition or Team Edition)
As mentioned previously, there are a couple of ways to install a bundle from the library. In this guide, we will go through the steps involved when using the 'Deploy from Azure' simple deployment. This method of deployment uses Azure Container Instances (ACI) to invoke the bundle using Porter and also for hosting the invocation image when doing the installation.
Before starting, you will need access to an Azure subscription and permission to create resources in that subscription.
You will also need to create a deployment service principal. The simplest way to do this is to use the Azure CLI tool via Azure Cloud Shell.
In the Azure Portal, open Cloud Shell by clicking the button in the top menu (if you haven't used Cloud Shell before, it will prompt you to create a Azure Storage Account which is used as backing storage).
When the shell has loaded, run the following command (replacing <name-of-service-principal>): az ad sp create-for-rbac -n <name-of-service-principal>
This will create the service principal and output the details you will need later (appId and password). Write these down.
Back to the Quickstarts Library: If you open the porter/mattermost-aks folder, you will see a 'Deploy from Azure' button under the 'Simple Deployment' header.
Clicking the button will open the 'Custom Deployment' page in the Azure Portal.
Under 'Deployment scope', select the Azure subscription you want to deploy the solution to and either select an existing resource group or create a new one.
Fill in the parameters:
| Parameter name | Description |
|---|---|
| Region | The Azure data center to deploy the application to |
| Cluster_name | The name of the AKS cluster to create (must be unique) |
| Cnab_action | The bundle action to invoke; choose 'install' here |
| Cnab_azure_client_id | Enter the appId saved earlier when creating the service principal Cnab_azure_client_secret enter the password saved earlier when creating the service principal |
| Dns_name | The prefix that will be used for the public FQDN for your application, which must be unique. For example, if you choose 'mattermost123', the FQDN will be 'mattermost123.<azure region>.cloudapp.azure.com' |
| Kubernetes_version | The version of Kubernetes that will be used on the AKS cluster; leave as '1.18.1' |
| Letsencrypt_email | Enter a valid email address that will be used when generating SSL certificates with Let's Encrypt. You will receive emails with reminders about renewing the certificate |
| Letsencrypt_environment | Select either 'staging' or 'prod'. This determines which Let's Encrypt environment to use. Select 'prod' |
| Mattermost_edition | You can select to install either the 'enterprise' or 'team' edition of Mattermost; defaults to 'enterprise' |
| Mysql_mysql Password | Enter a password that will be used for the application's default database user |
| Mysql_mysql Root Password | Enter a password that will be used for the application's root database user |
| Mysql_mysql User | Enter a username that will be used for the application's default database user |
| Node_count | The number of VMs to deploy in the AKS node pool (use between 1 and 4) |
| Node_vm_size | The VM size for the nodes in the pool (leave as 'Standard_D8s_v3') |
| Resource_group | The resource group to deploy the AKS cluster. This can be the same as the resource group selected in the 'Deployment Scope' section, if you wish |
Once filled, click 'Review + Create', then 'Create' to start the deployment.
This will take you to the deployment page where you can see the progress. Here we are creating an Azure Storage account for a persisting state, and an ACI group which will invoke the bundle. When this deployment finishes, select the 'Output' tab and you will see a command you can use to monitor the logs from the ACI container.
Copy this command, open Cloud Shell and run it in there.
This will show the output logs from the bundle installation process. When the installation completes, the end of the output will show the URL where you can access the Mattermost application.
Now you can follow this URL and start trying out Mattermost running in Azure.
