Configuring API Gateway using Command Central

[Clench_Paign_James3 (Clench Paign James)]

Authors: Embar Rangarajan, Narayanan (nae@softwareag.com)
Supported Versions: 10.5 and above (on-premise deployment only)

Overview of the tutorial

This tutorial helps to understand how a Command Central (CC) administrator can configure API Gateway from Command Central. We shall discuss the following in detail.

• Install API Gateway using Command Central
• Update fixes using Command Central
• Manage configurations and life cycle of API Gateway Data Store
• Product configurations of API Gateway
  • General Properties
  • License Keys
  • Loggers
  • Ports
  • Keystores
  • Truststores
• Inter-component & Cluster configurations
  • Elasticsearch
  • Kibana
  • Clustering

Required knowledge

This tutorial assumes the reader has

• a working knowledge of Command Central as a product
• a working knowledge of Command Central Templates
• a basic understanding of API Gateway as a product
• a basic understanding of API Gateway administrator configurations

Why?

Command Central is a centralized place where the administrator can configure multiple Software AG products at a time.  When the user installs API Gateway using Command Central, API Gateway and API Gateway Data Store are installed. API Gateway communicates with this API Gateway Data store by default. This feature helps the administrators to make API Gateway to use an external data store (Elasticsearch) to store its core data and analytics, configure external Kibana, in addition to managing the product configurations such as Ports, Keystores, Truststores, Loggers, License Keys, General Properties and Clustering. 

Prerequisite steps

Complete below prerequisites to get into the details of configuring API Gateway from Command Central.

• Install Command Central of version 10.5 and above

Details

This tutorial will guide the user to do the following.

1. Install API Gateway and apply fixes using Command Central
2. Manage API Gateway Data Store
3. Manage Product Configurations
4. Manage Inter-component and Cluster configurations

Install API Gateway & apply fixes using Command Central

There are two ways of installing API Gateway using Command Central.

1. Using Command Central UI
2. Using Command Central Templates

Installation of API Gateway using Command Central templates is discussed here. Sequence of steps to install API Gateway using templates as follows.

1. Add credentials to Command Central for connecting to server
2. Add repository where products are available
3. Add required license key to install API Gateway
4. Add API Gateway installation template in command central
5. Apply template. This will install API Gateway. (Template contains API Gateway related details)
6. For applying fix,
   • Add SUM related credential similar to Step 1
   • Add fix repository
   • Add fix template similar to installation template
   • Apply template

Installation & fix applying - Detailed Steps

• Credentials are required for connecting to SAG server. Usually this is maintained in an xml file. credentials_installer.xml
  • sagcc create configuration data local OSGI-CCE-ENGINE COMMON-CREDENTIALS -i credentials_installer.xml

• The repository should be added so that products can be installed from the repo. Same can be done using the command,
  • sagcc add repository products master name=webMethods-10.5 location=<repository url> credentials=SAGCONNECT description="10.5 repository"
  • credentials=SAGCONNECT. This is the alias for the credentials created in previous step. Open credentials_installer.xml and you can find the alias.

• Once repository is added, license required for API Gateway should be added to Command Central. With a valid license file, this can be added as
  • sagcc add license-tools keys apigateway_license -i license_apigateway.xml
  • apigateway_license is the license name that command central refers to this xml file

• Next step is to add template for installing API Gateway. Here is a sample template.yaml. This contains API Gateway with configurable values. Same can be found here at GitHub.
  • sagcc exec templates composite import -i sag-apigateway-server-trunk/template.yaml
  • This imports the template required for installing API Gateway.

• Now apply the template imported in above step. This will install API Gateway with values mentioned in the template.
  • sagcc exec templates composite apply sag-apigateway-server nodes=local is.instance.type=integrationServer agw.memory.max=512 repo.product=webMethods-10.5 os.platform=W64  agw.key.license=apigateway_license.
  • This install  API Gateway on mentioned node. In this case, its the local machine.

