Kube-Vaccine

This project demonstrates how to write API conversions for Kubernetes CRDs by taking a use case of Covid19 Vaccine registration.

---

Why do we need to do API conversions?

All kubernetes projects contains several APIs that evolves over time and moves to more stable version. This evolution leads to multiple release and keeps updating API server to support latest version. There are clients who also upgrade to latest version with subsequent releases. But what about those clients who still use older versions? So to serve them the requested data in older version, k8s API server needs to support older versions also, for that we write API conversion functions that fetches data from API server in latest version and convert it to requested version and serves the client.

Write API conversions for kubernetes custom resource "Registration"

---

Prerequisite

1. Install Go
2. kind cluster
3. kubebuilder

---

Steps

Step1: Create kubebuilder project

>> mkdir kube-vaccine
>> cd kube-vaccine
>> go mod init
>> kubebuilder init —domain gov.io

Step 2: Create 3 different API versions for kind Registeration

Now let's create APIs for kind Registration using

>> Kubebuilder create api —group cowin —kind Registration —version v1
    Create resource(y/n)  - y
    Create controller(y/n)  - y    

Similarly we create other API versions also, so finally output will be

// v1 API
type RegistrationSpec struct {
	Name             string `json:"name,omitempty"`
	VerifiedID       string `json:"verified_id,omitempty"`
	RegistrationDate string `json:"registration_date,omitempty"`
}

// v2 API
type RegistrationSpec struct {
	Name             string `json:"name,omitempty"`
	VerifiedID       string `json:"verified_id,omitempty"`
	RegistrationDate string `json:"registration_date,omitempty"`
	VaccineName      string `json:"vaccine_name,omitempty"`
}

// v3 API
type RegistrationSpec struct {
	Name           string           `json:"name,omitempty"`
	VerifiedID     string           `json:"verified_id,omitempty"`
	VaccineDetails []*VaccineDetail `json:"vaccine_details,omitempty"`
}

type VaccineDetail struct {
	RegistrationDate string `json:"registration_date,omitempty"`
	VaccineName      string `json:"vaccine_name,omitempty"`
}

Step 3: Make v3 API as storage version

Add tag // +kubebuilder:storageversion on v3 API Registration

Step 4: Create webhooks using kubebuilder command

kubebuilder create webhook --group cowin --kind Registration --version v3 --conversion

Step 5: Edit following files

1. Uncomment patches/webhook_in_registrations.yaml and patches/cainjection_in_registrations.yaml under patchesStrategy in config/crd/kustomization.yaml
2. Uncomment ../webhook and ../certmanager and all the vars related with CERTMANAGER in config/default/kustomization.yaml.
3. Delete maifest.yaml file from config/webhook and also comment manifest.yaml from config/webhook/kustomization.yaml
4. In Makefile file add CRD_OPTIONS ?= "crd:trivialVersions=false"
5. Update conversionReviewVersions: ["v1","v2","v3"] in config/crd/patches/webhook_in_registrations.yaml

Step 6: run below commands

make conversion-gen
make manifests
make install
bin/conversion-gen --input-dirs=./api/v1 --input-dirs=./api/v2 --build-tag=ignore_autogenerated_conversions --output-file-base=zz_generated.conversion --go-header-file=./hack/boilerplate.go.txt
make docker-build docker-push IMG=docker.io/<docker-name>/<img-name>:<img-tag>
kind load docker-image docker.io/<docker-name>/<img-name>:<img-tag> --name kind
make deploy IMG=docker.io/<docker-name>/<img-name>:<img-tag>

Test conversions are working fine

1. Apply v3 sample, using kubectl apply -f config/samples/cowin_v3_registration.yaml
2. Fetch v3 object in v1 API and store it in another file v3Tov1.yaml using kubectl get registration.v1.cowin.gov.io/registration-sample-v3 -o json > v3Tov1.yaml
3. Update the v3Tov1.yaml and change spec.name, then save it and apply kubectl apply -f v3Tov1.yaml
4. Now fetch the same object in v3 API and observe there is no loss in data, kubectl get registration.v3.cowin.gov.io/registration-sample-v3 -o json