API: Add new AdmissionControl service (experimental for now) #983

ryantxu · 2024-05-10T20:38:16Z

This adds an initial attempt at implementing validating/mutating hooks for plugin instance settings. This approach lets us use the existing settings structure while we evolve the k8s resource representation.

This service originally had a more generic storage/admission hook interface, but I think that should be tackled independently.

In grafana/grafana#87718 this is used to validate datasource settings before save

ryantxu · 2024-05-17T11:58:35Z

proto/backend.proto

@@ -217,7 +217,7 @@ message CheckHealthResponse {
 }

 //-----------------------------------------------------------------
-// Stream -- EXPERIMENTAL and is subject to change until 8.0


seems like we can remove this comment 🤣

Are you sure 😄

proto/backend.proto

marefr

Some initial comments

internal/automanagement/manager.go

proto/backend.proto

marefr

Sorry it took me some time to review this and grafana/grafana#87718. This is acceptable I think. However, it's still a bit hard for me to understand the full picture when grafana changes only implements MutateAdmisson. When/who calls ValidateAdmission?

Either I would suggest a PR for the grafana-app-sdk making use of these changes or either maybe begin with MutateAdmission and iterate from there?

The ConvertObject feels especially blurry adding/exposing when there's no direct use case currently that I can see, but I do understand it's needed eventually but maybe easier to handle as a separate change. To limit scope/review, could be useful/easier with smaller PR's/less changes. Thoughts?

Some nits/questions and some more tests would be nice in general.

backend/admission.go

backend/admission_test.go

backend/common.go

backend/app/manage.go

backend/datasource/manage.go

andresmgot

More or less same comment than @marefr. The usage / definition of the hooks is a bit confusing for me still.

backend/admission.go

andresmgot · 2024-05-22T09:28:20Z

backend/admission.go

+	ValidateAdmission(context.Context, *AdmissionRequest) (*AdmissionResponse, error)
+	MutateAdmission(context.Context, *AdmissionRequest) (*AdmissionResponse, error)
+	ConvertObject(context.Context, *ConversionRequest) (*AdmissionResponse, error)


Two things are confusing here:

ValidateAdmission and MutateAdmission have the same signature, which is confusing. For example, the validation hook is allowing to mutate the object, something I would not expect from a validation step. Should those requests / responses be different?

MutateAdmission and ConvertObject can also be confused since both allows you to modify the object in the request (and both have the same response struct) so it's not clear if a client should use one or the other.

These APIs really follow the k8s conventions -- and can eventually be wired up instead of setting up we webservice for each one 😃

When configuring the resource callbacks you choose if you want a simple "validate" -- eg, yes no, or "mutate" that will modify the body. "convert" is called when you need to return the value in a flavor different than what is saved

andresmgot · 2024-05-22T09:30:57Z

backend/admission.go

+// AdmissionRequest contains information from a kubernetes Admission request and decoded object(s).
+// See: https://github.com/kubernetes/kubernetes/blob/v1.30.0/pkg/apis/admission/types.go#L41
+// And: https://github.com/grafana/grafana-app-sdk/blob/main/resource/admission.go#L14


I think it's a bit weird that we are referencing Kubernetes code here in this package. It's okay if we apply the same concepts in this "legacy" package but comments should be self-explanatory, without pointing to code that does not apply to the traditional plugin workflow.

backend/admission.go

andresmgot · 2024-05-22T09:32:25Z

backend/admission.go

+	TargetVersion string `json:"target_version,omitempty"`
+}
+
+// See https://github.com/kubernetes/kubernetes/blob/v1.30.0/pkg/apis/admission/types.go#L118


this link only says "AdmissionResponse describes an admission response" which is not that helpful

andresmgot · 2024-05-22T09:33:57Z

backend/convert_from_protobuf_test.go

+	// 		"proto", "InstanceSettingsRequest", protoWalker.ZeroValueFieldCount, protoWalker.FieldCount)
+	// }
+
+	// TODO??


