Chapter 6. Transforming 3scale message content using policy extensions in Fuse

You can use Red Hat Fuse to create highly flexible policy extensions for Red Hat 3scale API Management. You can do this by creating policy extensions in Fuse on OpenShift and then configuring them as policies in the 3scale Admin Portal. Using an APIcast Camel proxy policy, you can perform complex transformations on request and response message content, for example, XML to JSON, which are implemented in the Apache Camel integration framework.

In addition, you can add or modify custom policy extensions dynamically in Camel, instead of rebuilding and redeploying a static APIcast container image. You can use any Camel Enterprise Integration Pattern (EIP) written in Camel Domain Specific Language (DSL) to implement an APIcast policy extension. This enables you to write policy extensions using a familiar programming language such as Java or XML. The example in this topic uses the Camel Netty4 HTTP component to implement the HTTP proxy in Java.

Note

This feature is not required if you are already using a Fuse Camel application in your 3scale API backend. In this case, you can use your existing Fuse Camel application to perform transformations.

Required software components

You must have the following Red Hat Integration components deployed on the same OpenShift cluster:

  • Fuse on OpenShift 7.7
  • 3scale On-premises 2.9
  • APIcast embedded (default Staging and Production), or APIcast self-managed

You can deploy the custom Fuse policy in a different OpenShift project than 3scale, but this is not required. However, you must ensure that communication between both projects is possible. For details, see Configuring network policy with OpenShift SDN.

Additional resources

6.1. Integrating APIcast with Apache Camel transformations in Fuse

You can integrate APIcast with a transformation written as an Apache Camel application in Fuse on OpenShift. When the policy extension transformation is configured and deployed in 3scale, the 3scale traffic goes through the Camel policy extension, which transforms the message content. In this case, Camel works as a reverse HTTP proxy, where APIcast sends the 3scale traffic to Camel, and Camel then sends the traffic on to the API backend.

The example in this topic creates the HTTP proxy using the Camel Netty4 HTTP component:

  • The request received over the HTTP proxy protocol is forwarded to the target service with the HTTP body converted to uppercase.
  • The response from the target service is processed by converting it to uppercase and then returned to the client.
  • This example shows the configuration required for HTTP and HTTPS use cases.

Prerequisites

  • You must have Fuse on OpenShift 7.7 and 3scale 2.9 deployed on the same OpenShift cluster. For installation details, see:

  • You must have cluster administrator privileges to install Fuse on OpenShift and 3scale and to create projects. However, you can create deployment configurations, deploy pods, or create services with edit access privileges per project.

Procedure

  1. Write an Apache Camel application in Java using the Camel netty4-http component to implement the HTTP proxy. You can then use any Camel component to transform the message.

    The following simple example performs an uppercase transformation of the request and response from the service:

    import java.nio.file.Files;
    import java.nio.file.Path;
    import java.util.Locale;
    
    import org.apache.camel.Exchange;
    import org.apache.camel.Message;
    import org.apache.camel.builder.RouteBuilder;
    import org.apache.camel.model.RouteDefinition;
    
    public class ProxyRoute extends RouteBuilder {
    
        @Override
        public void configure() throws Exception {
            final RouteDefinition from;
            if (Files.exists(keystorePath())) {
                from = from("netty4-http:proxy://0.0.0.0:8443?ssl=true&keyStoreFile=/tls/keystore.jks&passphrase=changeit&trustStoreFile=/tls/keystore.jks"); 1
            } else {
                from = from("netty4-http:proxy://0.0.0.0:8080");
            }
    
            from
                .process(ProxyRoute::uppercase)
                .toD("netty4-http:"
                    + "${headers." + Exchange.HTTP_SCHEME + "}://" 2
                    + "${headers." + Exchange.HTTP_HOST + "}:"
                    + "${headers." + Exchange.HTTP_PORT + "}"
                    + "${headers." + Exchange.HTTP_PATH + "}")
                .process(ProxyRoute::uppercase);
        }
    
        Path keystorePath() {
            return Path.of("/tls", "keystore.jks");
        }
    
        public static void uppercase(final Exchange exchange) { 3
            final Message message = exchange.getIn();
            final String body = message.getBody(String.class);
            message.setBody(body.toUpperCase(Locale.US));
        }
    
    }
    1
    In this simple example, if your Java keystore file is mounted at /tls/keystore.jks, the listening port is set to 8443.
    2
    When the Camel proxy policy is invoked by 3scale, the values for the HTTP_SCHEME, HTTP_HOST, HTTP_PORT, and HTTP_PATH headers are automatically set based on the values configured for the backend API in 3scale.
    3
    This simple example converts the message content to uppercase. You can perform more complex transformations on request and response message content, for example, XML to JSON, using Camel Enterprise Integration Patterns.
  2. Deploy your Camel application on OpenShift and expose it as a service. For more details, see Creating and Deploying Applications on Fuse on OpenShift.

6.2. Configuring an APIcast policy extension created using Apache Camel in Fuse on OpenShift

After you have implemented the Apache Camel transformation using Fuse on OpenShift, you can use the 3scale Admin Portal to configure it as a policy extension in the APIcast policy chain.

The policy extension enables you to configure a 3scale service to use a Camel HTTP proxy. This service is used to send the 3scale traffic over the HTTP proxy to perform request–response modifications in a third-party proxy. In this case, the third-party proxy is Apache Camel implemented using Fuse on OpenShift. You can also configure APIcast to connect to the Camel HTTP proxy service securely using TLS.

Note

The policy extension code is implemented in an Apache Camel application in Fuse on OpenShift and cannot be modified or deleted from 3scale.

Prerequisites

Procedure

  1. In the 3scale Admin Portal, select Integration > Policies.
  2. Select POLICIES > Add policy > Camel Service.
  3. Enter the OpenShift routes used to connect to the Camel HTTP proxy service in the appropriate fields:

    • https_proxy: Connect to the Camel HTTP proxy using the http protocol and TLS port, for example:

      http://camel-proxy.my-3scale-management-project.svc:8443
    • http_proxy: Connect to the Camel HTTP proxy using the http protocol and port, for example:

      http://camel-proxy.my-3scale-management-project.svc:8080
    • all_proxy: Connect to the Camel HTTP proxy using the http protocol and port when the protocol is not specified, for example:

      http://camel-proxy.my-3scale-management-project.svc:8080
  4. Promote the updated policy configuration to your staging or production environment. For example, click Promote v. 3 to Staging APIcast.
  5. Test the APIcast policy configuration using a 3scale curl command, for example:

    curl "https://testapi-3scale-apicast-staging.myuser.app.dev.3sca.net:443/?user_key=MY_USER_KEY" -k

    APIcast establishes a new TLS session for the connection to the Camel HTTP proxy.

  6. Confirm that the message content has been transformed, which in this example means converted to uppercase.
  7. If you wish to bypass APIcast and test the Camel HTTP proxy directly using TLS, you must use a custom HTTP client. For example, you can use the netcat command:

    $ print "GET https://mybackend.example.com HTTP/1.1\nHost: mybackend.example.com\nAccept: */*\n\n" | ncat --no-shutdown --ssl my-camel-proxy 8443

    This example creates an HTTP proxy request using the full URL after GET, and uses the ncat --ssl parameter to specify a TLS connection to the my-camel-proxy host on port 8443.

    Note

    You cannot use curl or other common HTTP clients to test the Camel HTTP proxy directly because the proxy does not support HTTP tunneling using the CONNECT method. When using HTTP tunneling with CONNECT, the transport is end-to-end encrypted, which does not allow the Camel HTTP proxy to mediate the payload.