Chapter 1. 3scale API management
If you deployed the Kafka Bridge on OpenShift Container Platform, you can use it with 3scale.
With a plain deployment of the Kafka Bridge, there is no provision for authentication or authorization, and no support for a TLS encrypted connection to external clients. 3scale API Management can secure the Kafka Bridge with TLS, and provide authentication and authorization. Integration with 3scale also means that additional features like metrics, rate limiting and billing are available.
With 3scale, you can use different types of authentication for requests from external clients wishing to access AMQ Streams. 3scale supports the following types of authentication:
- Standard API Keys
- Single randomized strings or hashes acting as an identifier and a secret token.
- Application Identifier and Key pairs
- Immutable identifier and mutable secret key strings.
- OpenID Connect
- Protocol for delegated authentication.
1.1. Kafka Bridge service discovery
3scale is integrated using service discovery, which requires that 3scale is deployed to the same OpenShift cluster as AMQ Streams and the Kafka Bridge.
Your AMQ Streams Cluster Operator deployment must have the following environment variables set:
- STRIMZI_CUSTOM_KAFKA_BRIDGE_SERVICE_LABELS
- STRIMZI_CUSTOM_KAFKA_BRIDGE_SERVICE_ANNOTATIONS
When the Kafka Bridge is deployed, the service that exposes the REST interface of the Kafka Bridge uses the annotations and labels for discovery by 3scale.
-
A
discovery.3scale.net=truelabel is used by 3scale to find a service. - Annotations provide information about the service.
You can check your configuration in the OpenShift console by navigating to Services for the Kafka Bridge instance. Under Annotations you will see the endpoint to the OpenAPI specification for the Kafka Bridge.
1.2. 3scale APIcast gateway policies
3scale is used in conjunction with 3scale APIcast, an API gateway deployed with 3scale that provides a single point of entry for the Kafka Bridge.
APIcast policies provide a mechanism to customize how the gateway operates. 3scale provides a set of standard policies for gateway configuration. You can also create your own policies.
For more information on APIcast policies, see the Red Hat 3scale documentation.
APIcast policies for the Kafka Bridge
A sample policy configuration for 3scale integration with the Kafka Bridge is provided with the policies_config.json file, which defines:
- Anonymous access
- Header modification
- Routing
- URL rewriting
Gateway policies are enabled or disabled through this file.
You can use this sample as a starting point for defining your own policies.
- Anonymous access
- The anonymous access policy exposes a service without authentication, providing default credentials (for anonymous access) when a HTTP client does not provide them. The policy is not mandatory and can be disabled or removed if authentication is always needed.
- Header modification
The header modification policy allows existing HTTP headers to be modified, or new headers added to requests or responses passing through the gateway. For 3scale integration, the policy adds headers to every request passing through the gateway from a HTTP client to the Kafka Bridge.
When the Kafka Bridge receives a request for creating a new consumer, it returns a JSON payload containing a
base_urifield with the URI that the consumer must use for all the subsequent requests. For example:{ "instance_id": "consumer-1", "base_uri":"http://my-bridge:8080/consumers/my-group/instances/consumer1" }When using APIcast, clients send all subsequent requests to the gateway and not to the Kafka Bridge directly. So the URI requires the gateway hostname, not the address of the Kafka Bridge behind the gateway.
Using header modification policies, headers are added to requests from the HTTP client so that the Kafka Bridge uses the gateway hostname.
For example, by applying a
Forwarded: host=my-gateway:80;proto=httpheader, the Kafka Bridge delivers the following to the consumer.{ "instance_id": "consumer-1", "base_uri":"http://my-gateway:80/consumers/my-group/instances/consumer1" }An
X-Forwarded-Pathheader carries the original path contained in a request from the client to the gateway. This header is strictly related to the routing policy applied when a gateway supports more than one Kafka Bridge instance.- Routing
A routing policy is applied when there is more than one Kafka Bridge instance. Requests must be sent to the same Kafka Bridge instance where the consumer was initially created, so a request must specify a route for the gateway to forward a request to the appropriate Kafka Bridge instance.
A routing policy names each bridge instance, and routing is performed using the name. You specify the name in the
KafkaBridgecustom resource when you deploy the Kafka Bridge.For example, each request (using
X-Forwarded-Path) from a consumer to:http://my-gateway:80/my-bridge-1/consumers/my-group/instances/consumer1is forwarded to:
http://my-bridge-1-bridge-service:8080/consumers/my-group/instances/consumer1URL rewriting policy removes the bridge name, as it is not used when forwarding the request from the gateway to the Kafka Bridge.
- URL rewriting
The URL rewiring policy ensures that a request to a specific Kafka Bridge instance from a client does not contain the bridge name when forwarding the request from the gateway to the Kafka Bridge.
The bridge name is not used in the endpoints exposed by the bridge.
1.3. 3scale APIcast for TLS validation
You can set up APIcast for TLS validation, which requires a self-managed deployment of APIcast using a template. The apicast service is exposed as a route.
You can also apply a TLS policy to the Kafka Bridge API.
1.4. Using an existing 3scale deployment
If you already have 3scale deployed to OpenShift and you wish to use it with the Kafka Bridge, ensure that you have the setup described in Deploying 3scale for the Kafka Bridge.
