Welcome to OSBA in Action

This repository includes examples of how to use Open Service Broker for Azure with both Cloud Foundry and Kubernetes.

If you encounter any issues, please open an issue.

You can also contact me at Jeremy Rickard or find me on Twitter at jrrickard. I'm also regularly on the Kubernetes Slack, you can find me there as @jerickar

Prerequisites
Setup
Take a Tour of The OSB API
Take A Tour of OSBA
Use OSBA with Cloud Foundry
Use OSBA with Kubernetes

Prerequisites

Git is installed
Docker is installed. You'll also want Docker Compose.
Curl is installed.
A Java JDK is installed.

Setup

Clone this Repository

Several of the steps below will use the contents of this repository. You'll want to clone it locally so that you can follow along.

git clone https://github.com/jeremyrickard/osba-in-action.git
cd osba-in-action

Once you've cloned it locally, you're ready to move on and setup your environment.

Create your Azure account

To follow this guide, you will need a Microsoft Azure Account. If you don't already have one, click this link to get started!

The Azure CLI

You'll also want 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.

To install on MacOS

brew install azure-cli

To install on Windows

Download and run the Azure CLI Installer (MSI).

To intall on Ubuntu 64-bit

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

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

Setup your Subscription

Now that you have the tools installed, let's identify your Azure subscription and save it for later use!

Run az login and follow the instructions in the command output to authorize az to use your account
List your Azure subscriptions:
```
az account list -o table
```

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

Bash

export AZURE_SUBSCRIPTION_ID="<SubscriptionId>"

PowerShell

$env:AZURE_SUBSCRIPTION_ID = "<SubscriptionId>"

You will also want to create a resource group. Create one with the az cli using the following command.

az group create --name osba-in-action --location eastus

Create A Service Principal

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

Create a service principal with RBAC enabled:

az ad sp create-for-rbac --name osba-in-action -o table

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>"

You now have your environment configured to work with Azure resources and OSBA! Next, let's take a look at OSB and OSBA.

Take a Tour of The OSB API

The Open Service Broker API is also developed on GitHub. You can find the repository here. There are regular developer meetings that you can attend, with all the necessary information found in the GitHub repo.

Take A Tour of OSBA

Open Service Broker for Azure is an open source project and can be found on GitHub! You can find it at https://github.com/Azure/open-service-broker-azure.

You can run Open Service Broker for Azure locally by running the following command:

docker-compose run -p 8080:8080 broker

While this is running, you can use cURL to interact with the broker. To verify that the catalog endpoint is working, run:

curl -u username:password http://localhost:8080/v2/catalog --header "X-Broker-API-Version: 2.13"

This will return a large blob of JSON that represents the Catalog.

Use OSBA with Cloud Foundry

To try out OSBA with Cloud Foundry, you'll first need to install Cloud Foundry! There are two ways to get going with CF locally. For both, you'll want to install the CF CLI.

Install CF Dev

The first way to install CF locally is to install PCF Dev. This requires an account with Pivotal. You can follow the instructions there to get started.

The second way is to use the newer open source CF Dev release. At the time of writing this guide, this only works on Mac OS.

Once you have these installed, you can run cf dev start to launch the local CF environment. Depending on your computer, this may take a little time. Once complete, log in to your instance and follow the following steps to register OSBA with your CF instance.

Run OSBA

Next, start OSBA up. The command above can be reused, but run it as a background process.

docker-compose run -p 8080:8080 broker

Register OSBA with Cloud Foundry. To do this, you'll need your IP address.

ifconfig

ipconfig

Register OSBA

Next, use the cf cli to register OSBA as a space scoped broker:

cf create-service-broker osba username password http://<IP-ADDRESS>:8080 --space-scoped

Now, you should be able to view the marketplace

cf marketplace

There should be a number of Azure services listed. Next, we'll provision an instance of the CosmosDB MongoDB Service.

Create a CosmosDB Instance with Cloud Foundry

First, verify there is no CosmosDB instance:

az cosmosdb list -g osba-in-action -o table

Next, create the service

cf create-service azure-cosmosdb-mongo-account account cosmosdb -c '{
  "location": "eastus",
  "resourceGroup": "osba-in-action",
  "ipFilters" : {
    "allowedIPRanges" : ["0.0.0.0/0"]
  }
}'

