Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Kong Gateway Operator
      Manage your Kong deployments on Kubernetes using YAML Manifests
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
  • API Specs
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Ingress Controller
1.2.x
  • Home icon
  • Kong Ingress Controller
  • Deployment
  • Validating Admission Controller
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.11.x (latest)
  • 2.10.x
  • 2.9.x
  • 2.8.x
  • 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
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • tldr;
  • Create a certificate for the admission controller
    • 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
You are browsing documentation for an outdated version. See the latest documentation here.

Validating Admission Controller

The Kong Ingress Controller ships with an Admission Controller for KongPlugin and KongConsumer resources in the configuration.konghq.com API group.

The Admission Controller 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 controller.

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

tldr;

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

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

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

Create a certificate for the admission controller

Kuberentes API-server makes an HTTPS call to the Admission Controller 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 Admission Controller’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")
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 Controller. 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 generatd 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
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 Kong Ingress Controller deployment to mount the certificate and key pair and also enable the admission controller:

$ 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"}]}}}}'
deployment.extensions/ingress-kong patched

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 param) as part of the Validation Webhook configuration as the API-server already trusts the internal CA.

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

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 -
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 -
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 folowing KongPlugin resource. The foo config property does not exist in the configuration definition and hence the Admission Controller returns back an error. If you remove the foo: bar configuration line, the plugin will be created succesfully.

$ 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 -
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
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
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?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • 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