Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.8.x (latest)
  • 2.7.x
  • 2.6.x
  • 2.5.x
  • 2.4.x
  • 2.3.x
  • 2.2.x
  • 2.1.x
  • 2.0.x
  • 1.3.x
  • 1.2.x
  • 1.1.x
  • 1.0.x
    • FAQ
    • Changelog
    • Architecture
    • Custom Resources
    • Deployment Methods
    • Kong for Kubernetes with Kong Enterprise
    • High-Availability and Scaling
    • Resource Classes
    • Security
    • Ingress Resource API Versions
    • Kong Ingress on Minikube
    • Kong for Kubernetes
    • Kong for Kubernetes Enterprise
    • Kong for Kubernetes with Kong Enterprise
    • Kong Ingress on AKS
    • Kong Ingress on EKS
    • Kong Ingress on GKE
    • Admission Controller
    • Installing Gateway APIs
    • Getting Started with KIC
    • Upgrading from previous versions
    • Getting Started using Istio
      • Using the Kong(Cluster)Plugin Resource
      • Using the KongIngress Resource
      • Using KongConsumer and Credential Resources
      • Using the TCPIngress Resource
      • Using the UDPIngress Resource
    • Using the ACL and JWT Plugins
    • Using cert-manager with Kong
    • Configuring a Fallback Service
    • Using an External Service
    • Configuring HTTPS Redirects for Services
    • Using Redis for Rate Limiting
    • Integrate KIC with Prometheus/Grafana
    • Configuring Circuit-Breaker and Health-Checking
    • Setting up a Custom Plugin
    • Using Ingress with gRPC
    • Setting up Upstream mTLS
    • Exposing a TCP-based Service
    • Exposing a UDP-based Service
    • Using the mTLS Auth Plugin
    • Configuring Custom Entities
    • Using the OpenID Connect Plugin
    • Rewriting Hosts and Paths
    • Preserving Client IP Address
    • Using Gateway API
    • Using Kong with Knative
    • KIC Annotations
    • CLI Arguments
    • Custom Resource Definitions
    • Plugin Compatibility
    • Version Compatibility
    • Troubleshooting
    • Prometheus Metrics

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Set up with a script
  • Set up using the Helm chart
  • Create a certificate for the admission webhook
    • Using self-signed certificate
    • Using in-built Kubernetes CA
    • Create the secret
  • Update the deployment
  • Enable the validating admission
  • Verify if it works
    • Verify duplicate KongConsumers
    • Verify incorrect KongPlugins
    • Verify incorrect credential secrets
Kubernetes Ingress Controller
2.3.x
  • Home
  • Kubernetes Ingress Controller
  • Deployment
  • Validating the Admission Webhook
You are browsing documentation for an outdated version. See the latest documentation here.

Validating the Admission Webhook

The Kubernetes Ingress Controller ships with an admission webhook for KongPlugin and KongConsumer resources in the configuration.konghq.com API group.

The admission webhook needs a TLS certificate and key pair which you need to generate as part of the deployment.

Following guide walks through a setup of how to create the required key-pair and enable the admission webhook.

Please note that this requires Kubernetes Ingress Controller >= 0.6 to be already installed in the cluster.

Set up with a script

If you are using the stock YAML manifests to install and setup Kong for Kubernetes, then you can set up the admission webhook using a single command:

curl -sL https://raw.githubusercontent.com/Kong/kubernetes-ingress-controller/main/hack/deploy-admission-controller.sh | bash

The output is similar to the following:

Generating a 2048 bit RSA private key
.......+++
.......................................................................+++
writing new private key to '/var/folders/h2/chkzcfsn4sl3nn99tk5551tc0000gp/T/tmp.SX3eOgD0/tls.key'
-----
secret/kong-validation-webhook created
deployment.apps/ingress-kong patched
validatingwebhookconfiguration.admissionregistration.k8s.io/kong-validations created

This script takes all the following commands and packs them together. You need kubectl and openssl installed on your workstation for this to work.

Set up using the Helm chart

If you are using the Helm chart, you can enable the webhook by setting ingressController.admissionWebhook.enabled=true in your values.yaml. It is set to true by default as of chart version 2.16.

The chart generates a self-signed certificate by default. ingressController.admissionWebhook.certificate contains settings to use a user-provided certificate instead.

Create a certificate for the admission webhook

Kubernetes API-server makes an HTTPS call to the admission webhook to verify if the custom resource is valid or not. For this to work, Kubernetes API-server needs to trust the CA certificate that is used to sign the admission webhook’s TLS certificate.

This can be accomplished either using a self-signed certificate or using Kubernetes CA. Follow one of the steps below and then go to Create the secret step below.

Please note the CN field of the x509 certificate takes the form <validation-service-name>.<ingress-controller-namespace>.svc, which in the default case is kong-validation-webhook.kong.svc.

Using self-signed certificate

Use openssl to generate a self-signed certificate:

