The information in this documentation is geared towards users that want to use Gloo Gateway proxies with the Kubernetes Gateway API. If you want to use the Gloo Edge API instead, see the Gloo Gateway (Gloo Edge API) documentation.
Test resources
Try out the resource validation capability in Gloo Gateway to check configuration before you apply it to your cluster.
The information in this guide assumes that you enabled strict validation, including the rejection of resources that result in a Warning state. To enable these settings, update your Gloo Gateway installation and include --set gateway.validation.alwaysAcceptResources=false, --set gateway.validation.enabled=true, and --set gateway.validation.allowWarnings=false. You can also edit the Settings resource directly. For more information, see Enable strict resource validation.
To test whether a YAML file is accepted by the validation webhook, you can use the kubectl apply --dry-run=server command as shown in the following examples.
Try to create a RouteOption with an invalid fault injection configuration and verify that your resource is denied by the validation API. The following example is missing the required HTTP status code field that is returned when the request is aborted.
Error from server: error when creating "STDIN": admission webhook "gloo.gloo-system.svc" denied the request: resource incompatible with current Gloo snapshot: [Validating *v1.RouteOption failed: 1 error occurred:
* Validating *v1.RouteOption failed: validating *v1.RouteOption name:"faults" namespace:"httpbin": 1 error occurred:
* Route Error: ProcessingError. Reason: *faultinjection.plugin: invalid abort status code '0', must be in range of [200,600). Route Name:
Try to create a VirtualHostOption resource with an invalid retry policy. In the following example, the baseInterval is greater than the maxInterval. Verify that the configuration is rejected.
kubectl apply --dry-run=server -f- <<EOF
apiVersion: gateway.solo.io/v1
kind: VirtualHostOption
metadata:
name: bad-retries
spec:
targetRefs:
- group: gateway.networking.k8s.io
kind: Gateway
name: http
sectionName: http
options:
retries:
retryOn: "5xx"
retryBackOff:
# An error is expected when the baseInterval is greater than the maxInterval
baseInterval: "1s"
maxInterval: "1ms"
EOF
Example output:
Error from server: error when creating "STDIN": admission webhook "gloo.gloo-system.svc" denied the request: resource incompatible with current Gloo snapshot: [Validating *v1.VirtualHostOption failed: 1 error occurred:
* Validating *v1.VirtualHostOption failed: validating *v1.VirtualHostOption name:"bad-retries" namespace:"default": 1 error occurred:
* VirtualHost Error: ProcessingError. Reason: invalid virtual host [vhost] while processing plugin basic_route: base interval: 1000 is > max interval: 1
Send a curl request to the validation API to test your resource configurations. For an overview of the fields that you must include as part of your request, see Validation API reference.
info
If an empty response {} is returned from the validation API, you might need to add or remove a bracket from your request. This response is returned also if the wrong bracket type is used, such as when you used {} instead of [].
notifications
The validation API currently assumes that all configuration that is sent to the API passes the Kubernetes object schema validation. For example, if your configuration contains valid Gloo Gateway configuration, but you use an API version or API kind that does not exist in your cluster, the validation API logs a warning, but accepts the request. To ensure that your resource configuration passes the Kubernetes object schema validation, use the dry run capability in Kubernetes instead.
Send a request with your resource configuration to the Gloo Gateway validation API. The following example shows successful and unsuccessful resource configuration validation for the RouteOption and VirtualHostOption resources.
The following RouteOption resource configures an invalid fault injection policy that aborts 50% of all traffic. The configuration is missing an HTTP status code.
{"response":{"uid":"1234","allowed":false,"status":{"metadata":{},"message":"resource incompatible with current Gloo snapshot: [Validating *v1.VirtualHostOption failed: 1 error occurred:\n\t* Validating *v1.VirtualHostOption failed: validating *v1.VirtualHostOption name:\"bad-retries\" namespace:\"httpbin\": 1 error occurred:\n\t* VirtualHost Error: ProcessingError. Reason: invalid virtual host [vhost] while processing plugin basic_route: base interval: 1000 is \u003e max interval: 1\n\n\n\n]","details":{"name":"bad-retries","group":"gateway.solo.io","kind":"VirtualHostOption","causes":[{"message":"Error Validating *v1.VirtualHostOption failed: 1 error occurred:\n\t* Validating *v1.VirtualHostOption failed: validating *v1.VirtualHostOption name:\"bad-retries\" namespace:\"httpbin\": 1 error occurred:\n\t* VirtualHost Error: ProcessingError. Reason: invalid virtual host [vhost] while processing plugin basic_route: base interval: 1000 is \u003e max interval: 1\n\n\n\n"}]}}}}%
Change the maxInterval to an invalid value, such as 5 ("maxInterval":"5"). This value is missing the time unit. Verify that the configuration is rejected.
{"response":{"uid":"1234","allowed":false,"status":{"metadata":{},"message":"resource incompatible with current Gloo snapshot: [1 error occurred:\n\t* could not unmarshal raw object: parsing resource from crd spec bad-retries in namespace httpbin into *v1.VirtualHostOption: bad Duration: time: missing unit in duration \"5\"\n\n]","details":{"name":"bad-retries","group":"gateway.solo.io","kind":"VirtualHostOption","causes":[{"message":"Error 1 error occurred:\n\t* could not unmarshal raw object: parsing resource from crd spec bad-retries in namespace httpbin into *v1.VirtualHostOption: bad Duration: time: missing unit in duration \"5\"\n\n"}]}}}}%
Change the maxInterval to a value that is greater than the baseInterval, such as 5s ("maxInterval":"5s"). Verify that your configuration is now accepted.
Information about the resource that is admitted to the webhook. In most cases, the resource defined in request.kind and request.resource is the same. They might differ only when changes in API versions or variations in resource naming were introduced, or if the resource that you admit belongs to a subresource. If this is the case, you must include the request.resource field in your request to the validation API. If request.kind and request.resource are the same, the request.resource section can be omitted.The following fields can be defined:
request.resource.group (string): The API group of the resource that you admit to the validation API.
request.resource.version (string): The API version of the resource that you want to admit.
request.resource.kind (string): The type of resource that you want to admit.
request.name
String
No
The name of the resource that you want to validate.
request.namespace
String
No
The namespace where you want to create, update, or delete the resource.
request.operation
String
Yes
The operation in Kubernetes that you want to use for your resource. The operation that you can set depends on the resource that you want to validate. You can find supported operations in the rules section in the Gloo Gateway validating admission webhook configuration.
request.userInfo
Object
No
Information about the user that sends the validation request. The following fields can be provided:
request.userInfo.username (string): The name of the user that sends the validation request, such as my-serviceaccount.
request.userInfo.uid (string): The unique identifier of the user.
request.userInfo.groups (array of strings): A list of groups that the user belongs to.
request.object
Object
Yes
The resource configuration that you want to validate, such as a RouteOption or VirtualHostOption, in JSON format. Refer to the API reference for more information about the fields that you can set for each resource.