k8sadmission

README

Kubernetes Admission Services

Kubernetes provides dynamic admission control, pieces of code that intercept requests to the Kubernetes API server, before the resource is persisted, but after the request has been authenticated and authorized.

There are two types of admission controllers which can be configured at runtime, and run as webhooks:

• MutatingAdmissionWebhook (invoked first, and can modify objects sent to the API server to enforce custom defaults)
• ValidatingAdmissionWebhook (invoked second, and can reject requests to enforce custom policies)

MutatingAdmissionWebhook

Gloo does not currently configure a MutatingAdmissionWebhook

ValidatingAdmissionWebhook

Gloo leverages the ValidatingAdmissionWebhook to validate proposed changes to custom resources (i.e. a VirtualService) before they are persisted in etcd. Where the structural schemas on CRDs provide syntactic validation, the validating webhook provides semantic validation.

Execution

Which resources are subject to the ValidatingAdmissionWebhook?

The ValidatingWebhookConfiguration is part of the Kubernetes API, and configured through a Helm template. Based on the webhook rules, only the API groups/resources that match the rules will be subject to validation

Where is the Webhook entrypoint defined?

The ValidatingWebhookConfiguration defines the name and path to the service which handles validation requests. In Gloo, this is the Gloo Service, at the /validation endpoint.

The ValidatingAdmissionWebhook constructor returns the http.Server which can handle these requests.

How is communication with the Webhook secured?

To verify the TLS connection with the webhook, a PEM-encoded CA bundle for validating the webhook's server certificate is provided in the webhook configuration.

The CaBundle can be defined in the following ways:

1. Manually
2. Using the Gloo Edge Certgen Job
3. Using the Cert-Manager CA Injector

When the ValidatingAdmissionWebhook is invoked, how does Gloo perform validation?

Gloo performs a robust set of validation during translation of resources, so that it does not push invalid configuration to the data plane. The warnings and errors that are encountered during translation, are aggregated on ResourceReports.

Instead of re-defining this same set of validation code in our webhook, we re-use the existing code by performing the following steps:

1. An HTTP request is received by the server
2. The request is unmarshalled, and then validated by the webhook
3. The webhook uses a configurable Validator to perform this logic. The validator implementation is defined here
4. The validator first runs translation of Gateway resources and rejects the proposal if warnings/errors were encountered during translation
5. The validator then runs gloo translation with the generated proxy, and rejects the proposal if warnings/errors were encountered during translation
6. If both Gateway translation and Gloo translation do not produce errors/warnings, the resource is accepted

Configuration

Where is the webhook configuration defined?

Webhook configuration is defined on the Gloo Settings resource

Debugging

What if requests aren't received by the webhook?

1. Turn on debug logs and confirm that requests are not being processed by the validation webhook.
2. Change the failure policy to Fail, so that if the webhook cannot be called, the admission request will be rejected.
3. Retry a change that would invoke the webhook, and examine the logs for pointers.

Commonly this occurs when the certificate has expired and needs to be regenerated.

Documentation

Index

• Constants
• Variables
• func NewCertificateProvider(certPath, keyPath string, logger *log.Logger, ctx context.Context, ...) (*certificateProvider, error)
• func NewGatewayValidatingWebhook(cfg WebhookConfig) (*http.Server, error)
• func NewGatewayValidationHandler(ctx context.Context, validator validation.Validator, watchNamespaces []string, ...) *gatewayValidationWebhook
• type AdmissionRequestWithProxies
• type AdmissionResponseWithProxies
• type AdmissionReviewWithProxies
• type WebhookConfig
  • func NewWebhookConfig(ctx context.Context, validator validation.Validator, watchNamespaces []string, ...) WebhookConfig

Constants

const (
	ValidationPath      = "/validation"
	SkipValidationKey   = "gateway.solo.io/skip_validation"
	SkipValidationValue = "true"
)

const (
	ApplicationJson = "application/json"
	ApplicationYaml = "application/x-yaml"
)

Variables

var (
	UnmarshalErr        = errors.New(unmarshalErrMsg)
	WrappedUnmarshalErr = func(err error) error {
		return errors.Wrapf(err, unmarshalErrMsg)
	}
	ListGVK = schema.GroupVersionKind{
		Version: "v1",
		Group:   "",
		Kind:    "List",
	}
)

Functions

func NewCertificateProvider

func NewCertificateProvider(certPath, keyPath string, logger *log.Logger, ctx context.Context, interval time.Duration) (*certificateProvider, error)

func NewGatewayValidatingWebhook

func NewGatewayValidatingWebhook(cfg WebhookConfig) (*http.Server, error)

func NewGatewayValidationHandler

func NewGatewayValidationHandler(
	ctx context.Context,
	validator validation.Validator,
	watchNamespaces []string,
	alwaysAccept bool,
	readGatewaysFromAllNamespaces bool,
	webhookNamespace string,
	kubeGatewayEnabled bool,
) *gatewayValidationWebhook

Types

type AdmissionRequestWithProxies

type AdmissionRequestWithProxies struct {
	v1beta1.AdmissionReview
	ReturnProxies bool `json:"returnProxies,omitempty"`
}

type AdmissionResponseWithProxies

type AdmissionResponseWithProxies struct {
	*v1beta1.AdmissionResponse
	Proxies []*gloov1.Proxy `json:"proxies,omitempty"`
}

Validation webhook works properly even if extra fields are provided in the response

type AdmissionReviewWithProxies

type AdmissionReviewWithProxies struct {
	AdmissionRequestWithProxies
	AdmissionResponseWithProxies
}

type WebhookConfig

type WebhookConfig struct {
	// contains filtered or unexported fields
}

func NewWebhookConfig

func NewWebhookConfig(
	ctx context.Context,
	validator validation.Validator,
	watchNamespaces []string,
	port int,
	serverCertPath, serverKeyPath string,
	alwaysAccept, readGatewaysFromAllNamespaces bool,
	webhookNamespace string,
	kubeGatewayEnabled bool,
) WebhookConfig