CEL matcher language reference
Common Expression Language (CEL) is anopen source non-Turing complete language that implements common semantics forexpression evaluation. Service Extensions uses a subset of CELconditions to make chain evaluation decisions based on attribute data. Ingeneral, a condition expression consists of one or more statements that arejoined by logical operators (&&,||, or!).
Attributes
For any given connection request, the proxy extracts attributes,which are a set of contextual information. Attributes have a fixed type (such asstring orint), and might be absent or present, depending on the context.Attributes are exposed to the CEL runtime during match condition processing.Attributes are not available to be sent to an extension service.
Request attributes
The following attributes can be extracted from requests:
| Attribute | Attribute type | Description |
|---|---|---|
request.headers | map{string,string} | A string-to-string map of the HTTP request headers. If a header contains multiple values, the value in this map is a comma-separated string of all values of the header. The keys in this map are in lowercase. |
request.method | string | The HTTP request method, such asGET orPOST. |
request.host | string | Convenience equivalent torequest.headers['host']. |
request.path | string | The requested HTTP URL path. |
request.query | string | The HTTP URL query in the format of No decoding is performed. |
request.scheme | string | The HTTP URL scheme, such as HTTP or HTTPS. Values for this attribute are in lowercase. |
request.backend_service_name | string | The backend service to which the request is forwarded. Not applicable for edge extensions. |
request.backend_service_project_number | int | When using Shared VPC, the project number of the backend service to which the request is forwarded. Not applicable for edge extensions. |
Connection attributes
The following attributes can be extracted from connections:
| Attribute | Attribute type | Description |
|---|---|---|
source.ip | string | The source IP address of the request. |
source.port | int | The connection port of the downstream client. |
connection.sni | string | The requested server name of the downstream TLS connection. |
connection.tls_version | string | The TLS version of the downstream TLS connection. Valid values:TLSv1,TLSv1.1,TLSv1.2, andTLSv1.3. |
connection.sha256_peer_certificate_digest | string | The hexadecimal-encoded SHA256 hash of the peer certificate in the downstream TLS connection, if present. |
Operators
Service Extensions supports several operators that you can useto build complex match conditions from simple expression statements.Service Extensions supportslogical operators, such as&&,||, and!, and string manipulationoperators, such asx.contains('y').
String manipulation operators match strings or substrings that you define. Forexample,request.host.endsWith('.example.com') evaluates totrue if the HTTPrequest was made to a domain ending withexample.com.
Logical operators let you verify multiple variables in a conditionalexpression. For example,request.method == 'GET' && request.host.matches('.example.com') joins twostatements and requires both statements to betrue to produce anoverall result oftrue.
Logical operators
The following table describes the logical operators that Service Extensionssupports.
| Example expression | Description |
|---|---|
x == "foo" | Returnstrue ifx is equal to the constant string literal argument. |
x == R"fo'o" | Returnstrue ifx is equal to the given raw string literal that does not interpret escape sequences. Raw string literals are convenient for expressing strings that the code must use to escape sequence characters. |
x == y | Returnstrue ifx is equal toy. |
x != y | Returnstrue ifx is not equal toy. |
x && y | Returnstrue if bothx andy aretrue. |
x || y | Returnstrue ifx,y, or both aretrue. |
!x | Returnstrue if the boolean valuex isfalse, or returnsfalse if the boolean valuex istrue. |
m['k'] | If keyk is present, returns the value at keyk in the string-to-string mapm. If keyk is not present, returns an error that causes the rule under evaluation to not match. |
String manipulation operators
The following table describes the string manipulation operators thatService Extensions supports.
| Expression | Description |
|---|---|
x.contains(y) | Returnstrue if the stringx contains the substringy. |
x.startsWith(y) | Returnstrue if the stringx begins with the substringy. |
x.endsWith(y) | Returnstrue if the stringx ends with the substringy. |
x.matches(y) | Returns Service Extensions uses the RE2::Latin1 option when it compiles the RE2 pattern, which disables Unicode features. Edge extensions let you use only one regular expression per CEL expression. |
x.lower() | Returns the lowercase value of stringx. |
x.upper() | Returns the uppercase value of stringx. |
int(x) | Converts the string result ofx to anint type. You can use the converted string for integer comparison by using standard arithmetic operators, such as greater than (>) and less than or equal to (≤). This works only for values that can be integers. |
Sample expressions
Match all requests to hostexample.com with backend servicebs1 in123as the final destination:
request.host == "example.com" && request.backend_service_name == "bs1" && request.backend_service_project_number == 123
Match all requests for the path*/inventory with an HTTP headerHello:
request.path.endsWith("/inventory") && request.headers["Hello"] != ""Limitations
The following limitations apply to CEL expressions when specified forService Extensions:
- Maximum expressions per extension: 1 for edge extensions and 5 forother extensions
- Maximum number of characters per regular expression: 100
- Maximum number of characters per CEL expression: 500
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-19 UTC.