document the webhook contract between the metacontroller and the controller about metacontroller

[enisoc]

I plan to write docs for this once the contract is formalized, but in the meantime here's some explanation of the current state.

Suppose you have a CompositeController defined like this:

apiVersion: metacontroller.k8s.io/v1alpha1
kind: CompositeController
metadata:
  name: catset-controller
spec:
  parentResource:
    apiVersion: ctl.enisoc.com/v1
    resource: catsets
  childResources:
    - apiVersion: v1
      resources: ["pods", "persistentvolumeclaims"]
  clientConfig:
    service:
      name: catset-controller
      namespace: metacontroller
  hooks:
    sync:
      path: /sync

CompositeController Sync Request

Whenever Metacontroller decides that the desired state needs to be recomputed, it will send a JSON object to your sync hook with the following fields:

• controller: The whole CompositeController object from above.

  i.e. what you'd get from kubectl get compositecontroller catset-controller -o json

• parent: The particular parent object for which it wants you to compute the desired state.

  i.e. what you'd get from kubectl get catset <parent-name> -o json

• children: A map (associative array) of child objects that already exist.

  Each field of the children object represents one of the types of childResources you specified in your CompositeController spec. The field name for each child type is <Kind>.<apiVersion>, so in this case there will be fields named Pod.v1 and PersistentVolumeClaim.v1.

  The value of each field is another associative array that maps the child object's name to the actual object as it was last observed. For example, if your CatSet already has some Pods, your hook might receive an entry in the children map like this:

  "Pod.v1": {
    "my-catset-0": { ... },
    "my-catset-1": { ... }
  }

  The contents of my-catset-0 will be just like what you'd get from kubectl get pod my-catset-0 -o json.

  You will only be sent children whose labels match the spec.selector field (interpreted the same as spec.selector in controllers like Deployment) of the parent object. Note that this is the new-style selector that supports set-based requirements.

  Note that Metacontroller also performs adoption and orphaning like built-in controllers. That means it might adopt (take control of) objects that happen to match your selector, if no other controller has claimed them. It will also orphan (release control of) objects that you currently control, if they no longer match your selector.

  Just like with built-in controllers, it's important that users of your custom controller specify a spec.selector in the parent object that is sufficiently precise to discriminate its child objects from those of other parents.

CompositeController Sync Response

Your hook should return a JSON object with the following fields:

• status: This is an arbitrary JSON object that will entirely replace the status field in the parent object.

  What you put in here is up to you, but usually it's best to follow conventions established by controllers like Deployment. You should compute status based only on the children that already existed when your hook was called; status represents a judgement on the last observed state, not the desired state.

• children: A list of JSON objects defining the desired children and their desired states.

  Note that this is a flat list of objects, not an associative array as in the children field of the request. Metacontroller groups the objects it sends you by type and name to save you from having to do it yourself, but it's actually redundant since each object contains this information.

  By default, you can think of each entry in the list as a JSON object to be sent to kubectl create -f - or kubectl replace -f - (depending on whether it already exists).

  If you optionally set spec.updateStrategy (note: this field will likely be renamed soon) to Apply in your CompositeController, then you should instead think of each entry in this list as being sent to kubectl apply -f -.

  In either case, any child you receive but do not return will be deleted (similar to kubectl apply --prune).

  Just like when working with kubectl, each object must contain its apiVersion and kind. You can only create/replace/apply objects of the types you specified in childResources in your CompositeController spec.