I guess this still need some work

ya --- reluctant to do so much handcrafted mess while still finding the right API structure 😛

then you can delete it for now?

I'll add the tests before merge -- they just require hand checking each property...

Now that I think we are close to the final structure -- i'll add them

ryantxu · 2024-05-23T10:10:22Z

I do understand it's needed eventually but maybe easier to handle as a separate change. To limit scope/review, could be useful/easier with smaller PR's/less changes. Thoughts?

@marefr I am sympathetic to that view, but given how much boilerplate code this is, the challenge is getting the plumbing right, and we know we can iterate on the message bodies -- this is all a new "service" so not introducing any breaking changes. The challenge of adding this much boilerplate in more PRs is a bit daunting 😬 By adding the core service here (that mimics well known apis!) the later PRs can focus on the usage something more than proto plumbing

Co-authored-by: Andres Martinez Gotor <andres.martinez@grafana.com>

ryantxu · 2024-05-23T12:03:47Z

@marefr @andresmgot -- I updated the message so each function returns its own type. Hopefully more clear now.

Regarding if we should split this into more PRs -- given how much is plumbing, it seems better to just get it all wired up and then iterate more with real usage. There is a 100% chance that the messages will need to evolve to fit all the usage we want, but the three functions are pretty well established patterns.

andresmgot · 2024-05-23T13:31:54Z

backend/admission.go

I had a comment here but I don't know if I ended up not sending it: Should this be defined in the experimental package? Since it's experimental and it can/will include breaking changes.

I don't believe there is any way to do that -- since it all has to hook into the grpc bits.

For the "stream" handler -- we had a similar process. It evolved a lot for ~6months before it becoming stable (and finally removing the warning in this PR -- doooh)

I suppose this particular file could be 🤔 but that is not too helpful given that the grpc ones can not

@marefr suggested it could be implemented like the other funky grpc plugins, but I fear that would make working with datasources annoyingly difficult. The approach proposed here lets us iterate on a good solution using our existing infrastructure, and only affects people who implement the new AdmissionControl service

yes, I am not talking about the grpc stuff but only these files / structs. From the plugin / grafana perspective, people would need to import this as experimental.AdmissionHandler which reflects better its status vs backend.AdmissionHandler

hymmm -- tried it, but it gets pretty silly with circular references -- the adapters are private and need to be in the backend package; everything needs access to PluginContext. There are fixes, but all are ugly. Would require something like moving (or duplicating?) PluginContext out of backend and making the adapters/serve.go public 🤷🏻

What about naming it ExperimentalAdmissionHandler? If that lets us move forward then seems ok to me.

I'll add more comments screaming it is experimental but open to suggestions

okay, then it's fine. Thanks for checking.

marefr

LGTM great work this is in a good enough shape to iterate from 💥

marefr · 2024-05-24T08:55:22Z

proto/backend.proto

