~olbohlen/cookie-operator.git

New file
			@@ -0,0 +1,257 @@
			* I need a cookie recipe database!

			...and because it makes total sense, we are going to abuse the K8s API for it.

			- thankfully we can extend K8s with Custom Resource Definitions (CRDs)
			- but how does it work?
			- =CustomResourceDefinitions= are themselves a =Resource=, based on a =ResourceDefinition=

			#+begin_example
			$ oc api-resources \| egrep "(NAME\|CustomResourceDefinition)"
			NAME SHORTNAMES APIVERSION NAMESPACED KIND
			customresourcedefinitions crd,crds apiextensions.k8s.io/v1 false CustomResourceDefinition
			$ oc explain crds
			KIND: CustomResourceDefinition
			VERSION: apiextensions.k8s.io/v1

			DESCRIPTION:
			CustomResourceDefinition represents a resource that should be exposed on
			the API server. Its name MUST be in the format <.spec.name>.<.spec.group>.
			[...]
			#+end_example

			* Preparing the cookierecipes CRD

			Let's create the CRD from https://www.eenfach.de/gitblit/blob/~olbohlen!cookie-operator.git/master/cookie-crd.yaml

			#+begin_example
			$ oc new-project kitchen
			Now using project "kitchen" on server "https://api.crc.testing:6443".
			$ oc create -f cookie-crd.yaml
			Error from server (Forbidden): error when creating "cookie-crd.yaml":
			customresourcedefinitions.apiextensions.k8s.io is forbidden: User "developer"
			cannot create resource "customresourcedefinitions" in API group "apiextensions.k8s.io"
			at the cluster scope

			$ oc login -u kubeadmin
			$ oc create -f cookie-crd.yaml
			customresourcedefinition.apiextensions.k8s.io/cookierecipes.de.eenfach.olbohlen created
			$ oc login -u developer
			#+end_example

			Now the cluster knows about the CRD and we could store recipes!

			* Storing some sample recipes

			We try to store sample cookie recipes...but:

			#+begin_example
			$ oc create -f sample-cookie.yaml
			Error from server (Forbidden): error when creating "sample-cookie.yaml":
			cookierecipes.de.eenfach.olbohlen is forbidden: User "developer" cannot create
			resource "cookierecipes" in API group "de.eenfach.olbohlen" in the namespace "kitchen"
			Error from server (Forbidden): error when creating "sample-cookie.yaml":
			cookierecipes.de.eenfach.olbohlen is forbidden: User "developer" cannot create
			resource "cookierecipes" in API group "de.eenfach.olbohlen" in the namespace "kitchen"
			#+end_example

			We need to set up some RBAC resources first:
			- a =ClusterRole= that allows viewing recipes
			- a =ClusterRole= that allows editing recipes
			- and a =ClusterRoleBinding= that allows that for authenticated users

			* Creating RBAC resources

			Apply the RBAC definitions from: https://www.eenfach.de/gitblit/blob/~olbohlen!cookie-operator.git/master/cookie-rbac.yaml
			#+begin_example
			$ oc login -u kubeadmin
			$ oc create -f cookie-rbac.yaml
			clusterrole.rbac.authorization.k8s.io/cookierecipe-edit created
			clusterrole.rbac.authorization.k8s.io/cookierecipe-view created
			clusterrolebinding.rbac.authorization.k8s.io/cookierecipe-edit created
			#+end_example

			The =ClusterRoleBinding= "cookierecipe-edit" allows =system:authenticated:oauth=
			group members to edit =cookierecipes=.
			=system:authenticated:oauth= contains all users that logged in via the OAuth
			service (via an =IdentityProvider=).

			* Storing some sample recipes (hopefully this time!!)

			Now we should be able to create the sample recipes:

			#+begin_example
			$ oc login -u developer
			$ oc create -f sample-cookie.yaml
			cookierecipe.de.eenfach.olbohlen/vintage-chocolate-chip created
			cookierecipe.de.eenfach.olbohlen/double-dipped-shortbread created
			$ oc get cookierecipe
			NAME AGE
			double-dipped-shortbread 17s
			vintage-chocolate-chip 17s
			#+end_example

			There is no functionality here - we just stored the recipes in the etcd via the K8s API.

			* Now can we do anything with our recipes?
			Of course we can oc get -o yaml for example on them and filter:

			#+begin_example
			$ oc get cookierecipe vintage-chocolate-chip -o yaml \| yq -y .spec.ingredients[0]
			amount: 150
			name: salted butter
			remarks: softened
			unit: grams
			#+end_example

			This is handy, as we can extract exactly the data which we need at a time.

			But...it's a lot of manual work...

			* I'm an operator with my pocket calculator

			Operators were introduced as "Kubernetes Native Applications" and that actually
			means nothing. Operators are in the end just =Pods=.

			These Pods run one or more containers, but one container should run a =Controller=
			that can interprete your =CustomResources=.

			So let's write a CookieRecipe Operator. In shell-script... :)

			Of course this Operator is not compatible with the =OperatorLifecycyleManager= (=OLM=),
			so we have to install it manually.

			* What do we need?

			We need:
			- a ContainerImage
			- and therefore probably a Containerfile
			- Controller code

			Then we are going to build the Operator ContainerImage and push it to a Registry.

			* Let's review the Containerfile

			The Containerfile is here:

			https://www.eenfach.de/gitblit/blob/~olbohlen!cookie-operator.git/master/Containerfile

			the base image is a "kshbase" image, which itself is based upon ubi9 containing also a ksh93
			and an oc client.

			* Have a look at the Controller

			The controller is written in KornShell 93 (ksh93), which is mostly bash compatible :)

			The code is here:

			https://www.eenfach.de/gitblit/blob/~olbohlen!cookie-operator.git/master/recipe-processor.ksh

			* Now let's also have a look at the deployment

			Note: this deployment does not use an =ImageStream=, so it would work also on native k8s

			https://www.eenfach.de/gitblit/blob/~olbohlen!cookie-operator.git/master/cookie-operator-deployment.yaml

			This deployment requires a =ServiceAccount= called "cookieprocessor", this =ServiceAccount= provides
			a Token to authenticate against the API (which we use in the controller script).

			* The ServiceAccount

			We need a =ServiceAccount=, but that alone will not help. The =ServiceAccount= is NOT member
			of =system:authenticated:oauth=, so it can't read =cookierecipes= based on the =ClusterRoleBinding= we created earlier.
			For that reason we also create a =RoleBinding= (namespaced!) that allows reading recipes:

			https://www.eenfach.de/gitblit/blob/~olbohlen!cookie-operator.git/master/cookieprocessor-sa.yaml

			* Building the stuff together

			#+begin_example
			$ oc create -f cookieprocessor-sa.yaml
			serviceaccount/cookieprocessor created
			rolebinding.rbac.authorization.k8s.io/cookierecipe-view created
			#+end_example

			The registry docker.eenfach.de requires login credentials, so we need to set up a secret and link it.
			First login to the registry with podman login, then pick the resulting auth.json:

			#+begin_example
			$ podman login -u olbohlen docker.eenfach.de
			Password:
			Login Succeeded!
			$ oc create secret generic docker-eenfach-de \
			> --from-file=.dockerconfigjson=${XDG_RUNTIME_DIR}/containers/auth.json \
			> --type kubernetes.io/dockerconfigjson
			secret/docker-eenfach-de created
			$ oc secrets link cookieprocessor docker-eenfach-de --for pull
			#+end_example

			* Deploying the Operator

			Now that we have everything in place, we will just deploy the Operator Pod:

			#+begin_example
			$ oc create -f cookie-operator-deployment.yaml
			deployment.apps/recipe-processor created
			$ oc get pod
			NAME READY STATUS RESTARTS AGE
			recipe-processor-7f9969697b-qt9lv 1/1 Running 0 17s
			$ oc logs -f recipe-processor-7f9969697b-qt9lv


			New recipe found: double-dipped-shortbread
			--------------------------------------------------------------------------

			Pre: we heat up the oven to 180 degrees Celsius

			Fetching ingredients from recipe:
			----------------------------------
			Fetching 200grams of salted butter (softened)
			[...]
			#+end_example

			The Operator will process both sample recipes.

			* Test the Operator

			We should test if the Operator notices new recipes, so let's create a third
			recipe from
			https://www.eenfach.de/gitblit/blob/~olbohlen!cookie-operator.git/master/oaty-hazelnut-cookies.yaml

			#+begin_example
			$ oc create -f oaty-hazelnut-cookies.yaml
			cookierecipe.de.eenfach.olbohlen/oaty-hazelnut created
			#+end_example

			After a few seconds, we should see in the Operator log:
			#+begin_example
			New recipe found: oaty-hazelnut
			--------------------------------------------------------------------------

			Pre: we heat up the oven to 180 degrees Celsius
			[...]
			#+end_example

			* Test for updated recipes

			But what if we update a resource?
			Keep the oc logs -f on the Operator Pod open, and in another terminal let's patch a recipe.

			#+begin_example
			$ oc patch cookierecipes double-dipped-shortbread --type merge \
			> -p '{"spec":{"temperature":172}}'
			cookierecipe.de.eenfach.olbohlen/double-dipped-shortbread patched
			#+end_example

			And again in the log you should see

			#+begin_example
			New recipe found: double-dipped-shortbread
			--------------------------------------------------------------------------

			Pre: we heat up the oven to 172 degrees Celsius

			Fetching ingredients from recipe:
			----------------------------------
			[...]
			#+end_example