Create a new install guide #479

jeremyrickard · 2018-06-13T20:59:18Z

This PR creates a new install guide and a helm chart that uses etcd-operator to create a new etcd cluster with backup capabilities.

carolynvs · 2018-06-14T15:27:12Z

docs/installation-aks.md

@@ -0,0 +1,407 @@
+# Install and Operate Open Service Broker for Azure on an Azure Container Service managed cluster
+
+Open Service Broker for Azure allows you to provision Azure services from your Kubernetes cluster. OSBA is integrated with Kubernetes using [Service Catalog](https://github.com/kubernetes-incubator/service-catalog). Both Service Catalog and OSBA have data persistence needs. When using Service Catalog and OSBA for development, it is sufficient to use the embedded storage options available with each application. For production use cases, however, we recommend more robust solutions. This guide provides details on setting up OSBA and associated software including Service Catalog, etcd and Redis for production scenarios. If you are new to OSBA, you may find the [AKS](quickstart-aks.md) or [Minikube](quickstart-minikube.md) Quickstart guides useful.


nit: May want to break this up into smaller paragraphs, e.g.

Open service broker for azure... Both Service Catalog and OSBA... If you are new to OSBA, ...

carolynvs · 2018-06-14T15:28:12Z

docs/installation-aks.md

+Open Service Broker for Azure allows you to provision Azure services from your Kubernetes cluster. OSBA is integrated with Kubernetes using [Service Catalog](https://github.com/kubernetes-incubator/service-catalog). Both Service Catalog and OSBA have data persistence needs. When using Service Catalog and OSBA for development, it is sufficient to use the embedded storage options available with each application. For production use cases, however, we recommend more robust solutions. This guide provides details on setting up OSBA and associated software including Service Catalog, etcd and Redis for production scenarios. If you are new to OSBA, you may find the [AKS](quickstart-aks.md) or [Minikube](quickstart-minikube.md) Quickstart guides useful.
+
+* [Prerequisites](#prerequisites)
+  * [Existing Clusters](#existing-cluster)


broken link

carolynvs · 2018-06-14T15:28:18Z

docs/installation-aks.md

+* [Create an Azure Redis Cache](#create-azure-redis-cache)
+* [Create a service principal](#create-a-service-principal)
+* [Configure the cluster with Open Service Broker for Azure](#configure-the-cluster-with-open-service-broker-for-azure)
+* [Next Steps](#next-steps)


broken link

carolynvs · 2018-06-14T15:33:06Z

docs/installation-aks.md

+
+#### Create a Kubernetes cluster using AKS
+
+* As AKS is currently in preview, you will need to enable it in your subscription


We should remove this, right?

still required :(

carolynvs · 2018-06-14T15:33:15Z

docs/installation-aks.md

+#### Create a Kubernetes cluster using AKS
+
+* As AKS is currently in preview, you will need to enable it in your subscription
+* AKS currently does _not_ support RBAC, so we will need to explicity disable that when we install service catalog.


this one is removed.

carolynvs · 2018-06-14T15:33:31Z

docs/installation-aks.md

+* As AKS is currently in preview, you will need to enable it in your subscription
+* AKS currently does _not_ support RBAC, so we will need to explicity disable that when we install service catalog.
+
+1. Enable AKS in your subscription, use the following command with the az cli:


still required :(

carolynvs · 2018-06-14T15:34:22Z

docs/installation-aks.md

+We will use Helm to install etcd Operator, Service Catalog and OSBA. In order to install Helm in your cluster, use the `helm` CLI:
+
+```console
+helm init


Is this the most safe way to run helm in prod? I'm wondering if since we are kind of saying this is prod safe way to install on aks that we may want to include any other security best practices in this command if necessary.

I believe the more proper way is to create a service account and create the RBAC policies. We do this in the quickstarts now, so i have updated this. I'll ping Matt F and see if he has any more feedback.

carolynvs · 2018-06-14T15:36:27Z

docs/installation-aks.md

+
+
+First, save your desired account name to an environment variable. It will be reused a few times.
+ **Bash**


needs a new line before this so that it gets its own paragraph

carolynvs · 2018-06-14T15:38:32Z

docs/installation-aks.md

+
+#### Create etcd Cluster
+
+Once etcd Operator has been installed, you can create a cluster. For production scenarios, we recommend a three node cluster. For convenience purposes, we have provided a Helm chart that will create a cluster and configure a Kubernetes CronJob to enable automatic backups of the cluster.


it would help to say why a 3 node cluster is good, like "blah blah HA blerp bleep"

~~For convenience purposes~~

carolynvs · 2018-06-14T15:40:36Z

docs/installation-aks.md

+
+Service Catalog requires etcd to persist state for everything it manages. We recommend using etcd Operator to install and manage an etcd cluster for Service Catalog. We have included sample values.yaml file to setup etcd operator with a version that supports Azure backup. 
+
+```console


super mega nit: For command blocks that just have a command and no $ and output, don't specify console so that the command prints in black. This better matches how the command blocks look when you do use $ along with console so that commands are always in black, and console output is always in blue on the doc page.

it just helps people visually scan the page.

carolynvs · 2018-06-14T15:42:56Z

docs/installation-aks.md

+
+Once you have created an etcd cluster, it is time to install Service Catalog. You will use Helm to install Service Catalog. There are a few values you will need to override for your Service Catalog installation:
+
+* RBAC must be disabled (pending AKS support)


oops you said that you are doing another pass for rbac, right? I'll stop blathering about rbac then 😇

carolynvs · 2018-06-14T15:44:15Z

docs/installation-aks.md

+
+* RBAC must be disabled (pending AKS support)
+* Embedded etcd must be disabled
+* You must point the installation at an external etcd.


"external etcd" maybe should be called "an etcd cluster" so that people aren't thinking we are talking about an off-cluster ... etcd cluster.

p.s. cluster cluster cluster

carolynvs · 2018-06-14T15:45:10Z

docs/installation-aks.md

+
+## Create Azure Redis Cache
+
+Open Service Broker for Azure uses Redis as a backing store for its state. We recommend using a managed Redis service, such as Azure Redis Cache. By default, Azure Redis Cache only keeps data in memory. For best results, you will want to use the Premium tier in order to configure backups of the Redis data. Please see [How to configure data persistence for a Premium Azure Redis Cache](https://docs.microsoft.com/en-us/azure/redis-cache/cache-how-to-premium-persistence) for instructions on how to create an Azure Redis Cache. Once created, you can obtain the hostname and keys from the Portal or via the CLI. 


"We recommend using Azure Redis Cache, a managed Redis service". Let's come right out and say that we commend out own stuff. 😀

"By default, Azure Redis Cache ... For best results, "

As long as we are making recommendations let's be crystal clear

"You should use the Premium tier of Azure Redis Cache, so take advantage of persistent backups because by default Redis is an in-memory only database. See How to configure..."

carolynvs · 2018-06-14T15:50:03Z

docs/installation-aks.md

+    absSecret: <abs-credential-secret-name> 
+```
+
+You will need to replace the spec.abs.path value with the backup you'd like to restore from. You will need the storage container as well as the file name. For example, if your absSecret was called `dandy-clownfish-svc-cat-etcd` and you used etcd-backups as the storage container as directed above and the file name was etcd.backup.2018-06-12_19:31:05, your restore yaml would look like:


let's add some backticks around spec.abs.path because ... codeblocks, all the beautiful codeblocks.

krancour · 2018-06-15T03:37:11Z

@jeremyrickard do you want this in v0.12.0?

jeremyrickard · 2018-06-15T03:40:10Z

We can do this after the v0.12.0 release, but ideally shortly there after. I’d like to go through this and update for RBAC since AKS is GA now. Shouldn’t be any major changes and will not have any code changes.

krancour · 2018-07-05T15:04:03Z

Makefile

@@ -349,6 +352,7 @@ PUBLISH_RC_CHART_CMD := bash -c ' \
 	&& mkdir repo \
 	&& cd repo \
 	&& sed -i "s/^version:.*/version: 0.0.1-$(GIT_VERSION)/g" ../open-service-broker-azure/Chart.yaml \
+	&& sed -i "s/^version:.*/version: 0.0.1-$(GIT_VERSION)/g" ../svc-cat-etcd/Chart.yaml \


Do we want the version of the etcd operator chart tied explicitly to the version of OSBA? I'm thinking not, but am willing to be convinced otherwise.

Is it possible that Azure/helm-charts is a better home for this new chart?

The new install docs, however, do clearly belong in this repo. No question there.

Do we want the version of the etcd operator chart tied explicitly to the version of OSBA? I'm thinking not, but am willing to be convinced otherwise.

It's not really the etcd operator chart, it's the chart that creates the cluster for service ctalog...but that doesn't change the fact that the answer is probably not.

Is it possible that Azure/helm-charts is a better home for this new chart?

Possible. I thought we had kind of turned that repo into something more akin to just examples. I could go either way.

I thought we had kind of turned that repo into something more akin to just examples.

Ya... I've been saying that, haven't I? Maybe I wasn't saying what I meant...

All I wanted to avoid was indiscriminately filling that repo with lots of forks of upstream charts that create additional burden without adding a lot of value. The highest value things sort of ended up being demonstrations of services that we didn't already have demos for-- i.e. examples, as you say.

idk if examples need to be the only use for that repo, though.

In my mind, the best place to keep chart source is close to the app source. (That's why the OSBA chart is here in this repo.) In this case, there is no app source (so to speak). The chart just contains resources managed by an operator. That makes me feel a little bit like it's out of place here.

There is, perhaps, an even stronger argument to be made, however, by acknowledging that the etcd this creates is only indirectly a prerequisite of OSBA. The thing most proximately dependent on it is svc cat...

That being the case, I wonder if we should be trying to upstream this to svc cat instead. It may even be that their documentation should be going over "here's how to run a decent etcd in production and here's a chart for it" instead of ours doing that. Perhaps ours should just say "follow the directions for setting up production-grade svc cat."

Thoughts?

The only issue I have with trying to upstream this is that it's very Azure specific. AFAIK, the operator only supports AWS and Azure for backup/recovery, so it would be of limited utility I think to the community in general. Happy to open it and see what happens.

jeremyrickard requested a review from krancour as a code owner June 13, 2018 20:59

jeremyrickard changed the title ~~Create a new install guide~~ WIP - Create a new install guide Jun 13, 2018

jeremyrickard added the in-progress label Jun 13, 2018

carolynvs reviewed Jun 14, 2018

View reviewed changes

jeremyrickard added 6 commits June 19, 2018 11:08

Initial install guide file

8a3bb5c

Adding Helm Chart

b0b6975

Update makefile to publish svc-cat-etcd chart

9c1b019

Fixing markdown

5cd77ad

Wording change

6d8c38a

Fix spelling issue

f81c642

jeremyrickard force-pushed the more-than-quickstart branch from ac2db94 to f81c642 Compare June 19, 2018 17:09

jeremyrickard added 2 commits June 20, 2018 08:10

Cleanup and Code Review

82cabf3

whitespace cleanup

f083a16

jeremyrickard changed the title ~~WIP - Create a new install guide~~ Create a new install guide Jun 25, 2018

jeremyrickard removed the in-progress label Jun 25, 2018

Merge branch 'master' into more-than-quickstart

c753215

krancour reviewed Jul 5, 2018

View reviewed changes

jeremyrickard added 3 commits July 5, 2018 09:23

Don't tie the svc cat cluster chart to osba version

0740f08

Merge branch 'master' into more-than-quickstart

ebdad8a

Merge branch 'master' into more-than-quickstart

58fa497

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create a new install guide #479

Create a new install guide #479

jeremyrickard commented Jun 13, 2018

carolynvs Jun 14, 2018

carolynvs Jun 14, 2018

carolynvs Jun 14, 2018

carolynvs Jun 14, 2018

jeremyrickard Jun 20, 2018

carolynvs Jun 14, 2018

jeremyrickard Jun 20, 2018

carolynvs Jun 14, 2018

jeremyrickard Jun 20, 2018

carolynvs Jun 14, 2018

jeremyrickard Jun 20, 2018

carolynvs Jun 14, 2018

carolynvs Jun 14, 2018 •

edited

Loading

carolynvs Jun 14, 2018

carolynvs Jun 14, 2018

carolynvs Jun 14, 2018

carolynvs Jun 14, 2018

carolynvs Jun 14, 2018

carolynvs Jun 14, 2018

carolynvs Jun 14, 2018

krancour commented Jun 15, 2018

jeremyrickard commented Jun 15, 2018

krancour Jul 5, 2018

jeremyrickard Jul 5, 2018

krancour Jul 6, 2018 •

edited

Loading

jeremyrickard Jul 12, 2018

		@@ -0,0 +1,407 @@
		# Install and Operate Open Service Broker for Azure on an Azure Container Service managed cluster

		Open Service Broker for Azure allows you to provision Azure services from your Kubernetes cluster. OSBA is integrated with Kubernetes using [Service Catalog](https://github.com/kubernetes-incubator/service-catalog). Both Service Catalog and OSBA have data persistence needs. When using Service Catalog and OSBA for development, it is sufficient to use the embedded storage options available with each application. For production use cases, however, we recommend more robust solutions. This guide provides details on setting up OSBA and associated software including Service Catalog, etcd and Redis for production scenarios. If you are new to OSBA, you may find the [AKS](quickstart-aks.md) or [Minikube](quickstart-minikube.md) Quickstart guides useful.


		#### Create a Kubernetes cluster using AKS

		* As AKS is currently in preview, you will need to enable it in your subscription



		First, save your desired account name to an environment variable. It will be reused a few times.
		Bash


		#### Create etcd Cluster

		Once etcd Operator has been installed, you can create a cluster. For production scenarios, we recommend a three node cluster. For convenience purposes, we have provided a Helm chart that will create a cluster and configure a Kubernetes CronJob to enable automatic backups of the cluster.


		Service Catalog requires etcd to persist state for everything it manages. We recommend using etcd Operator to install and manage an etcd cluster for Service Catalog. We have included sample values.yaml file to setup etcd operator with a version that supports Azure backup.

		```console


		Once you have created an etcd cluster, it is time to install Service Catalog. You will use Helm to install Service Catalog. There are a few values you will need to override for your Service Catalog installation:

		* RBAC must be disabled (pending AKS support)


		## Create Azure Redis Cache

		Open Service Broker for Azure uses Redis as a backing store for its state. We recommend using a managed Redis service, such as Azure Redis Cache. By default, Azure Redis Cache only keeps data in memory. For best results, you will want to use the Premium tier in order to configure backups of the Redis data. Please see [How to configure data persistence for a Premium Azure Redis Cache](https://docs.microsoft.com/en-us/azure/redis-cache/cache-how-to-premium-persistence) for instructions on how to create an Azure Redis Cache. Once created, you can obtain the hostname and keys from the Portal or via the CLI.

Create a new install guide #479

Are you sure you want to change the base?

Create a new install guide #479

Conversation

jeremyrickard commented Jun 13, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carolynvs Jun 14, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

krancour commented Jun 15, 2018

jeremyrickard commented Jun 15, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

krancour Jul 6, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carolynvs Jun 14, 2018 •

edited

Loading

krancour Jul 6, 2018 •

edited

Loading