Splitting up the Walkthrough for 1.6 and 1.7 instructions

.gitignore

@@ -20,3 +20,4 @@ contrib/build/*/tmp/*
 .pkg
 .kube
 .var
+docs/certs

README.md

@@ -40,6 +40,9 @@ _somewhere_ in a simple way:
     application configuration primitives in Kubernetes: Services, Secrets, and
     ConfigMaps.
 
+For more introduction, installation and self-guided demo instructions, please
+see the [introduction](./docs/introduction.md) doc.
+
 For more details about the design and features of this project see the
 [design](docs/design.md) doc.
 

contrib/examples/walkthrough/README.md

@@ -1,4 +1,6 @@
 ## Walkthrough Resources
 
-This directory contains API resources for use with the [demo
-walkthrough](../../../docs/walkthrough.md).
+This directory contains API resources for use with the demo walkthrough.
+
+Please see [the introduction document](../../../docs/introduction.md) for 
+instructions.

docs/devguide.md

@@ -267,5 +267,5 @@ the Kubernetes cluster as third party resources.
 
 ## Demo walkthrough
 
-Check out the [walk-through](walkthrough.md) for a detailed guide of an example
-deployment.
+Check out the [introduction](./introduction.md) to get started with 
+installation and a self-guided demo.

docs/install-1.6.md

@@ -0,0 +1,167 @@
+# Installing Service Catalog on Clusters Running Kubernetes 1.6 (DEPRECATED)
+
+This document contains instructions for installing the Service Catalog onto
+Kubernetes clusters running version 1.6. Since Service Catalog
+only officially supports versions 1.7 and later, these instructions are 
+deprecated and may be removed at any time.
+
+If you are running a Kubernetes cluster running version 1.7 or later, please 
+see the [installation instructions for 1.7](./install-1.7.md).
+
+# Step 1 - Prerequisites
+
+## Starting Kubernetes with DNS
+
+You *must* have a Kubernetes cluster with cluster DNS enabled. We can't list
+instructions here for enabling cluster DNS for all Kubernetes cluster
+installations, but here are a few notes:
+
+* If you are using Google Container Engine or minikube, you likely have cluster
+DNS enabled already.
+* If you are using hack/local-up-cluster.sh, ensure the
+`KUBE_ENABLE_CLUSTER_DNS` environment variable is set as follows:
+
+```console
+hack/local-up-cluster.sh -O
+```
+
+## Helm
+
+You *must* use [Helm](http://helm.sh/) v2 or newer in the installation steps
+below.
+
+If you already have Helm v2 or newer, execute `helm init` (if you haven't
+already) to install Tiller (the server-side component of Helm), and you should
+be done with Helm setup.
+
+If you don't already have Helm v2, see the
+[installation instructions](https://github.com/kubernetes/helm/blob/master/docs/install.md).
+
+If your kubernetes cluster has
+[RBAC](https://kubernetes.io/docs/admin/authorization/rbac/) enabled, you must
+ensure that the tiller pod has `cluster-admin` access. By default, `helm init`
+installs the tiller pod into `kube-system` namespace, with tiller configured to
+use the `default` service account.
+
+```console
+kubectl create clusterrolebinding tiller-cluster-admin --clusterrole=cluster-admin --serviceaccount=kube-system:default
+```
+
+`cluster-admin` access is required in order for helm to work correctly in
+clusters with RBAC enabled.  If you used the `--tiller-namespace` or
+`--service-account` flags when running `helm init`, the `--serviceaccount` flag
+in the previous command needs to be adjusted to reference the appropriate
+namespace and ServiceAccount name.
+
+## A Recent `kubectl`
+
+As with Kubernetes itself, interaction with the service catalog system is
+achieved through the `kubectl` command line interface. Chances are high that
+you already have this installed, however, the service catalog *requires*
+`kubectl` version 1.6 or newer.
+
+To proceed, we must:
+
+- Download and install `kubectl` version 1.6 or newer.
+- Configure `kubectl` to communicate with the service catalog's API server.
+
+To install `kubectl` follow the [standard instructions](https://kubernetes.io/docs/tasks/kubectl/install/).
+
+For example, on a mac,
+```console
+curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/darwin/amd64/kubectl
+chmod +x ./kubectl
+```
+
+We'll assume hereafter that all `kubectl` commands are using this
+newly-installed executable.
+
+
+# Step 2 - Installing the Service Catalog
+
+The service catalog is packaged as a Helm chart located in the
+[charts/catalog](../charts/catalog) directory in this repository, and supports a
+wide variety of customizations which are detailed in that directory's
+[README.md](../charts/catalog/README.md).
+
+## The Service Catalog Data Store
+
+We'll be interacting with a variety of resources in the following steps. The
+service catalog API server needs to store all of these resources in a data
+store. The data store implementation in the API server is pluggable, and we
+currently support the following implementations:
+
+1. Etcd 3
+2. Third Party Resources (also, known as TPRs) - this is an _alpha_ feature 
+right now. It has known issues and may be removed at any time.
+
+The first implementation requires that the API server has access to an Etcd 3 cluster, and the
+second only requires access to the Kubernetes API to store TPRs.
+
+Even if you store data in TPRs, you should still access data via the service catalog API. It is 
+possible to access data via the TPRs directly, but we don't recommend it.
+
+## Install
+
+To install the service catalog system with Etcd 3 as the backing data store:
+
+```console
+helm install charts/catalog --name catalog --namespace catalog
+```
+
+To install the service catalog system with TPRs as the backing data store:
+
+```console
+helm install charts/catalog --name catalog --namespace catalog --set apiserver.storage.type=tpr,apiserver.storage.tpr.globalNamespace=catalog
+```
+
+Regardless of which data store implementation you choose, the remainder of the steps in this
+walkthrough will stay the same.
+
+## API Server Authentication and Authorization
+
+Authentication and authorization are disabled in the Helm chart by default. To enable them, 
+set the `apiserver.auth.enabled` option on the Helm chart:
+
+```console
+helm install charts/catalog --name catalog --namespace catalog --set apiserver.auth.enabled=true
+```
+
+For more information about certificate setup, see the [documentation on
+authentication and authorization](./auth.md).
+
+
+## Do Overs
+
+If you make a mistake somewhere along the way in this walk-through and want to 
+start over, check out the 
+[Final Cleanup](./walkthrough-1.6.md#Step-9---Final-Cleanup) section in the 
+walkthrough document. Follow those instructions before you start over.
+
+## Step 3 - Configuring `kubectl` to Talk to the API Server
+
+To configure `kubectl` to communicate with the service catalog API server, we'll have to
+get the IP address that points to the `Service` that sits in front of the API server pod(s).
+If you installed the catalog with one of the `helm install` commands above, then this service 
+will be called `catalog-catalog-apiserver`, and be in the `catalog` namespace. 
+
+### Notes on Getting the IP Address
+
+How you get this IP address is highly dependent on your Kubernetes installation
+method. Regardless of how you do it, do not use the Cluster IP of the 
+`Service`. The `Service` is created as a `NodePort` in this walkthrough, you 
+will need to use the address of one of the nodes in your cluster.
+
+### Setting up a New `kubectl` Context
+
+When you determine the IP address of this service, set its value into the `SVC_CAT_API_SERVER_IP`
+environment variable and then run the following commands:
+
+```console
+kubectl config set-cluster service-catalog --server=https://${SVC_CAT_API_SERVER_IP}:30443 --insecure-skip-tls-verify=true
+kubectl config set-context service-catalog --cluster=service-catalog
+```
+
+Note: Your cloud provider may require firewall rules to allow your traffic get in.
+Please refer to the [Troubleshooting](./walkthrough-1.6.md#troubleshooting) 
+section of the walkthrough document for details.

docs/install-1.7.md

@@ -0,0 +1,77 @@
+# Installing Service Catalog on Clusters Running Kubernetes 1.7 and Above
+
+Kubernetes 1.7 or higher clusters run the 
+[API Aggregator](https://kubernetes.io/docs/concepts/api-extension/apiserver-aggregation/),
+which is a specialized proxy server that sits in front of the core API Server.
+
+The aggregator allows user-defined, Kubernetes compatible API servers to come 
+and go inside the cluster, and register themselves on demand to augment the 
+externally facing API that kubernetes offers.
+
+Instead of requiring the end-user to access multiple API servers, the API 
+aggregation system allows many servers to run inside the cluster, and combines
+all of their APIs into one externally facing API. 
+
+This system is very useful from an end-user's perspective, as it allows the 
+client to use a single API point with familiar, consistent tooling, 
+authentication and authorization.
+
+The Service Catalog utilizes API aggregation to present its API.
+
+# Step 1 - Generate TLS Certificates
+
+We provide a script to do all of the steps needed to set up TLS certificates
+that the aggregation system uses. If you'd like to read how to do this setup
+manually, please see the 
+[manual API aggregation setup document](./manual-api-aggregation-setup.md).
+
+Otherwise, read on for automated instructions.
+
+First, create a directory in which certificates will be generated:
+
+```console
+mkdir certs
+cd certs
+```
+
+We'll assume that you're operating from this `docs/certs` directory for the 
+remainder of this document.
+
+Next, create the certs:
+
+```console
+source ../../contrib/svc-cat-apiserver-aggregation-tls-setup.sh
+```
+
+# Step 2 - Install the Helm Chart
+
+Use helm to install the Service Catalog, associating it with the
+configured name ${HELM_NAME}, and into the specified namespace." This
+command also enables authentication and aggregation and provides the
+keys we just generated inline.
+
+The installation commands vary slightly between Linux and Mac OS X because of
+the versions of the `base64` command (Linux has GNU base64, Mac OS X has BSD 
+base64). If you're installing from a Linux based machine, run this:
+
+```
+helm install ../../charts/catalog \
+    --name ${HELM_RELEASE_NAME} --namespace ${SVCCAT_NAMESPACE} \
+    --set apiserver.auth.enabled=true \
+        --set useAggregator=true \
+        --set apiserver.tls.ca=$(base64 --wrap 0 ${SC_SERVING_CA}) \
+        --set apiserver.tls.cert=$(base64 --wrap 0 ${SC_SERVING_CERT}) \
+        --set apiserver.tls.key=$(base64 --wrap 0 ${SC_SERVING_KEY})
+```
+
+If you're on a Mac OS X based machine, run this:
+
+```
+helm install ../../charts/catalog \
+    --name ${HELM_RELEASE_NAME} --namespace ${SVCCAT_NAMESPACE} \
+    --set apiserver.auth.enabled=true \
+        --set useAggregator=true \
+        --set apiserver.tls.ca=$(base64 ${SC_SERVING_CA}) \
+        --set apiserver.tls.cert=$(base64 ${SC_SERVING_CERT}) \
+        --set apiserver.tls.key=$(base64 ${SC_SERVING_KEY})
+```

docs/introduction.md

@@ -0,0 +1,65 @@
+# Service Catalog Introduction
+
+The Kubernetes Service Catalog provides a Kubernetes-native interface to one
+or more [Open Service Broker API](https://openservicebrokerapi.org/) compatible
+service brokers.
+
+# Concepts
+
+The service catalog API has five main concepts:
+
+- Open Service Broker API Server: A server that acts as a service broker and conforms to the 
+[Open Service Broker API](https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md)
+specification. This software could be hosted within your own Kubernetes cluster
+or elsewhere.
+
+The remaining four concepts all map directly to new Kubernetes resource types
+that are provided by the service catalog API.
+
+- `ServiceBroker`: An in-cluster representation of a broker server. A resource of this
+type encapsulates connection details for that broker server. These are created
+and managed by cluster operators who wish to use that broker server to make new
+types of managed services available within their cluster.
+- `ServiceClass`: A *type* of managed service offered by a particular broker.
+Each time a new `ServiceBroker` resource is added to the cluster, the service catalog
+controller connects to the corresponding broker server to obtain a list of
+service offerings. A new `ServiceClass` resource will automatically be created
+for each.
+- `ServiceInstance`: A provisioned instance of a `ServiceClass`. These are created
+by cluster users who wish to make a new concrete _instance_ of some _type_ of
+managed service to make that available for use by one or more in-cluster
+applications. When a new `ServiceInstance` resource is created, the service catalog
+controller will connect to the appropriate broker server and instruct it to
+provision the service instance.
+- `ServiceInstanceCredential`: Access credential to a `ServiceInstance`. These
+are created by cluster users who wish for their applications to make use of a
+service `ServiceInstance`. Upon creation, the service catalog controller will
+create a Kubernetes `Secret` containing connection details and credentials for
+the service instance. Such `Secret`s can be mounted into pods as usual.
+
+These concepts and resources are the building blocks of the service catalog.
+
+# Installation
+
+Service Catalog installs into a Kubernetes cluster and runs behind the
+[Kubernetes API Aggregator](https://kubernetes.io/docs/concepts/api-extension/apiserver-aggregation/).
+
+The aggregator works best in Kubernetes versions 1.7 and above, so we only
+provide official support for Kubernetes 1.7 or higher. We do, however,
+provide instructions for versions 1.6 and lower. They are no longer 
+maintained and we do not recommend using them to run a production installation
+of Service Catalog.
+
+## Kubernetes 1.7 and Above
+
+- [Installation instructions](./install-1.7.md)
+- [Demo instructions](./walkthrough-1.7.md) (this is a work in progress)
+
+## Kubernetes 1.6 (Deprecated)
+
+We recommend that you run Service Catalog on Kubernetes version 1.7 or higher.
+The 1.6 instructions are deprecated, not maintained and may be removed in the
+future.
+
+- [Installation instructions](./install-1.6.md)
+- [Demo instructions](./walkthrough-1.6.md)