Skip to content

Commit 43f7cfb

Browse files
arschlespmorie
arschles
authored and
pmorie
committed
Splitting up the Walkthrough for 1.6 and 1.7 instructions (#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
1 parent 02e0217 commit 43f7cfb

File tree

10 files changed

+495
-262
lines changed

10 files changed

+495
-262
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,4 @@ contrib/build/*/tmp/*
2020
.pkg
2121
.kube
2222
.var
23+
docs/certs

‎README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,9 @@ _somewhere_ in a simple way:
3838
contain information necessary to connect to and authenticate to the
3939
service instance.
4040

41+
For more introduction, including installation and self-guided demo
42+
instructions, please see the [introduction](./docs/introduction.md) doc.
43+
4144
For more details about the design and features of this project see the
4245
[design](docs/design.md) doc.
4346

‎contrib/examples/walkthrough/README.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
## Walkthrough Resources
22

3-
This directory contains API resources for use with the [demo
4-
walkthrough](../../../docs/walkthrough.md).
3+
This directory contains API resources for use with the demo walkthrough.
4+
5+
Please see [the introduction document](../../../docs/introduction.md) for
6+
instructions.

‎docs/devguide.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -267,5 +267,5 @@ the Kubernetes cluster as third party resources.
267267

268268
## Demo walkthrough
269269

270-
Check out the [walk-through](walkthrough.md) for a detailed guide of an example
271-
deployment.
270+
Check out the [introduction](./introduction.md) to get started with
271+
installation and a self-guided demo.

‎docs/install-1.6.md

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Installing Service Catalog on Clusters Running Kubernetes 1.6 (DEPRECATED)
2+
3+
This document contains instructions for installing the Service Catalog onto
4+
Kubernetes clusters running version 1.6. Since Service Catalog
5+
only officially supports versions 1.7 and later, these instructions are
6+
deprecated and may be removed at any time.
7+
8+
If you are running a Kubernetes cluster running version 1.7 or later, please
9+
see the [installation instructions for 1.7](./install-1.7.md).
10+
11+
# Step 1 - Prerequisites
12+
13+
## Starting Kubernetes with DNS
14+
15+
You *must* have a Kubernetes cluster with cluster DNS enabled. We can't list
16+
instructions here for enabling cluster DNS for all Kubernetes cluster
17+
installations, but here are a few notes:
18+
19+
* If you are using Google Container Engine or minikube, you likely have cluster
20+
DNS enabled already.
21+
* If you are using hack/local-up-cluster.sh, ensure the
22+
`KUBE_ENABLE_CLUSTER_DNS` environment variable is set as follows:
23+
24+
```console
25+
KUBE_ENABLE_CLUSTER_DNS=true hack/local-up-cluster.sh -O
26+
```
27+
28+
## Helm
29+
30+
You *must* use [Helm](http://helm.sh/) v2 or newer in the installation steps
31+
below.
32+
33+
If you already have Helm v2 or newer, execute `helm init` (if you haven't
34+
already) to install Tiller (the server-side component of Helm), and you should
35+
be done with Helm setup.
36+
37+
If you don't already have Helm v2, see the
38+
[installation instructions](https://github.com/kubernetes/helm/blob/master/docs/install.md).
39+
40+
If your kubernetes cluster has
41+
[RBAC](https://kubernetes.io/docs/admin/authorization/rbac/) enabled, you must
42+
ensure that the tiller pod has `cluster-admin` access. By default, `helm init`
43+
installs the tiller pod into `kube-system` namespace, with tiller configured to
44+
use the `default` service account.
45+
46+
```console
47+
kubectl create clusterrolebinding tiller-cluster-admin --clusterrole=cluster-admin --serviceaccount=kube-system:default
48+
```
49+
50+
`cluster-admin` access is required in order for helm to work correctly in
51+
clusters with RBAC enabled. If you used the `--tiller-namespace` or
52+
`--service-account` flags when running `helm init`, the `--serviceaccount` flag
53+
in the previous command needs to be adjusted to reference the appropriate
54+
namespace and ServiceAccount name.
55+
56+
## A Recent `kubectl`
57+
58+
As with Kubernetes itself, interaction with the service catalog system is
59+
achieved through the `kubectl` command line interface. Chances are high that
60+
you already have this installed, however, the service catalog *requires*
61+
`kubectl` version 1.6 or newer.
62+
63+
To proceed, we must:
64+
65+
- Download and install `kubectl` version 1.6 or newer.
66+
- Configure `kubectl` to communicate with the service catalog's API server.
67+
68+
To install `kubectl` follow the [standard instructions](https://kubernetes.io/docs/tasks/kubectl/install/).
69+
70+
For example, on a mac,
71+
```console
72+
curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/darwin/amd64/kubectl
73+
chmod +x ./kubectl
74+
```
75+
76+
We'll assume hereafter that all `kubectl` commands are using this
77+
newly-installed executable.
78+
79+
80+
# Step 2 - Installing the Service Catalog
81+
82+
The service catalog is packaged as a Helm chart located in the
83+
[charts/catalog](../charts/catalog) directory in this repository, and supports a
84+
wide variety of customizations which are detailed in that directory's
85+
[README.md](../charts/catalog/README.md).
86+
87+
## The Service Catalog Data Store
88+
89+
We'll be interacting with a variety of resources in the following steps. The
90+
service catalog API server needs to store all of these resources in a data
91+
store. The data store implementation in the API server is pluggable, and we
92+
currently support the following implementations:
93+
94+
1. Etcd 3
95+
2. Third Party Resources (also, known as TPRs) - this is an _alpha_ feature
96+
right now. It has known issues and may be removed at any time.
97+
98+
The first implementation requires that the API server has access to an Etcd 3 cluster, and the
99+
second only requires access to the Kubernetes API to store TPRs.
100+
101+
Even if you store data in TPRs, you should still access data via the service catalog API. It is
102+
possible to access data via the TPRs directly, but we don't recommend it.
103+
104+
## Install
105+
106+
To install the service catalog system with Etcd 3 as the backing data store:
107+
108+
```console
109+
helm install charts/catalog --name catalog --namespace catalog
110+
```
111+
112+
To install the service catalog system with TPRs as the backing data store:
113+
114+
```console
115+
helm install charts/catalog --name catalog --namespace catalog --set apiserver.storage.type=tpr,apiserver.storage.tpr.globalNamespace=catalog
116+
```
117+
118+
Regardless of which data store implementation you choose, the remainder of the steps in this
119+
walkthrough will stay the same.
120+
121+
## API Server Authentication and Authorization
122+
123+
Authentication and authorization are disabled in the Helm chart by default. To enable them,
124+
set the `apiserver.auth.enabled` option on the Helm chart:
125+
126+
```console
127+
helm install charts/catalog --name catalog --namespace catalog --set apiserver.auth.enabled=true
128+
```
129+
130+
For more information about certificate setup, see the [documentation on
131+
authentication and authorization](./auth.md).
132+
133+
134+
## Do Overs
135+
136+
If you make a mistake somewhere along the way in this walk-through and want to
137+
start over, check out the "Final Cleanup" section in the
138+
[walkthrough document](./walkthrough-1.6.md). Follow those instructions before
139+
you start over.
140+
141+
## Step 3 - Configuring `kubectl` to Talk to the API Server
142+
143+
To configure `kubectl` to communicate with the service catalog API server, we'll have to
144+
get the IP address that points to the `Service` that sits in front of the API server pod(s).
145+
If you installed the catalog with one of the `helm install` commands above, then this service
146+
will be called `catalog-catalog-apiserver`, and be in the `catalog` namespace.
147+
148+
### Notes on Getting the IP Address
149+
150+
How you get this IP address is highly dependent on your Kubernetes installation
151+
method. Regardless of how you do it, do not use the Cluster IP of the
152+
`Service`. The `Service` is created as a `NodePort` in this walkthrough, you
153+
will need to use the address of one of the nodes in your cluster.
154+
155+
### Setting up a New `kubectl` Context
156+
157+
When you determine the IP address of this service, set its value into the `SVC_CAT_API_SERVER_IP`
158+
environment variable and then run the following commands:
159+
160+
```console
161+
kubectl config set-cluster service-catalog --server=https://${SVC_CAT_API_SERVER_IP}:30443 --insecure-skip-tls-verify=true
162+
kubectl config set-context service-catalog --cluster=service-catalog
163+
```
164+
165+
Note: Your cloud provider may require firewall rules to allow your traffic get in.
166+
Please refer to the [Troubleshooting](./walkthrough-1.6.md#troubleshooting)
167+
section of the walkthrough document for details.

‎docs/install-1.7.md

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# Installing Service Catalog on Clusters Running Kubernetes 1.7 and Above
2+
3+
Kubernetes 1.7 or higher clusters run the
4+
[API Aggregator](https://kubernetes.io/docs/concepts/api-extension/apiserver-aggregation/),
5+
which is a specialized proxy server that sits in front of the core API Server.
6+
7+
The aggregator allows user-defined, Kubernetes compatible API servers to come
8+
and go inside the cluster, and register themselves on demand to augment the
9+
externally facing API that kubernetes offers.
10+
11+
Instead of requiring the end-user to access multiple API servers, the API
12+
aggregation system allows many API servers to run inside the cluster, and combines
13+
all of their APIs into one externally facing API.
14+
15+
This system is very useful from an end-user's perspective, as it allows the
16+
client to use a single API point with familiar, consistent tooling,
17+
authentication and authorization.
18+
19+
The Service Catalog utilizes API aggregation to present its API.
20+
21+
# Prerequisites
22+
23+
# Step 1 - Prerequisites
24+
25+
## Starting Kubernetes with DNS
26+
27+
You *must* have a Kubernetes cluster with cluster DNS enabled. We can't list
28+
instructions here for enabling cluster DNS for all Kubernetes cluster
29+
installations, but here are a few notes:
30+
31+
* If you are using a cloud-based Kubernetes cluster or minikube, you likely
32+
have cluster DNS enabled already.
33+
* If you are using `hack/local-up-cluster.sh`, ensure the
34+
`KUBE_ENABLE_CLUSTER_DNS` environment variable is set and then run the install
35+
script
36+
37+
## Helm
38+
39+
You *must* use [Helm](http://helm.sh/) v2 or newer in the installation steps
40+
below.
41+
42+
If you already have Helm v2 or newer, execute `helm init` (if you haven't
43+
already) to install Tiller (the server-side component of Helm), and you should
44+
be done with Helm setup.
45+
46+
If you don't already have Helm v2, see the
47+
[installation instructions](https://github.com/kubernetes/helm/blob/master/docs/install.md).
48+
49+
## RBAC
50+
51+
Your Kubernetes cluster must have RBAC enabled, and your Tiller pod needs to
52+
have `cluster-admin` access. If you are using Minikube, make sure to run
53+
your `minikube start` command with this flag:
54+
55+
```console
56+
minikube start --extra-config=apiserver.Authorization.Mode=RBAC
57+
```
58+
59+
AssumingBy default, `helm init` installs the Tiller pod into the `kube-system`
60+
namespace, with Tiller configured to use the `default` service account.
61+
62+
Configure Tiller with `cluster-admin` access with the following command:
63+
64+
```console
65+
kubectl create clusterrolebinding tiller-cluster-admin \
66+
--clusterrole=cluster-admin \
67+
--serviceaccount=kube-system:default
68+
```
69+
70+
If you used the `--tiller-namespace` or `--service-account` flags when running
71+
`helm init`, the `--serviceaccount` flag in the previous command needs to be
72+
adjusted to reference the appropriate namespace and ServiceAccount name.
73+
74+
## A Recent `kubectl`
75+
76+
As with Kubernetes itself, interaction with the service catalog system is
77+
achieved through the `kubectl` command line interface. Chances are high that
78+
you already have this installed, however, the service catalog *requires*
79+
`kubectl` version 1.6 or newer.
80+
81+
To proceed, we must:
82+
83+
- Download and install `kubectl` version 1.6 or newer.
84+
- Configure `kubectl` to communicate with the service catalog's API server.
85+
86+
To install `kubectl` follow the [standard instructions](https://kubernetes.io/docs/tasks/kubectl/install/).
87+
88+
For example, on a mac,
89+
```console
90+
curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/darwin/amd64/kubectl
91+
chmod +x ./kubectl
92+
```
93+
94+
We'll assume that all `kubectl` commands are using this newly-installed
95+
executable.
96+
97+
# Step 1 - Generate TLS Certificates
98+
99+
We provide a script to do all of the steps needed to set up TLS certificates
100+
that the aggregation system uses. If you'd like to read how to do this setup
101+
manually, please see the
102+
[manual API aggregation setup document](./manual-api-aggregation-setup.md).
103+
104+
Otherwise, read on for automated instructions.
105+
106+
First, create a directory in which certificates will be generated:
107+
108+
```console
109+
mkdir certs
110+
cd certs
111+
```
112+
113+
We'll assume that you're operating from this `docs/certs` directory for the
114+
remainder of this document.
115+
116+
Next, install the `cfssl` toolchain (which the following script uses):
117+
118+
```console
119+
go get -u github.com/cloudflare/cfssl/cmd/...
120+
```
121+
122+
Finally, create the certs:
123+
124+
```console
125+
source ../../contrib/svc-cat-apiserver-aggregation-tls-setup.sh
126+
```
127+
128+
# Step 2 - Install the Helm Chart
129+
130+
Use helm to install the Service Catalog, associating it with the
131+
configured name ${HELM_NAME}, and into the specified namespace." This
132+
command also enables authentication and aggregation and provides the
133+
keys we just generated inline.
134+
135+
The installation commands vary slightly between Linux and Mac OS X because of
136+
the versions of the `base64` command (Linux has GNU base64, Mac OS X has BSD
137+
base64). If you're installing from a Linux based machine, run this:
138+
139+
```
140+
helm install ../../charts/catalog \
141+
--name ${HELM_RELEASE_NAME} --namespace ${SVCCAT_NAMESPACE} \
142+
--set apiserver.auth.enabled=true \
143+
--set useAggregator=true \
144+
--set apiserver.tls.ca=$(base64 --wrap 0 ${SC_SERVING_CA}) \
145+
--set apiserver.tls.cert=$(base64 --wrap 0 ${SC_SERVING_CERT}) \
146+
--set apiserver.tls.key=$(base64 --wrap 0 ${SC_SERVING_KEY})
147+
```
148+
149+
If you're on a Mac OS X based machine, run this:
150+
151+
```
152+
helm install ../../charts/catalog \
153+
--name ${HELM_RELEASE_NAME} --namespace ${SVCCAT_NAMESPACE} \
154+
--set apiserver.auth.enabled=true \
155+
--set useAggregator=true \
156+
--set apiserver.tls.ca=$(base64 ${SC_SERVING_CA}) \
157+
--set apiserver.tls.cert=$(base64 ${SC_SERVING_CERT}) \
158+
--set apiserver.tls.key=$(base64 ${SC_SERVING_KEY})
159+
```

0 commit comments

Comments
 (0)