Disclaimer: The scripts and content published here are provided solely as a courtesy to PTC customers. Each script is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the PTC be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the scripts, including any software vulnerabilities.
We’re back! In the effort to always keep you in the loop about how to run and manage your ThingWorx-based applications on container orchestrators, below you’ll find a few steps to deploy ThingWorx on Azure Kubernetes Service.
Azure Kubernetes Service (AKS) is a managed Kubernetes offering that further simplifies container-based application deployment and management. Kubernetes is a rapidly evolving platform that manages container-based applications and their associated networking and storage components. You may remember an earlier post titled “How can I deploy ThingWorx Docker images on Kubernetes?”—if you haven’t read it yet, I encourage you to check it out to learn more about deployment on Kubernetes.
These steps are intended to be used as a deployment manual and will not provide in-depth information about Kubernetes, AKS or the Helm package manager. We expect you to have the necessary skill sets to manage an AKS cluster. You can find more details about AKS here.
You should have downloaded the Docker scripts from our downloads portal and followed the instructions to build and publish the ThingWorx Docker images to your own Docker registry. Here is an FAQ that you may use for further reference.
Here are the prerequisites to get started:
- A working Azure subscription (If you don't have an Azure subscription, create a free account before you begin.)
- Azure CLI tool installed and configured (https://docs.microsoft.com/cli/azure/install-azure-cli )
- If you choose to install and use the CLI locally, this Quick Start requires that you run the Azure CLI version 2.0.46 or later. Run az --version to find your version.
- kubectl CLI tool installed and configured (https://kubernetes.io/docs/tasks/tools/install-kubectl/)
- Helm CLI tool installed and configured (https://docs.helm.sh/using_helm/#installing-helm)
You can run Azure CLI commands either from the Azure Portal, using the Azure Cloud Shell or from your workstation if you have Azure CLI installed and configured.
Open Azure Cloud Shell
Azure Cloud Shell is a free, interactive shell that you can use to run the steps in this post. Common Azure tools are preinstalled and configured in Cloud Shell for you to use with your account. Just copy the code, paste it in Cloud Shell, and then press Enter to run it. There are a few ways to open Cloud Shell:
Open Cloud Shell in your browser.
Select the Cloud Shell button on the menu in the upper-right corner of the Azure portal.
Create an AKS Cluster
Create a resource group
Create a resource group with the az group create command. An Azure resource group is a logical group in which Azure resources are deployed and managed. When you create a resource group, you are asked to specify a location. This location is where your resources run in Azure.
The following example creates a resource group named myAKSCluster in the eastus location.
$ az group create --name myAKSCluster --location eastus
You should expect the following output:
{
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myAKSCluster",
"location": "eastus",
"managedBy": null,
"name": "myAKSCluster",
"properties": {
"provisioningState": "Succeeded"
},
"tags": null
}
Great work.
Create AKS cluster
Now, we can use the az aks create command to create an AKS cluster. The following example creates a cluster named myAKSCluster with one node. Azure Monitor for containers is also enabled using the --enable-addons monitoring parameter. For more information on enabling the container health monitoring solution, see Monitor Azure Kubernetes Service Health.
$ az aks create --resource-group myAKSCluster --name myAKSCluster --node-count 1 --enable-addons monitoring --generate-ssh-keys
After several minutes, the command will complete and return JSON-formatted information about the cluster.
Connect to the cluster
To manage a Kubernetes cluster, use kubectl, the Kubernetes command-line client.
If you're using Azure Cloud Shell, kubectl is already installed. If you want to install it locally, you can use the az aks install-cli command.
$ az aks install-cli
To configure kubectl to connect to your Kubernetes cluster, use the az aks get-credentials command. This step downloads credentials and configures the Kubernetes CLI to use them.
$ az aks get-credentials --resource-group myAKSCluster --name myAKSCluster
To verify the connection to your cluster, use the kubectl get command to return a list of the cluster nodes. Just as a heads-up, note that it can take a few minutes for the nodes to appear.
$ kubectl get nodes
After running the above command, your output should read:
$ NAME STATUS ROLES AGE VERSION k8s-myAKSCluster-36346190-0 Ready agent 2m v1.11.5
Using ACR as a Docker registry
If you don't have your own Docker registry, don’t fear. You can use the Azure Container Registries service (ACR).
Here’s how:
Create an ACR instance using the az acr create command. Note that the registry name must be unique within Azure and contain 5-50 alphanumeric characters. In the following example, myContainerRegistry007 is used.
Update this to a unique value—because blending in and going with the flow isn’t as fun as being unique.
$ az acr create --resource-group myAKSCluster --name myContainerRegistry007 --sku Basic
When the registry is created, the output should be similar to the following:
{
"adminUserEnabled": false,
"creationDate": "2017-09-08T22:32:13.175925+00:00",
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.ContainerRegistry/registries/myContainerRegistry007",
"location": "eastus",
"loginServer": "myContainerRegistry007.azurecr.io",
"name": "myContainerRegistry007",
"provisioningState": "Succeeded",
"resourceGroup": "myResourceGroup",
"sku": {
"name": "Basic",
"tier": "Basic"
},
"status": null,
"storageAccount": null,
"tags": {},
"type": "Microsoft.ContainerRegistry/registries"
}
Throughout the rest of this Quick Start, you’ll see <acrName>. This is a placeholder for the container registry name, so go ahead and replace it with your own unique one.
Log in to ACR
Before pushing and pulling container images, be sure to log in to the ACR instance. To do so, use the az acr login command.
$ az acr login --name <acrName>
After running the command above, you should see a message, once completed, that says Login Succeeded.
You can also retrieve the ACR docker registry credentials using:
$ az acr credential show -n <acrName>
Push image to ACR
To push an image to an Azure Container registry, you must first have an image.
If you don't yet have any local container images, you can run the following commands after you have built the ThingWorx Docker images.
Replace <acrLoginServer> with the login server name of your ACR instance. Run:
$ docker tag thingworx-platform-postgres <acrLoginServer>/thingworx-platform-postgres:latest $ docker push <acrLoginServer>/thingworx-platform-postgres:latest
Deploy ThingWorx
In this example, we’ll use the ThingWorx platform with the PostgreSQL backend.
To prepare for the deployment, start by downloading the helm chart thingworx-0.1.0.tgz (extract from attached zip file).
You can take a look at what is configurable in this Helm chart by running the following command:
$ helm inspect thingworx-0.1.0.tgz
This will show you the default configuration ( values.yaml ) and instructions ( README.md ) provided within the package. In the next steps, we’ll show you how to override some of these values to make the deployment fit your environment.
Let's create your custom values file. Use your favorite text editor to create a new file that looks like the following example. Please note the comments and make the necessary adjustments.
# Uncomment the following lines if you're using a private Docker registry that requires a username and password
#imageCredentials:
# password: <acrPassword> # Your Docker Registry Password here
# registry: <acrLoginServer> # Your Docker Registry FQDN here
# username: <acrUsername> # Your Docker Registry Username here
registry:
domain: <acrLoginServer> # Your Docker Registry FQDN here
thingworx:
image:
repository: thingworx-platform-postgres # Your Thingworx Docker image name
tag: 8.4.0 # Your Thingworx Docker image tag
# Uncomment the following lines if you have the nginx-ingres addon installed on your cluster
# ingress:
# enabled: true
# annotations:
# kubernetes:
# io/ingress:
# class: nginx
# hosts:
# - twx.k8s.example.com # A FQDN that resolves to your cluster's ingress point
# Make sure you define your own usernames and passwords and don't use the defaults
postgresql:
postgresPassword: # YOUR_PG_ADMIN_PASSWORD
commonConf:
TWX_DATABASE_USERNAME: # YOUR_TWX_DB_USER
TWX_DATABASE_PASSWORD: # YOUR_TWX_DB_PASSWORD
RABBITMQ_USERNAME: # YOUR_RABBITMQ_USER
RABBITMQ_PASSWORD: # YOUR_RABBITMQ_PASSWORD
Save this file as myValues.yaml.
If you have never used Helm with your cluster before, you should run the following command. This will install/upgrade the Helm server-side component (Tiller) on your Kubernetes cluster.
$ helm init --upgrade
Now, to deploy ThingWorx, run the following command. This will deploy ThingWorx into your current kube config namespace. If you want to deploy it into a specific namespace, use the --namespace or -n flag.
$ helm upgrade --install -f myValues.yaml thingworx-test thingworx-0.1.0.tgz
Wait a few seconds and you should have ThingWorx deployed onto your Kubernetes cluster.
You can check the Helm release status with the following command:
$ helm ls
To check if the ThingWorx and PostgreSQL pods are ready, you can use kubectl:
$ kubectl get pods
If you have an Ingress set up on your cluster, you can open a browser and point it to the URL you created for it. If not, you can use kubectl to reach it with the following command:
$ kubectl port-forward service/thingworx-test-twx 8080
Leave the terminal open and point your browser to http://localhost:8080/Thingworx.
There you have it! You’ve just deployed ThingWorx Docker images on Azure Kubernetes Service. You’re awesome.
Any questions, just ask!
Stay connected,
Kaya