+}
+
+// Check if an object can be admitted
+message ValidationResponse {


This still needs some additional fields I suppose to be able to report back what/why validation failed, but guess it can be made in a follow up as well/when needed?

marefr

Some additional nits/suggestions, but no blockers really

marefr · 2024-05-24T09:39:43Z

backend/admission.go

+// This is modeled after the kubernetes model for admission controllers
+// Since grafana 11.1, this feature is under active development and will continue to evolve in 2024
+// This may also be replaced with a more native kubernetes solution that does not work with existing tooling
+type AdmissionHandler interface {


Nit. One thing that would be nice/useful is if a plugin doesn't have to implement all of these and return not implemented/custom errors - better if SDK can provide good defaults if not implemented. For example always return allowed = 1 for validation if not implemented. Then there's no risk of calling validate when creating/updating a datasource and not having to check for unimplemented errors.

type ValidateAdmissionHandler interface { // ValidateAdmission is a simple yes|no check if an object can be saved ValidateAdmission(context.Context, *AdmissionRequest) (*ValidationResponse, error) } // ValidateAdmissionFunc implements ValidateAdmissionHandler. type ValidateAdmissionFunc func(context.Context, *AdmissionRequest) (*ValidationResponse, error) func (f ValidateAdmissionFunc) ValidateAdmission(ctx context.Context, req *AdmissionRequest) (*ValidationResponse, error) { return f(ctx, req) } type MutateAdmissionHandler interface { // MutateAdmission converts the input into an object that can be saved, or rejects the request MutateAdmission(context.Context, *AdmissionRequest) (*MutationResponse, error) } // MutateAdmissionFunc implements MutateAdmissionHandler. type MutateAdmissionFunc func(context.Context, *AdmissionRequest) (*MutationResponse, error) func (f MutateAdmissionFunc) MutateAdmission(ctx context.Context, req *AdmissionRequest) (*MutationResponse, error) { return f(ctx, req) } type ConvertObjectHandler interface { // ConvertObject is called to covert objects between different versions ConvertObject(context.Context, *ConversionRequest) (*ConversionResponse, error) } // ConvertObjectFunc implements ConvertObjectHandler. type ConvertObjectFunc func(context.Context, *ConversionRequest) (*ConversionResponse, error) func (f ConvertObjectFunc) ConvertObject(ctx context.Context, req *ConversionRequest) (*ConversionResponse, error) { return f(ctx, req) } type AdmissionHandler interface { ValidateAdmissionHandler MutateAdmissionHandler ConvertObjectHandler } // to be used in ManageOpts type AdmissionHandlers struct { ValidateAdmission ValidateAdmissionHandler MutateAdmission MutateAdmissionHandler ConvertObject ConvertObjectHandler }

interesting -- lets find an approach in a follow up PR. Right now the clients will implement everything so you do not know if an implementation exists or not. The Conversion service will only be needed if multiple versions exist -- so that is a good canidate

Sounds good 👍

In k8s land you subscribe to webhooks which clearly indicates which one of validate/mutate your interest in so something similar from plugin dev perspective was what I had in mind

backend/admission.go

Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>

andresmgot

No more comments from my side, let's see how this goes 👍

add admission service

366c6cd

ryantxu requested review from joeblubaugh, toddtreece and IfSentient May 10, 2024 20:38

ryantxu added 7 commits May 10, 2024 23:40

tabs

5b1a3ad

use k8s names

479ee40

more adapters

0a0e017

more adapters

8debcd4

more adapters

4f7ef3c

better tests

53b94e1

add plugin context

20b1338

ryantxu mentioned this pull request May 13, 2024

Plugins: Support Admission validation hooks grafana/grafana#87718

Merged

ryantxu added 3 commits May 17, 2024 10:06

Merge remote-tracking branch 'origin/main' into validate-settings

80f737d

add instance settings callback

e42def7

add instance settings callback

bb04333

ryantxu changed the title ~~API: Add experimental Admission API~~ API: Add new InstanceSettings validation api (experimental for now) May 17, 2024

ryantxu commented May 17, 2024

View reviewed changes

ryantxu added 2 commits May 17, 2024 18:06

add function for fake client

c0a3f78

dooh

f850b5f

ryantxu marked this pull request as ready for review May 20, 2024 05:56

ryantxu requested a review from a team as a code owner May 20, 2024 05:56

ryantxu requested review from wbrowne, marefr, xnyo and andresmgot and removed request for a team May 20, 2024 05:56

joeblubaugh reviewed May 20, 2024

View reviewed changes

proto/backend.proto Show resolved Hide resolved

proto/backend.proto Outdated Show resolved Hide resolved

marefr reviewed May 20, 2024

View reviewed changes

internal/automanagement/manager.go Outdated Show resolved Hide resolved

proto/backend.proto Outdated Show resolved Hide resolved

ryantxu added 2 commits May 20, 2024 14:48

Merge remote-tracking branch 'origin/main' into validate-settings

35a409b

create and update functions

fc6110a

ryantxu added 3 commits May 21, 2024 11:34

storage >> admission

9686768

Use GVK not GVKR

0a5fbac

proto helpers

218525d

ryantxu changed the title ~~API: Add new StorageHandler service (experimental for now)~~ API: Add new AdmissionControl service (experimental for now) May 21, 2024

marefr reviewed May 21, 2024

View reviewed changes

ryantxu added 3 commits May 21, 2024 22:48

cleanup

68e4b33

Merge remote-tracking branch 'origin/main' into validate-settings

416574f

lint

a437721

andresmgot reviewed May 22, 2024

View reviewed changes

ryantxu and others added 4 commits May 23, 2024 13:11

Update backend/admission.go

be57ff5

Co-authored-by: Andres Martinez Gotor <andres.martinez@grafana.com>

use different response structs

fcce0f6

more cleanup

3662d46

added better conversion tests

9f22d16

ryantxu requested review from marefr, radiohead and andresmgot May 23, 2024 11:57

ryantxu added 2 commits May 23, 2024 15:05

test lint

a5f8757

Merge remote-tracking branch 'origin/main' into validate-settings

62dae98

andresmgot reviewed May 23, 2024

View reviewed changes

better comments

fd2f15b

marefr approved these changes May 24, 2024

View reviewed changes

add response status to validate method

9b8dfd5

marefr reviewed May 24, 2024

View reviewed changes

Update backend/admission.go

48f12a0

Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>

andresmgot approved these changes May 24, 2024

View reviewed changes

ryantxu merged commit 94941f4 into main May 24, 2024
4 checks passed

ryantxu deleted the validate-settings branch May 24, 2024 09:58

andresmgot mentioned this pull request May 29, 2024

Add Admission hooks to auto management #996

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API: Add new AdmissionControl service (experimental for now) #983

API: Add new AdmissionControl service (experimental for now) #983

ryantxu commented May 10, 2024 •

edited

Loading

ryantxu May 17, 2024

marefr May 21, 2024

marefr left a comment

marefr left a comment •

edited

Loading

andresmgot left a comment

andresmgot May 22, 2024 •

edited

Loading

ryantxu May 23, 2024

andresmgot May 22, 2024

andresmgot May 22, 2024

andresmgot May 22, 2024

ryantxu May 23, 2024

andresmgot May 23, 2024

ryantxu May 23, 2024

ryantxu commented May 23, 2024

ryantxu commented May 23, 2024

andresmgot May 23, 2024

ryantxu May 23, 2024 •

edited

Loading

ryantxu May 23, 2024

ryantxu May 23, 2024

andresmgot May 23, 2024

ryantxu May 23, 2024

andresmgot May 24, 2024 •

edited

Loading

marefr left a comment

marefr May 24, 2024

marefr left a comment

marefr May 24, 2024

ryantxu May 24, 2024

marefr May 24, 2024

marefr May 24, 2024

andresmgot left a comment

API: Add new AdmissionControl service (experimental for now) #983

API: Add new AdmissionControl service (experimental for now) #983

Conversation

ryantxu commented May 10, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marefr left a comment

Choose a reason for hiding this comment

marefr left a comment • edited Loading

Choose a reason for hiding this comment

andresmgot left a comment

Choose a reason for hiding this comment

andresmgot May 22, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ryantxu commented May 23, 2024

ryantxu commented May 23, 2024

Choose a reason for hiding this comment

ryantxu May 23, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andresmgot May 24, 2024 • edited Loading

Choose a reason for hiding this comment

marefr left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marefr left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andresmgot left a comment

Choose a reason for hiding this comment

ryantxu commented May 10, 2024 •

edited

Loading

marefr left a comment •

edited

Loading

andresmgot May 22, 2024 •

edited

Loading

ryantxu May 23, 2024 •

edited

Loading

andresmgot May 24, 2024 •

edited

Loading