quickstart-aks.md

Quickstart: Open Service Broker for Azure on an Azure Container Service managed cluster

This quickstart walks through using the Open Service Broker for Azure (OSBA) to deploy WordPress on an Azure Container Service (AKS) managed cluster.

WordPress requires a back-end MySQL database. Without OSBA, we would create a database in the Azure portal, and then manually configure the connection information. Now with OSBA our Kubernetes manifests can provision an Azure Database for MySQL on our behalf, save the connection information in Kubernetes secrets, and then bind them to our WordPress instance.

• Prerequisites
• Cluster Setup
  • Configure your Azure account
  • Create a Resource Group for AKS
  • Create a service principal
  • Create a Kubernetes cluster using AKS
  • Configure the cluster with Open Service Broker for Azure
• Deploy WordPress
• Next Steps

---

Prerequisites

• A Microsoft Azure account.
• Install the Azure CLI.
• Install the Kubernetes CLI.
• Install the Helm CLI.

Install the Azure CLI

Install az by following the instructions for your operating system. See the full installation instructions if yours isn't listed below. You will need az cli version 2.0.37 or greater.

MacOS

brew install azure-cli

Windows

Download and run the Azure CLI Installer (MSI).

Ubuntu 64-bit

1. Add the azure-cli repo to your sources:

   echo "deb [arch=amd64] https://packages.microsoft.com/repos/azure-cli/ wheezy main" | \
        sudo tee /etc/apt/sources.list.d/azure-cli.list

2. Run the following commands to install the Azure CLI and its dependencies:

   sudo apt-key adv --keyserver packages.microsoft.com --recv-keys 52E16F86FEE04B979B07E28DB02C46DF417A0893
   sudo apt-get install apt-transport-https
   sudo apt-get update && sudo apt-get install azure-cli

Install the Kubernetes CLI

Install kubectl by running the following command:

az aks install-cli

Install the Helm CLI

Helm is a tool for installing pre-configured applications on Kubernetes. Install helm by running the following command:

MacOS

brew install kubernetes-helm

Windows

1. Download the latest Helm release.
2. Decompress the tar file.
3. Copy helm.exe to a directory on your PATH.

Linux

curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get | bash

---

Cluster Setup

Now that we have all the tools, we need a Kubernetes cluster with Open Service Broker for Azure configured.

Configure your Azure account

First let's identify your Azure subscription and save it for use later on in the quickstart.

1. Run az login and follow the instructions in the command output to authorize az to use your account

2. List your Azure subscriptions:

   az account list -o table

3. Copy your subscription ID and save it in an environment variable:

   Bash

   export AZURE_SUBSCRIPTION_ID="<SubscriptionId>"

   PowerShell

   $env:AZURE_SUBSCRIPTION_ID = "<SubscriptionId>"

Create a Resource Group for AKS

When you create an AKS cluster, you must provide a resource group. Create one with the az cli using the following command.

az group create --name aks-group --location eastus

Create a service principal

This creates an identity for Open Service Broker for Azure to use when provisioning resources on your account on behalf of Kubernetes.

1. Create a service principal with RBAC enabled for the quickstart:

   az ad sp create-for-rbac --name osba-quickstart -o table

2. Save the values from the command output in environment variables:

   Bash

   export AZURE_TENANT_ID=<Tenant>
   export AZURE_CLIENT_ID=<AppId>
   export AZURE_CLIENT_SECRET=<Password>

   PowerShell

   $env:AZURE_TENANT_ID = "<Tenant>"
   $env:AZURE_CLIENT_ID = "<AppId>"
   $env:AZURE_CLIENT_SECRET = "<Password>"

Create a Kubernetes cluster using AKS

Next we will create a managed Kubernetes cluster using AKS. AKS will create a managed Kubernetes cluster for you. Once the cluster is created, getting started with OSBA is very similar to doing so on Minikube.

1. Enable AKS in your subscription, use the following command with the az cli:

   az provider register -n Microsoft.ContainerService

You should also ensure that the Microsoft.Compute and Microsoft.Network providers are registered in your subscription. If you need to enable them: console az provider register -n Microsoft.Compute az provider register -n Microsoft.Network

1. Create the AKS cluster!

   az aks create --resource-group aks-group --name osba-quickstart-cluster --generate-ssh-keys --kubernetes-version 1.9.6 --enable-rbac

   Note: Service Catalog may not work with Kubernetes versions less than 1.9.0. If you are attempting to use an older AKS cluster, you will need to upgrade. The earliest 1.9.x release available from AKS is 1.9.1, so you will need to upgrade to at least that version.

2. Configure kubectl to use the new cluster. You'll initially want to use the cluster admin user to configure Helm and Service Catalog.

   az aks get-credentials --resource-group aks-group --name osba-quickstart-cluster --admin

3. Verify your cluster is up and running

   kubectl get nodes

Configure the cluster with Open Service Broker for Azure

1. Before we can use Helm to install applications such as Service Catalog and WordPress on the cluster, we first need to prepare the cluster to work with Helm:

   kubectl create -f https://raw.githubusercontent.com/Azure/helm-charts/master/docs/prerequisities/helm-rbac-config.yaml
   helm init --service-account tiller

