From 9b2d2b302736e077368e77ade79b0f9ab9b57d54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Sun, 12 Feb 2023 15:20:31 +0100 Subject: [PATCH 1/6] Adds explanation of crate2nix and tilt based development workflow to the docs. For implementation, see: - https://github.com/stackabletech/operator-templating/pull/212 - https://github.com/stackabletech/hdfs-operator/pull/312 --- modules/contributor/nav.adoc | 1 + .../pages/testing_on_kubernetes.adoc | 64 +++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 modules/contributor/pages/testing_on_kubernetes.adoc diff --git a/modules/contributor/nav.adoc b/modules/contributor/nav.adoc index c977c0d7c..58d81f4e1 100644 --- a/modules/contributor/nav.adoc +++ b/modules/contributor/nav.adoc @@ -1,6 +1,7 @@ * xref:index.adoc[] ** xref:steps.adoc[] +** xref:testing_on_kubernetes.adoc[] ** xref:development_dashboard.adoc[] ** xref:style_guide.adoc[] ** Implementation guidelines diff --git a/modules/contributor/pages/testing_on_kubernetes.adoc b/modules/contributor/pages/testing_on_kubernetes.adoc new file mode 100644 index 000000000..2cee5f078 --- /dev/null +++ b/modules/contributor/pages/testing_on_kubernetes.adoc @@ -0,0 +1,64 @@ += Testing your Code on Kubernetes + +== Description +It can sometimes be a bit cumbersome to actually test your code on Kubernetes proper, as there are many moving parts involved. +You need to compile the code, build helm charts, build and push the container images, etc. + +While we do have CI actions for this, those actions also run some tests and other checks that can take a fair bit of time and are not readily available to developers outside of the Stackable organization. +Also, if you need to make changes to an operator and the framework at the same time, compiling the operator with your local version of the framework becomes very difficult in CI actions. + +For these reasons we have created a developer focused deployment mechanism that allows for easy local development, while still enabling full-scale testing in an actual Kubernetes cluster. + +The main tool that is used for enabling these short feedback loops is called https://tilt.dev/[Tilt]. +Tilt is a tool that continuously monitors your local codebase and automatically deploys any changes you make to the Kubernetes cluster defined by your current kubeconfig. + +Effectively this means, that when you have reached a state in your code that you would like to deploy to Kubernetes to look at more in depth, all you need to do is .. nothing - it has already been build, packaged and deployed in the background. + +A very important prerequisite for this of course is short build times! + +To shorten these, we have settled on a tool called https://github.com/kolloch/crate2nix[crate2nix]. +This tool uses the https://nixos.org/[Nix package manager] to cache intermediate build steps and only recompile what has actually changed, thus significantly shortening build times. + +== Installation +Due to the nature of how Nix works, all the setup steps are defined in the operator repositories and automatically applied when you start using this workflow. + +The only prerequisite you need to install is the actual Nix package manager - you can find installation instructions and additional documentation on the https://nixos.org/download.html[Nix website]. + +**TL/DR** +[source,bash] +---- +sh <(curl -L https://nixos.org/nix/install) --daemon +---- + +Just installing Nix does not affect your system much, as it keeps all its configuration and installed packages separate from other package managers and you won't even notice it is there, unless you actually start using it. + +== Using + +The build and deploy steps for installing and running the operator are defined in the `Tiltfile` in the operators repository. +We do encourage you to check out this file if you are interested in how things work under the hood, but you can also just use the command provided below and everything should _just work_. +For more context on how to read this file please have a look at the https://docs.tilt.dev/api.html[Tiltfile API Reference], which is based on https://github.com/bazelbuild/starlark/blob/master/spec.md[Starlark]. + +We provide a target in the Makefile to start everything up: + +[source,bash] +---- +make run-dev +---- + +After running this, Tilt should be up and doing its thing, in the console you'll see something similar to the following: + +---- +➜ hdfs-operator git:(main) ✗ make run-dev +nix run -f. tilt -- up --port 5430 +Tilt started on http://localhost:5430/ +v0.30.13, built + +(space) to open the browser +(s) to stream logs (--stream=true) +(t) to open legacy terminal mode (--legacy=true) +(ctrl-c) to exit +---- + +You can now either hit the spacebar to open the Tilt user interface, or manually navigate to the url shown. + +NOTE: The port used will be different for every repository from the Stackable organisation, in order to allow running multiple deployment workflows at the same time without getting port conflicts. From 1b95be36b35ed4438d5f4de3e6be682b6f257fdd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Mon, 13 Feb 2023 10:28:51 +0100 Subject: [PATCH 2/6] Update modules/contributor/pages/testing_on_kubernetes.adoc Co-authored-by: Natalie --- modules/contributor/pages/testing_on_kubernetes.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/contributor/pages/testing_on_kubernetes.adoc b/modules/contributor/pages/testing_on_kubernetes.adoc index 2cee5f078..d81d9f958 100644 --- a/modules/contributor/pages/testing_on_kubernetes.adoc +++ b/modules/contributor/pages/testing_on_kubernetes.adoc @@ -12,7 +12,7 @@ For these reasons we have created a developer focused deployment mechanism that The main tool that is used for enabling these short feedback loops is called https://tilt.dev/[Tilt]. Tilt is a tool that continuously monitors your local codebase and automatically deploys any changes you make to the Kubernetes cluster defined by your current kubeconfig. -Effectively this means, that when you have reached a state in your code that you would like to deploy to Kubernetes to look at more in depth, all you need to do is .. nothing - it has already been build, packaged and deployed in the background. +Effectively this means, that when you have reached a state in your code that you would like to deploy to Kubernetes to look at more in depth, all you need to do is .. nothing - it has already been built, packaged and deployed in the background. A very important prerequisite for this of course is short build times! From d1ffd513ff23bf86860899f3bc0df5b8e2d9434b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Mon, 13 Feb 2023 13:50:46 +0100 Subject: [PATCH 3/6] Addressed review comment on enabling nix-command --- modules/contributor/pages/testing_on_kubernetes.adoc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/modules/contributor/pages/testing_on_kubernetes.adoc b/modules/contributor/pages/testing_on_kubernetes.adoc index d81d9f958..b91bf04ed 100644 --- a/modules/contributor/pages/testing_on_kubernetes.adoc +++ b/modules/contributor/pages/testing_on_kubernetes.adoc @@ -30,6 +30,11 @@ The only prerequisite you need to install is the actual Nix package manager - yo sh <(curl -L https://nixos.org/nix/install) --daemon ---- +After this is done you also need to add a setting to your Nix config in `/etc/nix/nix.conf`: +---- +experimental-features = nix-command +---- + Just installing Nix does not affect your system much, as it keeps all its configuration and installed packages separate from other package managers and you won't even notice it is there, unless you actually start using it. == Using From a7d03dab0fed49b3f25e9da272b3ff4b43ca593e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Mon, 13 Feb 2023 15:04:44 +0100 Subject: [PATCH 4/6] Changed link to Starlark spec to refer to commit hash. --- modules/contributor/pages/testing_on_kubernetes.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/contributor/pages/testing_on_kubernetes.adoc b/modules/contributor/pages/testing_on_kubernetes.adoc index b91bf04ed..1e9ba9e27 100644 --- a/modules/contributor/pages/testing_on_kubernetes.adoc +++ b/modules/contributor/pages/testing_on_kubernetes.adoc @@ -41,7 +41,7 @@ Just installing Nix does not affect your system much, as it keeps all its config The build and deploy steps for installing and running the operator are defined in the `Tiltfile` in the operators repository. We do encourage you to check out this file if you are interested in how things work under the hood, but you can also just use the command provided below and everything should _just work_. -For more context on how to read this file please have a look at the https://docs.tilt.dev/api.html[Tiltfile API Reference], which is based on https://github.com/bazelbuild/starlark/blob/master/spec.md[Starlark]. +For more context on how to read this file please have a look at the https://docs.tilt.dev/api.html[Tiltfile API Reference], which is based on https://github.com/bazelbuild/starlark/blob/32993fa0d1f1e4f3af167d249be95885ba5014ad/spec.md[Starlark]. We provide a target in the Makefile to start everything up: From 3a3497a5b0490b161b74b609a9a9f9d89932869a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Mon, 13 Feb 2023 22:35:10 +0100 Subject: [PATCH 5/6] Added section about configuring the registry used by Tilt. --- .../contributor/pages/testing_on_kubernetes.adoc | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/modules/contributor/pages/testing_on_kubernetes.adoc b/modules/contributor/pages/testing_on_kubernetes.adoc index 1e9ba9e27..55b43f913 100644 --- a/modules/contributor/pages/testing_on_kubernetes.adoc +++ b/modules/contributor/pages/testing_on_kubernetes.adoc @@ -67,3 +67,19 @@ v0.30.13, built You can now either hit the spacebar to open the Tilt user interface, or manually navigate to the url shown. NOTE: The port used will be different for every repository from the Stackable organisation, in order to allow running multiple deployment workflows at the same time without getting port conflicts. + +=== Configuring the Registry Used +If you are using a local Kubernetes like Kind, K3s or similar for your development Tilt will work right out of the box for you, as it will directly push the images to your local Kubernetes cluster (see https://docs.tilt.dev/personal_registry.html for more information). + +If you are using a remote cluster, Tilt will push the generated container images to a remote registry, in order for your Kubernetes to be able to access them. +We have configured `docker.stackable.tech/sandbox` as the default registry, as this is what all our developers use. +External contributors will not have access to this registry and need to override this to a registry of their choice. + +Overriding the default registry can be done by providing a file called `tilt_options.json` in the same directory as the Tiltfile. + +[source, json] +---- +{ +"default_registry": "docker.stackable.tech/soenkeliebau", +} +---- \ No newline at end of file From b9e5ea61f53ad142aabbb72c41ca9570cb52e556 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Liebau?= Date: Tue, 14 Feb 2023 12:47:01 +0100 Subject: [PATCH 6/6] Try to get this branch deployed by Netlify preview --- antora-playbook.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/antora-playbook.yml b/antora-playbook.yml index 96950a162..691ee5177 100644 --- a/antora-playbook.yml +++ b/antora-playbook.yml @@ -19,7 +19,7 @@ content: sources: - url: https://github.com/stackabletech/documentation.git tags: [] - branches: [main, release/*] + branches: [HEAD, release/*] # stackablectl - url: https://github.com/stackabletech/stackablectl.git start_path: docs