diff --git a/.gitignore b/.gitignore index 363d77ffb09..d04a92bb284 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,4 @@ contrib/build/*/tmp/* .pkg .kube .var +docs/certs diff --git a/README.md b/README.md index 1cf4f181dd1..dd7a2267037 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,9 @@ _somewhere_ in a simple way: application configuration primitives in Kubernetes: Services, Secrets, and ConfigMaps. +For more introduction, including 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. diff --git a/contrib/examples/walkthrough/README.md b/contrib/examples/walkthrough/README.md index f608be0d894..40ae1f71bde 100644 --- a/contrib/examples/walkthrough/README.md +++ b/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. diff --git a/docs/devguide.md b/docs/devguide.md index 313f53fd65a..23139fbe3b7 100644 --- a/docs/devguide.md +++ b/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. diff --git a/docs/install-1.6.md b/docs/install-1.6.md new file mode 100644 index 00000000000..eeb8e599fe0 --- /dev/null +++ b/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 +KUBE_ENABLE_CLUSTER_DNS=true 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" section in the +[walkthrough document](./walkthrough-1.6.md). 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. diff --git a/docs/install-1.7.md b/docs/install-1.7.md new file mode 100644 index 00000000000..1b383db5f64 --- /dev/null +++ b/docs/install-1.7.md @@ -0,0 +1,159 @@ +# 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 API 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. + +# Prerequisites + +# 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 a cloud-based Kubernetes cluster 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 and then run the install +script + +## 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). + +## RBAC + +Your Kubernetes cluster must have RBAC enabled, and your Tiller pod needs to +have `cluster-admin` access. If you are using Minikube, make sure to run +your `minikube start` command with this flag: + +```console +minikube start --extra-config=apiserver.Authorization.Mode=RBAC +``` + +AssumingBy default, `helm init` installs the Tiller pod into the `kube-system` +namespace, with Tiller configured to use the `default` service account. + +Configure Tiller with `cluster-admin` access with the following command: + +```console +kubectl create clusterrolebinding tiller-cluster-admin \ + --clusterrole=cluster-admin \ + --serviceaccount=kube-system:default +``` + +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 that all `kubectl` commands are using this newly-installed +executable. + +# 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, install the `cfssl` toolchain (which the following script uses): + +```console +go get -u github.com/cloudflare/cfssl/cmd/... +``` + +Finally, 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}) +``` diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 00000000000..2648535615b --- /dev/null +++ b/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) diff --git a/docs/api-aggregation-setup.md b/docs/manual-api-aggregation-setup.md similarity index 62% rename from docs/api-aggregation-setup.md rename to docs/manual-api-aggregation-setup.md index 72632d9fb30..e3114da4f8b 100644 --- a/docs/api-aggregation-setup.md +++ b/docs/manual-api-aggregation-setup.md @@ -1,17 +1,16 @@ +# Manual API Aggregation Setup -# Setting up Service Catalog for API Aggregation in Kubernetes +This document describes how to manually set up artifacts that the helm chart +for Service Catalog needs to integrate with the API aggregator. -The aggregator is a server that sits in front of the core API -Server. It allows API servers to come and go and register themselves -on demand to increase the API that kubernetes offers. Instead of -having multiple API servers on different ports, it allows them all to -be combined and aggregated together. This is good for several -reasons. It allows a client to only use a single API point. This -provides a much better user experience. It allows the server to be -secured once behind a single API point. +This repository provides a script to automatically set those artifacts up, and +we recommend that you use it. If you'd like to do so, please see the +[install document](./install-1.7.md). + +# Step 1 - Create TLS Certificates We need to provide a set of certificates to be provided as a -certificate bundle to the APIService apiregistration endpoint. +certificate bundle to the `APIService` resource. For development purposes, it is convenient to use the existing CA automatically set up by the kubernetes development environment. The @@ -21,44 +20,58 @@ kubernetes infrastructure CAs or certificates. This script should be `source`ed to define all of the variables it contains in the current shell process. -The aggregator is a new feature of kubernetes and is an alpha API -running as a separate pod in kubernetes v1.6. The aggregator is -enabled by default in kubernetes v1.7 as a beta API, and is the -default secure endpoint directly integrated into the core kubernetes -APIServer. +For background on why we need to deal with certificates and CA's at all, you +may read the [the auth doc](auth.md) (this is not required, however). + +## Install `cfssl` Tools + +Before we continue, you'll need to install the `cfssl` tools: + +```console +go get -u github.com/cloudflare/cfssl/cmd/... +``` + +## Create a Certificates Directory + +Please create a fresh directory called `certs` to hold the configuration +and certificates that we'll generate in the following steps: + +```console +mkdir certs +cd certs +``` -For background on why we're messing with certificates and CA's at all, -please check [the auth doc](auth.md). +## Check That the API Aggregator is Enabled -# Steps +Run the following: -## Prerequisites -You need `cfssl` tools, install with `go get -u github.com/cloudflare/cfssl/cmd/...`. +```console +kubectl api-versions +``` -It is recommended to create a fresh directory, such as `certs/`, to -hold the generated config and certificates, before running the script. +This endpoint must list `apiregistration.k8s.io/v1beta1`. If it does not, your +Kubernetes installation is likely version 1.6 or previous. We recommend running +1.7 or later, but if you decide to continue, please see the +[installation document for Kubernetes 1.6](./install-1.6.md). -## Check that aggregator is enabled +This `apiregistration.k8s.io/v1beta1` API Group will not show up if you are +connecting to the insecure port of the core API server, so be sure that your +`kubectl` configuration file (often located at `~/.kube/config`) is pointing +to an https endpoint. -`kubectl api-versions` MUST list `apiregistration.k8s.io/v1beta1` (or -`apiregistration.k8s.io/v1alpha1` if running in kubernetes v1.6) +## Create Environment Variables -This API Group will not show up if you are talking to the insecure -port. The insecure port is not behind the aggregator. The aggregator -does not support routing of requests to the insecure port. You must -talk to the secure port, as the aggregator does not serve an API on -the insecure port. +The following environment variables will be used during the following steps. +They will be passed to the certificate generation tools as well as the final +`helm install` step. -## Variables used during the rest of the steps +They are important to set, as the signed certificates will be bound to the +exact service name that is defined below as `SVCCAT_SERVICE_NAME`. -These will be used during the steps and for the final `helm -install`. They are key to set, as the signed certificates will be -bound to the exact service name that is defined below as -`SVCCAT_SERVICE_NAME`. `SVCCAT_SERVICE_NAME` will be the exact DNS -entry that the generated certificate is bound to, so any deviation -from the use of these defined variables will result in a certificate -that is useless for the purposes of aggregation. All of the DNS -entries must match. +`SVCCAT_SERVICE_NAME` will be the exact DNS entry that the generated +certificate is bound to, so any deviation from the use of these defined +variables will result in a certificate that is useless for the purposes of +aggregation. ``` export HELM_RELEASE_NAME=catalog @@ -66,20 +79,21 @@ export SVCCAT_NAMESPACE=catalog export SVCCAT_SERVICE_NAME=${HELM_RELEASE_NAME}-catalog-apiserver ``` -## Set up the certificate bundle +## Get a Certificate Authority (CA) and Keys -The APIService expects a certificate bundle. We can create our own, or -pull the one from kube core for reuse. +There are two options to get a CA and keys. -The certificate bundle is made up of Certificate Authority, a Serving -Certificate, and the Serving Private Key. +### Option 1 - Create Our Own CA and Generate Keys -### Create our own new CA and generate keys +The `APIService` resource expects a certificate bundle. We can create our own, +or pull the one core Kubernetes API server for reuse. -This is an example. It is written with zero understanding of the best -practices of secure certificate generation. +The certificate bundle is made up of Certificate Authority, a Serving +Certificate, and the Serving Private Key. -``` +Run the following to create a CA and generate keys: + +```console export CA_NAME=ca export ALT_NAMES="\"${SVCCAT_SERVICE_NAME}.${SVCCAT_NAMESPACE}\",\"${SVCCAT_SERVICE_NAME}.${SVCCAT_NAMESPACE}.svc"\" @@ -123,7 +137,7 @@ export SC_SERVING_CERT=apiserver.pem export SC_SERVING_KEY=apiserver-key.pem ``` -## Get the appropriate tls ca/cert/key from kube +### Options 2 - Get the Appropriate TLS CA, Certificate and Key from Kubernetes If you are in a cloud provider environment, you most likely do not have access to the appropriate keys. @@ -144,14 +158,14 @@ cp /var/run/kubernetes/${SERVINGCA_CERT} . cp /var/run/kubernetes/${SERVINGCA_KEY} . ``` -### Create a cfssl config file for a new signing key +## Create a cfssl Config File For a New Signing Key ``` export PURPOSE=server echo '{"signing":{"default":{"expiry":"43800h","usages":["signing","key encipherment","'${PURPOSE}'"]}}}' > "${PURPOSE}-ca-config.json" ``` -### Use the existing keys plus the config file to generate the new signing certificate and key +## Use the Existing Keys and the Config File to Generate the New Signing Certificate and Key ``` export NAME_SPACE=catalog @@ -160,7 +174,7 @@ export ALT_NAMES="\"${SERVICE_NAME}.${NAME_SPACE}\",\"${SERVICE_NAME}.${NAME_SPA echo '{"CN":"'${SERVICE_NAME}'","hosts":['${ALT_NAMES}'],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=${SERVINGCA_CERT} -ca-key=${SERVINGCA_KEY} -config=server-ca-config.json - | cfssljson -bare apiserver ``` -### Final Key Names +## Final Key Names These variables define the final names of the resulting keys. @@ -170,7 +184,7 @@ export SC_SERVING_CERT=apiserver.pem export SC_SERVING_KEY=apiserver-key.pem ``` -## Install the Service Catalog Chart with Helm +# Step 2 - Install the Service Catalog Chart with Helm Use helm to install the Service Catalog, associating it with the configured name ${HELM_NAME}, and into the specified namespace." This @@ -220,12 +234,3 @@ export SERVICECATALOGCONFIG=~/.kube/config export KUBECONFIG=~/.kube/config make test-e2e ``` - -# Summary - -Before installing the helm chart, run the script in contrib by -`source`ing it, to define all of the necessary variables. - -```shell -source /contrib/svc-cat-apiserver-aggregation-tls-setup.sh -``` diff --git a/docs/walkthrough.md b/docs/walkthrough-1.6.md similarity index 53% rename from docs/walkthrough.md rename to docs/walkthrough-1.6.md index 139c593e002..935bccccf18 100644 --- a/docs/walkthrough.md +++ b/docs/walkthrough-1.6.md @@ -1,148 +1,21 @@ -# Service Catalog Demonstration Walkthrough +# Service Catalog Demonstration Walkthrough (DEPRECATED) This document outlines the basic features of the service catalog by walking through a short demo. -## Step 0 - Prerequisites +This document contains instructions for a self-guided demo of the Service +Catalog for 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. -### Starting Kubernetes with DNS +If you are running a Kubernetes cluster running version 1.7 or later, please +see [walkthrough-1.7.md](./walkthrough-1.7.md). -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: +This document assumes that you've installed Service Catalog onto your cluster. +If you haven't, please see the +[installation instructions for 1.6](./install-1.6.md). -* 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 -``` - -### Getting Helm and installing Tiller - -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. - - -## Step 1 - 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](https://github.com/kubernetes-incubator/service-catalog/blob/master/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 - -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 "Cleaning Up" section below. Follow those instructions before you start over. - -## Step 2 - Understanding Service Catalog Components - -The service catalog API has five main concepts: - -- ServiceBroker 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. - -## Step 3 - Installing the UPS ServiceBroker +# Step 1 - Installing the UPS ServiceBroker In order to effectively demonstrate the service catalog, we will require a sample broker server. To proceed, we will deploy the [User Provided Service @@ -164,57 +37,7 @@ To install with defaults: helm install charts/ups-broker --name ups-broker --namespace ups-broker ``` -## Step 4 - Installing the Latest `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 5 - 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, so you'll likely need to use the IP address of the node or 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](#troubleshooting) section for details. - -## Step 6 - Creating a ServiceBroker Resource +# Step 2 - Creating a ServiceBroker Resource Next, we'll register a broker server with the catalog by creating a new [`ServiceBroker`](../contrib/examples/walkthrough/ups-broker.yaml) resource. @@ -276,7 +99,7 @@ Notice that the `status` field has been set to reflect that the broker server's catalog of service offerings has been successfully added to our cluster's service catalog. -## Step 7 - Viewing ServiceClasses +# Step 3 - Viewing ServiceClasses The controller created a `ServiceClass` for each service that the UPS broker provides. We can view the `ServiceClass` resources available in the cluster by @@ -322,7 +145,7 @@ plans: externalID: 86064792-7ea2-467b-af93-ac9694d96d52 ``` -## Step 8 - Provisioning a New ServiceInstance +# Step 4 - Provisioning a New ServiceInstance Now that a `ServiceClass` named `user-provided-service` exists within our cluster's service catalog, we can provision an instance of that. We do so by @@ -381,7 +204,7 @@ status: type: Ready ``` -## Step 9 - ServiceInstanceCredential to the ServiceInstance +# Step 5 - ServiceInstanceCredential to the ServiceInstance Now that our `ServiceInstance` has been created, we can bind to it. To accomplish this, we will create a [`ServiceInstanceCredential`](../contrib/examples/walkthrough/ups-instance-credential.yaml) @@ -454,7 +277,7 @@ ups-instance-credential Opaque 2 Notice that a new `Secret` named `ups-instance-credential` has been created. -## Step 10 - Unbinding from the ServiceInstance +# Step 6 - Unbinding from the ServiceInstance Now, let's unbind from the instance. To do this, we simply *delete* the `ServiceInstanceCredential` resource that we previously created: @@ -472,7 +295,7 @@ NAME TYPE DATA AGE default-token-3k61z kubernetes.io/service-account-token 3 30m ``` -## Step 11 - Deprovisioning the ServiceInstance +# Step 7 - Deprovisioning the ServiceInstance Now, we can deprovision the instance. To do this, we simply *delete* the `ServiceInstance` resource that we previously created: @@ -481,7 +304,7 @@ Now, we can deprovision the instance. To do this, we simply *delete* the kubectl --context=service-catalog delete -n test-ns instances ups-instance ``` -## Step 12 - Deleting the ServiceBroker +# Step 8 - Deleting the ServiceBroker Next, we should remove the broker server, and the services it offers, from the catalog. We can do so by simply deleting the broker: @@ -498,7 +321,7 @@ kubectl --context=service-catalog get serviceclasses No resources found ``` -## Step 13 - Final Cleanup +# Step 9 - Final Cleanup To clean up, delete all our helm deployments: diff --git a/docs/walkthrough-1.7.md b/docs/walkthrough-1.7.md new file mode 100644 index 00000000000..a8a842d7b42 --- /dev/null +++ b/docs/walkthrough-1.7.md @@ -0,0 +1,8 @@ +# Service Catalog Demonstration Walkthrough + +This document assumes that you've installed Service Catalog onto your cluster. +If you haven't, please see [install-1.7.md](./install-1.7.md). + +This document is a work in progress. Instructions for the self-guided demo +will be similar to those in the [1.6 walkthrough](./walkthrough-1.6.md), +but note that the commands in that document will not work as-is.