openssl req -x509 -newkey rsa:2048 -keyout tls.key -out tls.crt -days 365  \
    -nodes -subj "/CN=kong-validation-webhook.kong.svc" \
    -extensions EXT -config <( \
   printf "[dn]\nCN=kong-validation-webhook.kong.svc\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:kong-validation-webhook.kong.svc\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")

The output is similar to the following:

Generating a 2048 bit RSA private key
..........................................................+++
.............+++
writing new private key to 'key.pem'

Using in-built Kubernetes CA

Kubernetes comes with an in-built CA which can be used to provision a certificate for the admission webhook. Please refer to the this guide on how to generate a certificate using the in-built CA.

Create the secret

Next, create a Kubernetes secret object based on the key and certificate that was generated in the previous steps. Here, we assume that the PEM-encoded certificate is stored in a file named tls.crt and private key is stored in tls.key.

kubectl create secret tls kong-validation-webhook -n kong \
    --key tls.key --cert tls.crt

The output is similar to the following:

secret/kong-validation-webhook created

Update the deployment

Once the secret is created, update the Ingress Controller deployment:

Execute the following command to patch the Kubernetes Ingress Controller deployment to mount the certificate and key pair and also enable the admission webhook:

kubectl patch deploy -n kong ingress-kong \
    -p '{"spec":{"template":{"spec":{"containers":[{"name":"ingress-controller","env":[{"name":"CONTROLLER_ADMISSION_WEBHOOK_LISTEN","value":":8080"}],"volumeMounts":[{"name":"validation-webhook","mountPath":"/admission-webhook"}]}],"volumes":[{"secret":{"secretName":"kong-validation-webhook"},"name":"validation-webhook"}]}}}}'

The output is similar to the following:

deployment.extensions/ingress-kong patched

If you are using the Helm chart, run helm upgrade -f <path to values.yamvl> <release name> kong/kong after enabling the webhook or updating the certificate configuration. Note that chart versions 2.16 and later enable the webhook by default.

Enable the validating admission

If you are using Kubernetes CA to generate the certificate, you don’t need to supply a CA certificate (in the caBunde parameter) as part of the Validation Webhook configuration as the API-server already trusts the internal CA.

echo "apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: kong-validations
webhooks:
- name: validations.kong.konghq.com
  objectSelector:
    matchExpressions:
    - key: owner
      operator: NotIn
      values:
      - helm
  failurePolicy: Fail
  sideEffects: None
  admissionReviewVersions: ["v1", "v1beta1"]
  rules:
  - apiGroups:
    - configuration.konghq.com
    apiVersions:
    - '*'
    operations:
    - CREATE
    - UPDATE
    resources:
    - kongconsumers
    - kongplugins
  - apiGroups:
    - ''
    apiVersions:
    - 'v1'
    operations:
    - UPDATE
    resources:
    - secrets
  clientConfig:
    service:
      namespace: kong
      name: kong-validation-webhook
    caBundle: $(cat tls.crt  | base64) " | kubectl apply -f -

The output is similar to the following:

validatingwebhookconfiguration.admissionregistration.k8s.io/kong-validations configured

Verify if it works

Verify duplicate KongConsumers

Create a KongConsumer with username as harry:

echo "apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: harry
  annotations:
    kubernetes.io/ingress.class: kong
username: harry" | kubectl apply -f -

The output is similar to the following:

kongconsumer.configuration.konghq.com/harry created

Now, create another KongConsumer with the same username:

echo "apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: harry2
  annotations:
    kubernetes.io/ingress.class: kong
username: harry" | kubectl apply -f -

The output is similar to the following:

Error from server: error when creating "STDIN": admission webhook "validations.kong.konghq.com" denied the request: consumer already exists

The validation webhook rejected the KongConsumer resource as there already exists a consumer in Kong with the same username.

Verify incorrect KongPlugins

Try to create the following KongPlugin resource. The foo config property does not exist in the configuration definition and hence the admission webhook returns back an error. If you remove the foo: bar configuration line, the plugin will be created successfully.

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: request-id
config:
  foo: bar
  header_name: my-request-id
plugin: correlation-id
" | kubectl apply -f -

The output is similar to the following:

Error from server: error when creating "STDIN": admission webhook "validations.kong.konghq.com" denied the request: 400 Bad Request {"fields":{"config":{"foo":"unknown field"}},"name":"schema violation","code":2,"message":"schema violation (config.foo: unknown field)"}

Verify incorrect credential secrets

With 0.7 and above versions of the controller, validations also take place for incorrect secret types and wrong parameters to the secrets:

kubectl create secret generic some-credential \
  --from-literal=kongCredType=basic-auth \
  --from-literal=username=foo

The output is similar to the following:

Error from server: admission webhook "validations.kong.konghq.com" denied the request: missing required field(s): password
kubectl create secret generic some-credential \
  --from-literal=kongCredType=wrong-auth \
  --from-literal=sdfkey=my-sooper-secret-key

The output is similar to the following:

Error from server: admission webhook "validations.kong.konghq.com" denied the request: invalid credential type: wrong-auth
Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023