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

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    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.

                              Directories

                              Path Synopsis
                              Package admission provides implementation for admission webhook and methods to implement admission webhook handlers.
                              Package admission provides implementation for admission webhook and methods to implement admission webhook handlers.
                              builder
                              Package builder provides methods to build admission webhooks.
                              Package builder provides methods to build admission webhooks.
                              internal
                              cert
                              Package cert provides functions to manage certificates for webhookClientConfiguration.
                              Package cert provides functions to manage certificates for webhookClientConfiguration.
                              cert/generator
                              Package generator provides an interface and implementation to provision certificates.
                              Package generator provides an interface and implementation to provision certificates.
                              cert/writer
                              Package writer provides method to provision and persist the certificates.
                              Package writer provides method to provision and persist the certificates.