APIRule v2 Custom Resource

The apirules.gateway.kyma-project.io CustomResourceDefinition (CRD) describes the kind and the format of data the APIGateway Controller listens for. To get the up-to-date CRD in the yaml format, run the following command:

kubectl get crd apirules.gateway.kyma-project.io -o yaml

Specification of APIRule v2 Custom Resource

This table lists all parameters of APIRule v2 CRD together with their descriptions:

Spec:

Field	Required	Description	Validation
gateway	YES	Specifies the Istio Gateway. The value must reference an actual Gateway in the cluster.	It must be in the namespace/gateway format. The namespace and the Gateway cannot be longer than 63 characters each.
corsPolicy	NO	Allows configuring CORS headers sent with the response. If corsPolicy is not defined, the CORS headers are enforced to be empty.	None
corsPolicy.allowHeaders	NO	Specifies headers allowed with the Access-Control-Allow-Headers CORS header.	None
corsPolicy.allowMethods	NO	Specifies methods allowed with the Access-Control-Allow-Methods CORS header.	None
corsPolicy.allowOrigins	NO	Specifies origins allowed with the Access-Control-Allow-Origins CORS header.	None
corsPolicy.allowCredentials	NO	Specifies whether credentials are allowed in the Access-Control-Allow-Credentials CORS header.	None
corsPolicy.exposeHeaders	NO	Specifies headers exposed with the Access-Control-Expose-Headers CORS header.	None
corsPolicy.maxAge	NO	Specifies the maximum age of CORS policy cache. The value is provided in the Access-Control-Max-Age CORS header.	None
hosts	YES	Specifies the Service's communication address for inbound external traffic. It must be a RFC 1123 label or a valid, fully qualified domain name (FQDN) in the following format: at least two domain labels with characters, numbers, or hyphens. If you use a short host name at the spec.hosts level, the referenced Gateway must provide the same single host for all Server definitions and it must be prefixed with *.. Otherwise, the validation fails.	Lowercase RFC 1123 label or FQDN format.
service.name	NO	Specifies the name of the exposed Service. If you don't specify a service is defined at the spec.service level, each defined access rule must specify a service at the spec.rules.service level. Otherwise, the validation fails.	None
service.namespace	NO	Specifies the namespace of the exposed Service.	None
service.port	NO	Specifies the communication port of the exposed Service.	None
timeout	NO	Specifies the timeout for HTTP requests in seconds for all Access Rules. The value can be overridden for each Access Rule. If no timeout is specified, the default timeout of 180 seconds applies.	The maximum timeout is limited to 3900 seconds (65 minutes).
rules	YES	Specifies the list of Access Rules.	None
rules.service	NO	Services definitions at this level have higher precedence than the Service definition at the spec.service level.	None
rules.path	YES	Specifies the path on which the service is exposed. The supported configurations are: Exact path (e.g. /abc) - matches the specified path exactly. Usage of the {*} operator (e.g. /foo/{*} or /foo/{*}/bar) - matches any request that matches the pattern with exactly one path segment in the operator's place. Usage of the {**} operator (e.g. /foo/{**} or /foo/{**}/bar) - matches any request that matches the pattern with zero or more path segments in the operator's place. {**} must be the last operator in the path. Wildcard path /* - matches all paths. It's equivalent to the /{**} path.	The value might contain operators {*} and/or {**}. It can also be a wildcard match /*. The order of rules in the APIRule CR is important. Rules defined earlier in the list have a higher priority than those defined later.
rules.methods	NO	Specifies the list of HTTP request methods available for spec.rules.path. The list of supported methods is defined in RFC 9910: HTTP Semantics and RFC 5789: PATCH Method for HTTP.	None
rules.noAuth	NO	Setting noAuth to true disables authorization.	Must be set to true if jwt and extAuth are not specified.
rules.request	NO	Defines request modification rules, which are applied before forwarding the request to the target workload.	None
rules.request.cookies	NO	Specifies a list of cookie key-value pairs, that are forwarded inside the Cookie header.	None
rules.request.headers	NO	Specifies a list of header key-value pairs that are forwarded as header=value to the target workload.	None
rules.jwt	NO	Specifies the Istio JWT access strategy.	Must exists if noAuth and extAuth are not specified.
rules.jwt.authentications	YES	Specifies the list of authentication objects.	None
rules.jwt.authentications.issuer	YES	Identifies the issuer that issued the JWT. The value must be a URL. Although HTTP is allowed, it is recommended that you use only HTTPS endpoints.	None
rules.jwt.authentications.jwksUri	YES	Contains the URL of the provider’s public key set to validate the signature of the JWT. The value must be a URL. Although HTTP is allowed, it is recommended that you use only HTTPS endpoints.	None
rules.jwt.authentications.fromHeaders	NO	Specifies the list of headers from which the JWT token is extracted.	None
rules.jwt.authentications.fromHeaders.name	YES	Specifies the name of the header.	None
rules.jwt.authentications.fromHeaders.prefix	NO	Specifies the prefix used before the JWT token. The default is Bearer.	None
rules.jwt.authentications.fromParams	NO	Specifies the list of parameters from which the JWT token is extracted.	None
rules.jwt.authorizations	NO	Specifies the list of authorization objects.	None
rules.jwt.authorizations.requiredScopes	NO	Specifies the list of required scope values for the JWT.	None
rules.jwt.authorizations.audiences	NO	Specifies the list of audiences required for the JWT.	None
rules.extAuth	NO	Specifies the Istio External Authorization access strategy.	Must exists if noAuth and jwt are not specified.
rules.extAuth.authorizers	YES	Specifies the Istio External Authorization authorizers. In case extAuth is configured, at least one must be present.	Validated that the provider exists in Istio external authorization providers.
rules.extAuth.restrictions	NO	Specifies the Istio External Authorization JWT restrictions. Field configuration is the same as for rules.jwt.	None
rules.timeout	NO	Specifies the timeout, in seconds, for HTTP requests made to spec.rules.path. Timeout definitions set at this level take precedence over any timeout defined at the spec.timeout level.	The maximum timeout is limited to 3900 seconds (65 minutes).

Status:

The following table lists the fields of the status section.

Field	Description
status.state	Defines the reconciliation state of the APIRule. The possible states are Ready, Warning, Error, Processing or Deleting.
status.description	Detailed description of status.state.

Sample Custom Resource

See an exemplary APIRule custom resource:

apiVersion: gateway.kyma-project.io/v2
kind: APIRule
metadata:
  name: service-exposed
spec:
  gateway: kyma-system/kyma-gateway
  hosts:
    - foo.bar
  service:
    name: foo-service
    namespace: foo-namespace
    port: 8080
  timeout: 360
  rules:
    - path: /*
      methods: [ "GET" ]
      noAuth: true

This sample APIRule illustrates the usage of a short host name. It uses the domain from the referenced Gateway kyma-system/kyma-gateway:

apiVersion: gateway.kyma-project.io/v2
kind: APIRule
metadata:
  name: service-exposed
spec:
  gateway: kyma-system/kyma-gateway
  hosts:
    - foo
  service:
    name: foo-service
    namespace: foo-namespace
    port: 8080
  timeout: 360
  rules:
    - path: /*
      methods: [ "GET" ]
      noAuth: true

This sample APIRule illustrates an example of explicitly defined corsPolicy with working preflight requests:

apiVersion: gateway.kyma-project.io/v2
kind: APIRule
metadata:
  name: service-exposed
spec:
  gateway: kyma-system/kyma-gateway
  hosts:
    - foo
  service:
    name: foo-service
    namespace: foo-namespace
    port: 8080
  timeout: 360
  rules:
    - path: /*
      methods: [ "GET", "OPTIONS" ]
      noAuth: true
  corsPolicy:
    allowOrigins:
      - regex: .*

Related Information

• Ordering Rules in APIRule v2
• APIRule Access Strategies