|
1 | | -# DEVELOPER GUIDE --- WIP |
| 1 | +# Developer Guide |
2 | 2 |
|
3 | 3 | ## Contributing |
4 | 4 | // TODO(user): Add detailed information on how you would like others to contribute to this project |
5 | 5 |
|
| 6 | + |
6 | 7 | ### How it works |
7 | 8 | This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/). |
8 | 9 |
|
9 | 10 | It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/) |
10 | 11 | which provides a reconcile function responsible for synchronizing resources until the desired state is reached on the cluster. |
11 | 12 |
|
12 | | - |
13 | 13 | ## Local development |
14 | 14 |
|
15 | 15 | ### Prerequisites |
16 | 16 |
|
17 | 17 | * **kubectl**. See [Instaling kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl). |
18 | | -* **minikube**. See [Instaling minkube](https://kubernetes.io/docs/tasks/tools/#minikube). |
| 18 | +* Available local or remote Kubernetes cluster with cluster admin privileges. For instance **minikube**. See [Instaling minkube](https://kubernetes.io/docs/tasks/tools/#minikube). |
19 | 19 | * A copy of the Backstage Operator sources: |
20 | 20 | ```sh |
21 | 21 | git clone https://github.com/janus-idp/operator |
22 | 22 | ``` |
23 | 23 |
|
24 | 24 | ### Local Tests |
25 | 25 |
|
26 | | -To run both unit tests (since 0.0.2) and Kubernetes integration tests ([envtest](https://book.kubebuilder.io/reference/envtest.html)): |
| 26 | +To run: |
| 27 | +* all the unit tests |
| 28 | +* part of [Integration Tests](../integration_tests/README.md) which does not require a real cluster. |
27 | 29 |
|
28 | 30 | ```sh |
29 | 31 | make test |
30 | 32 | ``` |
31 | 33 |
|
32 | | -### Test on the local cluster |
| 34 | +It only takes a few seconds to run, but covers quite a lot of functionality. For early regression detection, it is recommended to run it as often as possible during development. |
33 | 35 |
|
34 | | -You’ll need a Kubernetes cluster to run against. |
35 | | -You can use [minikube](https://kubernetes.io/docs/tasks/tools/#minikube) or [kind](https://kubernetes.io/docs/tasks/tools/#kind) to get a local cluster for testing, or run against a remote cluster. |
| 36 | +### Test on the cluster |
36 | 37 |
|
37 | | -**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows). |
| 38 | +For testing, you will need a Kubernetes cluster, either remote (with sufficient admin rights) or local, such as [minikube](https://kubernetes.io/docs/tasks/tools/#minikube) or [kind](https://kubernetes.io/docs/tasks/tools/#kind) |
38 | 39 |
|
39 | 40 | - Build and push your image to the location specified by `IMG`: |
40 | 41 | ```sh |
41 | 42 | make image-build image-push IMG=<your-registry>/backstage-operator:tag |
42 | 43 | ``` |
43 | 44 |
|
44 | | -- Install the CRDs into the local cluster (minikube is installed and running): |
| 45 | +- Install the Custom Resource Definitions into the local cluster (minikube is installed and running): |
45 | 46 | ```sh |
46 | 47 | make install |
47 | 48 | ``` |
| 49 | +**IMPORTANT:** If you are editing the CRDs, make sure you reinstall it before deploying. |
48 | 50 |
|
49 | | -- You can run your controller standalone (this will run in the foreground, so switch to a new terminal if you want to leave it running) |
50 | | -This way you can see controllers log just in your terminal window which is quite convenient for debugging: |
| 51 | +- To delete the CRDs from the cluster: |
51 | 52 | ```sh |
52 | | -make run |
| 53 | +make uninstall |
53 | 54 | ``` |
54 | 55 |
|
55 | | -- Or deploy the controller to the cluster with the image specified by `IMG`: |
| 56 | +### Run the controller standalone |
| 57 | + |
| 58 | +You can run your controller standalone (this will run in the foreground, so switch to a new terminal if you want to leave it running) |
| 59 | +This way you can see controllers log just in your terminal window which is quite convenient for debugging. |
56 | 60 | ```sh |
57 | | -make deploy [IMG=<your-registry>/backstage-operator:tag] |
| 61 | +make [install] run |
58 | 62 | ``` |
59 | 63 |
|
60 | | -- To generate deployment manifest, use: |
| 64 | +You can use it for manual and automated ([such as](../integration_tests/README.md) `USE_EXISTING_CLUSTER=true make integration-test`) tests efficiently, but, note, RBAC is not working with this kind of deployment. |
| 65 | + |
| 66 | +### Deploy operator to the real cluster |
| 67 | + |
| 68 | +For development, most probably, you will need to specify the image you build and push: |
61 | 69 | ```sh |
62 | | -make deployment-manifest [IMG=<your-registry>/backstage-operator:tag] |
| 70 | +make deploy [IMG=<your-registry>/backstage-operator[:tag]] |
63 | 71 | ``` |
64 | | -it will create the file rhdh-operator-${VERSION}.yaml on the project root and you will be able to share it to make it possible to deploy operator with: |
| 72 | +
|
| 73 | +To undeploy the controller from the cluster: |
65 | 74 | ```sh |
66 | | -kubectl apply -f <path-or-url-to-deployment-script> |
| 75 | +make undeploy |
67 | 76 | ``` |
68 | 77 |
|
69 | | -### Uninstall CRDs |
70 | | -To delete the CRDs from the cluster: |
| 78 | +- To generate deployment manifest, use: |
71 | 79 | ```sh |
72 | | -make uninstall |
| 80 | +make deployment-manifest [IMG=<your-registry>/backstage-operator:tag] |
73 | 81 | ``` |
74 | | -### Undeploy controller |
75 | | -UnDeploy the controller from the cluster: |
| 82 | +it will create the file rhdh-operator-${VERSION}.yaml on the project root and you will be able to share it to make it possible to deploy operator with: |
76 | 83 | ```sh |
77 | | -make undeploy |
| 84 | +kubectl apply -f <path-or-url-to-deployment-script> |
78 | 85 | ``` |
79 | | -### Build and Deploy with OLM: |
80 | | -1. To build operator, bundle and catalog images: |
| 86 | +
|
| 87 | +### Deploy with Operator Lifecycle Manager (valid for v0.3.0+): |
| 88 | +
|
| 89 | +#### OLM |
| 90 | +
|
| 91 | +Make sure your cluster supports **OLM**. For instance [Openshift](https://www.redhat.com/en/technologies/cloud-computing/openshift) supports it out of the box. |
| 92 | +If needed install it using: |
| 93 | +
|
81 | 94 | ```sh |
82 | | -make release-build |
| 95 | +make install-olm |
83 | 96 | ``` |
84 | | -2. To push operator, bundle and catalog images to the registry: |
| 97 | +
|
| 98 | +#### Build and push images |
| 99 | +
|
| 100 | +There are a bunch of commands to build and push to the registry necessary images. |
| 101 | +For development purpose, most probably, you will need to specify the image you build and push with IMAGE_TAG_BASE env variable: |
| 102 | +
|
| 103 | +* `[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make image-build` builds operator manager image (**backstage-operator**) |
| 104 | +* `[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make image-push` pushes operator manager image to **your-registry** |
| 105 | +* `[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make bundle-build` builds operator manager image (**backstage-operator-bundle**) |
| 106 | +* `[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make bundle-push` pushes bundle image to **your-registry** |
| 107 | +* `[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make catalog-build` builds catalog image (**backstage-operator-catalog**) |
| 108 | +* `[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make catalog-push` pushes catalog image to **your-registry** |
| 109 | +
|
| 110 | +You can do it all together using: |
85 | 111 | ```sh |
86 | | -make release-push |
| 112 | +[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make release-build release-push |
87 | 113 | ``` |
88 | | -3. To deploy or update catalog source: |
| 114 | +
|
| 115 | +#### Deploy or update the Catalog Source |
| 116 | +
|
89 | 117 | ```sh |
90 | | -make catalog-update |
| 118 | +[OLM_NAMESPACE=<olm-namespace>] [IMAGE_TAG_BASE=<your-registry>/backstage-operator] make catalog-update |
91 | 119 | ``` |
92 | | -4. To deloy the operator with OLM |
| 120 | +You can point the namespace where OLM installed. By default, in a vanilla Kubernetes, OLM os deployed on 'olm' namespace. In Openshift you have to explicitly point it to **openshift-marketplace** namespace. |
| 121 | +
|
| 122 | +#### Deploy the Operator with OLM |
| 123 | +Default namespace to deploy the Operator is called **backstage-system** , this name fits one defined in [kustomization.yaml](../config/default/kustomization.yaml). So, if you consider changing it you have to change it in this file and define **OPERATOR_NAMESPACE** environment variable. |
| 124 | +Following command creates OperatorGroup and Subscription on Operator namespace |
93 | 125 | ```sh |
94 | | -make deploy-olm |
| 126 | +[OPERATOR_NAMESPACE=<operator-namespace>] make deploy-olm |
95 | 127 | ``` |
96 | | -5. To undeploy the operator with OLM |
| 128 | +To undeploy the Operator |
97 | 129 | ```sh |
98 | 130 | make undeploy-olm |
99 | 131 | ``` |
100 | 132 |
|
101 | | -6. To deploy the operator to Openshift with OLM |
| 133 | +#### Convenient commands to build and deploy operator with OLM |
| 134 | +
|
| 135 | +**NOTE:** OLM has to be installed as a prerequisite |
| 136 | +
|
| 137 | +* To build and deploy the operator to vanilla Kubernetes with OLM |
102 | 138 | ```sh |
103 | | -make deploy-openshift [IMAGE_TAG_BASE=<your-registry>/backstage-operator] |
| 139 | +[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make deploy-k8s-olm |
104 | 140 | ``` |
105 | 141 |
|
106 | | -### Modifying the API definitions |
107 | | -If you are editing the API definitions, make sure you: |
108 | | -- run `make install` before deploying the operator with `make deploy` |
109 | | -- regenerate the manifests and bundle if you plan to deploy the operator with OLM using: |
| 142 | +* To build and deploy the operator to Openshift with OLM |
110 | 143 | ```sh |
111 | | -make manifests bundle |
| 144 | +[IMAGE_TAG_BASE=<your-registry>/backstage-operator] make deploy-openshift |
112 | 145 | ``` |
| 146 | +
|
| 147 | +
|
113 | 148 | **NOTE:** Run `make help` for more information on all potential `make` targets |
114 | 149 |
|
115 | 150 | More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html) |
|
0 commit comments