Apigee - On Prem deployment

Apigee is a platform for developing and managing APIs. By fronting services with a proxy layer, Apigee provides an abstraction for your backend service APIs and provides security, rate limiting, quotas, analytics, and more. Traceable provides a JavaScript (JS) policy to capture request and response passing through your Apigee deployment to detect any anomalous behavior or attacks. The following deployment diagram shows a high-level architecture of traffic flow through Apigee and Traceable agent. Traceable's policy captures the incoming request and makes an asynchronous call to Traceable's platform.

Before you begin

Make a note of the following points before you begin with the deployment:

• The document expects a basic working knowledge of Apigee environment.
• Traceable supports Apigee private cloud v4.51.00.
• Make sure that Traceable platform agent is already deployed on a VM that is accessible from the Apigee environment. For more information, see Virtual Machine.
• Make a note of the IP address of the Traceable platform agent. This would be used in Traceable policy configuration.
• Make sure that port numbers 5442 (HTTP) and 5443 (HTTPS) are available for receiving data on Traceable platform agent.

Download

Download the Traceable policy for Apigee from Traceable's download site. Navigate to agent > apigee > latest to download the traceable-shareflow.zip file. Save the file. This file would be used in the Configuration section.

Configuration

The configuration of Traceable policy for Apigee consists of the following two steps:

1. Adding Traceable agent for Apigee as sharedflow
2. Attaching Traceable agent to:
   1. All API proxies using FlowHooks, or
   2. To a specific API proxy only

Step 1 - Add Traceable agent for Apigee as Shared Flow

Complete the following steps to add Traceable's Shared Flow:

1. Login to your Apigee account.
2. Click on Shared Flows from the APIs drop-down menu. The Shared Flows page is displayed.
3. On the Shared Flows page, click on + Shared Flow button to add a new Shared Flow. The Build a Shared Flow page is displayed. 
4. Click on Shared Flow Bundle radio button to add a *.zip archive. Click on the Next button. 
5. Browse to the location where you have saved the Traceable's Shared Flow zip archive file in the Download section. You can give it any name in the Shared Flow Name field. Click on the Next  button. Note that you cannot have two Shared Flows with the same name. 
6. Click on the Build button in the build step. The summary steps shows the successful upload of the Shared Flow.
7. Click on the Shared Flow link to open it in the editor.
8. In the editor window, click on the Develop tab and click on Policies and navigate to TraceableJS policy. The default values for different configurations are already set. You can update the configuration values as per your requirement. The important configuration is ta_reporting_endpoint which is the IP address of the Traceable platform agent. Make sure that the URL is in the same format as in the default value, that is, http://traceable_platform_agent_ip_address:5442
9. Click on Save.
10. Deploy the Shared Flow by clicking on Deployment as shown in the screenshot of step number 8.

Traceable agent configurations

The following table lists the various Traceable agent configurations.

Step 2 - Attach the traceable agent

You can attach the Traceable agent either to all the API proxies or to a specific API proxy. Follow the steps in the one of the following sections. 

Option 1 - Attach Traceable agent to all API proxies using FlowHooks

Complete the following steps to attach Traceable agent to all the API proxies:

1. Click on the APIs drop-down menu and click on Environment Configuration.
2. Click on FlowHooks tab in the Environment Configuration page.
3. Click on Edit button to attach traceable-agent Shared Flow to Pre-proxy Flow Hook and Post-proxy Flow Hook. 
4. Select the traceable-sharedflow from Pre-prxoy and Post-proxy Flow Hook and click on Save.

Option 2 - Attach Traceable agent to a specific API proxy

Complete the following steps to attach Traceable agent to a specific API proxy:

1. Navigate to APIs drop-down menu and click on API Proxies.
2. On the API Proxies page, click on the API proxy to which you want to attach the traceable-agent. 
3. Add the policy- Complete the following steps:
   1. Add a policy by clicking on the + sign next to Policies. 
   2. In the Add Policy pop-up window, navigate to Extension and click on Flow Callout. Update the name and select the Share Flow from the drop-down menu.
   3. Click on Add
4. Choose Proxy Endpoint- Complete the following steps to attach Traceable agent to endpoints:
   1. Click on PreFlow under Proxy Endpoint. 
   2. Click on + Step in the flow diagram for request. The Add Step dialog box is displayed. 
   3.  In the Add Step dialog window, click on Existing Policy Instance.
   4. Select the Flow Callout policy that was added earlier and click on Add.
   5.  Repeat the above steps, 4a to 4d, for response by clicking on PostFlow.
5. Add a Fault Rule in both Proxy Endpoints and Target Endpoints in xml as follows. The Fault Rule makes sure that Traceable policy is executed even in case of any error. Update the name of flow callout policy.
   ActionScript

       <FaultRules>
           <FaultRule name="traceable fault rule">
               <Step>
                   <Name>NAME_OF_TRACEABLE_FLOW_CALLOUT_POLICY_ADDED_ABOVE</Name>
               </Step>
           </FaultRule>
       </FaultRules>

6. Click on Save. Redeploy the policy if it is saved as a new version by clicking on the Deployment button.

Send requests to your API proxy. 

Verification

To verify a successful installation, log into Traceable platform and check whether you are receiving the traces.

Upgrade and uninstall

To upgrade Traceable's policy, first uninstall or delete the current policy and then follow the installation steps. To delete the policy complete the following steps:

1. Navigate to APIs > Shared Flows.
2. Click on the delete button to delete the Shared Flow.
3. If you have attached the Traceable agent, then navigate to detach the agent by selecting none from the Pre-proxy and Post-proxy flow as mentioned in step 4 of Option 1.

Troubleshooting

In Apigee UI, you can go to any API Proxy on which traceable agent is attached, and click on the Traces/Debug tab. Start the trace session, send a request, and check the flow of request and variables in TraceableJS policy on both the request and response side. Verify that ExportSpansJS policy was executed on the Response side (not skipped).
Make sure connection from Apigee to Traceable Platform is proper.