• In case of fix installation,
  • sagcc create configuration data local OSGI-CCE-ENGINE COMMON-CREDENTIALS -i credentials_fixes.xml. This is for connecting to fix repository.
  • sagcc add repository fixes master name=GA_Fix_Repo location=<Fix repo location> credentials=EMPOWER description="105 GA fix repo"
  • sagcc exec templates composite import -i sag-apigateway-server-qa-fix/template.yaml . template.yaml
  • sagcc exec templates composite apply sag-apigateway-server-fix nodes=local is.instance.type=integrationServer agw.memory.max=512 repo.product=webMethods-10.5 os.platform=W64  agw.key.license=apigateway_license is.instance.type=integrationServer repo.fix=GA_Fix_Repo

Now that API Gateway is installed,  API Gateway is listed in Command Central UI.

API Gateway product layout in Command Central

In Command Central, API Gateway is organized as follows

API Gateway | API Gateway Data Store  contains details about default Elasticsearch shipped with API Gateway.

IS_<profile> contains details about API Gateway, Digital Event Services, Event Routing, Integration Server.

Manage API Gateway Data Store

Command Central lists API Gateway and API Gateway Data Store shipped with API Gateway. API Gateway stores all its core and analytics data in this Data Store by default. API Gateway Data Store can be started, stopped and restarted as shown below. Clustering details, Keystores, Ports, Properties, and Truststores can also be managed.

Ports

Ports used for API Gateway Data Store are displayed in this section. No new ports can be added. Only existing ports can be edited.

Click one of these Ports and API Gateway Data Store ports can be edited.

Configure Ports using Template

Here are the commands to configure Ports using template.

• sagcc exec templates composite import -i ports.yaml (ports.yaml)
• sagcc exec templates composite apply sag-apigw-datastore-port nodes=local port.alias=port_alias port.number=port_number

Keystore

This section lists available Keystores. No new Keystores can be added but existing ones can be edited.

Configure Keystores using Template

Here are the commands to configure Keystores using template.

• sagcc exec templates composite import -i keystores.yaml (keystores.yml)
• sagcc exec templates composite apply sag-apigw-datastore-keystore nodes=local keystore.location=location_of_keystore keystore.password=password

Trust stores

This section lists available Truststores. Existing truststores can be edited.

Configure Truststores using Template

Here are the commands to configure Truststores using template.

• sagcc exec templates composite import -i truststores.yaml (truststores.yaml)
• sagcc exec templates composite apply sag-apigw-datastore-truststore nodes=local truststore.location=location_of_truststore truststore.password=password

Properties

This section lists properties maintained in elasticsearch.yml file. Properties can be edited and the same will be saved to elasticsearch.yml file that API Gateway Data Store uses.

Configure Properties using Template

Here are the commands to configure properties using template.

sagcc exec templates composite import -i properties.yaml (properties.yaml)
sagcc exec templates composite apply sag-apigw-datastore-properties nodes=local

Clustering

This section lists clustering configuration and can be edited for Elasticsearch to a cluster.

Configure Clustering using Template

Here are the commands to configure clustering details using template.

• sagcc exec templates composite import -i clustering.yaml (clustering.yaml)
• sagcc exec templates composite apply sag-apigw-datastore-clustering nodes=local  node.name=node_name node.host=node_host node.port=node_port

What are new in release 10.5?

With this release, users can use external Elasticsearch and configure API Gateway to communicate with that Elasticsearch. Once API Gateway is installed using Command Central, it lists installed Integration Server instances as shown in the below image. The image shows the IS instance apigateway with the name IS_apigateway. Under IS_apigateway, Users can configure external Elasticsearch details, external Kibana details, configure API Gateway product configurations such as General Properties, Clustering details, Loggers, License Keys, etc.

Manage Product Configurations

This section explains how to manage product configurations of API Gateway using Command Central.

Ports

This section enables user to configure different types of ports available in API Gateway. Below ports are supported

• HTTP
• HTTPS
• WebSocket
• API Gateway External Port
• API Gateway Internal Port

Creating a HTTP Port

Create a HTTP Port. Choose Enable as Yes to enable the port after creation. Provide a valid Port and Alias for the port. Provide other details as applicable.

