jboyd01/gist:3b69bf8d09e074ed2ddc8b83faffebc4

## gistfile1.txt
Purpose
Allow brokers to register callbacks (webhooks) that can be used for validation prior to the platform attempting to Create, Update or Delete (CUD) a Service Instance or Binding.

There will likely be a lot of discussion on the actual implementation details, initially this proposal will just focus on surfacing the issue and proposing the use of pre-action validation so Brokers have an opportunity to indicate to the platform that an action will or will not be accepted for processing.  Once the SIG has discussed and given general agreement, we'll drill into a detailed design.

This feature allows a broker to register webhooks for precheck validation for Instances and Bindings.  That is, if indicated by the broker, the Platform will invoke a validating webhook just prior to invoking the actual call to create, update or delete an Instance or Binding.  The webhook will be invoked with the same parameters and payload as the actual create/update/delete operation, but this operation is a dry-run for Broker validation only.  The broker may accept the request and respond with a status 200 OK or may return an error matching the same set of possible returns codes as is documented for the actual operation.  At this time, the validation must be synchronous.

Platforms are not required to execute precheck validations - if the platform does not, it is expected the CUD operation will fail in the same manner as the validation would have failed.


Rationale:
Some platforms (Kubernetes being one) create platform metadata that represents the Service Instance and Service Binding.  In many cases these objects are created or updated prior to invoking Broker endpoints create, update or delete the Broker resource.  If the Broker encounters an error or rejects the request the platform  usually leaves the platform object in an error or modified state that no longer reflects the Broker's resource and requires the user or administrator to clean it up or roll it back.  Sometimes the platform and user can not recover and is unable to roll back the object to its prior state.  The addition of the precheck allows the platform to fail the user's request early before any platform metadata objects are modified that would have have otherwise required cleanup.

Scenario 1 (Instance Update):
User A's update operation will fail because of some ACL or other business policy check.  Prior to validation webhooks, the platform's metadata object is updated with the end user's changes but the update operation is marked as failed.  If user B then attempts a different update on the object by editing the current object, he'll be working with user A's change as well.  If user B doesn't realize this and commits the change, the broker will see the full set of updates and will assume these updates are being requested by user B and if he has privileges, an unintended update may be executed.   The precheck adds the ability to verify A's access and other business checks prior to making any changes to the platform metadata object.  With prechecks in place, the platform metadata object would never be updated if user A's precheck update operation failed.

Scenario 2 (Instance Deletion):
Today without validating webhooks, when a user deletes an instance the platform metadata object is irreversibly marked as deleted - even if the Broker rejects the delete, the platform object was marked for deletion and this can not be undone.  Eventually the Platform resource must be deleted and re-created if necessary - this entails someone with the required privileges actually deleting the resource with Platform command, waiting for the Broker to also successfully delete its resources, and then recreating the Instance and any associated Bindings.  With a validating precheck, the platform checks early to see if the broker is going to reject the operation and if so, the platform can abort the operation and present an appropriate error message to the end user.

High Level Design:
1)  In the Broker Catalog response, the Broker indicates if it wants precheck validations invoked for Instances and Bindings.

2)  If the Broker wants precheck validation, it must accept validation invocations at /v2/service_instances/validate:instance_id  and /v2/service_instances/:instance_id/service_bindings/validate:binding_id.  The validation requests are formed exactly as original target operation except for the addition of the /validate in the URL and the platform must not specify accepts_incomplete=true.  Otherwise the request has identical request headers, parameters and body, and invocation method.  IE to validate deleting a Binding, the platform will execute a HTTP DELETE against /v2/service_instances/:instance_id/service_bindings/validate:binding_id
	Purpose
	Allow brokers to register callbacks (webhooks) that can be used for validation prior to the platform attempting to Create, Update or Delete (CUD) a Service Instance or Binding.

	There will likely be a lot of discussion on the actual implementation details, initially this proposal will just focus on surfacing the issue and proposing the use of pre-action validation so Brokers have an opportunity to indicate to the platform that an action will or will not be accepted for processing. Once the SIG has discussed and given general agreement, we'll drill into a detailed design.

	This feature allows a broker to register webhooks for precheck validation for Instances and Bindings. That is, if indicated by the broker, the Platform will invoke a validating webhook just prior to invoking the actual call to create, update or delete an Instance or Binding. The webhook will be invoked with the same parameters and payload as the actual create/update/delete operation, but this operation is a dry-run for Broker validation only. The broker may accept the request and respond with a status 200 OK or may return an error matching the same set of possible returns codes as is documented for the actual operation. At this time, the validation must be synchronous.

	Platforms are not required to execute precheck validations - if the platform does not, it is expected the CUD operation will fail in the same manner as the validation would have failed.


	Rationale:
	Some platforms (Kubernetes being one) create platform metadata that represents the Service Instance and Service Binding. In many cases these objects are created or updated prior to invoking Broker endpoints create, update or delete the Broker resource. If the Broker encounters an error or rejects the request the platform usually leaves the platform object in an error or modified state that no longer reflects the Broker's resource and requires the user or administrator to clean it up or roll it back. Sometimes the platform and user can not recover and is unable to roll back the object to its prior state. The addition of the precheck allows the platform to fail the user's request early before any platform metadata objects are modified that would have have otherwise required cleanup.

	Scenario 1 (Instance Update):
	User A's update operation will fail because of some ACL or other business policy check. Prior to validation webhooks, the platform's metadata object is updated with the end user's changes but the update operation is marked as failed. If user B then attempts a different update on the object by editing the current object, he'll be working with user A's change as well. If user B doesn't realize this and commits the change, the broker will see the full set of updates and will assume these updates are being requested by user B and if he has privileges, an unintended update may be executed. The precheck adds the ability to verify A's access and other business checks prior to making any changes to the platform metadata object. With prechecks in place, the platform metadata object would never be updated if user A's precheck update operation failed.

	Scenario 2 (Instance Deletion):
	Today without validating webhooks, when a user deletes an instance the platform metadata object is irreversibly marked as deleted - even if the Broker rejects the delete, the platform object was marked for deletion and this can not be undone. Eventually the Platform resource must be deleted and re-created if necessary - this entails someone with the required privileges actually deleting the resource with Platform command, waiting for the Broker to also successfully delete its resources, and then recreating the Instance and any associated Bindings. With a validating precheck, the platform checks early to see if the broker is going to reject the operation and if so, the platform can abort the operation and present an appropriate error message to the end user.

	High Level Design:
	1) In the Broker Catalog response, the Broker indicates if it wants precheck validations invoked for Instances and Bindings.

	2) If the Broker wants precheck validation, it must accept validation invocations at /v2/service_instances/validate:instance_id and /v2/service_instances/:instance_id/service_bindings/validate:binding_id. The validation requests are formed exactly as original target operation except for the addition of the /validate in the URL and the platform must not specify accepts_incomplete=true. Otherwise the request has identical request headers, parameters and body, and invocation method. IE to validate deleting a Binding, the platform will execute a HTTP DELETE against /v2/service_instances/:instance_id/service_bindings/validate:binding_id