controller-runtime: Index | Files | Directories

package webhook

import ""

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().
	Handlers(mutatingHandler1, mutatingHandler2).
if err != nil {
	// handle error

webhook2, err := NewWebhookBuilder().
	Operations(admissionregistrationv1beta1.Create, admissionregistrationv1beta1.Update).
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


Package Files

bootstrap.go doc.go server.go util.go

type BootstrapOptions Uses

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
    Service *Service
    // Host is the host name of .webhooks.clientConfig.url
    // 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 Uses

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

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

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

func NewServer Uses

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

NewServer creates a new admission webhook server.

func (*Server) Handle Uses

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

Handle registers a http.Handler for the given pattern.

func (*Server) InjectClient Uses

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

InjectClient injects the client into the server

func (*Server) InjectDecoder Uses

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

InjectDecoder injects the client into the server

func (*Server) InstallWebhookManifests Uses

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 Uses

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

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

func (*Server) Register Uses

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

Register validates and registers webhook(s) in the server

func (*Server) Start Uses

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 Uses

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.

ServerOptions are options for configuring an admission webhook server.

type Service Uses

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 Uses

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.


admissionPackage admission provides implementation for admission webhook and methods to implement admission webhook handlers.
admission/builderPackage builder provides methods to build admission webhooks.

Package webhook imports 29 packages (graph) and is imported by 2 packages. Updated 2018-12-15. Refresh now. Tools for package owners.