From 2eda33f20e2344c71e6c929287702e657d6e12f9 Mon Sep 17 00:00:00 2001 From: Ish Shah Date: Fri, 10 May 2019 11:08:24 -0700 Subject: [PATCH 1/4] Initial Proposal --- doc/proposals/webhook-proposal.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 doc/proposals/webhook-proposal.md diff --git a/doc/proposals/webhook-proposal.md b/doc/proposals/webhook-proposal.md new file mode 100644 index 00000000000..5060b8eb9cc --- /dev/null +++ b/doc/proposals/webhook-proposal.md @@ -0,0 +1,30 @@ +## Webhook Support + +Implementation Owner: theishshah +Status: Draft + +[Background](#Background) +[Goals](#Goals) +[Design overview](#Design_overview) +[User facing usage](#User_facing_usage) +[Observations and open questions](#Observations_and_open_questions) + +### Background + +The upcoming stable version of controller runtime has support for running a webhook server and having webhooks to mutate or validate pods. The mutation webhook can change various attributes of a pod, and the validation webhook can read pod attributes and allow/deny a pod to run based on this information. + +### Goals + +The goal of this proposal is to add the abilty for users to quickly add a webhook server and only implement the validation/mutation logic for their webhooks. + +### Design overview + +All of the necesary files and changes for the generated operator occur in the cmd/manager/ directory. The code to create and register the server is in the main.go file and can be completely generated with no additional input needed from the user. In addition the osdk will provide 2 files, 1 each for validation and mutation webhooks. These will have a template Handle function in which the user can define the desired behavior for their pod validation/mutation logic. + +### User facing usage (if needed) + +My suggested method for interacting with this feature is to have a command in the osdk which can be run after generating the base operator. The new command `generate webhook` will write the files cmd/manager/main.go, cmd/manager/mutationwebhook.go, and cmd/manager/validationwebhook.go + +### Observations and open questions + +< Any open questions that need solving or implementation details should go here. These can be removed at the end of the proposal if they are resolved. > From 6028d8354e727807aa2a48b1b3d47ba1b91f4ae8 Mon Sep 17 00:00:00 2001 From: Ish Shah Date: Fri, 10 May 2019 11:10:12 -0700 Subject: [PATCH 2/4] add example --- doc/proposals/webhook-proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/proposals/webhook-proposal.md b/doc/proposals/webhook-proposal.md index 5060b8eb9cc..a8406ce5f2b 100644 --- a/doc/proposals/webhook-proposal.md +++ b/doc/proposals/webhook-proposal.md @@ -27,4 +27,4 @@ My suggested method for interacting with this feature is to have a command in th ### Observations and open questions -< Any open questions that need solving or implementation details should go here. These can be removed at the end of the proposal if they are resolved. > +[Here](https://github.com/operator-framework/operator-sdk-samples/pull/63) is an example of the planned implementation on the alpha version of controller runtime. From 2e293ee2b17e9986125f15f9bf091ef823c13e2d Mon Sep 17 00:00:00 2001 From: Ish Shah Date: Sun, 23 Jun 2019 22:32:15 -0700 Subject: [PATCH 3/4] updated content and formatting --- doc/proposals/webhook-proposal.md | 115 ++++++++++++++++++++++++++++-- 1 file changed, 111 insertions(+), 4 deletions(-) diff --git a/doc/proposals/webhook-proposal.md b/doc/proposals/webhook-proposal.md index a8406ce5f2b..4591b44766d 100644 --- a/doc/proposals/webhook-proposal.md +++ b/doc/proposals/webhook-proposal.md @@ -1,12 +1,17 @@ ## Webhook Support Implementation Owner: theishshah + Status: Draft [Background](#Background) + [Goals](#Goals) + [Design overview](#Design_overview) + [User facing usage](#User_facing_usage) + [Observations and open questions](#Observations_and_open_questions) ### Background @@ -15,16 +20,118 @@ The upcoming stable version of controller runtime has support for running a webh ### Goals -The goal of this proposal is to add the abilty for users to quickly add a webhook server and only implement the validation/mutation logic for their webhooks. +The goal of this proposal is to add the abilty for users to quickly add a webhook server and only implement the validation/mutation logic for their webhooks. Ideally this will support per-API webhooks, however, the proposal is not there yet. ### Design overview -All of the necesary files and changes for the generated operator occur in the cmd/manager/ directory. The code to create and register the server is in the main.go file and can be completely generated with no additional input needed from the user. In addition the osdk will provide 2 files, 1 each for validation and mutation webhooks. These will have a template Handle function in which the user can define the desired behavior for their pod validation/mutation logic. +All of the necesary files and changes for the generated operator occur in the `cmd/manager/` directory. + +osdk-webhook.go will be responsible for containing the logic to start up a webhook server, including a `webhookServer` struct to contain the necesary information to start the server. + +The webhook initilization logic function will be a function which returns successfully _without_ starting the server if the user does not enable webhook support via the command line (planned command is `$ operator-sdk generate webhooks`, more detail is outlined in the next section). If a user chooses to generate webhooks, the osdk-webhook.go file will be overwritten with a new file to contain a server init function with full functionality. Additionally it will generate the server information struct populated with the deafult values. Controller runtime defaults for these values are `Port: 9876` and `CertDir: "/tmp/cert"`. + +```go +type webhookServer struct { + Port int + CertDir string +} +``` + +The initialization function will be called in the main.go file, regardless of whether or not a user opts in, however no actions are taken unless the user chooses to generate webhooks. + +```go +func WebhookInit() error { + log.Info("Starting webhook server") + hookServer := &webhook.Server{ + Port: hookServerCfg.Port, + CertDir: hookServerCfg.CertDir, + } + + if err := mgr.Add(hookServer); err != nil { + log.Error(err, "Unable to register webhook server") + return err + } + + log.Info("Registering webhooks to the webhook server") + + hookServer.Register("/mutate-pods", &webhook.Admission{Handler: &podAnnotator{}}) + hookServer.Register("/validate-pods", &webhook.Admission{Handler: &podValidator{}}) + + return nil +} +``` + + +In addition to the above file being used to start up the server, an additional files (`mutationswebhook.go` and `validationwebhooks.go`) will generated when the user chooses to include webhooks. These are the files which have the necesary boilerplate for a user to implement the `Handle` function in order to run custom logic on validation and admission of pods. + +```go +type podInteraction struct { + client client.Client + decoder *admission.Decoder +} + +func (i *podInteraction) Handle(ctx context.Context, req admission.Request) admission.Response { + pod := &corev1.Pod{} + + err := i.decoder.Decode(req, pod) + if err != nil { + return admission.Errored(http.StatusBadRequest, err) + } + + //Insert mutation/validation logic here + + //BRANCH + //Block A contains the boiler plate logic for patching a mutation + //Block B contains the boilder plate logic for + + //BLOCK A + marshaledPod, err := json.Marshal(pod) + if err != nil { + return admission.Errored(http.StatusInternalServerError, err) + } + + return admission.PatchResponseFromRaw(req.Object.Raw, marshaledPod) + + //BLOCK B + if FAILURE_CONDITION { + return admission.Denied(fmt.Sprintf("reason for failure")) + } + + return admission.Allowed("") + + //END BRANCH +} + +// podInteraction implements inject.Client. +// A client will be automatically injected. + +// InjectClient injects the client. +func (i *podInteraction) InjectClient(c client.Client) error { + i.client = c + return nil +} + +// podInteraction implements admission.DecoderInjector. +// A decoder will be automatically injected. + +// InjectDecoder injects the decoder. +func (i *podInteraction) InjectDecoder(d *admission.Decoder) error { + i.decoder = d + return nil +} + +``` + ### User facing usage (if needed) -My suggested method for interacting with this feature is to have a command in the osdk which can be run after generating the base operator. The new command `generate webhook` will write the files cmd/manager/main.go, cmd/manager/mutationwebhook.go, and cmd/manager/validationwebhook.go +My suggested method for interacting with this feature is to have a command in the osdk which can be run after generating the base operator. The new command `$ operator-sdk generate webhook` will write the files cmd/manager/osdk-webhook.go, cmd/manager/mutationwebhook.go, and cmd/manager/validationwebhook.go + +Flags + +* `--port` int - Port to start webhook server on +* `--cert-dir` string - Certificate directory ### Observations and open questions -[Here](https://github.com/operator-framework/operator-sdk-samples/pull/63) is an example of the planned implementation on the alpha version of controller runtime. +[Here](https://github.com/operator-framework/operator-sdk-samples/pull/63) is an example of the planned implementation on the alpha version of controller runtime (out of date, currently being re-implemented with new/updated design). From a17b077894fa2e49b13669023e7ef2b731fa0d03 Mon Sep 17 00:00:00 2001 From: Ish Shah Date: Mon, 8 Jul 2019 07:28:53 -0700 Subject: [PATCH 4/4] formatting and flags --- doc/proposals/webhook-proposal.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/doc/proposals/webhook-proposal.md b/doc/proposals/webhook-proposal.md index 4591b44766d..bf0bb3fdea3 100644 --- a/doc/proposals/webhook-proposal.md +++ b/doc/proposals/webhook-proposal.md @@ -16,7 +16,7 @@ Status: Draft ### Background -The upcoming stable version of controller runtime has support for running a webhook server and having webhooks to mutate or validate pods. The mutation webhook can change various attributes of a pod, and the validation webhook can read pod attributes and allow/deny a pod to run based on this information. +The upcoming stable version of controller runtime (`v0.2.0`) has support for running a webhook server and having webhooks to mutate or validate pods. The mutation webhook can change various attributes of a pod, and the validation webhook can read pod attributes and allow/deny a pod to run based on this information. ### Goals @@ -26,7 +26,7 @@ The goal of this proposal is to add the abilty for users to quickly add a webhoo All of the necesary files and changes for the generated operator occur in the `cmd/manager/` directory. -osdk-webhook.go will be responsible for containing the logic to start up a webhook server, including a `webhookServer` struct to contain the necesary information to start the server. +`osdk-webhook.go` will be responsible for containing the logic to start up a webhook server, including a `webhookServer` struct to contain the necesary information to start the server. The webhook initilization logic function will be a function which returns successfully _without_ starting the server if the user does not enable webhook support via the command line (planned command is `$ operator-sdk generate webhooks`, more detail is outlined in the next section). If a user chooses to generate webhooks, the osdk-webhook.go file will be overwritten with a new file to contain a server init function with full functionality. Additionally it will generate the server information struct populated with the deafult values. Controller runtime defaults for these values are `Port: 9876` and `CertDir: "/tmp/cert"`. @@ -37,7 +37,7 @@ type webhookServer struct { } ``` -The initialization function will be called in the main.go file, regardless of whether or not a user opts in, however no actions are taken unless the user chooses to generate webhooks. +The initialization function will be called in the main.go file, regardless of whether or not a user opts in, however no actions are taken unless the user chooses to generate webhooks. The main function is unmodified by calling for `generate webhook` as the function call to initialize the webhook will exist when the operator is initially created. Until a user chooses to generate webhooks the webhook initiating function will simply return error free without performaning any action. ```go func WebhookInit() error { @@ -62,7 +62,7 @@ func WebhookInit() error { ``` -In addition to the above file being used to start up the server, an additional files (`mutationswebhook.go` and `validationwebhooks.go`) will generated when the user chooses to include webhooks. These are the files which have the necesary boilerplate for a user to implement the `Handle` function in order to run custom logic on validation and admission of pods. +In addition to the above file being used to start up the server, additional files (`mutationswebhook.go` and `validationwebhooks.go`) will generated when a user chooses to include webhooks. These are the files which have the necessary boilerplate for a user to implement the `Handle` function in order to run custom logic on validation and admission of pods. ```go type podInteraction struct { @@ -125,13 +125,10 @@ func (i *podInteraction) InjectDecoder(d *admission.Decoder) error { ### User facing usage (if needed) -My suggested method for interacting with this feature is to have a command in the osdk which can be run after generating the base operator. The new command `$ operator-sdk generate webhook` will write the files cmd/manager/osdk-webhook.go, cmd/manager/mutationwebhook.go, and cmd/manager/validationwebhook.go +My suggested method for interacting with this feature is to have a command in the osdk which can be run after generating the base operator. The new command `$ operator-sdk generate webhook` will write the files `pkg/osdk-webhook/osdk-webhook.go`, `pkg/osdk-webhook/mutationwebhook.go`, and `pkg/osdk-webhook/validationwebhook.go` -Flags +These flags are only used as part of the generate webhook command: * `--port` int - Port to start webhook server on * `--cert-dir` string - Certificate directory -### Observations and open questions - -[Here](https://github.com/operator-framework/operator-sdk-samples/pull/63) is an example of the planned implementation on the alpha version of controller runtime (out of date, currently being re-implemented with new/updated design).