Note, this provision action may take some time, so you'll want to check the status with:

cf service cosmosdb

When it's done, you can verify that it was created with the Azure CLI:

az cosmosdb list -g osba-in-action -o table

Deploy an App

Next, we'll push the spring-music sample application to your CF instance and bind it to CosmosDB! A copy of the Spring Music app is in this repository and it contains a CF manifest that will bind to your new cosmosdb instance.

---
applications:
- name: spring-music
  memory: 1G
  path: build/libs/spring-music.jar
env:
   JBP_CONFIG_SPRING_AUTO_RECONFIGURATION: '[enabled: false]'
   RUNTIME: cf
   SPRING_PROFILES_ACTIVE: cosmosdb
services:
- cosmosdb

Now, you're ready to push the app!

cd spring-music
./gradlew clean assemble
cf push

Once this finishes, you can access the app at http://http://spring-music.v3.pcfdev.io/

Deploying an application to CF is as simple as that. Because you've included a service reference in the manifest, the CosmosDB instance will automatically be bound to your new app. You should be able to access it at:

Use OSBA with Kubernetes

You can use either Minikube or the Azure Kubernetes Service to experiment with OSBA and the OSBA GitHub repository provides great quick-start guides for both! We'll use Minikube here, to show an experience similar to Cloud Foundry. The Kubernetes CLI, kubectl, doesn't have great integration for Service Brokers. Instead, you'll want to install the service catalog cli.

Install the Service Catalog CLI

Follow the appropriate instructions for your operating system to install svcat. The binary can be used by itself, or as a kubectl plugin.

The snippets below install the latest version of svcat. We also publish binaries for our canary (master) builds, and tags using the following prefixes:

Latest release: https://download.svcat.sh/cli/latest
Tagged releases: https://download.svcat.sh/cli/VERSION where VERSION is the release, for example v0.1.20.
Canary builds: https://download.svcat.sh/cli/canary
Previous canary builds: https://download.svcat.sh/cli/VERSION-GITDESCRIBE where GITDESCRIBE is the result of calling git describe --tags, for example v0.1.20-1-g203c8ad.

MacOS with Homebrew

brew update
brew install kubernetes-service-catalog-client

MacOS

curl -sLO https://download.svcat.sh/cli/latest/darwin/amd64/svcat
chmod +x ./svcat
mv ./svcat /usr/local/bin/
svcat version --client

Linux

curl -sLO https://download.svcat.sh/cli/latest/linux/amd64/svcat
chmod +x ./svcat
mv ./svcat /usr/local/bin/
svcat version --client

Windows

The snippet below adds a directory to your PATH for the current session only. You will need to find a permanent location for it and add it to your PATH.

iwr 'https://download.svcat.sh/cli/latest/windows/amd64/svcat.exe' -UseBasicParsing -OutFile svcat.exe
mkdir -f ~\bin
$env:PATH += ";${pwd}\bin"
svcat version --client

Create a Cluster

Most of this demonstration can be completed on either a local or remote Kubernetes cluster. You can chose to run locally, with Minikube, or using the Azure Kubernetes Service (AKS). Instructions for both can be found below

Create a Minikube cluster

The next step is to install Minikube. Minikube has someprerequisites you'll need to install first, specifically you'll need a Hypervisor and the kubectl command line tool. The Minikube documentation has links to help you get going on the appropriate system. Once installed, you can create a Minikube cluster with the following command

minikube start

When you run this command, the cluster will start with RBAC enabled and your kubectl configuration will automatically be updated. You can skip down to Install Helm at this point.

Create an AKS cluster

To use Service Catalog with AKS, you'll first need to create an AKS cluster. This can be done with the Azure portal or with the Azure CLI. The following Azure CLI command will create a 3 node AKS cluster.

az aks create --resource-group osba-in-action --name osba-in-action --generate-ssh-keys

This will take some time to fully provision. When it completes, you'll want to get the relevant cluster configuration for your kubectl configuration with the following command:

az aks get-credentials --resource-group osba-in-action --name osba-in-action --admin

You cluster should be ready to use with the following steps now!

Install Helm

Next, you'll need to install Helm. Helm is a tool for installing pre-configured applications on Kubernetes. We'll use it to install Service Catalog, OSBA and our Spring Music app.

