From 7b6b771d9c522728f4ae0bfa17c55d98bd6fd0ea Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Mon, 28 Aug 2017 14:21:50 -0700 Subject: [PATCH 01/22] 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} (59%) 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 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..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 59% rename from docs/api-aggregation-setup.md rename to docs/install-1.7.md index 72632d9fb30..1816fe6ff71 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 @@ -223,9 +244,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. From c1e2665d9152497de63d38f6ef5a62f711a1fb87 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 11:26:28 -0700 Subject: [PATCH 02/22] Making the readme link relative --- docs/install-1.6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install-1.6.md b/docs/install-1.6.md index 54e9b215ed4..acbdc10162b 100644 --- a/docs/install-1.6.md +++ b/docs/install-1.6.md @@ -82,7 +82,7 @@ newly-installed executable. 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). +[README.md](../charts/catalog/README.md). ## The Service Catalog Data Store From b7afcc4b82d343e1307479b7748f7b17d25d2918 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 11:26:37 -0700 Subject: [PATCH 03/22] Linking to the right final cleanup page --- docs/install-1.6.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/install-1.6.md b/docs/install-1.6.md index acbdc10162b..dc54bcd1af1 100644 --- a/docs/install-1.6.md +++ b/docs/install-1.6.md @@ -133,8 +133,10 @@ 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. +If you make a mistake somewhere along the way in this walk-through and want to +start over, check out the +[Final Cleanup](./walkthrough-1.6.md#Step-9---Final-Cleanup) section in the +walkthrough document. Follow those instructions before you start over. ## Step 3 - Configuring `kubectl` to Talk to the API Server From 79fc07f563e5fbc20af8fd5a806ea7250cac178d Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 11:27:12 -0700 Subject: [PATCH 04/22] Adding period at end of sentence --- docs/install-1.6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install-1.6.md b/docs/install-1.6.md index dc54bcd1af1..1425312f2ff 100644 --- a/docs/install-1.6.md +++ b/docs/install-1.6.md @@ -93,7 +93,7 @@ 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 +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. From 08f96219215bdb942a1e9f79f47e3a665e9e5448 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 11:28:19 -0700 Subject: [PATCH 05/22] Using curly fracked env var syntax --- docs/install-1.6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install-1.6.md b/docs/install-1.6.md index 1425312f2ff..633f41efbb7 100644 --- a/docs/install-1.6.md +++ b/docs/install-1.6.md @@ -158,7 +158,7 @@ When you determine the IP address of this service, set its value into the `SVC_C 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-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 ``` From df2970f90d5ad7c3a70005751a4a82c84434fd33 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 11:29:15 -0700 Subject: [PATCH 06/22] Fixing NodePort language --- docs/install-1.6.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/install-1.6.md b/docs/install-1.6.md index 633f41efbb7..5f73591eabe 100644 --- a/docs/install-1.6.md +++ b/docs/install-1.6.md @@ -147,10 +147,10 @@ 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. +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 From 85523970e0a2cd80c1fe2c2b219a1520c1f31b9e Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 11:29:48 -0700 Subject: [PATCH 07/22] Cd-ing into certs dir --- docs/install-1.7.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/install-1.7.md b/docs/install-1.7.md index 1816fe6ff71..2afea5ac2b2 100644 --- a/docs/install-1.7.md +++ b/docs/install-1.7.md @@ -50,6 +50,7 @@ and certificates that we'll generate in the following steps: ```console mkdir certs +cd certs ``` ## Check That the API Aggregator is Enabled From 0ad2a9a1cbbfefc63d09aabebf0efea648ea33a9 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 11:31:21 -0700 Subject: [PATCH 08/22] Removing file names, replacing with more descriptive text --- docs/install-1.6.md | 2 +- docs/walkthrough-1.6.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/install-1.6.md b/docs/install-1.6.md index 5f73591eabe..27da09145dc 100644 --- a/docs/install-1.6.md +++ b/docs/install-1.6.md @@ -6,7 +6,7 @@ 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). +see the [installation instructions for 1.7](./install-1.7.md). # Step 1 - Prerequisites diff --git a/docs/walkthrough-1.6.md b/docs/walkthrough-1.6.md index eb820272f9d..20e81360b46 100644 --- a/docs/walkthrough-1.6.md +++ b/docs/walkthrough-1.6.md @@ -12,7 +12,8 @@ If you are running a Kubernetes cluster running version 1.7 or later, please see [walkthrough-1.7.md](./walkthrough-1.7.md). 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 haven't, please see the +[installation instructions for 1.6](./install-1.6.md). # Step 1 - Installing the UPS ServiceBroker From fdc2f558a9c226e4c7d85f05893047b941367d80 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 11:31:59 -0700 Subject: [PATCH 09/22] Adding more description to tooling --- docs/install-1.7.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/install-1.7.md b/docs/install-1.7.md index 2afea5ac2b2..bee38775a20 100644 --- a/docs/install-1.7.md +++ b/docs/install-1.7.md @@ -13,8 +13,8 @@ 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. +client to use a single API point with familiar, consistent tooling, +authentication and authorization. The Service Catalog utilizes API aggregation to present its API. Read on to discover how to install it. From a9f90375350e36bbde796538ca13f8b7b9552c45 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 11:32:37 -0700 Subject: [PATCH 10/22] Removing DNS entries note --- docs/install-1.7.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install-1.7.md b/docs/install-1.7.md index bee38775a20..fe996a25f6f 100644 --- a/docs/install-1.7.md +++ b/docs/install-1.7.md @@ -83,7 +83,7 @@ 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. +aggregation. ``` export HELM_RELEASE_NAME=catalog From ca93148cedec2987939ff751e66d86668eac2eb2 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 12:18:50 -0700 Subject: [PATCH 11/22] Kube core => core Kubernetes API server --- docs/install-1.7.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/install-1.7.md b/docs/install-1.7.md index fe996a25f6f..66379f24df4 100644 --- a/docs/install-1.7.md +++ b/docs/install-1.7.md @@ -93,8 +93,8 @@ export SVCCAT_SERVICE_NAME=${HELM_RELEASE_NAME}-catalog-apiserver ## Create Our Own CA and Generate Keys -The `APIService` resource expects a certificate bundle. We can create our own, or -pull the one from kube core for reuse. +The `APIService` resource expects a certificate bundle. We can create our own, +or pull the one core Kubernetes API server for reuse. The certificate bundle is made up of Certificate Authority, a Serving Certificate, and the Serving Private Key. From 7707e94a4b5a8ce517bc72d65391845be2940109 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 12:40:46 -0700 Subject: [PATCH 12/22] Specifying that there are 2 options for getting a CA and keys --- docs/install-1.7.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/install-1.7.md b/docs/install-1.7.md index 66379f24df4..f81369bd197 100644 --- a/docs/install-1.7.md +++ b/docs/install-1.7.md @@ -91,7 +91,11 @@ export SVCCAT_NAMESPACE=catalog export SVCCAT_SERVICE_NAME=${HELM_RELEASE_NAME}-catalog-apiserver ``` -## Create Our Own CA and Generate Keys +## Get a Certificate Authority (CA) and Keys + +There are two options to get a CA and keys. + +### Option 1 - Create Our Own 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. @@ -145,7 +149,7 @@ export SC_SERVING_CERT=apiserver.pem export SC_SERVING_KEY=apiserver-key.pem ``` -## Get the Appropriate TLS CA, Certificate and Key from Kubernetes +### 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. From 46ab2fadec83599a819917c4789bb312a2e4b1a5 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 12:41:38 -0700 Subject: [PATCH 13/22] Noting WIP for the 1.7 walkthrough --- docs/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/introduction.md b/docs/introduction.md index d8e3913bed7..2648535615b 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -53,7 +53,7 @@ of Service Catalog. ## Kubernetes 1.7 and Above - [Installation instructions](./install-1.7.md) -- [Demo instructions](./walkthrough-1.7.md) +- [Demo instructions](./walkthrough-1.7.md) (this is a work in progress) ## Kubernetes 1.6 (Deprecated) From c12c1a583548609f9143a2aa3cdadbd0603e9569 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 12:53:26 -0700 Subject: [PATCH 14/22] Ignoring the certs directory MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The install instructions say that you should create this directory, so let’s ignore it --- .gitignore | 1 + 1 file changed, 1 insertion(+) 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 From 9a862e324cff3a6ed8dc8dd8f5b61f73d0e9b216 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 12:53:46 -0700 Subject: [PATCH 15/22] Splitting the aggregated API install docs w/ script from the manual install docs --- docs/install-1.7.md | 210 ++---------------------- docs/manual-api-aggregation-setup.md | 236 +++++++++++++++++++++++++++ 2 files changed, 251 insertions(+), 195 deletions(-) create mode 100644 docs/manual-api-aggregation-setup.md diff --git a/docs/install-1.7.md b/docs/install-1.7.md index f81369bd197..337fdeca73d 100644 --- a/docs/install-1.7.md +++ b/docs/install-1.7.md @@ -16,187 +16,34 @@ 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. Read on -to discover how to install it. +The Service Catalog utilizes API aggregation to present its API. -# Step 1 - TLS Certificates +# Step 1 - Generate TLS Certificates -We need to provide a set of certificates to be provided as a -certificate bundle to the `APIService` resource. +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). -For development purposes, it is convenient to use the existing CA -automatically set up by the kubernetes development environment. The -[script in contrib](../contrib/svc-cat-apiserver-aggregation-tls-setup.sh) -generates a fresh CA and certificate setup, without using any existing -kubernetes infrastructure CAs or certificates. This script should be -`source`ed to define all of the variables it contains in the current -shell process. +Otherwise, read on for automated instructions. -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: +First, create a directory in which certificates will be generated: ```console mkdir certs cd certs ``` -## Check That the API Aggregator is Enabled - -Run the following: - -```console -kubectl api-versions -``` - -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. - -``` -export HELM_RELEASE_NAME=catalog -export SVCCAT_NAMESPACE=catalog -export SVCCAT_SERVICE_NAME=${HELM_RELEASE_NAME}-catalog-apiserver -``` - -## Get a Certificate Authority (CA) and Keys - -There are two options to get a CA and keys. - -### Option 1 - Create Our Own 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. +We'll assume that you're operating from this `docs/certs` directory for the +remainder of this document. -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: +Next, create the certs: ```console -export CA_NAME=ca - -export ALT_NAMES="\"${SVCCAT_SERVICE_NAME}.${SVCCAT_NAMESPACE}\",\"${SVCCAT_SERVICE_NAME}.${SVCCAT_NAMESPACE}.svc"\" - -export SVCCAT_CA_SETUP=svc-cat-ca.json -cat >> ${SVCCAT_CA_SETUP} << EOF -{ - "hosts": [ ${ALT_NAMES} ], - "key": { - "algo": "rsa", - "size": 2048 - }, - "names": [ - { - "C": "US", - "L": "san jose", - "O": "kube", - "OU": "WWW", - "ST": "California" - } - ] -} -EOF - - -cfssl genkey --initca ${SVCCAT_CA_SETUP} | cfssljson -bare ${CA_NAME} -# now the files 'ca.csr ca-key.pem ca.pem' exist - -export SVCCAT_CA_CERT=${CA_NAME}.pem -export SVCCAT_CA_KEY=${CA_NAME}-key.pem - -export PURPOSE=server -echo '{"signing":{"default":{"expiry":"43800h","usages":["signing","key encipherment","'${PURPOSE}'"]}}}' > "${PURPOSE}-ca-config.json" - -echo '{"CN":"'${SVCCAT_SERVICE_NAME}'","hosts":['${ALT_NAMES}'],"key":{"algo":"rsa","size":2048}}' \ - | cfssl gencert -ca=${SVCCAT_CA_CERT} -ca-key=${SVCCAT_CA_KEY} -config=server-ca-config.json - \ - | cfssljson -bare apiserver - -export SC_SERVING_CA=${SVCCAT_CA_CERT} -export SC_SERVING_CERT=apiserver.pem -export SC_SERVING_KEY=apiserver-key.pem -``` - -### 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. - -The key we are looking for in an already running system is the -`--root-ca-file` flag to the controller-manager. - -The following is an example based on a real kubernetes cluster. The -various files may be named differently and in different locations. - - -``` -export SERVING_NAME=server-ca -export SERVINGCA_CERT=${SERVING_NAME}.crt -export SERVINGCA_KEY=${SERVING_NAME}.key -# a default location -cp /var/run/kubernetes/${SERVINGCA_CERT} . -cp /var/run/kubernetes/${SERVINGCA_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 and the Config File to Generate the New Signing Certificate and Key - -``` -export NAME_SPACE=catalog -export SERVICE_NAME=catalog-catalog-apiserver -export ALT_NAMES="\"${SERVICE_NAME}.${NAME_SPACE}\",\"${SERVICE_NAME}.${NAME_SPACE}.svc"\" -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 - -These variables define the final names of the resulting keys. - -``` -export SC_SERVING_CA=${SERVINGCA_CERT} -export SC_SERVING_CERT=apiserver.pem -export SC_SERVING_KEY=apiserver-key.pem +source ../../contrib/svc-cat-apiserver-aggregation-tls-setup.sh ``` -# Step 2 - Install the Service Catalog Chart with Helm +# 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 @@ -208,7 +55,7 @@ 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 \ +helm install ../../charts/catalog \ --name ${HELM_RELEASE_NAME} --namespace ${SVCCAT_NAMESPACE} \ --set apiserver.auth.enabled=true \ --set useAggregator=true \ @@ -220,7 +67,7 @@ helm install charts/catalog \ If you're on a Mac OS X based machine, run this: ``` -helm install charts/catalog \ +helm install ../../charts/catalog \ --name ${HELM_RELEASE_NAME} --namespace ${SVCCAT_NAMESPACE} \ --set apiserver.auth.enabled=true \ --set useAggregator=true \ @@ -228,30 +75,3 @@ helm install charts/catalog \ --set apiserver.tls.cert=$(base64 ${SC_SERVING_CERT}) \ --set apiserver.tls.key=$(base64 ${SC_SERVING_KEY}) ``` - -`servicecatalog.k8s.io/v1alpha1` should show up under `kubectl -api-versions` almost immediately, but kubectl will be slow to respond -to other commands until the apiserver is fully running. - -If it doesn't show up the kubectl discovery cache is stale and needs -to be deleted. It may be located in the `.kube` directory, -approximately `~/.kube/cache/discovery/`. - -Now Service Catalog e2e tests should work with the same `kubeconfig` set -for both the core APIServer access and the Service Catalog APIServer -access. - -``` -export SERVICECATALOGCONFIG=~/.kube/config -export KUBECONFIG=~/.kube/config -make test-e2e -``` - -# Summary - -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 -``` diff --git a/docs/manual-api-aggregation-setup.md b/docs/manual-api-aggregation-setup.md new file mode 100644 index 00000000000..e3114da4f8b --- /dev/null +++ b/docs/manual-api-aggregation-setup.md @@ -0,0 +1,236 @@ +# Manual API Aggregation Setup + +This document describes how to manually set up artifacts that the helm chart +for Service Catalog needs to integrate with the API aggregator. + +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` resource. + +For development purposes, it is convenient to use the existing CA +automatically set up by the kubernetes development environment. The +[script in contrib](../contrib/svc-cat-apiserver-aggregation-tls-setup.sh) +generates a fresh CA and certificate setup, without using any existing +kubernetes infrastructure CAs or certificates. This script should be +`source`ed to define all of the variables it contains in the current +shell process. + +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 +``` + +## Check That the API Aggregator is Enabled + +Run the following: + +```console +kubectl api-versions +``` + +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. + +``` +export HELM_RELEASE_NAME=catalog +export SVCCAT_NAMESPACE=catalog +export SVCCAT_SERVICE_NAME=${HELM_RELEASE_NAME}-catalog-apiserver +``` + +## Get a Certificate Authority (CA) and Keys + +There are two options to get a CA and keys. + +### Option 1 - Create Our Own 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. + +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"\" + +export SVCCAT_CA_SETUP=svc-cat-ca.json +cat >> ${SVCCAT_CA_SETUP} << EOF +{ + "hosts": [ ${ALT_NAMES} ], + "key": { + "algo": "rsa", + "size": 2048 + }, + "names": [ + { + "C": "US", + "L": "san jose", + "O": "kube", + "OU": "WWW", + "ST": "California" + } + ] +} +EOF + + +cfssl genkey --initca ${SVCCAT_CA_SETUP} | cfssljson -bare ${CA_NAME} +# now the files 'ca.csr ca-key.pem ca.pem' exist + +export SVCCAT_CA_CERT=${CA_NAME}.pem +export SVCCAT_CA_KEY=${CA_NAME}-key.pem + +export PURPOSE=server +echo '{"signing":{"default":{"expiry":"43800h","usages":["signing","key encipherment","'${PURPOSE}'"]}}}' > "${PURPOSE}-ca-config.json" + +echo '{"CN":"'${SVCCAT_SERVICE_NAME}'","hosts":['${ALT_NAMES}'],"key":{"algo":"rsa","size":2048}}' \ + | cfssl gencert -ca=${SVCCAT_CA_CERT} -ca-key=${SVCCAT_CA_KEY} -config=server-ca-config.json - \ + | cfssljson -bare apiserver + +export SC_SERVING_CA=${SVCCAT_CA_CERT} +export SC_SERVING_CERT=apiserver.pem +export SC_SERVING_KEY=apiserver-key.pem +``` + +### 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. + +The key we are looking for in an already running system is the +`--root-ca-file` flag to the controller-manager. + +The following is an example based on a real kubernetes cluster. The +various files may be named differently and in different locations. + + +``` +export SERVING_NAME=server-ca +export SERVINGCA_CERT=${SERVING_NAME}.crt +export SERVINGCA_KEY=${SERVING_NAME}.key +# a default location +cp /var/run/kubernetes/${SERVINGCA_CERT} . +cp /var/run/kubernetes/${SERVINGCA_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 and the Config File to Generate the New Signing Certificate and Key + +``` +export NAME_SPACE=catalog +export SERVICE_NAME=catalog-catalog-apiserver +export ALT_NAMES="\"${SERVICE_NAME}.${NAME_SPACE}\",\"${SERVICE_NAME}.${NAME_SPACE}.svc"\" +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 + +These variables define the final names of the resulting keys. + +``` +export SC_SERVING_CA=${SERVINGCA_CERT} +export SC_SERVING_CERT=apiserver.pem +export SC_SERVING_KEY=apiserver-key.pem +``` + +# 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 +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}) +``` + +`servicecatalog.k8s.io/v1alpha1` should show up under `kubectl +api-versions` almost immediately, but kubectl will be slow to respond +to other commands until the apiserver is fully running. + +If it doesn't show up the kubectl discovery cache is stale and needs +to be deleted. It may be located in the `.kube` directory, +approximately `~/.kube/cache/discovery/`. + +Now Service Catalog e2e tests should work with the same `kubeconfig` set +for both the core APIServer access and the Service Catalog APIServer +access. + +``` +export SERVICECATALOGCONFIG=~/.kube/config +export KUBECONFIG=~/.kube/config +make test-e2e +``` From 09b29e347f69bc0a741683622e81b680f909aee7 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 12:59:57 -0700 Subject: [PATCH 16/22] Adding cfssl install instructions --- docs/install-1.7.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/install-1.7.md b/docs/install-1.7.md index 337fdeca73d..631e0e8a612 100644 --- a/docs/install-1.7.md +++ b/docs/install-1.7.md @@ -37,7 +37,13 @@ cd certs We'll assume that you're operating from this `docs/certs` directory for the remainder of this document. -Next, create the certs: +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 From bcdbc68ff040a46aecfcf8283fd30b353d95899c Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 13:08:31 -0700 Subject: [PATCH 17/22] Adding a prerequisites section to the 1.7 install doc --- docs/install-1.7.md | 76 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/docs/install-1.7.md b/docs/install-1.7.md index 631e0e8a612..1ef58fdfca2 100644 --- a/docs/install-1.7.md +++ b/docs/install-1.7.md @@ -18,6 +18,82 @@ 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 From 063b5bdb452e8d6220825517dccc25fa99b67af7 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 13:17:20 -0700 Subject: [PATCH 18/22] s/many servers/many API servers --- docs/install-1.7.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install-1.7.md b/docs/install-1.7.md index 1ef58fdfca2..1b383db5f64 100644 --- a/docs/install-1.7.md +++ b/docs/install-1.7.md @@ -9,7 +9,7 @@ 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 +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 From cddc00500a181b6420d34ac72e167132203e0eb7 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 13:17:56 -0700 Subject: [PATCH 19/22] Adding deprecated note to the 1.6 walkthrough doc --- docs/walkthrough-1.6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/walkthrough-1.6.md b/docs/walkthrough-1.6.md index 20e81360b46..935bccccf18 100644 --- a/docs/walkthrough-1.6.md +++ b/docs/walkthrough-1.6.md @@ -1,4 +1,4 @@ -# 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. From b553a5a5e8b5b2a5359a48fb31ff7fd612909dab Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 13:45:45 -0700 Subject: [PATCH 20/22] Removing the link to "final cleanup" --- docs/install-1.6.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/install-1.6.md b/docs/install-1.6.md index 27da09145dc..dd1372d8338 100644 --- a/docs/install-1.6.md +++ b/docs/install-1.6.md @@ -134,9 +134,9 @@ authentication and authorization](./auth.md). ## Do Overs If you make a mistake somewhere along the way in this walk-through and want to -start over, check out the -[Final Cleanup](./walkthrough-1.6.md#Step-9---Final-Cleanup) section in the -walkthrough document. Follow those instructions before you start over. +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 From c1e97fe3d7c5f5880c77eea588a436d0f6cf9d19 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 14:49:28 -0700 Subject: [PATCH 21/22] Clarify the link to the intro doc --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b1e56ae51f3..dd7a2267037 100644 --- a/README.md +++ b/README.md @@ -40,8 +40,8 @@ _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 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. From 67f8ad5d1a94b45de3304bbf0528c354f749c57a Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 29 Aug 2017 14:51:06 -0700 Subject: [PATCH 22/22] Adding the env var to the local-up command --- docs/install-1.6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install-1.6.md b/docs/install-1.6.md index dd1372d8338..eeb8e599fe0 100644 --- a/docs/install-1.6.md +++ b/docs/install-1.6.md @@ -22,7 +22,7 @@ DNS enabled already. `KUBE_ENABLE_CLUSTER_DNS` environment variable is set as follows: ```console -hack/local-up-cluster.sh -O +KUBE_ENABLE_CLUSTER_DNS=true hack/local-up-cluster.sh -O ``` ## Helm