apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: <api instance name> namespace: # optional namespace name spec: address: <proxy address including port and path> services: # optional map of upstream services <name>: address: <service address> routes: # optional array of routes to service - config: # optional route configuration destinationPath: <optional base path to upstream service> rules: # optional route rules policies: # optional array of policies - policyRef: name: <name of the policy> namespace: <optional namespace of the policy> config: # optional policy configuration rules: # optional policy rules
Declarative Configuration Reference Guide
Anypoint Flex Gateway running in Local Mode supports two configuration models:
-
The resource-based model, common in Kubernetes, is ideal for granular definitions. Resources each contain one of the following values for configuration
kind
:-
ApiInstance
-
Service
-
PolicyBinding
-
Configuration
-
-
The inline model is ideal for concise definitions, but is less versatile (for example, automated policies can only be applied in resource-based definitions.)
Inline definitions contain a single
ApiInstance
value for configurationkind
, under which services and policies are both defined.
Refer to the Examples section for examples of both.
This reference guide describes the available resources that are applicable to either resource-based configurations or inline configurations.
API Instance
Parameter | Required or Optional | Default Value | Description |
---|---|---|---|
|
Required |
N/A |
The API instance identifier that is used as a target reference for other resources, such as policy bindings. |
|
Optional |
|
|
|
Required |
N/A |
The proxy address URL, including protocol, host, port and optional path. If the base path is specified, it must be absent in any |
|
Optional |
Empty |
A map of named services and their routes. |
|
Required |
N/A |
The service address (and port). Supported format: |
|
Optional |
Empty |
An array of routes configured for this API instance towards the service. If left empty, a default route will be established to the service that will route all traffic. |
|
Optional |
Empty |
The configuration for this route. If left empty, a default configuration will be applied with an empty |
|
Optional |
Empty |
The path to prepend to forwarded requests to the upstream service. For example, if "destinationPath: /api/v1", requests to this API instance with a path like "/orders" will be routed upstream to "/api/v1/orders". |
|
Optional |
Empty |
An array of rules for this route. Refer to spec.rules in Policy Binding. |
|
Optional |
Empty |
An array of policies to apply to this API Instance. |
|
Required |
N/A |
The policy name. |
|
Optional |
The value of |
The namespace where the policy is defined. For provided policies, the value of this field should be |
|
Optional |
Empty |
The policy’s configuration. Refer to spec.config in Policy Binding. To use environment variables in |
|
Optional |
Empty |
An array of rules for applying this policy to the API Instance. spec.rules in Policy Binding. |
API Instance Examples
The following resource specifies an ApiInstance
with metadata that describes the instance identifier. The metadata.name
value is used as the target reference for other resources, such as policy bindings. The spec.services.routes.config.destinationPath
value prepends /v1/apps
to the specified paths under rules
, acting in a similar manner as a base path.
apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: hello-flex-gateway-instance spec: address: http://0.0.0.0:8080 services: json: address: https://<upstream address>:443/ routes: - rules: - path: /api(/users/.*) - path: /api(/comments/.*) config: destinationPath: /v1/apps
Port Sharing
The following ApiInstance
resources demonstrate API port sharing, with two distinct API instances listening on port 8080.
--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: httpbin-example spec: address: http://0.0.0.0:8080/api/httpbin/ services: upstream: address: https://<upstream address>:443 --- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: json-example spec: address: http://0.0.0.0:8080/api/json/ services: upstream: address: https://<upstream address>:443
Both services listen on port 8080, for example:
curl http://localhost:8080/api/httpbin/get -v curl http://localhost:8080/api/json/users/1 -v
The base path of APIs sharing a port must not clash. For example, the following path combination is not allowed: http://0.0.0.0:8080/cats http://0.0.0.0:8080/cats/dogs |
TLS applies to the port. Therefore, the same TLS policy applies to all API instances sharing the port. |
Policy Binding
apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: <policy binding name> namespace: <namespace name> spec: targetRef: name: <api instance name> namespace: <optional api instance namespace> policyRef: name: <policy name> namespace: <optional policy namespace> config: # optional policy configuration order: # optional policy read order rules: # optional policy rules - path: <path regular expression> methods: <methods regular expression> host: <host regular expression> headers: <headers map> <header-name>: <header value regular expression>
Parameter | Required or Optional | Default Value | Description |
---|---|---|---|
|
Required |
N/A |
The identifier of the policy binding. |
|
Optional |
|
|
|
Required |
N/A |
The API instance identifier to which the policy is bound to. |
|
Optional |
The value of |
The namespace where the target is defined. |
|
Required |
N/A |
The policy name. See the list of available policies. |
|
Optional |
The value of |
The namespace where the policy is defined. For provided policies, the value of this field should be |
|
Optional |
Empty |
The policy configuration. The content of this field depends on the specified policy. See the list of available policies. To use environment variables in |
|
Optional |
50 |
The policy read order in the overall policy execution chain. |
|
Optional |
Empty |
An array of rules that will determine if the policy applies to a given request. These rules are checked in an OR fashion. The first one to hold will enable applying the policy to the request. The attributes in each rule object apply in an AND fashion. If path and host are defined, both must match for that rule to hold true. |
|
Optional |
|
A regular expression to match the request path. Capture groups in this regular expression will be used to define path rewriting when routing the request upstream. If "path: /api(/.*)", requests with the path /api/orders will be routed upstream as /orders. Multiple capture groups can be specified, and the replacement will be the concatenation of all captured substrings. |
|
Optional |
|
A regular expression to match the request host. |
|
Optional |
|
A regular expression to match the request method. |
|
Optional |
Empty |
A map of header names and value regular expressions that must be present in the request. Each entry’s key is the expected header name and the value is a regular expression to match the header value. |
Policy Binding Examples
The following resource binds a route
policy to the API instance, routing traffic specified by the rules
to the proxy address specified in the Service
configuration snippet:
apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: hello-flex-gateway-route namespace: e-commerce spec: targetRef: name: hello-flex-gateway-instance policyRef: name: route namespace: default config: destinationRef: name: json namespace: e-commerce rules: - path: /api/json(/.*)
The following resource binds a http-basic-authentication-flex
policy to the API instance - requiring requests to include the basic credentials defined in config.username
and config.password
. The policy is given a read order value of 2
.
apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: hello-flex-gateway-auth namespace: e-commerce spec: targetRef: name: hello-flex-gateway-instance namespace: e-commerce policyRef: name: http-basic-authentication-flex namespace: default config: username: chris password: admin order: 2
Environment Variables for Policy Bindings
Both policy binding resources and inline policy bindings support environment variables in config
fields. The environment variables available are dependent on your environment.
To reference your environment variable, specify your environment variable prefixed by $
, for example:
- policyRef: name: http-basic-authentication-flex config: username: $USERNAME password: $PASSWORD
Service
apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: <service name> namespace: <namespace name> spec: address: <service address including port>
Parameter | Required or Optional | Default Value | Description |
---|---|---|---|
|
Required |
N/A |
The service identifier. |
|
Optional |
|
|
|
Required |
N/A |
The service address URL, including protocol, host and port. Supported format: |
Service Example
The following resource defines a Service
with metadata that describes the service identifier. The metadata.namespace
value matches the namespace specified in the ApiInstance
configuration. The spec.address
is the address of the API implementation:
apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: json-example namespace: e-commerce spec: address: https://<upstream address>:443/
Configuration
Define a desired gateway state by creating a Configuration
entity. Configuration
entities specify several runtime configuration aspects for Flex Gateway itself, such as logging and shared storage. The definition includes the following:
apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: <value> namespace: <namespace name> spec: logging: # logging configuration sharedStorage: # shared storage configuration
Parameter | Required or Optional | Default Value | Description |
---|---|---|---|
|
Required |
N/A |
The Configuration entity. |
|
Optional |
|
The namespace value used to isolate Configuration entities. |
|
Required |
N/A |
The configuration object that defines gateway characteristics. Objects include: |
Logging
The logging
object configures the delivery of runtime and access logs enabled via the message logging policy. Logs are delivered to any supported Fluent Bit v2.0 output.
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
name: <value>
namespace: <namespace name>
spec:
logging:
outputs:
- name: <output-name>
type: <output-type>
parameters:
<param-name>: <param-value>
runtimeLogs:
logLevel: <value>
outputs: <value>
accessLogs:
outputs: <value>
Parameter | Required or Optional | Default Value | Description |
---|---|---|---|
|
Required |
N/A |
The name of this output to later refer to in runtime and access logs configurations. |
|
Required |
N/A |
An output type supported by Fluent Bit. For Fluent Bit output types, see Fluent Bit Outputs documentation . |
|
Required |
N/A |
A map of parameters for the specific Fluent Bit output type. For Fluent Bit output type parameters, see Fluent Bit Outputs documentation . |
|
Optional |
Empty |
A list of output names to redirect access logs to. |
|
Optional |
|
A parameter specifying log detail. The supported |
|
Optional |
Empty |
A list of output names to redirect runtime logs to. |
Leaving a value blank applies the default value to your configuration.
In addition to parameters above, Flex Gateway offers variables for logging output. When configured, the variables render as one of their respective outputs in the logs:
Variable | Description | Outputs |
---|---|---|
|
Date and time of the logged event |
A specific time, for example, |
|
Flex Gateway service where the logged event occurred |
|
|
|
|
|
Log type |
|
Logging Example
apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: logging spec: logging: outputs: - name: log-to-file type: file parameters: path: /var/log file: log.txt format: template template: | [{date}][{logger}][{level}][{kind}] {message} runtimeLogs: logLevel: info outputs: - log-to-file accessLogs: outputs: - log-to-file
Shared Storage
The sharedStorage
object configures the gateway for shared storage. Production workflows should use Redis (minimum version 4.0.0), though defining it is optional. If Redis is not defined, shared storage services at port 4000 are still available but will use an in-memory implementation.
Optionally, you can use Redis with Transport Layer Security (TLS) to protect sensitive data, prevent unauthorized access, and maintain the reliability of your services.
apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name: shared-storage-redis spec: sharedStorage: redis: address: <string> // REQUIRED username: <string> // OPTIONAL password: <string> // OPTIONAL db: <string> // OPTIONAL tls: // OPTIONAL trustedCA: <string> // OPTIONAL certificate: // OPTIONAL keyPassphrase <string> // OPTIONAL key: <string> // REQUIRED crt: <string> // REQUIRED alpn: <array> // OPTIONAL skipValidation: <boolean> // OPTIONAL minversion: <string> // OPTIONAL maxversion: <string> // OPTIONAL ciphers: <array> // OPTIONAL
Parameter | Required or Optional | Default Value | Description |
---|---|---|---|
|
Required |
N/A |
The Redis instance address in |
|
Optional |
Empty |
The Redis user name |
|
Optional |
Empty |
The Redis user password |
|
Optional |
0 |
The Redis database number to use |
|
Optional |
Empty |
The Redis TLS configuration |
|
Optional |
N/A |
Root certificate authority to use when verifying server certificates |
|
Optional |
N/A |
Client certificate to present to the server |
|
Optional |
|
The certificate key passphrase. If specified, use the private key format that includes a DEK-Info header. If unspecified, the private key must not be encrypted. |
|
Required |
N/A |
The private key part of the certificate |
|
Required |
N/A |
The public key part of the certificate |
|
Optional |
|
If true, any certificate presented by the server is accepted. |
|
Optional |
|
The minimum TLS version allowed |
|
Optional |
|
The maximum TLS version allowed |
|
Optional |
Empty list |
A prioritized list of supported application level protocols; for example, h2, http/1.1 |
|
Optional |
TLS/Redis supports the same ciphers as the TLS policy, except the following:
|
Redis Shared Storage Example
The Redis storage service is an implementation of a REST API object store that functions as a bridge between the object store interface and a Redis backend.
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
name: shared-storage-redis
spec:
sharedStorage:
redis:
address: redis.e-commerce.svc:6379
username: ecomm-user
password: ecomm-pwd-123
DB: 7
Redis with TLS Shared Storage Example
Optionally, you can use Redis with TLS to protect data and ensure secure communication.
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
name: shared-storage-redis
spec:
sharedStorage:
redis:
address: internal.redis.com:6379
tls:
skipValidation: false
minVersion: "1.1"
maxVersion: "1.3"
alpn:
- h2
- http/1.1
ciphers:
- TLS_AES_128_GCM_SHA256
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256
- TLS_RSA_WITH_3DES_EDE_CBC_SHA
- TLS_RSA_WITH_AES_128_CBC_SHA
- TLS_RSA_WITH_AES_256_CBC_SHA
- TLS_RSA_WITH_AES_128_CBC_SHA256
- TLS_RSA_WITH_AES_128_GCM_SHA256
- TLS_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
trustedCA: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
certificate:
keyPassphrase: "****"
key: |
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
crt: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
Local Shared Storage Example
The local storage service is an implementation of a REST API object store that saves data in memory. All data is lost when Flex Gateway is stopped or restarted.
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
name: rtm-config
namespace: sales
spec:
sharedStorage:
local:
enabled: true
Examples
Inline Configuration Example
apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: api-example spec: address: http://0.0.0.0:8080 services: api-example: address: https://<your url>:443/ routes: - rules: - path: /api(/users/.*) - path: /api(/comments/.*) config: destinationPath: /v1/apps policies: - policyRef: name: http-basic-authentication-flex config: username: chris password: admin
Resource-Based Configuration Example
--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: ApiInstance metadata: name: ingress-http spec: address: http://0.0.0.0:8080 --- apiVersion: gateway.mulesoft.com/v1alpha1 kind: Service metadata: name: json spec: address: https://<your url>:443/ --- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: ingress-http-route spec: targetRef: name: ingress-http policyRef: name: route config: destinationRef: name: json rules: - path: /api(/users/.*) - path: /api(/comments/.*) --- apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: ingress-http-authentication spec: targetRef: name: ingress-http policyRef: name: http-basic-authentication-flex config: username: chris password: admin