Note the port is created and enabled.

Creating a HTTPS Port

Provide valid details for https port. You will see previously added Keystore and Truststore. Choose desired Keystore and Truststore.

Similarly, WebSocket, API Gateway External, API Gateway Internal ports can be configured.

Configure Ports using Template

Here are the commands to configure a HTTP port using template

• sagcc exec templates composite import -i httpPort.yaml (httpPort.yaml)
• sagcc exec templates composite apply httpPortAlias

Keystores Configuration

Keystores configuration contains list of Keystores available in API Gateway. New Keystores can be added or existing Keystores can be deleted. This page lists all Keystores added in the API Gateway. Add a Keystore from this page by clicking + on right side.

Provide an alias for Keystore. Provide Keystore Type, Provider, Location of the Keystore. This should be the absolute path of Keystore. And provide valid Keystore password.

Once Keystore is added, It will show newly added Keystore in this list.

Configure Keystores using Template

Here are the commands to configure a keystore using template

• sagcc exec templates composite import -i keystore.yaml (keystore.yaml)
• sagcc exec templates composite apply keyStoreAlias nodes=local keystore.path=youekeystorepath keystore.password=keystorepassword key.alias=keyAlias key.password=keyPassword

Truststores

Adding a Truststore is similar to adding a Keystore.

Configure Truststores using Template

Here are the commands to configure a Truststore using template

• sagcc exec templates composite import -i truststore.yaml (trustStore.yaml)
• sagcc exec templates composite apply trustStoreAlias nodes=local truststore.location=trustStoreLocation truststore.password=trustStorePassword

License Keys

This section lists available licenses to be used for APIGateway. This is a read only section in command central.

To add or remove license used by different products in command central, click license tab.

This page now lists all licenses. To add a new license, click +

General Properties

This section contains Extended settings and Watt settings that can be configured for the API Gateway.

Extended settings can be changed in this section. The properties are listed as key value pairs. Once saved, changes are effective immediately.

Watt settings can be changed in this section. The properties are listed as key value pairs. Once saved, changes are effective immediately.

Loggers

This section shows all the available components and  various log levels for each of these sections. This page lists  components and their corresponding log levels.

Log level can be changed from the drop. Log level for API Gateway is set to debug from info in the dropdown.

Manage Inter-component & Cluster configurations

This section explains about configuring external Elasticsearch, external Kibana and  Clustering details from Command Central. With this release, Users can use external Elasticsearch, external Kibana and configure API Gateway to communicate with these components. Prior to this release, API Gateway can communicate to this Internal Data Store alone.

External Elasticsearch configuration

This section helps to configure internal or external Elasticsearch for API Gateway. Choose Elasticsearch from the drop-down.

Provide Tenant name. Choose Auto start as No, if you are configuring External Elasticsearch.

The transport section contains Host and Port where the Elasticsearch is running. If Auto start is Yes, leave the default. In case of external Elasticsearch, change the details accordingly.

If the Elasticsearch is protected with basic auth, provide the details in this section.

If the Elasticsearch is protected with https, Enable SSL. Provide valid Keystore and Truststore details.

Provide additional configurations that defines the API Gateway's connectivity to Elasticsearch.

Once done. Click Save. Now Pending restart is changed to true. Restart API Gateway and changes will be effective.

With this release, a new section API Gateway is added  under IS instance  where all the above-stated configurations can be made.

Now you will see a list of API Gateway configurations that can be set or modified from Command Central UI.

Configure External Elastic Search Using Template

Here is the command to configure external elastic search using templates.

• sagcc exec templates composite import -i cc-minimal-es.yaml (cc-minimal-es.yaml)
• sagcc exec templates composite apply cc-minimal-es nodes=local ssl_username=username ssl_password=password eshost=eshost esport=esport keystore_location=your_keystore_location keystore_alias=alias_of_keystore truststore_location=your_truststore_location truststorealias=your_truststore_alias truststore_password=truststorepassword

Kibana Configuration

This section helps to configure Kibana for API Gateway. Either internal Kibana can be used or external  Kibana can be configured. In case of external Kibana, Autostart should be No.

