forked from kubernetes-retired/service-catalog
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Splitting up the Walkthrough for 1.6 and 1.7 instructions (kubernetes…
…-retired#1163) * Splitting the walkthrough up For 1.6 and 1.7 instructions * Making the readme link relative * Linking to the right final cleanup page * Adding period at end of sentence * Using curly fracked env var syntax * Fixing NodePort language * Cd-ing into certs dir * Removing file names, replacing with more descriptive text * Adding more description to tooling * Removing DNS entries note * Kube core => core Kubernetes API server * Specifying that there are 2 options for getting a CA and keys * Noting WIP for the 1.7 walkthrough * Ignoring the certs directory The install instructions say that you should create this directory, so let’s ignore it * Splitting the aggregated API install docs w/ script from the manual install docs * Adding cfssl install instructions * Adding a prerequisites section to the 1.7 install doc * s/many servers/many API servers * Adding deprecated note to the 1.6 walkthrough doc * Removing the link to "final cleanup" * Clarify the link to the intro doc * Adding the env var to the local-up command
- Loading branch information
Showing
10 changed files
with
495 additions
and
262 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -20,3 +20,4 @@ contrib/build/*/tmp/* | |
.pkg | ||
.kube | ||
.var | ||
docs/certs |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,167 @@ | ||
# Installing Service Catalog on Clusters Running Kubernetes 1.6 (DEPRECATED) | ||
|
||
This document contains instructions for installing the Service Catalog onto | ||
Kubernetes clusters running version 1.6. Since Service Catalog | ||
only officially supports versions 1.7 and later, these instructions are | ||
deprecated and may be removed at any time. | ||
|
||
If you are running a Kubernetes cluster running version 1.7 or later, please | ||
see the [installation instructions for 1.7](./install-1.7.md). | ||
|
||
# Step 1 - Prerequisites | ||
|
||
## Starting Kubernetes with DNS | ||
|
||
You *must* have a Kubernetes cluster with cluster DNS enabled. We can't list | ||
instructions here for enabling cluster DNS for all Kubernetes cluster | ||
installations, but here are a few notes: | ||
|
||
* If you are using Google Container Engine or minikube, you likely have cluster | ||
DNS enabled already. | ||
* If you are using hack/local-up-cluster.sh, ensure the | ||
`KUBE_ENABLE_CLUSTER_DNS` environment variable is set as follows: | ||
|
||
```console | ||
KUBE_ENABLE_CLUSTER_DNS=true hack/local-up-cluster.sh -O | ||
``` | ||
|
||
## Helm | ||
|
||
You *must* use [Helm](http://helm.sh/) v2 or newer in the installation steps | ||
below. | ||
|
||
If you already have Helm v2 or newer, execute `helm init` (if you haven't | ||
already) to install Tiller (the server-side component of Helm), and you should | ||
be done with Helm setup. | ||
|
||
If you don't already have Helm v2, see the | ||
[installation instructions](https://github.com/kubernetes/helm/blob/master/docs/install.md). | ||
|
||
If your kubernetes cluster has | ||
[RBAC](https://kubernetes.io/docs/admin/authorization/rbac/) enabled, you must | ||
ensure that the tiller pod has `cluster-admin` access. By default, `helm init` | ||
installs the tiller pod into `kube-system` namespace, with tiller configured to | ||
use the `default` service account. | ||
|
||
```console | ||
kubectl create clusterrolebinding tiller-cluster-admin --clusterrole=cluster-admin --serviceaccount=kube-system:default | ||
``` | ||
|
||
`cluster-admin` access is required in order for helm to work correctly in | ||
clusters with RBAC enabled. If you used the `--tiller-namespace` or | ||
`--service-account` flags when running `helm init`, the `--serviceaccount` flag | ||
in the previous command needs to be adjusted to reference the appropriate | ||
namespace and ServiceAccount name. | ||
|
||
## A Recent `kubectl` | ||
|
||
As with Kubernetes itself, interaction with the service catalog system is | ||
achieved through the `kubectl` command line interface. Chances are high that | ||
you already have this installed, however, the service catalog *requires* | ||
`kubectl` version 1.6 or newer. | ||
|
||
To proceed, we must: | ||
|
||
- Download and install `kubectl` version 1.6 or newer. | ||
- Configure `kubectl` to communicate with the service catalog's API server. | ||
|
||
To install `kubectl` follow the [standard instructions](https://kubernetes.io/docs/tasks/kubectl/install/). | ||
|
||
For example, on a mac, | ||
```console | ||
curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/darwin/amd64/kubectl | ||
chmod +x ./kubectl | ||
``` | ||
|
||
We'll assume hereafter that all `kubectl` commands are using this | ||
newly-installed executable. | ||
|
||
|
||
# Step 2 - Installing the Service Catalog | ||
|
||
The service catalog is packaged as a Helm chart located in the | ||
[charts/catalog](../charts/catalog) directory in this repository, and supports a | ||
wide variety of customizations which are detailed in that directory's | ||
[README.md](../charts/catalog/README.md). | ||
|
||
## The Service Catalog Data Store | ||
|
||
We'll be interacting with a variety of resources in the following steps. The | ||
service catalog API server needs to store all of these resources in a data | ||
store. The data store implementation in the API server is pluggable, and we | ||
currently support the following implementations: | ||
|
||
1. Etcd 3 | ||
2. Third Party Resources (also, known as TPRs) - this is an _alpha_ feature | ||
right now. It has known issues and may be removed at any time. | ||
|
||
The first implementation requires that the API server has access to an Etcd 3 cluster, and the | ||
second only requires access to the Kubernetes API to store TPRs. | ||
|
||
Even if you store data in TPRs, you should still access data via the service catalog API. It is | ||
possible to access data via the TPRs directly, but we don't recommend it. | ||
|
||
## Install | ||
|
||
To install the service catalog system with Etcd 3 as the backing data store: | ||
|
||
```console | ||
helm install charts/catalog --name catalog --namespace catalog | ||
``` | ||
|
||
To install the service catalog system with TPRs as the backing data store: | ||
|
||
```console | ||
helm install charts/catalog --name catalog --namespace catalog --set apiserver.storage.type=tpr,apiserver.storage.tpr.globalNamespace=catalog | ||
``` | ||
|
||
Regardless of which data store implementation you choose, the remainder of the steps in this | ||
walkthrough will stay the same. | ||
|
||
## API Server Authentication and Authorization | ||
|
||
Authentication and authorization are disabled in the Helm chart by default. To enable them, | ||
set the `apiserver.auth.enabled` option on the Helm chart: | ||
|
||
```console | ||
helm install charts/catalog --name catalog --namespace catalog --set apiserver.auth.enabled=true | ||
``` | ||
|
||
For more information about certificate setup, see the [documentation on | ||
authentication and authorization](./auth.md). | ||
|
||
|
||
## Do Overs | ||
|
||
If you make a mistake somewhere along the way in this walk-through and want to | ||
start over, check out the "Final Cleanup" section in the | ||
[walkthrough document](./walkthrough-1.6.md). Follow those instructions before | ||
you start over. | ||
|
||
## Step 3 - Configuring `kubectl` to Talk to the API Server | ||
|
||
To configure `kubectl` to communicate with the service catalog API server, we'll have to | ||
get the IP address that points to the `Service` that sits in front of the API server pod(s). | ||
If you installed the catalog with one of the `helm install` commands above, then this service | ||
will be called `catalog-catalog-apiserver`, and be in the `catalog` namespace. | ||
|
||
### Notes on Getting the IP Address | ||
|
||
How you get this IP address is highly dependent on your Kubernetes installation | ||
method. Regardless of how you do it, do not use the Cluster IP of the | ||
`Service`. The `Service` is created as a `NodePort` in this walkthrough, you | ||
will need to use the address of one of the nodes in your cluster. | ||
|
||
### Setting up a New `kubectl` Context | ||
|
||
When you determine the IP address of this service, set its value into the `SVC_CAT_API_SERVER_IP` | ||
environment variable and then run the following commands: | ||
|
||
```console | ||
kubectl config set-cluster service-catalog --server=https://${SVC_CAT_API_SERVER_IP}:30443 --insecure-skip-tls-verify=true | ||
kubectl config set-context service-catalog --cluster=service-catalog | ||
``` | ||
|
||
Note: Your cloud provider may require firewall rules to allow your traffic get in. | ||
Please refer to the [Troubleshooting](./walkthrough-1.6.md#troubleshooting) | ||
section of the walkthrough document for details. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,159 @@ | ||
# Installing Service Catalog on Clusters Running Kubernetes 1.7 and Above | ||
|
||
Kubernetes 1.7 or higher clusters run the | ||
[API Aggregator](https://kubernetes.io/docs/concepts/api-extension/apiserver-aggregation/), | ||
which is a specialized proxy server that sits in front of the core API Server. | ||
|
||
The aggregator allows user-defined, Kubernetes compatible API servers to come | ||
and go inside the cluster, and register themselves on demand to augment the | ||
externally facing API that kubernetes offers. | ||
|
||
Instead of requiring the end-user to access multiple API servers, the API | ||
aggregation system allows many API servers to run inside the cluster, and combines | ||
all of their APIs into one externally facing API. | ||
|
||
This system is very useful from an end-user's perspective, as it allows the | ||
client to use a single API point with familiar, consistent tooling, | ||
authentication and authorization. | ||
|
||
The Service Catalog utilizes API aggregation to present its API. | ||
|
||
# Prerequisites | ||
|
||
# Step 1 - Prerequisites | ||
|
||
## Starting Kubernetes with DNS | ||
|
||
You *must* have a Kubernetes cluster with cluster DNS enabled. We can't list | ||
instructions here for enabling cluster DNS for all Kubernetes cluster | ||
installations, but here are a few notes: | ||
|
||
* If you are using a cloud-based Kubernetes cluster or minikube, you likely | ||
have cluster DNS enabled already. | ||
* If you are using `hack/local-up-cluster.sh`, ensure the | ||
`KUBE_ENABLE_CLUSTER_DNS` environment variable is set and then run the install | ||
script | ||
|
||
## Helm | ||
|
||
You *must* use [Helm](http://helm.sh/) v2 or newer in the installation steps | ||
below. | ||
|
||
If you already have Helm v2 or newer, execute `helm init` (if you haven't | ||
already) to install Tiller (the server-side component of Helm), and you should | ||
be done with Helm setup. | ||
|
||
If you don't already have Helm v2, see the | ||
[installation instructions](https://github.com/kubernetes/helm/blob/master/docs/install.md). | ||
|
||
## RBAC | ||
|
||
Your Kubernetes cluster must have RBAC enabled, and your Tiller pod needs to | ||
have `cluster-admin` access. If you are using Minikube, make sure to run | ||
your `minikube start` command with this flag: | ||
|
||
```console | ||
minikube start --extra-config=apiserver.Authorization.Mode=RBAC | ||
``` | ||
|
||
AssumingBy default, `helm init` installs the Tiller pod into the `kube-system` | ||
namespace, with Tiller configured to use the `default` service account. | ||
|
||
Configure Tiller with `cluster-admin` access with the following command: | ||
|
||
```console | ||
kubectl create clusterrolebinding tiller-cluster-admin \ | ||
--clusterrole=cluster-admin \ | ||
--serviceaccount=kube-system:default | ||
``` | ||
|
||
If you used the `--tiller-namespace` or `--service-account` flags when running | ||
`helm init`, the `--serviceaccount` flag in the previous command needs to be | ||
adjusted to reference the appropriate namespace and ServiceAccount name. | ||
|
||
## A Recent `kubectl` | ||
|
||
As with Kubernetes itself, interaction with the service catalog system is | ||
achieved through the `kubectl` command line interface. Chances are high that | ||
you already have this installed, however, the service catalog *requires* | ||
`kubectl` version 1.6 or newer. | ||
|
||
To proceed, we must: | ||
|
||
- Download and install `kubectl` version 1.6 or newer. | ||
- Configure `kubectl` to communicate with the service catalog's API server. | ||
|
||
To install `kubectl` follow the [standard instructions](https://kubernetes.io/docs/tasks/kubectl/install/). | ||
|
||
For example, on a mac, | ||
```console | ||
curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/darwin/amd64/kubectl | ||
chmod +x ./kubectl | ||
``` | ||
|
||
We'll assume that all `kubectl` commands are using this newly-installed | ||
executable. | ||
|
||
# Step 1 - Generate TLS Certificates | ||
|
||
We provide a script to do all of the steps needed to set up TLS certificates | ||
that the aggregation system uses. If you'd like to read how to do this setup | ||
manually, please see the | ||
[manual API aggregation setup document](./manual-api-aggregation-setup.md). | ||
|
||
Otherwise, read on for automated instructions. | ||
|
||
First, create a directory in which certificates will be generated: | ||
|
||
```console | ||
mkdir certs | ||
cd certs | ||
``` | ||
|
||
We'll assume that you're operating from this `docs/certs` directory for the | ||
remainder of this document. | ||
|
||
Next, install the `cfssl` toolchain (which the following script uses): | ||
|
||
```console | ||
go get -u github.com/cloudflare/cfssl/cmd/... | ||
``` | ||
|
||
Finally, create the certs: | ||
|
||
```console | ||
source ../../contrib/svc-cat-apiserver-aggregation-tls-setup.sh | ||
``` | ||
|
||
# Step 2 - Install the Helm Chart | ||
|
||
Use helm to install the Service Catalog, associating it with the | ||
configured name ${HELM_NAME}, and into the specified namespace." This | ||
command also enables authentication and aggregation and provides the | ||
keys we just generated inline. | ||
|
||
The installation commands vary slightly between Linux and Mac OS X because of | ||
the versions of the `base64` command (Linux has GNU base64, Mac OS X has BSD | ||
base64). If you're installing from a Linux based machine, run this: | ||
|
||
``` | ||
helm install ../../charts/catalog \ | ||
--name ${HELM_RELEASE_NAME} --namespace ${SVCCAT_NAMESPACE} \ | ||
--set apiserver.auth.enabled=true \ | ||
--set useAggregator=true \ | ||
--set apiserver.tls.ca=$(base64 --wrap 0 ${SC_SERVING_CA}) \ | ||
--set apiserver.tls.cert=$(base64 --wrap 0 ${SC_SERVING_CERT}) \ | ||
--set apiserver.tls.key=$(base64 --wrap 0 ${SC_SERVING_KEY}) | ||
``` | ||
|
||
If you're on a Mac OS X based machine, run this: | ||
|
||
``` | ||
helm install ../../charts/catalog \ | ||
--name ${HELM_RELEASE_NAME} --namespace ${SVCCAT_NAMESPACE} \ | ||
--set apiserver.auth.enabled=true \ | ||
--set useAggregator=true \ | ||
--set apiserver.tls.ca=$(base64 ${SC_SERVING_CA}) \ | ||
--set apiserver.tls.cert=$(base64 ${SC_SERVING_CERT}) \ | ||
--set apiserver.tls.key=$(base64 ${SC_SERVING_KEY}) | ||
``` |
Oops, something went wrong.