DoS protected resource specification

NGINX App Protect DoS protected resource specification

Note:
This feature is only available using the NGINX Plus NGINX App Protect DoS Module.

DoS Protected resource specification

Below is an example of a DoS protected resource.

apiVersion: appprotectdos.f5.com/v1beta1
kind: DosProtectedResource
metadata:
  name: dos-protected
spec:
  enable: true
  name: "my-dos"
  apDosMonitor:
    uri: "webapp.example.com"

DosProtectedResource.apDosPolicy

The apDosPolicy is a reference (qualified identifier in the format namespace/name) to the policy configuration defined as an ApDosPolicy.

DosProtectedResource.apDosMonitor

This is how NGINX App Protect DoS monitors the stress level of the protected object. The monitor requests are sent from localhost (127.0.0.1).

Invalid DoS Protected resources

NGINX will treat a DoS protected resource as invalid if one of the following conditions is met:

• The DoS protected resource doesn’t pass the comprehensive validation.
• The DoS protected resource isn’t present in the cluster.

Validation

Two types of validation are available for the DoS protected resource:

• Structural validation, done by kubectl and the Kubernetes API server.
• Comprehensive validation, done by NGINX Ingress Controller.

Structural validation

The custom resource definition for the DoS protected resource includes a structural OpenAPI schema, which describes the type of every field of the resource.

If you try to create (or update) a resource that violates the structural schema – for example, the resource uses a string value instead of a bool in the enable field – kubectl and the Kubernetes API server will reject the resource.

• Example of kubectl validation:

  kubectl apply -f apdos-protected.yaml
  

  error: error validating "examples/app-protect-dos/apdos-protected.yaml": error validating data: ValidationError(DosProtectedResource.spec.enable): invalid type for com.f5.appprotectdos.v1beta1.DosProtectedResource.spec.enable: got "string", expected "boolean"; if you choose to ignore these errors, turn validation off with --validate=false
  

• Example of Kubernetes API server validation:

  kubectl apply -f access-control-policy-allow.yaml --validate=false
  

  The DosProtectedResource "dos-protected" is invalid: spec.enable: Invalid value: "string": spec.enable in body must be of type boolean: "string"
  

If a resource passes structural validation, then NGINX Ingress Controller will start comprehensive validation.

Comprehensive validation

NGINX Ingress Controller validates the fields of a DoS protected resource. If a resource is invalid, NGINX Ingress Controller will reject it. The resource will continue to exist in the cluster, but NGINX Ingress Controller will ignore it.

You can use kubectl to check if NGINX Ingress Controller successfully applied a DoS protected resource configuration. For our example dos-protected DoS protected resource, we can run:

kubectl describe dosprotectedresource dos-protected

Events:
  Type    Reason          Age                From                      Message
  ----    ------          ----               ----                      -------
  Normal  AddedOrUpdated  12s (x2 over 18h)  nginx-ingress-controller  Configuration for default/dos-protected was added or updated

Note how the events section includes a Normal event with the AddedOrUpdated reason that informs us that the configuration was successfully applied.

If you create an invalid resource, NGINX Ingress Controller will reject it and emit a Rejected event. For example, if you create a dos protected resource dos-protected with an invalid URI bad in the dosSecurityLog/dosLogDest field, you will get:

kubectl describe policy webapp-policy

Events:
  Type     Reason    Age   From                      Message
  ----     ------    ----  ----                      -------
  Warning  Rejected  2s    nginx-ingress-controller  error validating DosProtectedResource: dos-protected invalid field: dosSecurityLog/dosLogDest err: invalid log destination: bad, must follow format: <ip-address | localhost | dns name>:<port> or stderr

The events section has Warning event with the rejection error in the message.

Warning:
If you invalidate an existing resource, NGINX Ingress Controller will reject it.