From 933ea734fe57245ace7c5bc01502bcd426274043 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Mon, 28 Aug 2017 14:21:50 -0700 Subject: [PATCH] Splitting the walkthrough up For 1.6 and 1.7 instructions --- README.md | 3 + contrib/examples/walkthrough/README.md | 6 +- docs/devguide.md | 4 +- docs/install-1.6.md | 165 ++++++++++++++ ...pi-aggregation-setup.md => install-1.7.md} | 131 ++++++----- docs/introduction.md | 65 ++++++ docs/{walkthrough.md => walkthrough-1.6.md} | 212 ++---------------- docs/walkthrough-1.7.md | 8 + 8 files changed, 340 insertions(+), 254 deletions(-) create mode 100644 docs/install-1.6.md rename docs/{api-aggregation-setup.md => install-1.7.md} (56%) create mode 100644 docs/introduction.md rename docs/{walkthrough.md => walkthrough-1.6.md} (53%) create mode 100644 docs/walkthrough-1.7.md diff --git a/README.md b/README.md index 1cf4f181dd1..b1e56ae51f3 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, 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 47c8d6156c9..18735caa4a5 100644 --- a/docs/devguide.md +++ b/docs/devguide.md @@ -266,5 +266,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..54e9b215ed4 --- /dev/null +++ b/docs/install-1.6.md @@ -0,0 +1,165 @@ +# 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 [install-1.7.md](./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](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 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 "Cleaning Up" section below. 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, 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](./walkthrough-1.6.md#troubleshooting) +section of the walkthrough document for details. diff --git a/docs/api-aggregation-setup.md b/docs/install-1.7.md similarity index 56% rename from docs/api-aggregation-setup.md rename to docs/install-1.7.md index 0df07de61e3..282d57ee436 100644 --- a/docs/api-aggregation-setup.md +++ b/docs/install-1.7.md @@ -1,17 +1,28 @@ +# Installing Service Catalog on Clusters Running Kubernetes 1.7 and Above -# Setting up Service Catalog for API Aggregation in Kubernetes +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 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. +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 tooling, authentication and +authorization. + +The Service Catalog utilizes API aggregation to present its API. Read on +to discover how to install it. + +# Step 1 - 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 +32,57 @@ 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). -For background on why we're messing with certificates and CA's at all, -please check [the auth doc](auth.md). +## Install `cfssl` Tools -# Steps +Before we continue, you'll need to install the `cfssl` tools: -## Prerequisites -You need `cfssl` tools, install with `go get -u github.com/cloudflare/cfssl/cmd/...`. +```console +go get -u github.com/cloudflare/cfssl/cmd/... +``` + +## Create a Certificates Directory -It is recommended to create a fresh directory, such as `certs/`, to -hold the generated config and certificates, before running the script. +Please create a fresh directory called `certs` to hold the configuration +and certificates that we'll generate in the following steps: -## Check that aggregator is enabled +```console +mkdir certs +``` -`kubectl api-versions` MUST list `apiregistration.k8s.io/v1beta1` (or -`apiregistration.k8s.io/v1alpha1` if running in kubernetes v1.6) +## Check That the API Aggregator is Enabled -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. +Run the following: -## Variables used during the rest of the steps +```console +kubectl api-versions +``` -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. +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). + +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. + +## Create Environment Variables + +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. + +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`. + +`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. ``` export HELM_RELEASE_NAME=catalog @@ -66,20 +90,17 @@ export SVCCAT_NAMESPACE=catalog export SVCCAT_SERVICE_NAME=${HELM_RELEASE_NAME}-catalog-apiserver ``` -## Set up the certificate bundle +## Create Our Own CA and Generate Keys -The APIService expects a certificate bundle. We can create our own, or +The `APIService` resource expects a certificate bundle. We can create our own, or pull the one from kube core for reuse. The certificate bundle is made up of Certificate Authority, a Serving -Certificate, and the Serving Private Key. - -### Create our own new CA and generate keys +Certificate, and the Serving Private Key. -This is an example. It is written with zero understanding of the best -practices of secure certificate generation. +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 +144,7 @@ export SC_SERVING_CERT=apiserver.pem export SC_SERVING_KEY=apiserver-key.pem ``` -## Get the appropriate tls ca/cert/key from kube +## 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 +165,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 +181,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 +191,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 @@ -207,9 +228,9 @@ 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. +Before installing the helm chart, run the script in the `contrib` directory +by `source`ing it. From the root of this repository, run this command: ```shell -source /contrib/svc-cat-apiserver-aggregation-tls-setup.sh +source ./contrib/svc-cat-apiserver-aggregation-tls-setup.sh ``` diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 00000000000..d8e3913bed7 --- /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) + +## 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/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..eb820272f9d 100644 --- a/docs/walkthrough.md +++ b/docs/walkthrough-1.6.md @@ -3,146 +3,18 @@ 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 [install-1.6.md](./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 +36,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 +98,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 +144,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 +203,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 +276,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 +294,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 +303,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 +320,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.