Service Catalog docs (kubernetes#5867)

* Service Catalog docs (+16 squashed commits) Squashed commits: [765e81d] rework install-service-catalog.md [d81f799] tweak diagrams [b7a3da7] Add tooltips [3b256c5] more rework [828000e] architecture diagram redux [0b809d5] rework [7829301] Outline provision-bind-external-service.md w/ filler text [144fbb3] install service catalog v1 [47b5be4] Reorder images and bullet points [fb577ae] Update What's Next links [8ac984c] Include snippet for install and provision docs [c2eeece] Add Install Service Catalog doc [a84df64] Add hard line break [7fb12c6] Add task [75c46d3] Add List, Provision, and Bind diagrams [6386feb] Service Catalog concept doc * Add install-service-catalog-using-helm * switch mysql examples to message queuing instead * Incorporate feedback * incorporate additional feedback * Incorporate tech review feedback
leihenshang · Nov 21, 2017 · bb0d277 · bb0d277
1 parent e7e7aa0
commit bb0d277
Show file tree

Hide file tree

Showing 13 changed files with 1,055 additions and 1 deletion.
diff --git a/_data/concepts.yml b/_data/concepts.yml
@@ -33,6 +33,7 @@ toc:
     - docs/concepts/cluster-administration/network-plugins.md
     - docs/concepts/cluster-administration/device-plugins.md
     - docs/concepts/cluster-administration/sysctl-cluster.md
+  - docs/concepts/service-catalog/index.md
 
 - title: Containers
   section:

diff --git a/_data/glossary/managed-service.yaml b/_data/glossary/managed-service.yaml
@@ -0,0 +1,9 @@
+id: managed-service
+name: Managed Service
+tags:
+- extension
+short-description: >
+  A software offering maintained by a third-party provider.
+long-description: >
+  Some examples of Managed Services are AWS EC2, Azure SQL Database, and GCP Pub/Sub, but they can be any software offering that can be used by an application.
+  [Service Catalog](/docs/concepts/service-catalog/) provides a way to list, provision, and bind with Managed Services offered by {% glossary_tooltip text="Service Brokers" term_id="service-broker" %}.
diff --git a/_data/glossary/service-broker.yaml b/_data/glossary/service-broker.yaml
@@ -0,0 +1,9 @@
+id: service-broker
+name: Service Broker
+tags:
+- extension
+short-description: >
+  An endpoint for a set of {% glossary_tooltip text="Managed Services" term_id="managed-service" %} offered and maintained by a third-party.
+long-description: >
+  {% glossary_tooltip text="Service Brokers" term_id="service-broker" %} implement the [Open Service Broker API spec](https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md) and provide a standard interface for applications to use their Managed Services.
+  [Service Catalog](/docs/concepts/service-catalog/) provides a way to list, provision, and bind with Managed Services offered by Service Brokers.
diff --git a/_data/glossary/service-catalog.yaml b/_data/glossary/service-catalog.yaml
@@ -0,0 +1,8 @@
+id: service-catalog
+name: Service Catalog
+tags:
+- extension
+short-description: >
+  An extension API that enables applications running in Kubernetes clusters to easily use external managed software offerings, such as a datastore service offered by a cloud provider.
+long-description: >
+  Service Catalog provides a way to list, provision, and bind with external {% glossary_tooltip text="Managed Services" term_id="managed-service" %} from {% glossary_tooltip text="Service Brokers" term_id="service-broker" %} without needing detailed knowledge about how those services are created or managed.
diff --git a/_data/tasks.yml b/_data/tasks.yml
@@ -100,14 +100,16 @@ toc:
   - title: Use Explorer to Examine the Runtime Environment
     path: https://github.com/kubernetes/kubernetes/tree/release-1.5/examples/explorer
 
-- title: Access and Extend the Kubernetes API
+- title: Extend Kubernetes
   section:
   - docs/tasks/access-kubernetes-api/http-proxy-access-api.md
   - docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md
   - docs/tasks/access-kubernetes-api/extend-api-third-party-resource.md
   - docs/tasks/access-kubernetes-api/migrate-third-party-resource.md
   - docs/tasks/access-kubernetes-api/configure-aggregation-layer.md
   - docs/tasks/access-kubernetes-api/setup-extension-api-server.md
+  - docs/tasks/service-catalog/install-service-catalog-using-helm.md
+  - docs/tasks/service-catalog/install-service-catalog-using-sc.md
 
 - title: TLS
   section:

diff --git a/docs/concepts/service-catalog/index.md b/docs/concepts/service-catalog/index.md
@@ -0,0 +1,234 @@
+---
+title: Service Catalog
+approvers:
+- chenopis
+---
+
+{% capture overview %}
+{% glossary_definition term_id="service-catalog" length="all" prepend="Service Catalog is " %}  
+
+A *Service Broker*, as defined by the [Open Service Broker API spec](https://github.com/openClusterServiceBrokerapi/ClusterServiceBroker/blob/v2.13/spec.md), is an endpoint for a set of Managed Services offered and maintained by a third-party, which could be a cloud provider such as AWS, GCP, or Azure.
+Some examples of *Managed Services* are Microsoft Azure Cloud Queue, Amazon Simple Queue Service, and Google Cloud Pub/Sub, but they can be any software offering that can be used by an application.
+
+Using Service Catalog, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can browse the list of {% glossary_tooltip text="Managed Services" term_id="managed-service" %} offered by a {% glossary_tooltip text="Service Brokers" term_id="service-broker" %}, provision an instance of a Managed Service, and bind with it to make it available to an application within the Kubernetes cluster.
+
+{% endcapture %}
+
+
+{% capture body %}
+## Example use case
+
+An {% glossary_tooltip text="Application Developer" term_id="application-developer" %} wants to use message queuing as part of their application running in a Kubernetes cluster.
+However, they do not want to deal with the overhead of setting such a service up and administering it themselves.
+Fortunately, there is a cloud provider that offers message queuing as a *Managed Service* through their *Service Broker*.
+
+A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can setup Service Catalog and use it to communicate with the cloud provider's {% glossary_tooltip text="Service Broker" term_id="service-broker" %} to provision an instance of the message queuing service and make it available to the application within the Kubernetes cluster.
+The {% glossary_tooltip text="Application Developer" term_id="application-developer" %} therefore does not need to concern themselves with the implementation details or management of the message queue.
+Their application can simply use it as a service.
+
+## Architecture
+
+Service Catalog uses the [Open Service Broker API](https://github.com/openClusterServiceBrokerapi/ClusterServiceBroker) to communicate with Service Brokers, acting as an intermediary for the Kubernetes API Server in order to negotiate the initial provisioning and retrieve the credentials necessary for the application to use a Managed Service.
+
+It is implemented as an extension API server and a controller manager, using Etcd for storage. It also uses the [aggregation layer](/docs/concepts/api-extension/apiserver-aggregation/) available in Kubernetes 1.7+ to present its API.
+
+<br>
+
+![Service Catalog Architecture](/images/docs/service-catalog-architecture.svg)
+
+
+### API Resources
+
+Service Catalog installs the `servicecatalog.k8s.io` API and provides the following Kubernetes resources:
+
+* `ClusterServiceBroker`: An in-cluster representation of a Service Broker, encapsulating its server connection details.
+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.
+* `ClusterServiceClass`: A Managed Service offered by a particular Service Broker.
+When a new `ClusterServiceBroker` resource is added to the cluster, the Service Catalog controller connects to the Service Broker to obtain a list of available Managed Services. It then creates a new `ClusterServiceClass` resource corresponding to each Managed Service.
+* `ClusterServicePlan`: A specific offering of a Managed Service. For example, a Managed Service may have different plans available, such as a free tier or paid tier, or it may have different configuration options, such as using SSD storage or having more resources. Similar to `ClusterServiceClass`, when a new `ClusterServiceBroker` is added to the cluster, the Service Catalog creates a new `ClusterServicePlan` resource corresponding to each Service Plan available for each Managed Service.
+* `ServiceInstance`: A provisioned instance of a `ClusterServiceClass`.
+These are created by Cluster Operators to make a specific instance of a Managed Service 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 Service Broker and instruct it to provision the service instance.
+* `ServiceBinding`: Access credentials to a `ServiceInstance`.
+These are created by Cluster Operators who want 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, which can be mounted into Pods.
+
+### Authentication
+
+Service Catalog supports these methods of authentication: 
+
+* Basic (username/password)
+* [OAuth 2.0 Bearer Token](https://tools.ietf.org/html/rfc6750)
+
+## Usage
+
+A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can use the Service Catalog API Resources to provision Managed Services and make them available within a Kubernetes cluster. The steps involved are:
+
+1. Listing the Managed Services and Service Plans available from a Service Broker.
+1. Provisioning a new instance of the Managed Service.
+1. Binding to the Managed Service, which returns the connection credentials.
+1. Mapping the connection credentials into the application.
+
+### Listing Managed Services and Service Plans
+
+First, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} must create a `ClusterServiceBroker` resource within the `servicecatalog.k8s.io` group. This resource contains the URL and connection details necessary to access a Service Broker endpoint.
+
+This is an example of a `ClusterServiceBroker` resource:
+
+```yaml
+apiVersion: servicecatalog.k8s.io/v1beta1
+kind: ClusterServiceBroker
+metadata:
+  name: cloud-broker
+spec:
+  # Points to the endpoint of a Service Broker. (This example is not a working URL.)
+  url:  https://servicebroker.somecloudprovider.com/v1alpha1/projects/service-catalog/brokers/default
+  #####
+  # Additional values can be added here, which may be used to communicate
+  # with the Service Broker, such as bearer token info or a caBundle for TLS.
+  #####
+```
+
+The following is a sequence diagram illustrating the steps involved in listing Managed Services and Plans available from a Service Broker:
+
+![List Services](/images/docs/service-catalog-list.svg){:height="80%" width="80%"}
+
+1. Once the `ClusterServiceBroker` resource is added to Service Catalog, it triggers a *List Services* call to the external Service Broker.
+1. The Service Broker returns a list of available Managed Services and Service Plans, which are cached locally in `ClusterServiceClass` and `ClusterServicePlan` resources.
+1. A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can then get the list of available Managed Services using the following command:
+
+        kubectl get clusterserviceclasses -o=custom-columns=SERVICE\ NAME:.metadata.name,EXTERNAL\ NAME:.spec.externalName
+
+    It should output a list of service names with a format similar to:
+
+        SERVICE NAME                           EXTERNAL NAME
+        4f6e6cf6-ffdd-425f-a2c7-3c9258ad2468   cloud-provider-service
+        ...                                    ...
+
+    They can also view the Service Plans available using the following command:
+
+        kubectl get clusterserviceplans -o=custom-columns=PLAN\ NAME:.metadata.name,EXTERNAL\ NAME:.spec.externalName
+
+    It should output a list of plan names with a format similar to:
+
+        PLAN NAME                              EXTERNAL NAME
+        86064792-7ea2-467b-af93-ac9694d96d52   service-plan-name
+        ...                                    ...
+
+
+### Provisioning a new instance
+
+A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can initiate the provisioning of a new instance by creating a `ServiceInstance` resource. 
+
+This is an example of a `ServiceInstance` resource:
+
+```yaml
+apiVersion: servicecatalog.k8s.io/v1beta1
+kind: ServiceInstance
+metadata:
+  name: cloud-queue-instance
+  namespace: cloud-apps
+spec:
+  # References one of the previously returned services
+  clusterServiceClassExternalName: cloud-provider-service
+  clusterServicePlanExternalName: service-plan-name
+  #####
+  # Additional parameters can be added here, 
+  # which may be used by the Service Broker.
+  #####
+```
+
+The following sequence diagram illustrates the steps involved in provisioning a new instance of a Managed Service:
+
+![Provision a Service](/images/docs/service-catalog-provision.svg){:height="80%" width="80%"}
+
+1. When the `ServiceInstance` resource is created, Service Catalog initiates a *Provision Instance* call to the external Service Broker.
+1. The Service Broker creates a new instance of the Managed Service and returns an HTTP response.
+1. A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can then check the status of the instance to see if it is ready.
+
+### Binding to a Managed Service
+
+After a new instance has been provisioned, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} must bind to the Managed Service to get the connection credentials and service account details necessary for the application to use the service. This is done by creating a `ServiceBinding` resource. 
+
+The following is an example of a `ServiceBinding` resource:
+
+```yaml
+apiVersion: servicecatalog.k8s.io/v1beta1
+kind: ServiceBinding
+metadata:
+  name: cloud-queue-binding
+  namespace: cloud-apps
+spec:
+  instanceRef:
+    name: cloud-queue-instance
+  #####
+  # Additional information can be added here, such as a secretName or 
+  # service account parameters, which may be used by the Service Broker.
+  #####
+```
+
+The following sequence diagram illustrates the steps involved in binding to a Managed Service instance:
+
+![Bind to a Managed Service](/images/docs/service-catalog-bind.svg){:height="80%" width="80%"}
+
+1. After the `ServiceBinding` is created, Service Catalog makes a *Bind Instance* call to the external Service Broker.
+1. The Service Broker enables the application permissions/roles for the appropriate service account.
+1. The Service Broker returns the information necessary to connect and access the Managed Service instance. This is provider and service-specific so the information returned may differ between Service Providers and their Managed Services.
+
+### Mapping the connection credentials
+
+After binding, the final step involves mapping the connection credentials and service-specific information into the application.
+These pieces of information are stored in secrets that the application in the cluster can access and use to connect directly with the Managed Service.
+
+<br>
+
+![Map connection credentials](/images/docs/service-catalog-map.svg)
+
+#### Pod Configuration File
+
+One method to perform this mapping is to use a declarative Pod configuration.
+
+The following example describes how to map service account credentials into the application. A key called `sa-key` is stored in a volume named `provider-cloud-key`, and the application mounts this volume at `/var/secrets/provider/key.json`. The environment variable `GOOGLE_APPLICATION_CREDENTIALS` is mapped from the value of the mounted file.
+
+```yaml
+...
+    spec:
+      volumes:
+        - name: provider-cloud-key
+          secret:
+            secretName: sa-key
+      containers:
+...
+          volumeMounts:
+          - name: provider-cloud-key
+            mountPath: /var/secrets/provider
+          env:
+          - name: PROVIDER_APPLICATION_CREDENTIALS
+            value: "/var/secrets/provider/key.json"
+```
+
+The following example describes how to map secret values into application environment variables. In this example, the messaging queue topic name is mapped from a secret named `provider-queue-credentials` with a key named `topic` to the environment variable `TOPIC`.
+
+
+```yaml
+...
+          env:
+          - name: "TOPIC"
+            valueFrom:
+                secretKeyRef:
+                   name: provider-queue-credentials
+                   key: topic
+```
+
+{% endcapture %}
+
+
+{% capture whatsnext %}
+* If you are familiar with {% glossary_tooltip text="Helm Charts" term_id="helm-chart" %}, [install Service Catalog using Helm](/docs/tasks/service-catalog/install-service-catalog-using-helm/) into your Kubernetes cluster. Alternatively, you can [install Service Catalog using the SC tool](/docs/tasks/service-catalog/install-service-catalog-using-sc/).
+* View [sample service brokers](https://github.com/openClusterServiceBrokerapi/ClusterServiceBroker/blob/master/gettingStarted.md#sample-service-brokers).
+* Explore the [kubernetes-incubator/service-catalog](https://github.com/kubernetes-incubator/service-catalog) project.
+
+{% endcapture %}
+
+
+{% include templates/concept.md %}
diff --git a/docs/tasks/service-catalog/install-service-catalog-using-helm.md b/docs/tasks/service-catalog/install-service-catalog-using-helm.md
@@ -0,0 +1,100 @@
+---
+title: Install Service Catalog using Helm
+approvers:
+- chenopis
+---
+
+{% capture overview %}
+{% glossary_definition term_id="service-catalog" length="long" %}
+
+Use [Helm](https://helm.sh/) to install Service Catalog on your Kubernetes cluster. Up to date information on this process can be found at the [kubernetes-incubator/service-catalog](https://github.com/kubernetes-incubator/service-catalog/blob/master/docs/install.md) repo.
+
+{% endcapture %}
+
+
+{% capture prerequisites %}
+* Understand the key concepts of [Service Catalog](/docs/concepts/service-catalog/).
+* Service Catalog requires a Kubernetes cluster running version 1.7 or higher.
+* You must have a Kubernetes cluster with cluster DNS enabled.
+    * If you are using a cloud-based Kubernetes cluster or {% glossary_tooltip text="Minikube" term_id="minikube" %}, you may already have cluster DNS enabled.
+    * If you are using `hack/local-up-cluster.sh`, ensure that the `KUBE_ENABLE_CLUSTER_DNS` environment variable is set, then run the install script.
+* [Install and setup kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) v1.7 or higher. Make sure it is configured to connect to the Kubernetes cluster.
+* Install [Helm](http://helm.sh/) v2.7.0 or newer.
+    * Follow the [Helm install instructions](https://github.com/kubernetes/helm/blob/master/docs/install.md).
+    * If you already have an appropriate version of Helm installed, execute `helm init` to install Tiller, the server-side component of Helm.
+
+{% endcapture %}
+
+
+{% capture steps %}
+## Add the service-catalog Helm repository
+
+Once Helm is installed, add the *service-catalog* Helm repository to your local machine by executing the following command:
+
+```shell
+helm repo add svc-cat https://svc-catalog-charts.storage.googleapis.com
+```
+
+Check to make sure that it installed successfully by executing the following command:
+
+```shell
+helm search service-catalog
+```
+
+If the installation was successful, the command should output the following:
+
+```
+NAME            VERSION DESCRIPTION
+svc-cat/catalog 0.0.1   service-catalog API server and controller-manag...
+```
+
+## Enable RBAC
+
+Your Kubernetes cluster must have RBAC enabled, which requires your Tiller Pod(s) to have `cluster-admin` access.
+
+If you are using {% glossary_tooltip text="Minikube" term_id="minikube" %}, run the `minikube start` command with the following flag:
+
+```shell
+minikube start --extra-config=apiserver.Authorization.Mode=RBAC
+```
+
+If you are using `hack/local-up-cluster.sh`, set the `AUTHORIZATION_MODE` environment variable with the following values:
+
+```
+AUTHORIZATION_MODE=Node,RBAC hack/local-up-cluster.sh -O
+```
+
+By default, `helm init` installs the Tiller Pod into the `kube-system` namespace, with Tiller configured to use the `default` service account.
+
+**NOTE:** If you used the `--tiller-namespace` or `--service-account` flags when running `helm init`, the `--serviceaccount` flag in the following command needs to be adjusted to reference the appropriate namespace and ServiceAccount name.
+{: .note}
+
+Configure Tiller to have `cluster-admin` access:
+
+```shell
+kubectl create clusterrolebinding tiller-cluster-admin \
+    --clusterrole=cluster-admin \
+    --serviceaccount=kube-system:default
+```
+
+
+## Install Service Catalog in your Kubernetes cluster
+
+Install Service Catalog from the root of the Helm repository using the following command:
+
+```shell
+helm install svc-cat/catalog \
+    --name catalog --namespace catalog
+```
+
+{% endcapture %}
+
+
+{% capture whatsnext %}
+* View [sample service brokers](https://github.com/openservicebrokerapi/servicebroker/blob/master/gettingStarted.md#sample-service-brokers).
+* Explore the [kubernetes-incubator/service-catalog](https://github.com/kubernetes-incubator/service-catalog) project.
+
+{% endcapture %}
+
+
+{% include templates/task.md %}