Install helm by running the following command:

To install on MacOS:

brew install kubernetes-helm

To install on Windows:

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

To install on Linux:

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

Next, deploy Helm to your cluster:

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

This may take a few moments, so you can watch the status of Helm by looking for the status of the Tiller pod, which will be in the kube-system namespace:

kubectl get pods -n kube-system -w

Install Service Catalog

Once the Helm Tiller pod is running, you can install Service Catalog and OSBA on your cluster. First, install Service Catalog.

helm repo add svc-cat https://svc-catalog-charts.storage.googleapis.com
helm install svc-cat/catalog --name catalog --namespace catalog

Again, you'll want to wait until the pods are running before moving on.

$ 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

You can use the -w flag as well to wait for the output to change.

Install Open Service Broker for Azure

Next, install OSBA. Here, you will use the environment variables that were set above, so use the appropriate commands below.

With Bash, do the following

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 \
  --set modules.minStability=experimental

On windows, use PowerShell to do the following:

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 `
  --set modules.minStability="experimental"

After you've run these commands, be sure to check on the status of Open Service Broker for Azure 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 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

Create a CosmosDB Instance with Kubernetes

Now, we are ready to create a ServiceInstance using the service catalog cli:

svcat provision cosmosdb --class azure-cosmosdb-mongo-account --plan account  --params-json '{
  "location": "eastus",
  "resourceGroup": "osba-in-action",
  "ipFilters" : {
    "allowedIPRanges" : ["0.0.0.0/0"]
  }
}'

Once that completes, you can deploy the application using Helm

helm install ./contrib/kubernetes/charts/spring-music -n spring-music

Deploy an App on Kubernetes

Now we should be able to access our application:

$ kubectl get pods
NAME                                         READY     STATUS    RESTARTS   AGE
spring-music-spring-music-7c9d967686-n5zc7   1/1       Running   0          1m
$ kubectl port-forward spring-music-spring-music-7c9d967686-n5zc7 8080:8080

Now you can open a web browser and go to http://localhost:8080. You can also verify data has been created in the new instance with the Azure Portal

Advanced Topics

A new feature in Service Catalog is the ability to register service brokers in specific namespaces. This, when combined with another feature called Catalog Restrictions, enables you to expose very specific services to different teams. You can leverage Kubernetes Role Based Access Control in order to limit who can provision services, and what services they can provision.

To try out these capabilities, please see OSBA Namespace Broker Demo

Cleanup

To remove the resources we have created in Azure, you can run the following command to remove the resource group:

az group delete -n osba-in-action

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Welcome to OSBA in Action

Prerequisites

Setup

Clone this Repository

Create your Azure account

The Azure CLI

Setup your Subscription

Create A Service Principal

Take a Tour of The OSB API

Take A Tour of OSBA

Use OSBA with Cloud Foundry

Install CF Dev

Run OSBA

Register OSBA

Create a CosmosDB Instance with Cloud Foundry

Deploy an App

Use OSBA with Kubernetes

Install the Service Catalog CLI

MacOS with Homebrew

MacOS

Linux

Windows

Create a Cluster

Create a Minikube cluster

Create an AKS cluster

Install Helm

Install Service Catalog

Install Open Service Broker for Azure

Create a CosmosDB Instance with Kubernetes

Deploy an App on Kubernetes

Advanced Topics

Cleanup

Files

README.md

Latest commit

History

README.md

File metadata and controls

Welcome to OSBA in Action

Prerequisites

Setup

Clone this Repository

Create your Azure account

The Azure CLI

Setup your Subscription

Create A Service Principal

Take a Tour of The OSB API

Take A Tour of OSBA

Use OSBA with Cloud Foundry

Install CF Dev

Run OSBA

Register OSBA

Create a CosmosDB Instance with Cloud Foundry

Deploy an App

Use OSBA with Kubernetes

Install the Service Catalog CLI

MacOS with Homebrew

MacOS

Linux

Windows

Create a Cluster

Create a Minikube cluster

Create an AKS cluster

Install Helm

Install Service Catalog

Install Open Service Broker for Azure

Create a CosmosDB Instance with Kubernetes

Deploy an App on Kubernetes

Advanced Topics

Cleanup