Skip to content

Commit 4ffcfb4

Browse files
adam-sandoradam-sandor
committed
rewrite README to be more detailed, as well as match the actual example :D
1 parent f9a8626 commit 4ffcfb4

File tree

1 file changed

+59
-35
lines changed

1 file changed

+59
-35
lines changed

‎samples/mysql-schema/README.md

Lines changed: 59 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,77 @@
1-
# WebServer Operator
1+
# MySQL Schema Operator
22

3-
This is a more complex example of how a Custom Resource backed by an Operator can serve as
4-
an abstraction layer. This Operator will use an webserver resource, which mainly contains a
5-
static webpage definition and creates a nginx Deployment backed by a ConfigMap which holds
6-
the html.
3+
This example shows how an operator can control resources outside of the Kubernetes cluster. In this case it will be
4+
managing MySQL schemas in an existing database server. This is a common scenario in many organizations where developers
5+
need to create schemas for different applications and environments, but the database server itself is managed by a
6+
different team. Using this operator a dev team can create a CR in their namespace and have a schema provisioned automatically.
7+
Access to the MySQL server is configured in the configuration of the operator, so admin access is restricted.
78

89
This is an example input:
910
```yaml
10-
apiVersion: "sample.javaoperatorsdk/v1"
11-
kind: WebServer
11+
apiVersion: "mysql.sample.javaoperatorsdk/v1"
12+
kind: MySQLSchema
1213
metadata:
13-
name: mynginx-hello
14+
name: mydb
1415
spec:
15-
html: |
16-
<html>
17-
<head>
18-
<title>Webserver Operator</title>
19-
</head>
20-
<body>
21-
Hello World!!
22-
</body>
23-
</html>
16+
encoding: utf8
2417
```
2518
19+
Creating this custom resource will prompt the operator to create a schema named `mydb` in the MySQL server and update
20+
the resource status with its URL. Once the resource is deleted, the operator will delete the schema. Obviously don't
21+
use it as is with real databases.
22+
2623
### Try
2724

28-
The quickest way to try the operator is to run it on your local machine, while it connects to a local or remote
29-
Kubernetes cluster. When you start it it will use the current kubectl context on your machine to connect to the cluster.
25+
To try how the operator works you will need the following:
26+
* JDK installed (minimum version 8, tested with 13)
27+
* Maven installed (tested with 3.6.3)
28+
* A working Kubernetes cluster (tested with v1.15.9-gke.24)
29+
* kubectl installed (tested with v1.15.5)
30+
* Docker installed (tested with 19.03.8)
31+
* Container image registry
32+
How to configure all the above depends heavily on where your Kubernetes cluster is hosted.
33+
If you use [minikube](https://minikube.sigs.k8s.io/docs/) you will need to configure kubectl and docker differently
34+
than if you'd use [GKE](https://cloud.google.com/kubernetes-engine/). You will have to read the documentation of your
35+
Kubernetes provider to figure this out.
36+
37+
Once you have the basics you can build and deploy the operator.
3038

31-
Before you run it you have to install the CRD on your cluster by running `kubectl apply -f crd/crd.yaml`
39+
### Build & Deploy
40+
41+
1. We will be building the Docker image from the source code using Maven, so we have to configure the Docker registry
42+
where the image should be pushed. Do this in your ~/.m2/settings.xml. In the example below I'm setting it to
43+
the [Container Registry](https://cloud.google.com/container-registry/) in Google Cloud Europe.
44+
45+
```xml
46+
<properties>
47+
<docker-registry>eu.gcr.io/my-gcp-project</docker-registry>
48+
</properties>
49+
```
3250

33-
When the Operator is running you can create some Webserver Custom Resources. You can find a sample custom resource in
34-
`crd/webserver.yaml`. You can create it by running `kubectl apply -f webserver.yaml`
51+
1. The following Maven command will build the jar file, package it as a Docker image and push it to the registry.
3552

36-
After the Operator has picked up the new webserver resource (see the logs) it should create the nginx server in the
37-
same namespace where the webserver resource is created. To connect to the server using your browser you can
38-
run `kubectl get service` and view the service created by the Operator. It should have a NodePort configured. If you are
39-
running a single-node cluster (e.g. Docker for Mac or Minikube) you can connect to the VM on this port to access the
40-
page.
53+
`mvn package dockerfile:build dockerfile:push`
4154

42-
You can also try to change the html code in `crd/webserver.yaml` and do another `kubectl apply -f crd/webserver.yaml`.
43-
This should update the actual nginx deployment with new configuration.
55+
1. Deploy the test MySQL on your cluster if you want to use it. Note that if you have an already running MySQL server
56+
you want to use, you can skip this step, but you will have to configure the operator to use that server.
57+
58+
`kubectl apply -f k8s/mysql.yaml`
59+
1. Deploy the CRD:
4460

45-
### Build
61+
`kubectl apply -f k8s/crd.yaml`
62+
1. Set up RBAC:
4663

47-
You can build the sample using `mvn package dockerfile:build` this will produce a Docker image you can push to the registry
48-
of your choice. The jar file is built using your local Maven and JDK and then copied into the Docker image.
64+
`kubectl apply -f k8s/rbac.yaml`
65+
1. Make a copy of `k8s/deployment.yaml` and replace ${DOCKER_REGISTRY} and ${OPERATOR_VERSION} to the
66+
right values. You will want to set `OPERATOR_VERSION` to the one used for building the Docker image. `DOCKER_REGISTRY` should
67+
be the same as you set the docker-registry property in your `settings.xml`.
68+
If you look at the environment variables you will notice this is where the access to the MySQL server is configured.
69+
The default values assume the server is running in another Kubernetes namespace (called `mysql`), uses the `root` user
70+
with a not very secure password. In case you want to use a different MySQL server, this is where you configure it.
4971

50-
### Deployment
72+
1. Run `kubectl apply -f copy-of-deployment.yaml` to deploy the operator. You can wait for the deployment to succeed using
73+
this command: `kubectl rollout status deployment mysql-schema-operator -w`. `-w` will cause kubectl to continuously monitor
74+
the deployment until you stop it.
5175

52-
1. Deploy the CRD: kubectl apply -f crd/crd.yaml
53-
2. Deploy the operator: kubectl apply -f k8s/deployment.yaml
76+
1. Now you are ready to create some databases! To create a database schema called `mydb` just apply the `k8s/example.yaml`
77+
file with kubectl: `kubectl apply -f k8s/example.yaml`. You can modify the database name in the file to create more schemas.

0 commit comments

Comments
 (0)