2. Deploy Service Catalog on the cluster:

   helm repo add svc-cat https://svc-catalog-charts.storage.googleapis.com
   helm install svc-cat/catalog --name catalog --namespace catalog \
      --set apiserver.storage.etcd.persistence.enabled=true \
      --set apiserver.healthcheck.enabled=false \
      --set controllerManager.healthcheck.enabled=false \
      --set apiserver.verbosity=2 \
      --set controllerManager.verbosity=2

3. Deploy Open Service Broker for Azure on the cluster:

   Bash

   helm repo add azure https://kubernetescharts.blob.core.windows.net/azure
   helm install azure/open-service-broker-azure --name osba --namespace osba \
     --set azure.subscriptionId=$AZURE_SUBSCRIPTION_ID \
     --set azure.tenantId=$AZURE_TENANT_ID \
     --set azure.clientId=$AZURE_CLIENT_ID \
     --set azure.clientSecret=$AZURE_CLIENT_SECRET

   PowerShell

   helm repo add azure https://kubernetescharts.blob.core.windows.net/azure
   helm install azure/open-service-broker-azure --name osba --namespace osba `
     --set azure.subscriptionId=$env:AZURE_SUBSCRIPTION_ID `
     --set azure.tenantId=$env:AZURE_TENANT_ID `
     --set azure.clientId=$env:AZURE_CLIENT_ID `
     --set azure.clientSecret=$env:AZURE_CLIENT_SECRET

   Note: to install OSBA with experimental modules enabled, use the --set modules.minStability=EXPERIMENTAL argument.

4. Check on the status of everything that we have installed by running the following command and checking that every pod is in the Running state. You may need to wait a few minutes, rerunning the command until all of the resources are ready.

   $ kubectl get pods --namespace catalog
   NAME                                                     READY     STATUS    RESTARTS   AGE
   po/catalog-catalog-apiserver-5999465555-9hgwm            2/2       Running   4          9d
   po/catalog-catalog-controller-manager-554c758786-f8qvc   1/1       Running   11         9d
   
   $ kubectl get pods --namespace osba
   NAME                                           READY     STATUS    RESTARTS   AGE
   po/osba-azure-service-broker-8495bff484-7ggj6   1/1       Running   0          9d
   po/osba-redis-5b44fc9779-hgnck                  1/1       Running   0          9d

---

Deploy WordPress

Now that we have a cluster with Open Service Broker for Azure, we can deploy WordPress to Kubernetes and OSBA will handle provisioning an Azure Database for MySQL and binding it to our WordPress installation.

helm install azure/wordpress --name osba-quickstart --namespace osba-quickstart

Use the following command to tell when WordPress is ready:

$ kubectl get deploy osba-quickstart-wordpress -n osba-quickstart -w

NAME                        DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
osba-quickstart-wordpress   1         1         1            0           1m
...
osba-quickstart-wordpress   1         1         1            1           2m

Note: While provisioning WordPress and Azure Database for MySQL using Helm, all of the required resources are created in Kubernetes at the same time. As a result of these requests, Service Catalog will create a secret containing the the binding credentials for the database. This secret will not be created until after the Azure Database for MySQL is created, however. The WordPress container will depend on this secret being created before the container will fully start. Kubernetes and Service Catalog both employ a retry backoff, so you may need to wait several minutes for everything to be fully provisioned.

Login to WordPress

1. Run the following command to open WordPress in your browser:

   export SERVICE_IP=$(kubectl get svc --namespace osba-quickstart osba-quickstart-wordpress -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
   open http://$SERVICE_IP/admin

2. To retrieve the password, run this command:

   kubectl get secret osba-quickstart-wordpress -n osba-quickstart -o jsonpath="{.data.wordpress-password}" | base64 --decode

3. Login using the username user and the password you just retrieved.

Uninstall WordPress

Using Helm to uninstall the osba-quickstart release will delete all resources associated with the release, including the Azure Database for MySQL instance.

helm delete osba-quickstart --purge

Since deprovisioning occurs asynchronously, the corresponding serviceinstance resource will not be fully deleted until that process is complete. When the following command returns no resources, deprovisioning is complete:

$ kubectl get serviceinstances -n osba-quickstart
No resources found.

Optional: Further Cleanup

At this point, the Azure Database of MySQL instance should have been fully deprovisioned. In the unlikely event that anything has gone wrong, to ensure that you are not billed for idle resources, you can delete the Azure resource group that contained the database. In the case of the WordPress chart, Azure Database for MySQL was provisioned in a resource group whose name matches the Kubernetes namespace into which WordPress was deployed.

az group delete --name osba-quickstart --yes --no-wait

To remove the service principal:

az ad sp delete --id http://osba-quickstart

To tear down the AKS cluster:

az aks delete --resource-group aks-group --name osba-quickstart-cluster --no-wait

Next Steps

Our AKS managed Kubernetes cluster communicated with Azure via OSBA, provisioned an Azure Database for MySQL instance, and bound our WordPress installation to that new database.

With OSBA any cluster can rely on Azure to provide all those pesky "as a service" goodies that make life easier.

Now that you have a cluster with OSBA, adding more applications is quick. Try out another to see for yourself:

• Concourse CI
• phpBB

All of our OSBA-enabled helm charts are available in the Azure/helm-charts repository.

Contributing

Do you have an application in mind that you'd like to use with OSBA? We'd love to have it! Learn how to contribute a new chart to our helm repository.