Create an implementor guide

[nebhale]

The spec is focused (properly) on what implementations must and must not do. It's hard for an implementor trying to understand how they can implement the specification. We should create an implementor guide that gives a non-normative overview of the concepts and recommendations for implementing the spec.

Topics to cover include:

mounting secrets as readonly

[baijum]

I would like to see this topic explained:
What is the purpose of "type" and "provider" fields in the binding secret?

[baijum]

Add the discussion from #125 into the guide

[baijum]

Based on the discussion in the Slack:

---

Question: If there is a change in the ProvisionedService secret data value, how to make it reflect in the application container?

It can be achieved by triggering the application reconciliation through a change in the PodSpec-able resource.
To force trigger the application reconciliation, the implementation can change the volume name.
For example, the volume name could be constructed by combining ServiceBinding resource's .metadata.name and Secret resource's resourceVersion value. e.g., account-service-5731

[baijum]

https://kubernetes.slack.com/archives/C012F2GPMTQ/p1615207548014400

---

Baiju:
The spec is silent about what causes the service binding reconciler to be triggered. I can think of few cases when the service binding reconciler should be triggered. 1) When the secret pointed through provisioned service is changed or a direct secret 2) A new application with a label matching the label selector comes up 3) An application is recreated with the given name. I wonder whether the spec should say something about this?

Scott:
I've viewed this as an implementation detail for the spec itself. The spec is primarily concerned with interoperability by defining the contracts at the edges. These suggestions are useful as part of an implementors guide.

[baijum]

Document how to project ServiceBinding resource's .spec.type and .spec.provider into the container.
See this comment: #154 (comment)

[baijum]

I think we can move this issue to the website repo.