controller-runtime: sigs.k8s.io/controller-runtime/pkg/webhook Index | Files | Directories

package webhook

import "sigs.k8s.io/controller-runtime/pkg/webhook"

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

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
    // 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 Uses

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 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.
    *BootstrapOptions
}

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.

Directories

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

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