Prepare environment¶
Install Toolchain¶
For efficient workflows, tools make life easier. Please install:
- skaffold, v1.7.0
- kustomize, v2.0.3 (same as in
kubectl
, necessary as long as this issue hasn’t been resolved)
When you opt for using a local cluster (see below), add:
Important
The tools mentioned in Getting started are obligatory.
Tip
You might consider using a tooling management tool (ha!) like ASDF for installation and keeping up-to-date.
Note
You don’t need to worry about anything related to Dataverse Java compilation and packaging. Image building will take care of it. So if you don’t have Maven installed, don’t use an IDE (like in CI) or just want to try out sth.: you are all set. Go ahead.
Spin up cluster¶
Wether you need a test, ephemeral, staging or whatever cluster, using the tools outlined here is just one example how to do it. Take this as a proven working path, but feel free to roll your own and give feedback.
Local cluster¶
When running on your laptop or workstation, you have two options.
Either use minikube
or kind
.
Minikube is easier to get started with, but uses more resources. KinD is not so easy, but very low on resource usage. Up to you.
If you want to use k3s
, microk8s
or similar, please consult the
Skaffold docs, search via Google, etc. Again: PRs welcome.
Minikube¶
Please follow Start with setup of minikube VM to create your cluster. No need to deploy yet, we are just preparing for now.
Kubernetes IN Docker (“KinD”)¶
Skaffold supports this out of the box. Using kind
, your context will be set
to sth. like “kind-kind”, which triggers loading images into a local kind
cluster
instead of pushing to a remote registry.
After installing Docker and kind
, you simply need to run (context will be
set for you):
kind create cluster
If you prefer a specific K8s version, e.g. 1.14.6 expand/hide
kind create cluster --image kindest/node:v1.14.6
Note
Please note that kind
might have some troubles with changing host networks and
switching to a new DNS resolver. You might need to rebuild the cluster, which is
no big deal (very fast).
Remote cluster¶
Currently only using a Local cluster with kind
is supported by this project.
PRs and ideas welcome.
Hint
We’ll most likely need Kaniko or similar for that in your cluster, as Docker Hub must not be cluttered.
Clone source files¶
For building images from any branch or commit of Dataverse, you need to have
it in your (Docker) build context. Easily achieved by running the following
after cloning the project (master
branch):
git clone https://github.com/IQSS/dataverse-kubernetes.git
cd dataverse-kubernetes
git submodule sync --recursive
git submodule update --init --recursive
This will checkout the upstream Dataverse project into ./dataverse
, pulling
the develop
branch and tags. Please read the below carefully.
Tip
- For more on how to use Git Submodules, have a look here, or here, maybe here or or last resort.
- You can even point your IDE to this new subfolder and it will work like a champ.
Note
You think this is weird and/or cumbersome? Expand/hide
As long as K8s usage is not a first class citizen for IQSS, this project should not (or cannot) be included in Dataverse upstream.
+ We don't have to deal with upstream merge process for PRs and can move independent and quicker.
+ We can use tools like Skaffold, Kustomization, etc only usable when living at the topmost level.
- We have to deal with `git submodules` and somewhat bloated image builds.
- We cannot use fancy Maven tools like JIB and others.
Checkout target branch¶
When a release in this project is tagged, the submodule is updated to point to the latest commit available upstream. For any real world scenarios, you will need to checkout something different.
If you want a feature branch, add your fork or whatever necessary: just follow normal
git submodule
routines.
Example: Switch to latest develop
¶
cd ./dataverse
git checkout develop
git pull origin develop:develop
Example: Switch to feature branch in (your) fork¶
cd ./dataverse
git remote add poikilotherm https://github.com/poikilotherm/dataverse.git
git fetch poikilotherm
git pull poikilotherm poikilotherm/5974-oidc-impl:testbranch
git checkout testbranch