Merge pull request #1501 from kevindelgado/doc-webhook-tls

📖 Better document TLS requirements for webhook servers

Author: k8s-ci-robot

pkg/webhook/admission/webhook.go

@@ -230,6 +230,10 @@ type StandaloneOptions struct {
 // and instrumenting the webhook with metrics.
 //
 // Use this to attach your webhook to an arbitrary HTTP server or mux.
+//
+// Note that you are responsible for terminating TLS if you use StandaloneWebhook
+// in your own server/mux. In order to be accessed by a kubernetes cluster,
+// all webhook servers require TLS.
 func StandaloneWebhook(hook *Webhook, opts StandaloneOptions) (http.Handler, error) {
 	if opts.Scheme == nil {
 		opts.Scheme = scheme.Scheme

pkg/webhook/example_test.go

@@ -83,6 +83,10 @@ func Example() {
 
 // This example creates a webhook server that can be
 // ran without a controller manager.
+//
+// Note that this assumes and requires a valid TLS
+// cert and key at the default locations
+// tls.crt and tls.key
 func ExampleServer_StartStandalone() {
 	// Create a webhook server
 	hookServer := &Server{

pkg/webhook/server.go

@@ -41,6 +41,12 @@ var DefaultPort = 9443
 
 // Server is an admission webhook server that can serve traffic and
 // generates related k8s resources for deploying.
+//
+// TLS is required for a webhook to be accessed by kubernetes, so
+// you must provide a CertName and KeyName or have valid cert/key
+// at the default locations (tls.crt and tls.key). If you do not
+// want to configure TLS (i.e for testing purposes) run an
+// admission.StandaloneWebhook in your own server.
 type Server struct {
 	// Host is the address that the server will listen on.
 	// Defaults to "" - all addresses.