|
1 | | -# Contributing to MongoDB Kubernetes Operator |
| 1 | +# Contributing to MongoDB Controllers for Kubernetes (MCK) - Community |
2 | 2 |
|
3 | 3 | First you need to get familiar with the [Architecture guide](architecture.md), which explains |
4 | 4 | from a high perspective how everything works together. |
5 | 5 |
|
6 | | -After our experience building the [Enterprise MongoDB Kubernetes |
7 | | -Operator](https://github.com/mongodb/mongodb-kubernetes), we have |
8 | | -realized that it is very important to have a clean environment to work, and as such we have |
9 | | -adopted a strategy that makes it easier for everyone to contribute. |
10 | | - |
11 | 6 | This strategy is based on using |
12 | 7 | [`envtest`](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest) for setting up the tests |
13 | 8 | and `go test` for running the tests, and making the test-runner itself run as a Kubernetes Pod. This |
@@ -45,231 +40,3 @@ each one of them in charge of some part of the lifecycle of the MongoDB database |
45 | 40 | * Please ensure you have signed our Contributor Agreement. You can find it [here](https://www.mongodb.com/legal/contributor-agreement). |
46 | 41 |
|
47 | 42 | * Please ensure that all commits are signed. |
48 | | - |
49 | | -## Developer Configuration |
50 | | - |
51 | | -The operator is built using `golang`. We use a simple |
52 | | -json file that describe some local options that you need to set for the testing environment |
53 | | -to be able to run properly. Create a json file with the following content: |
54 | | - |
55 | | -```json |
56 | | -{ |
57 | | - "namespace": "mongodb", |
58 | | - "repo_url": "localhost:5000", |
59 | | - "operator_image": "mongodb-kubernetes-operator", |
60 | | - "e2e_image": "community-operator-e2e", |
61 | | - "version_upgrade_hook_image": "mongodb-kubernetes-operator-version-upgrade-post-start-hook", |
62 | | - "agent_image": "mongodb-agent-ubi-dev", |
63 | | - "readiness_probe_image": "mongodb-kubernetes-readinessprobe", |
64 | | - "s3_bucket": "" |
65 | | -} |
66 | | -``` |
67 | | - |
68 | | -#### Config Options |
69 | | - |
70 | | -1. `namespace` is the namespace that will be used by scripts/tooling. All the resources will be deployed here. |
71 | | -2. `repo_url` the repository that should be used to push/pull all images. |
72 | | -3. `operator_image` will be used as the name of the operator deployment, and the name of the operator image when build. |
73 | | -4. `e2e_image` the name of e2e test image that will be built. |
74 | | -5. `version_upgrade_hook_image` the name of the version upgrade post start hook image. |
75 | | -6. `agent_image` the name of the agent image. |
76 | | -7. `s3_bucket` the S3 bucket that Dockerfiles will be pushed to as part of the release process. Note: this is only required when running the release tasks locally. |
77 | | - |
78 | | - |
79 | | -You can set the `MONGODB_COMMUNITY_CONFIG` environment variable to be the absolute path of this file. |
80 | | -It will default to `~/.community-operator-dev/config.json` |
81 | | - |
82 | | -Please see [here](./build_operator_locally.md) to see how to build and deploy the operator locally. |
83 | | - |
84 | | -## Configure Docker registry |
85 | | - |
86 | | -The build process consists of multiple Docker images being built. You need to specify |
87 | | -where you want the locally built images to be pushed. The Docker registry needs to be |
88 | | -accessible from your Kubernetes cluster. |
89 | | - |
90 | | -### Local kind cluster |
91 | | -For local testing you can use a [local Kind cluster](build_operator_locally.md#steps). |
92 | | - |
93 | | -## Test Namespace |
94 | | - |
95 | | -You can change the namespace used for tests, if you are using `Kind`, for |
96 | | -instance, you can leave this as `mongodb`. |
97 | | - |
98 | | -## Python Environment |
99 | | - |
100 | | -The test runner is a Python script, in order to use it a virtualenv needs to be |
101 | | -created. |
102 | | - |
103 | | -**Python 3.9 is not supported yet. Please use Python 3.8.** |
104 | | - |
105 | | -### Pip |
106 | | -```sh |
107 | | -python -m venv venv |
108 | | -source venv/bin/activate |
109 | | -python -m pip install -r requirements.txt |
110 | | -``` |
111 | | - |
112 | | -### Pipenv |
113 | | - |
114 | | -* create a python environment and install dependencies. |
115 | | -```bash |
116 | | -pipenv install -r requirements.txt |
117 | | -``` |
118 | | - |
119 | | -* activate the python environment. |
120 | | -```bash |
121 | | -pipenv shell |
122 | | -``` |
123 | | - |
124 | | - |
125 | | -# Deploying the Operator |
126 | | - |
127 | | -In order to deploy the Operator from source, you can run the following command. |
128 | | - |
129 | | -```sh |
130 | | -make operator-image deploy |
131 | | -``` |
132 | | - |
133 | | -This will build and deploy the operator to namespace specified in your configuration file. |
134 | | - |
135 | | -If you are using a local docker registry you should run the following command. |
136 | | -The additional `IMG_BUILD_ARGS=--insecure` variable will add the `--insecure` flag to the command creating the manifests. |
137 | | -This is necessary if your local registry is not secure. Read more about the flag on the [documentatio](https://docs.docker.com/reference/cli/docker/manifest/#working-with-insecure-registries) |
138 | | - |
139 | | -```sh |
140 | | -IMG_BUILD_ARGS=--insecure make operator-image deploy |
141 | | -``` |
142 | | - |
143 | | - |
144 | | -#### See the operator deployment |
145 | | -```sh |
146 | | -kubectl get pods |
147 | | -``` |
148 | | - |
149 | | -#### (Optional) Create a MongoDBCommunity Resource |
150 | | - |
151 | | -Follow the steps outlined [here](./deploy-configure.md) to deploy some resources. |
152 | | - |
153 | | -#### Cleanup |
154 | | -To remove the operator and any created resources you can run |
155 | | - |
156 | | -```sh |
157 | | -make undeploy |
158 | | -``` |
159 | | - |
160 | | -Alternatively, you can run the operator locally. Make sure you follow the steps outlined in [run-operator-locally.md](run-operator-locally.md) |
161 | | - |
162 | | -```sh |
163 | | -make run |
164 | | -``` |
165 | | - |
166 | | -# Running Tests |
167 | | - |
168 | | -### Unit tests |
169 | | - |
170 | | -Unit tests should be run from the root of the project with: |
171 | | - |
172 | | -```sh |
173 | | -make test |
174 | | -``` |
175 | | - |
176 | | -### E2E Tests |
177 | | - |
178 | | -If this is the first time running E2E tests, you will need to ensure that you have built and pushed |
179 | | -all images required by the E2E tests. You can do this by running the following command, |
180 | | -or with the additional `IMG_BUILD_ARGS=--insecure` described above. |
181 | | - |
182 | | -```sh |
183 | | -make all-images |
184 | | -``` |
185 | | - |
186 | | -For subsequent tests you can use |
187 | | - |
188 | | -```sh |
189 | | -make e2e-k8s test=<test-name> |
190 | | -``` |
191 | | - |
192 | | -This will only re-build the e2e test image. Add `IMG_BUILD_ARGS=--insecure` if necessary |
193 | | - |
194 | | -We have built a simple mechanism to run E2E tests on your cluster using a runner |
195 | | -that deploys a series of Kubernetes objects, runs them, and awaits for their |
196 | | -completion. If the objects complete with a Success status, it means that the |
197 | | -tests were run successfully. |
198 | | - |
199 | | -The available tests can be found in the `tests/e2e` directory, at the time of this |
200 | | -writing we have: |
201 | | - |
202 | | -```sh |
203 | | -$ ls -l test/e2e |
204 | | -replica_set |
205 | | -replica_set_change_version |
206 | | -replica_set_readiness_probe |
207 | | -replica_set_scale |
208 | | -... |
209 | | -``` |
210 | | - |
211 | | -The tests should run individually using the runner like this, or additionally with `IMG_BUILD_ARGS=--insecure`: |
212 | | - |
213 | | -```sh |
214 | | -make e2e-k8s test=replica_set |
215 | | -``` |
216 | | - |
217 | | -This will run the `replica_set` E2E test which is a simple test which installs a |
218 | | -MongoDB Replica Set and asserts that the deployed server can be connected to. |
219 | | - |
220 | | -### Run the test locally with go test & Telepresence |
221 | | -```sh |
222 | | -make e2e-telepresence test=<test-name> |
223 | | -``` |
224 | | - |
225 | | -This method uses telepresence to allow connectivity as if your local machine is in the kubernetes cluster, |
226 | | -there will be full MongoDB connectivity using `go test` locally. |
227 | | - |
228 | | -Note: you must install [telepresence](https://www.getambassador.io/docs/telepresence/latest/quick-start/) before using this method. |
229 | | - |
230 | | -If on MacOS, you can run `make install-prerequisites-macos` which will perform the installation. |
231 | | - |
232 | | -### Running with Github Actions |
233 | | - |
234 | | -Run a single test |
235 | | - |
236 | | -```sh |
237 | | -make e2e-gh test=<test-name> |
238 | | -``` |
239 | | - |
240 | | -Run all tests. |
241 | | - |
242 | | -* Navigate to the Actions tab on the github repo |
243 | | -* `Run E2E` > `Run Workflow` > `Your Branch` |
244 | | - |
245 | | -Note: the code must be pushed to a remote branch before this will work. |
246 | | - |
247 | | - |
248 | | -## Troubleshooting |
249 | | -When you run a test locally, if the `e2e-test` pod is present, you will have to |
250 | | -first manually delete it; failing to do so will cause the `e2e-test` pod to fail. |
251 | | - |
252 | | -# Writing new E2E tests |
253 | | - |
254 | | -You can start with the `replica_set` test as a starting point to write a new test. |
255 | | -The tests are written using `envtest` and they are run using `go test`. |
256 | | - |
257 | | -Adding a new test is as easy as creating a new directory in `test/e2e` with the |
258 | | -new E2E test, and to run them: |
259 | | - |
260 | | -```sh |
261 | | -make e2e test=<test-name> |
262 | | -``` |
263 | | - |
264 | | -# Before Committing your code |
265 | | - |
266 | | -## Set up pre-commit hooks |
267 | | -To set up the pre-commit hooks, please create symbolic links from the provided [hooks](https://github.com/mongodb/mongodb-kubernetes-operator/tree/master/scripts/git-hooks): |
268 | | - |
269 | | -* Navigate to your `.git/hooks` directory: |
270 | | - |
271 | | - `cd .git/hooks` |
272 | | - |
273 | | -* Create a symlink for every file in the `scripts/git-hooks` directory: |
274 | | - |
275 | | - `ln -s -f ../../scripts/git-hooks/* .` |
0 commit comments