Runtime Policies in CentraSite and API Gateway
Introduction
CentraSite is a tool for API management and especially supports the whole service's lifecycle. Such a service lifecycle starts with an idea for a service and then passes through coordination and design phases. At some point in time, the service is deployed to one or more enforcement points. Later stages cover service versioning and updates as well as obtaining statistics concerning the service usage. CentraSite also offers the opportunity to define runtime policies upon the services. Such runtime policies cover topics as security restrictions, authentication, and logging. When deploying the service to some enforcement point, the runtime policies may be transmitted also, in order to enable the enforcement point to run the service in coherence with the runtime policies specified. For a long time the preferred enforcement point for CentraSite was the Mediator.
With API Gateway as enforcement point, however, the definition of runtime policies is also possible at the enforcement point itself. This is even supposed to become the preferred way of dealing with runtime policies. In fact, with the most recent version of CentraSite (10.4) the definition of runtime policies in CentraSite is switched off per default.
CentraSite and Mediator
Up to version 9.10, released April, 2016, CentraSite's main enforcement point was the Mediator. The following uses CentraSite and Mediator in version 9.12, released October, 2016. Both CentraSite and the Mediator are installed using the SoftwareAG Installer. In the Installer, the Mediator is listed below the Integration Server (IS) entry.
Having installed Mediator, the underlying IS must be started via 'All Programs' > 'Software AG' > 'Start Servers' > 'Start Integration Server' > 'Start default'. Start as an administrator. The IS takes some time to get up. Afterwards, go to the Mediator Console via 'All Programs' > 'Software AG' > 'Start Administration' > 'Integration Server Administrator' > 'default'. This opens the IS console. It is also possible to go to the IS Administrator from a browser window by the URL 'http://localhost:5555'.
From the IS console, the Mediator console is available under 'Solutions' > 'Mediator'.
CentraSite needs to know about the Mediator instances it intends to deploy its services to. These settings are established from the CentraSite Business User Interface (BUI). Start the BUI via 'All Programs' > 'Software AG' > 'Tools' > 'CentraSite Business User Interface', or direct your browser to 'http://localhost:53307/BusinessUI'.
From the BUI main menu choose 'Manage Governance Rules' and there click on the 'Add Gateway' icon. From the 'Gateway' drop-down box choose 'Mediator'. Give a name to the gateway to be created, for example 'Mediator'. Specify under which credentials Mediator connects to CentraSite (Administrator/manage should do), provide the IS endpoint (http://localhost:5555), and specify how CentraSite connects to Mediator (for example, check the 'Use CentraSite credentials' box). Press 'Publish' to save the new 'Mediator' gateway.
Note that in older versions of CentraSite, Mediator targets have to be created via CentraSite Control; choose 'Operations' > 'Targets' from the Control main menu.
Now having introduced the Mediator instance to CentraSite, services can be deployed to this enforcement point. When going to the detail view of a Service asset for which CentraSite also contains the WSDL, the service can be virtualized and subsequently published to the Mediator. During the virtualization step, the BUI exhibits a screen allowing the selection of runtime policies the service should be later on deployed with.
To enforce a service invocation to be logged, for example, open the 'Policy Enforcement' tab on the left, explore the section on 'Logging and Monitoring', and drag the 'Log Invocation' entry into the 'Enforce' box on the right.
Having virtualized and deployed the service, the new offering can be viewed in the Mediator console. Choose 'Services' on the left.
Following the service's name, there are two links namely [VSD] and [WSDL]. Whereas the WSDL link exhibits the service's WSDL as it was taken from CentraSite, the VSD link leads to a so-called Virtual Service Description, a WSDL that also includes policy specifications.
The VSD excerpt shows the manifestation of a runtime policy that states that service invocations are to be logged and the logs should be directed towards the CentraSite data storage which was the default storage media in 9.12.
This means that service calls are registered in CentraSite and are thus visible for example in the Virtual Services's detail view (under 'Runtime Events') and in the respective predefined reports (Run-Time Asset Usage, among others). Note that with older versions of Mediator this might require configuration adjustments in the Mediator's 'CentraSite Communication' section.
Runtime Policies in API Gateway
The first release of API Gateway was version 9.12, October 2016. For some time, the new API Gateway and the Mediator existed in parallel the last mediator release being 10.1 (October 2017). For the following observations, we take the most recent API Gateway release namely 10.4 being released April, 2019.
Different from the Mediator, API Gateway has its own top-level entry in the SoftwareAG Installer. This top-level entry contains three sub-entries. When choosing the 'API Gateway 10.4' sub-entry, 'Data Store 10.4' is selected also. This means that the API Gateway works based on the IS whereas the other option, 'Microgateway 10.4', would use a different mechanism. For our purposes herein we choose the suggested 'Data Store 10.4' option which, for those parts of the API Gateway capabilities that were there in Mediator already, the functionality we get is roughly similar.
Somewhere later during the installation procedure, we are asked to utilize the IS' own internal database or an external one. We choose the suggested option (internal DB).
Having installed API Gateway based on IS, the underlying IS must be started via 'All Programs' > 'Software AG' > 'Start Servers' > 'Start Integration Server' > 'Start default'. Start as an administrator. The IS takes some time to get up. In addition to the IS command window, another one for Elasticsearch appears. Afterwards, go to the API Gateway Console via 'All Programs' > 'Software AG' > 'Start Administration' > 'Integration Server Administrator' > 'default'. This opens the IS console. It is also possible to go to the IS Administrator from a browser window by the URL 'http://localhost:5555'.
From the IS console, the API Gateway console is available under 'Solutions' > 'API Gateway'.
CentraSite needs to know about the API Gateway instances it intends to deploy its services to. These settings are established from the CentraSite Business User Interface (BUI). Start the BUI via 'All Programs' > 'Software AG' > 'Tools' > 'CentraSite Business User Interface', or direct your browser to http://localhost:53307/BusinessUI.
From the BUI main menu choose 'Governance Rules' and there click on the 'Add Gateway' icon. From the 'Gateway' drop-down box choose 'API Gateway'. Give a name to the gateway to be created, for example 'API Gateway 1'. Specify under which credentials API Gateway connects to CentraSite (Administrator/manage should do), provide the IS endpoint (http://localhost:5555), and specify how CentraSite connects to API Gateway (for example, check the 'Use CentraSite credentials' box). Press 'Publish' to save the new 'API Gateway' gateway.
Now having introduced the API Gateway instance to CentraSite, services can be deployed to this enforcement point. When going to the detail view of a Service asset for which CentraSite also contains the WSDL, the service can be virtualized and subsequently published to the API Gateway. During the virtualization step, the BUI no longer exhibits a screen allowing the selection of runtime policies the service should be later on deployed with. However, the functionality to define runtime policies has not been dropped from CentraSite, but is now switched off per default.
When publishing the service to API Gateway after such a policy-less virtualization step, CentraSite issues a warning that no runtime policies are included in the deployment.
Policies can now be defined using API Gateway. In the API Gateway console choose "APIs" in the top-menu. From the listed APIs choose the just deployed service and again from the detail view's top-level menu "Policies". On the left choose "Traffic Monitoring". Click the "Edit" button. to enable changing policies. A warning appears telling us that policy amendments when applied upon a running service become effective at once. Hover over the entry "Log Invocation" below "Traffic Monitoring" and click the small plus sign that appears. This adds a respective policy to the policy properties editor on the right. Choose "CentraSite" as the destination for log entries.
Press "Save" to make the policy effective.
API Gateway, but Runtime Policies still in CentraSite
As mentioned previously, the functionality to define runtime policies has not been dropped from CentraSite, but is now switched off per default. A selection screen for runtime policies can be obtained still by adjusting the CentraSite configuration. In the CentraSite configuration file centrasite.xml under the install-dir's CentraSite\cast\cswebapps\BusinessUI\custom\conf folder.
Uncomment the last line and set the "RuntimeComponentSetting" element's attribute "enabled" to true. The CentraSite runtime needs to be restarted to make the configuration changes effective.
If virtualizing the service now with the additional policies screen, policies as the log invocation policy can be selected. Subsequently publishing it, no warning about ignoring the policies is given and, indeed, the policies are copied to API Gateway.
In the API Gateway console choose "APIs" in the top menu. From the listed APIs choose the just deployed service and again from the detail view's top-level menu "Policies". On the left choose "Traffic Monitoring" or click on the respective box in the picture. The policy properties editor on the right shows the property copied from CentraSite and already effective with the deployed service.
Viewing Runtime Data
Independent of the way we chose to define the policy, in the end all invocations of the service are logged and the log entries can be stored as specified. One option is to store these in CentraSite. In this case, the easiest way of checking the invocations is from the Virtual Service's detail view in the CentraSite Business UI. Choose "Runtime Events" on the left, specify "API Gateway 1", "Last 1 hour", "1h" as selection criteria, and press "Refine".
CentraSite offers additional means to view runtime data, among others using predefined or custom reports.