Select Kibana from dropdown to configure Kibana details.

Edit Kibana. Choose Auto start as No for external Kibana.

Once saved, Pending restart is true which requires API Gateway restart for the changes to be effective.

Configure External Kibana using Template

Here are the commands to configure external kibana using template

• sagcc exec templates composite import -i cc-kibana.yaml (cc-kibana.yaml)
• sagcc exec templates composite apply cc-kibana nodes=local host=hostname port=portnumber

Clustering Configuration

Administrator can configure cluster details for the API Gateway in API Gateway section. In order to cluster API Gateway, Terracotta server should be running. Click Configuration to view various configurations.

Please note, you have to configure Elasticsearch clustering independently. This section covers only API Gateway clustering. For more details on clustering refer to API Gateway High Availability and Sizing.

Select API Gateway under the instance IS_apigateway and select Clustering from drop down.

This page shows initial clustering details. Status is Disabled since it has not yet been clustered. Pending restart is false. Once changes are made, this will change to true as it requires a restart.

Click Disabled to configure clustering details. Edit to configure.

Select Enabled to enable clustering for API Gateway. Provide Cluster name of the desired choice. Add Terracotta server host and port details where Terracotta server is up and running. Provide additional details as required and Save.

 Now that Pending restart is true and Status as Enabled, API Gateway should be restarted for the changes to be effective.

Once  API Gateway is restarted, the values are updated in API Gateway. Same can be seen in API Gateway also.

Configure Clustering details using Template

Here are the commands to configure clustering using template.

• sagcc exec templates composite import -i cc-clustering.yaml (cc-clustering.yaml)
• sagcc exec templates composite apply commandcentral-clustering-alias nodes=local tchost=terracotta_host tcport=terracotta_port

How these configurations work?

Once these configurations are edited and saved, a special file called cc-config.yml is created under <InstallationDirectory>/IntegrationServer/instances/apigateway/packages/WmAPIGateway/resources/configuration. Once API Gateway is restarted , settings from this file will be applied. This cc-config.yml is referred in <InstallationDirectory>/IntegrationServer/instances/apigateway/packages/WmAPIGateway/resources/configuration/config-sources.yml. On first-time installation and when nothing has been configured, cc-config.yml file will not be present. In this case Elasticsearch, Clustering and Kibana configurations are fetched from the internal data store. Whereas product configurations are always fetched from internal datastore. Once configurations are edited in command central, values will be written to cc-config.yml. Subsequent restarts will be using these values. If internal datastore is down, still configurations can be done in command central.

Limitations

• For now (till 10.5), Command Central support is limited only to a few aforementioned product configurations

Troubleshooting

• If external Elasticsearch is used, make sure ES is running before API Gateway is installed
• For Clustering, make sure Terracotta server is running and es nodes are clustered
• If external Kibana is used, make sure Kibana server is started before API Gateway is started

References

• Follow this github link to install API Gateway using command central with templates -  https://github.com/SoftwareAG/sagdevops-templates/tree/master/templates/sag-apigateway-server
• Secure Elasticsearch using search guard plugin - https://docs.search-guard.com/latest/demo-installer

Downloadable artifacts

• Elasticsearch 7.2 download: https://www.elastic.co/downloads/past-releases/elasticsearch-7-2-0
• Kibana 7.2 download: https://www.elastic.co/downloads/past-releases/kibana-7-2-0

Learn more

• For details on starting API Gateway using externalized configurations, refer Starting API Gateway using externalized configurations

cc-clustering.yaml (862 Bytes)

cc-kibana.yaml (618 Bytes)

cc-minimal-es.yaml (1.92 KB)

clustering.yaml (916 Bytes)

credentials_installer.xml (284 Bytes)

httpPort.yaml (1.97 KB)

keystore.yaml (4.04 KB)

keystores.yml (757 Bytes)

ports.yaml (741 Bytes)

properties.yaml (1.28 KB)

template.yaml (2.99 KB)

trustStore.yaml (61.3 KB)

truststores.yaml (781 Bytes)