This change adds some developper documentation.

Change-Id: I5b366b1e30a6e4c095ce859587261f76b75d4c3e
Tristan Cacqueray 3 years ago
parent 54643ac881
commit ebc121774b

@ -0,0 +1,66 @@
# Developper documentation
The zuul operator is a container application that manages a
zuul service described by a high level description (named CR).
Its goal is to create the kubernetes resources and to perform
the runtime operations.
To describe the kubernetes resources such as Deployment and Service,
the zuul operator uses the Dhall language to convert the CR input
into the kubernetes resources.
To apply and manage the resources, the zuul operator uses Ansible
through the operator-framework to execute the roles/zuul when
a Zuul CR is requested.
The following sections explain how to evaluate the Dhall configuration
and the Ansible task locally, outside of a kubernetes pod.
This simplifies the development and contribution process.
## Setup tools
Install the `dhall-to-yaml` and `yaml-to-dhall` tool by following this tutorial:
Or use the zuul-operator image:
alias dhall-to-yaml="$CR run --rm --entrypoint dhall-to-yaml -i"
alias yaml-to-dhall="$CR run --rm --entrypoint yaml-to-dhall -i"
## Evaluate the dhall expression manually:
First you need to convert a CR spec to a dhall record, for example using the test file `playbooks/files/cr_spec.yaml`:
INPUT=$(yaml-to-dhall "(./conf/zuul/input.dhall).Input.Type" < playbooks/files/cr_spec.yaml)
Then you can evaluate the resources function, for example to get the scheduler service:
dhall-to-yaml --omit-empty --explain <<< "(./conf/zuul/resources.dhall ($INPUT)).Components.Zuul.Scheduler"
Or get all the kubernetes resources:
dhall-to-yaml --omit-empty <<< "(./conf/zuul/resources.dhall ($INPUT)).List"
## Run the ansible roles locally
Given a working `~/.kube/config` context, you can execute the Ansible roles directly using:
ansible-playbook -v playbooks/files/local.yaml
Then cleanup the resources using:
ansible-playbook -v playbooks/files/local.yaml -e k8s_state=absent