What are intercepts?

Intercepts provide a way to attach ad-hoc routing rules for a service deployed on the TrueFoundry platform. We can use it to redirect traffic arriving at a service to another one on the basis of a header. It can be useful to test a new release for a service by intercepting the traffic on the main service and redirecting it to the the copied service.

Using UI

1. Before intercepts can be enabled for a service, we need to allow intercepts for that service. It can be done by checking Allow intercepts under the service definition. This will trigger a service re-deployment and we will be able to add interception rules.

2. In the service details page, a tab called Intercept Rules will be available now. We can start adding intercept rules here. Multiple such rules can be added here
   
   An intercept rule consists of five inputs -
   1. Port to redirect from - This has to be one of the exposed ports on this service. This rule will apply to traffic arriving at this port
   2. Target service - The service the traffic is to be forwarded. It has to be one of the services in the same cluster
   3. Target service port - The port on the destination service where traffic is to be forwarded to. This has to be one of the exposed ports of that service
   4. Header name - This is the name of the header matching which the traffic is to be forwarded
   5. Header value - Value of the header that the matching which the traffic is to be forwarded
3. To test the intercept you can send a request to the service with the header set to the value in intercept rule and verify that the request indeed lands on the service set as destination. Eg - curl -H "<header name>: <header value>" https://<service endpoint> . If the intercept rules don't match, the request will continue to go to the original service.

How to create intercepts?

Using API

Create an intercept

API: https://docs.truefoundry.com/reference/interceptcreateorupdateintercept

This API call expects a manifest field to be supplied which needs to be of the following format -

{
    "type": "intercept",
  // Name of the service that is being intercepted
  "name": "<service_name>",
  // All the intercepting rules are collated into this array
  "rules": [{
    // The port that the intercept is to be applied to
    "port": <port_number>,
    "match": {
        "type": "header",
      // Name of the header that is to be used for matching
        "name": "<header_name>",
      // Exact value of the header which is to be used for matching
        "exact_match": "<header_value>"
    },
    "action": {
        "type": "forward",
      // URI of the service where the traffic is to be forward.
      // Must be the internal FQDN for a service in the same cluster.
      // The rules for writing the same can be found here - https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services
        "service_uri": "<destination_service_name>.<destination_workspace_name>.svc.cluster.local",
      // Port of the destination which is to be used to receive the forwarded traffic
        "port": <port_number>
    }
  }]
}

This will create and attach an intercept to the application passed in the applicationId field

Getting associated intercept for a service

API: https://docs.truefoundry.com/reference/applicationgetassociatedintercept

This API accepts the application ID for the service for which the intercept is to be fetched. The intercept details can be found under deployment.manifest field.

Getting and deleting intercept details

Getting: https://docs.truefoundry.com/reference/applicationgetapplication

Deleting: https://docs.truefoundry.com/reference/applicationdeleteapplication

Here ID of the intercept received in the previous API can be passed as application ID to get and delete intercept.

📘

A service if associated with an intercept cannot be deleted until the intercept is deleted first