Skip to content
This repository was archived by the owner on May 28, 2021. It is now read-only.

Commit 5d59def

Browse files
prydieowainlewis
authored andcommitted
Some improvements to the installation tutorial (#146)
1 parent dfadcd7 commit 5d59def

File tree

1 file changed

+58
-76
lines changed

1 file changed

+58
-76
lines changed

docs/tutorial.md

Lines changed: 58 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -4,84 +4,87 @@ This guide provides a quick-start guide for users of the Oracle MySQL Operator.
44

55
## Prerequisites
66

7-
* Kubernetes
8-
* The mysql-operator repo checked out locally
7+
* A Kubernetes v1.8.0+ cluster.
8+
* The mysql-operator Git repository checked out locally.
9+
* [Helm](https://github.com/kubernetes/helm) installed and configured in your cluster.
910

10-
#### Create a namespace and Docker secret for the registry username/password
11+
### Configuring Helm and Tiller
1112

12-
First create the namespace that the operator will reside in. By default this is mysql-operator:
13+
Before deploying the mysql-operator, you must ensure [Tiller](https://github.com/kubernetes/helm)
14+
is installed in your cluster. Tiller is the server side component to Helm.
1315

14-
```
15-
kubectl create ns mysql-operator
16-
```
17-
18-
## Deploy a version of the MySQL Operator using Helm
19-
20-
The MySQL Operator is installed into your cluster with a Helm chart
16+
Your cluster administrator may have already setup and configured Helm for you,
17+
in which case you can skip this step.
2118

22-
### Ensure you have Helm installed and working.
19+
Full documentation on installing Helm can be found in the [Installing helm docs](https://github.com/kubernetes/helm/blob/master/docs/install.md).
2320

24-
Install the helm tool locally by following [these instructions](https://docs.helm.sh/using_helm/#installing-helm)
21+
If your cluster has RBAC (Role Based Access Control) enabled, you will need to
22+
take special care when deploying Tiller, to ensure Tiller has permission to
23+
create resources as a cluster administrator. More information on deploying Helm
24+
with RBAC can be found in the [Helm RBAC docs](https://github.com/kubernetes/helm/blob/master/docs/rbac.md).
2525

26-
If you have not already installed tiller to your cluster set it up with:
26+
## Installation
2727

28-
```bash
29-
helm init
30-
```
28+
### Create a namespace
3129

32-
Verify helm is installed :
33-
```bash
34-
helm version
30+
First create a namespace for the mysql-operator. By default this is
31+
`mysql-operator` unless you specify `--set operator.namespace=` when installing
32+
the mysql-operator Helm chart.
3533

36-
Client: &version.Version{SemVer:"v2.5.0", GitCommit:"012cb0ac1a1b2f888144ef5a67b8dab6c2d45be6", GitTreeState:"clean"}
37-
Server: &version.Version{SemVer:"v2.5.0", GitCommit:"012cb0ac1a1b2f888144ef5a67b8dab6c2d45be6", GitTreeState:"clean"}
34+
```console
35+
$ kubectl create ns mysql-operator
3836
```
3937

4038
### Installing the Chart
4139

42-
The helm chart for the operator is [included in this git repo](../mysql-operator), run the following in the root of the checked out `mysql-operator` repo.
40+
The helm chart for the operator is [included in this Git repository](../mysql-operator),
41+
run the following in the root of the checked out `mysql-operator` repository.
4342

44-
To install the chart in a cluster without RBAC with the release name `my-release`:
43+
To install the chart in a cluster without RBAC with the release name `mysql-operator`:
4544

4645
```console
47-
$ helm install --name my-release mysql-operator
46+
$ helm install \
47+
--name mysql-operator \
48+
mysql-operator
4849
```
4950

50-
If your cluster has RBAC disabled then you will need to run:
51-
52-
```console
53-
$ helm install --name my-release mysql-operator --set rbac.enabled=false
54-
```
51+
If your cluster does not use RBAC (Role Based Access Control), you will need to
52+
disable creation of RBAC resources by adding `--set rbac.enabled=false` to your
53+
`helm install` command above.
5554

56-
The above command deploys the MySQL Operator on the Kubernetes cluster in the default configuration. The [configuration](#configuration) section lists the parameters that can be configured during installation.
55+
The above command deploys the MySQL Operator on the Kubernetes cluster in the
56+
default configuration. The [configuration](#configuration) section lists the
57+
parameters that can be configured during installation.
5758

5859
> **Tip**: List all releases using `helm list`
5960
6061
### Uninstalling the Chart
6162

62-
To uninstall/delete the `my-release` deployment:
63+
To uninstall/delete the `mysql-operator` deployment:
6364

6465
```console
65-
$ helm delete my-release
66+
$ helm delete mysql-operator
6667
```
6768

68-
The command removes all the Kubernetes components associated with the chart and deletes the release.
69-
7069
### Configuration
7170

72-
The following tables lists the configurable parameters of the MySQL-operator chart and their default values.
71+
The following tables lists the configurable parameters of the MySQL-operator
72+
chart and their default values.
7373

7474
Parameter | Description | Default
7575
--------- | ----------- | -------
7676
`rbac.enabled` | If true, enables RBAC | `true`
7777
`operator.namespace` | Controls the namespace in which the operator is deployed | `mysql-operator`
78+
`operator.global` | Controls whether the `mysql-operator` is installed in cluster-wide mode or in a single namespace | `true`
79+
`image.tag` | The version of the mysql-operator to install | `0.1.1`
7880

7981
## Create a simple MySQL cluster
8082

81-
The first time you create a MySQL Cluster in a namespace you need to create the
83+
The first time you create a MySQL Cluster in a namespace (other than in the
84+
namespace into which you installed the mysql-operator) you need to create the
8285
`mysql-agent` ServiceAccount and RoleBinding in that namespace:
8386

84-
```bash
87+
```console
8588
$ cat <<EOF | kubectl create -f -
8689
apiVersion: v1
8790
kind: ServiceAccount
@@ -105,26 +108,27 @@ subjects:
105108
EOF
106109
```
107110

108-
Now let's create a new MySQL cluster. Create a cluster.yaml file with the following contents
111+
Now let's create a new MySQL cluster. Create a `cluster.yaml` file with the following contents:
109112

110113
```yaml
111-
apiVersion: mysql.oracle.com/v1
114+
apiVersion: mysql.oracle.com/v1alpha1
112115
kind: Cluster
113116
metadata:
114-
name: myappdb
117+
name: my-app-db
118+
namespace: my-namespace
115119
```
116120
117121
And create it with **kubectl**
118122
119-
```
123+
```console
120124
$ kubectl apply -f cluster.yaml
121-
mysqlcluster "myappdb" created
125+
mysqlcluster "my-app-db" created
122126
```
123127

124128
You should now have a cluster in the default namespace
125129

126-
```
127-
$ kubectl get mysqlclusters
130+
```console
131+
$ kubectl -n my-namespace get mysqlclusters
128132
NAME KIND
129133
myappdb Cluster.v1alpha1.mysql.oracle.com
130134
```
@@ -133,18 +137,20 @@ To find out how to create larger clusters, and configure storage see [Clusters](
133137

134138
#### Verify that you can connect to MySQL
135139

136-
The first thing you need to do is fetch the MySQL root password which is auto-generated for us by default and stored ia secret named `<dbname>-root-password`
140+
The first thing you need to do is fetch the MySQL root password which is
141+
auto-generated for us by default and stored in a Secret named `<dbname>-root-password`
137142

138-
```
139-
$ kubectl get secret myappdb-root-password -o jsonpath="{.data.password}" | base64 -D
143+
```console
144+
$ kubectl -n my-namespace get secret my-app-db-root-password -o jsonpath="{.data.password}" | base64 -D
140145
ETdmMKh2UuDq9m7y
141146
```
142147

143-
You can use a MySQL client container to verify that you can connect to MySQL inside the Kubernetes cluster.
148+
You can use a MySQL client container to verify that you can connect to MySQL
149+
from within the Kubernetes cluster.
144150

145-
```
146-
$ kubectl run mysql-client --image=mysql:5.7 -i -t --rm --restart=Never \
147-
-- mysql -h myappdb -uroot -pETdmMKh2UuDq9m7y -e 'SELECT 1'
151+
```console
152+
$ kubectl run mysql-client --image=mysql:5.7 -it --rm --restart=Never \
153+
-- mysql -h my-app-db -uroot -pETdmMKh2UuDq9m7y -e 'SELECT 1'
148154
Waiting for pod default/mysql-client to be running, status is Pending, pod ready: false
149155
mysql: [Warning] Using a password on the command line interface can be insecure.
150156
+---+
@@ -153,27 +159,3 @@ mysql: [Warning] Using a password on the command line interface can be insecure.
153159
| 1 |
154160
+---+
155161
```
156-
157-
# Troubleshooting
158-
159-
## cannot list configmaps in the namspace "kube-system"
160-
161-
Note: If `helm list` gives the following error
162-
163-
```console
164-
Error: User "system:serviceaccount:kube-system:default" cannot list configmaps in the namespace "kube-system". (get configmaps)
165-
```
166-
167-
then it could be because the cluster you are targeting has role-based-authentication (RBAC) enabled. To fix this, issue the following commands:
168-
169-
```console
170-
kubectl create serviceaccount --namespace kube-system tiller
171-
kubectl create clusterrolebinding \
172-
tiller-cluster-rule \
173-
--clusterrole=cluster-admin \
174-
--serviceaccount=kube-system:tiller
175-
kubectl patch deploy --namespace kube-system \
176-
tiller-deploy \
177-
-p '{"spec":{"template":{"spec":{"serviceAccount":"tiller"}}}}'
178-
```
179-

0 commit comments

Comments
 (0)