webhook

Documentation

Overview

Package webhook provides methods to build and bootstrap a webhook server.

Currently, it only supports admission webhooks. It will support CRD conversion webhooks in the near future.

Build webhooks

// mgr is the manager that runs the server.
webhook1, err := NewWebhookBuilder().
	Name("foo.k8s.io").
	Mutating().
	Path("/mutating-pods").
	Operations(admissionregistrationv1beta1.Create).
	ForType(&corev1.Pod{}).
	WithManager(mgr).
	Handlers(mutatingHandler1, mutatingHandler2).
	Build()
if err != nil {
	// handle error
}

webhook2, err := NewWebhookBuilder().
	Name("bar.k8s.io").
	Validating().
	Path("/validating-deployment").
	Operations(admissionregistrationv1beta1.Create, admissionregistrationv1beta1.Update).
	ForType(&appsv1.Deployment{}).
	WithManager(mgr).
	Handlers(validatingHandler1).
	Build()
if err != nil {
	// handle error
}

Create a webhook server.

as, err := NewServer("baz-admission-server", mgr, ServerOptions{
	CertDir: "/tmp/cert",
	BootstrapOptions: &BootstrapOptions{
		Secret: &apitypes.NamespacedName{
			Namespace: "default",
			Name:      "foo-admission-server-secret",
		},
		Service: &Service{
			Namespace: "default",
			Name:      "foo-admission-server-service",
			// Selectors should select the pods that runs this webhook server.
			Selectors: map[string]string{
				"app": "foo-admission-server",
			},
		},
	},
})
if err != nil {
	// handle error
}

Register the webhooks in the server.

err = as.Register(webhook1, webhook2)
if err != nil {
	// handle error
}

Start the server by starting the manager

err := mrg.Start(signals.SetupSignalHandler())
if err != nil {
	// handle error
}

Index

• type BootstrapOptions
• type Server
  • func NewServer(name string, mgr manager.Manager, options ServerOptions) (*Server, error)
  • func (s *Server) Handle(pattern string, handler http.Handler)
  • func (s *Server) InjectClient(c client.Client) error
  • func (s *Server) InjectDecoder(d atypes.Decoder) error
  • func (s *Server) InstallWebhookManifests() error
  • func (s *Server) RefreshCert() (bool, error)
  • func (s *Server) Register(webhooks ...Webhook) error
  • func (s *Server) Start(stop <-chan struct{}) error
• type ServerOptions
• type Service
• type Webhook

Types

type BootstrapOptions

type BootstrapOptions struct {
	// MutatingWebhookConfigName is the name that used for creating the MutatingWebhookConfiguration object.
	MutatingWebhookConfigName string
	// ValidatingWebhookConfigName is the name that used for creating the ValidatingWebhookConfiguration object.
	ValidatingWebhookConfigName string

	// Secret is the location for storing the certificate for the admission server.
	// The server should have permission to create a secret in the namespace.
	// This is optional. If unspecified, it will write to the filesystem.
	// It the secret already exists and is different from the desired, it will be replaced.
	Secret *apitypes.NamespacedName

	// Deprecated: Writer will not be used anywhere.
	Writer io.Writer

	// Service is k8s service fronting the webhook server pod(s).
	// This field is optional. But one and only one of Service and Host need to be set.
	// This maps to field .webhooks.getClientConfig.service
	// https://github.com/kubernetes/api/blob/183f3326a9353bd6d41430fc80f96259331d029c/admissionregistration/v1beta1/types.go#L260
	Service *Service
	// Host is the host name of .webhooks.clientConfig.url
	// https://github.com/kubernetes/api/blob/183f3326a9353bd6d41430fc80f96259331d029c/admissionregistration/v1beta1/types.go#L250
	// This field is optional. But one and only one of Service and Host need to be set.
	// If neither Service nor Host is unspecified, Host will be defaulted to "localhost".
	Host *string
	// contains filtered or unexported fields
}

BootstrapOptions are options for bootstrapping an admission webhook server.

type Server

type Server struct {
	// Name is the name of server
	Name string

	// ServerOptions contains options for configuring the admission server.
	ServerOptions
	// contains filtered or unexported fields
}

Server is an admission webhook server that can serve traffic and generates related k8s resources for deploying.

func NewServer

func NewServer(name string, mgr manager.Manager, options ServerOptions) (*Server, error)

NewServer creates a new admission webhook server.

func (*Server) Handle

func (s *Server) Handle(pattern string, handler http.Handler)

Handle registers a http.Handler for the given pattern.

func (*Server) InjectClient

func (s *Server) InjectClient(c client.Client) error

InjectClient injects the client into the server

func (*Server) InjectDecoder

func (s *Server) InjectDecoder(d atypes.Decoder) error

InjectDecoder injects the client into the server

func (*Server) InstallWebhookManifests

func (s *Server) InstallWebhookManifests() error

InstallWebhookManifests creates the admissionWebhookConfiguration objects and service if any. It also provisions the certificate for the admission server.

func (*Server) RefreshCert

func (s *Server) RefreshCert() (bool, error)

RefreshCert refreshes the certificate using Server's Provisioner if the certificate is expiring.

func (*Server) Register

func (s *Server) Register(webhooks ...Webhook) error

Register validates and registers webhook(s) in the server

func (*Server) Start

func (s *Server) Start(stop <-chan struct{}) error

Start runs the server. It will install the webhook related resources depend on the server configuration.

type ServerOptions

type ServerOptions struct {
	// Port is the port number that the server will serve.
	// It will be defaulted to 443 if unspecified.
	Port int32

	// CertDir is the directory that contains the server key and certificate.
	// If using FSCertWriter in Provisioner, the server itself will provision the certificate and
	// store it in this directory.
	// If using SecretCertWriter in Provisioner, the server will provision the certificate in a secret,
	// the user is responsible to mount the secret to the this location for the server to consume.
	CertDir string

	// Client is a client defined in controller-runtime instead of a client-go client.
	// It knows how to talk to a kubernetes cluster.
	// Client will be injected by the manager if not set.
	Client client.Client

	// DisableWebhookConfigInstaller controls if the server will automatically create webhook related objects
	// during bootstrapping. e.g. webhookConfiguration, service and secret.
	// If false, the server will install the webhook config objects. It is defaulted to false.
	DisableWebhookConfigInstaller *bool

	// BootstrapOptions contains the options for bootstrapping the admission server.
	*BootstrapOptions
}

ServerOptions are options for configuring an admission webhook server.

type Service

type Service struct {
	// Name of the service
	Name string
	// Namespace of the service
	Namespace string
	// Selectors is the selector of the service.
	// This must select the pods that runs this webhook server.
	Selectors map[string]string
}

Service contains information for creating a service

type Webhook

type Webhook interface {
	// GetName returns the name of the webhook.
	GetName() string
	// GetPath returns the path that the webhook registered.
	GetPath() string
	// GetType returns the Type of the webhook.
	// e.g. mutating or validating
	GetType() types.WebhookType
	// Handler returns a http.Handler for the webhook.
	Handler() http.Handler
	// Validate validates if the webhook itself is valid.
	// If invalid, a non-nil error will be returned.
	Validate() error
}

Webhook defines the basics that a webhook should support.