Skip to content

Commit 65f1e35

Browse files
t-finet-fine
authored
Merge pull request #592 from t-fine/nginx-operator-sdk-v1.x
Issue 543: nginx ansible operator-sdk v1.27
2 parents 6d8c2cd + 4294c38 commit 65f1e35

File tree

7 files changed

+179
-143
lines changed

7 files changed

+179
-143
lines changed

‎edge/services/nginx-operator/CreateService.md

Lines changed: 103 additions & 139 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Follow the steps on this page to create your first ansible operator that deploys
1414
- Open the Docker **Preferences** dialog
1515
- Uncheck **Securely store Docker logins in macOS keychain**
1616

17-
3. Install [operator-sdk](https://github.com/operator-framework/operator-sdk/tree/v0.19.x#prerequisites) and all its prerequisites. This example was created using version `0.19`, and has not been tested on any other versions.
17+
3. Install [operator-sdk](https://v1-27-x.sdk.operatorframework.io/docs/installation/) and all its prerequisites.
1818

1919
4. Install the Kubenetes CLI [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
2020

@@ -57,111 +57,87 @@ Follow the steps on this page to create your first ansible operator that deploys
5757
brew install git jq
5858
```
5959

60-
## <a id=build-publish-your-op></a> Building and Publishing Your Own Operator Example Edge Service
60+
## <a id=build-publish-your-op></a> Building and Publishing Your Own Nginx Ansible Operator Example Edge Service
6161

62-
In order to deploy a containerized edge service to an edge cluster, a software developer first has to build a Kubernetes Operator that deploys the containerized edge service in a Kubernetes cluster. There are several options when writing a Kubernetes operator. This example will guide through creating an ansible operator. The following steps were originally performed on the cluster host machine.
63-
64-
1. Create a new operator application and generate a default directory layout based on the input name, and move into the created default operator directory:
62+
In order to deploy a containerized edge service to an edge cluster, a software developer first has to build a Kubernetes Operator that deploys the containerized edge service in a Kubernetes cluster. There are several options when writing a Kubernetes operator. This example will guide through creating an ansible operator. These steps are based on the [Ansible Operator Tutorial](https://v1-27-x.sdk.operatorframework.io/docs/building-operators/ansible/tutorial/) on the official `operator-sdk` website. If you have never created an operator before, I highly suggest skimming over the information there as well. The following steps were originally performed on the cluster host machine.
6563

64+
1. Creating yourself a base working directory, and grab the Makefile int his repo:
6665
```bash
67-
operator-sdk new my-operator --type=ansible --api-version=my.operator.com/v1alpha1 --kind=MyOperator
68-
cd my-operator/
66+
mkdir operator-example-service
67+
cd operator-example-service/
68+
wget https://raw.githubusercontent.com/open-horizon/examples/master/edge/services/nginx-operator/Makefile
6969
```
7070

71-
**Note:** If you are following these steps to create an operator that will deploy your own service, you should modify the names used above, **not** modify things manually in the generated files.
72-
73-
The above command will give you an empty ansible operator. At the very least you will need to define a `deployment`, `service`, and a set of tasks to deploy your service. If you look in the [ansible-role-files](https://github.com/open-horizon/examples/tree/master/edge/services/hello-operator/ansible-role-files) directory you can see these three files and how they are used to deploy the `nginxinc/nginx-unprivileged` image, and how they expose the port `8080`. There are several methods for configuring cluster network traffic, which you can read about in the [OCP traffic overview documentation](https://docs.openshift.com/container-platform/4.6/networking/configuring_ingress_cluster_traffic/overview-traffic.html). For this service we've going to create a service of type `NodePort` and `expose` our service with a route.
74-
75-
2. Obtain the `deployment`, `service`, and task file and move them into the `my-operator` roles directory with the following commands:
76-
71+
2. Export the following environment variables to customize the `operator-sdk` init:
7772
```bash
78-
wget https://raw.githubusercontent.com/open-horizon/examples/master/edge/services/nginx-operator/ansible-role-files/deployment.j2 && mv deployment.j2 roles/myoperator/templates/
79-
wget https://raw.githubusercontent.com/open-horizon/examples/master/edge/services/nginx-operator/ansible-role-files/service.j2 && mv service.j2 roles/myoperator/templates/
80-
wget https://raw.githubusercontent.com/open-horizon/examples/master/edge/services/nginx-operator/ansible-role-files/main.yml && mv main.yml roles/myoperator/tasks/
73+
export OPERATOR_GROUP_NAME=my-nginx-ansible-operator
74+
export OPERATOR_TYPE=ansible
75+
export OPERATOR_API_VERSION=v1alpha1
76+
export OPERATOR_DOMAIN=$DOCKER_HUB_ID
77+
export OPERATOR_KIND=MyNginxAnsibleOperator
78+
export OPERATOR_NAMESPACE=operator-project
8179
```
8280

83-
3. **FOR OCP EDGE CLUSTERS ONLY:** Obtain the `route`, and modified task file and move them into the `my-operator` roles directory:
84-
81+
3. Create `my-nginx-ansible-operator`:
8582
```bash
86-
wget https://raw.githubusercontent.com/open-horizon/examples/master/edge/services/nginx-operator/ansible-role-files/route.j2 && mv route.j2 roles/myoperator/templates/
87-
wget https://raw.githubusercontent.com/open-horizon/examples/master/edge/services/nginx-operator/ansible-role-files/main-route.yml && mv main-route.yml roles/myoperator/tasks/main.yml
83+
make init
8884
```
8985

90-
4. **FOR OCP EDGE CLUSTERS ONLY:** By default the operator does not have the permission to create routes, however, with the following command you can add the lines needed to the `deploy/role.yaml` file so the operator can expose the `nginx` service with a route:
86+
The above Makefile command will:
87+
- Create a new `my-nginx-ansible-operator` project and generate the entire operator structure and empty `roles/mynginxansibleoperator`
88+
- Create a `MyNginxAnsibleOperator` API
89+
- Added `services` to the operator RBAC
90+
- Changed the default namespace to the value set with `OPERATOR_NAMESPACE`
91+
- Added `size: 1` to the operators custom resource
9192

93+
4. Gather the necessary nginx deployment, service, and task files for the operator to deploy the nginx service:
9294
```bash
93-
echo "- apiGroups:
94-
- route.openshift.io
95-
resources:
96-
- routes
97-
- routes/custom-host
98-
verbs:
99-
- get
100-
- list
101-
- watch
102-
- patch
103-
- update
104-
- create
105-
- delete" >> deploy/role.yaml
95+
make nginx-files
10696
```
10797

108-
5. Build the operator image (use ppc64le for power arch):
109-
98+
5. Build and push the operator:
11099
```bash
111-
operator-sdk build docker.io/$DOCKER_HUB_ID/my.operator_amd64:1.0.0
112-
docker push docker.io/$DOCKER_HUB_ID/my.operator_amd64:1.0.0
100+
make build push
113101
```
114102

115-
6. In the `deploy/operator.yaml` file, replace `"REPLACE_IMAGE"` with the operator image name you built and pushed in the previous step (use ppc64le for power arch):
116-
117-
```text
118-
image: "<docker-hub-id>/my.operator_amd64:1.0.0"
103+
6. Deploy the operator locally:
119104
```
120-
121-
7. Apply the required resources to run the operator
122-
123-
```bash
124-
kubectl apply -f deploy/crds/my.operator.com_myoperators_crd.yaml
125-
kubectl apply -f deploy/service_account.yaml
126-
kubectl apply -f deploy/role.yaml
127-
kubectl apply -f deploy/role_binding.yaml
128-
kubectl apply -f deploy/operator.yaml
129-
kubectl apply -f deploy/crds/my.operator.com_v1alpha1_myoperator_cr.yaml
105+
make deploy
130106
```
131107
132-
8. Ensure the operator pod and the deployed service pod are running:
133-
108+
7. After a few moments you should see your pods begin to start and your service get created:
134109
```bash
135-
kubectl get pods
110+
kubectl get pods -n $OPERATOR_NAMESPACE
136111
```
137112

138113
If everything deployed correctly, you should see output similar to the following after around 60 seconds:
139114

140115
```text
141-
NAME READY STATUS RESTARTS AGE
142-
nginx-7d5598fb56-vw6lz 1/1 Running 0 12s
143-
my-operator-55c6f56c47-b6p7c 1/1 Running 0 48s
116+
NAME READY STATUS RESTARTS AGE
117+
nginx-6ccdb77fd6-6s59q 1/1 Running 0 2s
118+
my-nginx-ansible-operator-controller-manager-7b65577c94-smsm6 2/2 Running 0 10s
144119
```
145120

146-
9. Check that the service is up:
121+
8. Check that the service is up:
147122

148123
```bash
149-
kubectl get service
124+
kubectl get service -n $OPERATOR_NAMESPACE
150125
```
151126

152127
If everything deployed correctly, you should see output similar to the following after around 60 seconds:
153128

154129
```text
155-
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
156-
nginx NodePort 172.30.37.113 <none> 80:30080/TCP 24h
130+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
131+
my-nginx-ansible-operator-controller-manager-metrics-service ClusterIP 10.43.46.134 <none> 8443/TCP 23s
132+
nginx NodePort 10.43.193.244 <none> 80:30080/TCP 12s
157133
```
158134

159135
If you are using an **OCP edge cluster** you will need to `curl` the service using the exposed `route`.
160136

161-
10. Get the exposed route name:
137+
9. Get the exposed route name:
162138

163139
```bash
164-
kubectl get route -n openhorizon-agent
140+
kubectl get route -n $OPERATOR_NAMESPACE
165141
```
166142

167143
If the route was exposed correctly you should see output similar to the following:
@@ -171,7 +147,7 @@ In order to deploy a containerized edge service to an edge cluster, a software d
171147
nginx-route nginx-route-openhorizon-agent.apps.apollo5.cp.fyre.ibm.com nginx 8080 None
172148
```
173149

174-
11. `curl` the service to test if it is functioning correctly:
150+
10. `curl` the service to test if it is functioning correctly:
175151

176152
**OCP edge cluster** substitute the above `HOST/PORT` value:
177153

@@ -182,7 +158,7 @@ In order to deploy a containerized edge service to an edge cluster, a software d
182158
**k3s or microk8s edge cluster**:
183159

184160
```bash
185-
curl <external-ip-address>:30080
161+
curl <ip-address>:30080
186162
```
187163

188164
If the service is running you should see following `Welcome to nginx!` output:
@@ -215,27 +191,15 @@ In order to deploy a containerized edge service to an edge cluster, a software d
215191
</html>
216192
```
217193

218-
12. Delete the resources to stop your operator pod and service:
219-
220-
```bash
221-
kubectl delete crd myoperators.my.operator.com
222-
kubectl delete deployment my-operator
223-
kubectl delete serviceaccount my-operator
224-
kubectl delete rolebinding my-operator
225-
kubectl delete role my-operator
226-
```
227-
228-
**Note:** if any pods are stuck in the `Terminating` state after running the previous commands you can force delete them with the following command:
229-
230-
```bash
231-
kubectl -n <namespace> delete pods --grace-period=0 --force <pod_name(s)>
232-
```
233-
234-
13. Create a tar archive that contains the files inside the operators `deploy/` directory:
194+
11. Delete the operator:
195+
```bash
196+
make undeploy
197+
```
235198

236-
```bash
237-
tar -zcvf operator.tar.gz deploy/*
238-
```
199+
12. Create an `operator.tar.gz` file before moving onto the next section.
200+
```bash
201+
make tar
202+
```
239203

240204
## <a id=publish-op-service></a> Publish Your Operator Example Edge Service
241205

@@ -244,8 +208,7 @@ In order to deploy a containerized edge service to an edge cluster, a software d
244208
1. Create a new working directory for a new horizon project:
245209

246210
```bash
247-
mkdir my-operator && cd my-operator/
248-
hzn dev service new -V 1.0.0 -s my-first-operator -c cluster
211+
hzn dev service new -V 1.0.0 -s $OPERATOR_GROUP_NAME -c cluster
249212
```
250213

251214
2. Transfer the `operator.tar.gz` archive you created in the previous section to your `my-operator/` directory.
@@ -335,13 +298,12 @@ In order to deploy a containerized edge service to an edge cluster, a software d
335298
kubectl get pods -n openhorizon-agent
336299
```
337300
338-
If everything deployed correctly, you should see output similar to the following:
301+
If everything deployed correctly, you should see output similar to the following after around 60 seconds:
339302
340303
```text
341-
NAME READY STATUS RESTARTS AGE
342-
agent-dd984ff96-jmmdl 1/1 Running 0 1d
343-
nginx-7d5598fb56-vw6lz 1/1 Running 0 12s
344-
my-operator-55c6f56c47-b6p7c 1/1 Running 0 48s
304+
NAME READY STATUS RESTARTS AGE
305+
nginx-6ccdb77fd6-6s59q 1/1 Running 0 2s
306+
my-nginx-ansible-operator-controller-manager-7b65577c94-smsm6 2/2 Running 0 10s
345307
```
346308
347309
7. Check that the service is up:
@@ -350,70 +312,72 @@ In order to deploy a containerized edge service to an edge cluster, a software d
350312
kubectl get service -n openhorizon-agent
351313
```
352314
353-
If everything deployed correctly you should see output similar to the following after around 60 seconds:
315+
If everything deployed correctly, you should see output similar to the following after around 60 seconds:
354316
355317
```text
356-
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
357-
nginx NodePort 172.30.37.113 <none> 80:30080/TCP 24h
318+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
319+
my-nginx-ansible-operator-controller-manager-metrics-service ClusterIP 10.43.46.134 <none> 8443/TCP 23s
320+
nginx NodePort 10.43.193.244 <none> 80:30080/TCP 12s
358321
```
359322
360323
If you are using an **OCP edge cluster** you will need to `curl` the service using the exposed `route`.
361324
362325
8. Get the exposed route name:
363326
364-
```bash
365-
kubectl get route -n openhorizon-agent
366-
```
327+
```bash
328+
kubectl get route -n openhorizon-agent
329+
```
367330
368-
If the route was exposed correctly you should see output similar to the following:
331+
If the route was exposed correctly you should see output similar to the following:
369332
370-
```text
371-
NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD
372-
nginx-route nginx-route-openhorizon-agent.apps.apollo5.cp.fyre.ibm.com nginx 8080 None
373-
```
333+
```text
334+
NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD
335+
nginx-route nginx-route-openhorizon-agent.apps.apollo5.cp.fyre.ibm.com nginx 8080 None
336+
```
374337
375338
9. `curl` the service to test if it is functioning correctly:
376-
**OCP edge cluster** substitute the above `HOST/PORT` value:
377339
378-
```bash
379-
curl nginx-route-openhorizon-agent.apps.apollo5.cp.fyre.ibm.com
380-
```
340+
**OCP edge cluster** substitute the above `HOST/PORT` value:
341+
342+
```bash
343+
curl nginx-route-openhorizon-agent.apps.apollo5.cp.fyre.ibm.com
344+
```
381345
382-
**k3s or microk8s edge cluster**:
346+
**k3s or microk8s edge cluster**:
383347
384-
```bash
385-
curl <external-ip-address>:30080
386-
```
348+
```bash
349+
curl <ip-address>:30080
350+
```
387351
388-
If the service is running, you should see the following `Welcome to nginx!` output:
352+
If the service is running you should see following `Welcome to nginx!` output:
389353
390-
```html
391-
<!DOCTYPE html>
392-
<html>
393-
<head>
394-
<title>Welcome to nginx!</title>
395-
<style>
396-
body {
354+
```html
355+
<!DOCTYPE html>
356+
<html>
357+
<head>
358+
<title>Welcome to nginx!</title>
359+
<style>
360+
body {
397361
width: 35em;
398-
margin: 0 auto;
399-
font-family: Tahoma, Verdana, Arial, sans-serif;
400-
}
401-
</style>
402-
</head>
403-
<body>
404-
<h1>Welcome to nginx!</h1>
405-
<p>If you see this page, the nginx web server is successfully installed and
406-
working. Further configuration is required.</p>
407-
408-
<p>For online documentation and support please refer to
409-
<a href="http://nginx.org/">nginx.org</a>.<br/>
410-
Commercial support is available at
411-
<a href="http://nginx.com/">nginx.com</a>.</p>
412-
413-
<p><em>Thank you for using nginx.</em></p>
414-
</body>
415-
</html>
416-
```
362+
margin: 0 auto;
363+
font-family: Tahoma, Verdana, Arial, sans-serif;
364+
}
365+
</style>
366+
</head>
367+
<body>
368+
<h1>Welcome to nginx!</h1>
369+
<p>If you see this page, the nginx web server is successfully installed and
370+
working. Further configuration is required.</p>
371+
372+
<p>For online documentation and support please refer to
373+
<a href="http://nginx.org/">nginx.org</a>.<br/>
374+
Commercial support is available at
375+
<a href="http://nginx.com/">nginx.com</a>.</p>
376+
377+
<p><em>Thank you for using nginx.</em></p>
378+
</body>
379+
</html>
380+
```
417381
418382
10. Unregister your edge cluster:
419383

0 commit comments

Comments
 (0)