Authors: Embar Rangarajan, Narayanan (firstname.lastname@example.org)
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
- Inter-component & Cluster configurations
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
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.
Complete below prerequisites to get into the details of configuring API Gateway from Command Central.
- Install Command Central of version 10.5 and above
This tutorial will guide the user to do the following.
- Install API Gateway and apply fixes using Command Central
- Manage API Gateway Data Store
- Manage Product Configurations
- 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.
- Using Command Central UI
- 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.
- Add credentials to Command Central for connecting to server
- Add repository where products are available
- Add required license key to install API Gateway
- Add API Gateway installation template in command central
- Apply template. This will install API Gateway. (Template contains API Gateway related details)
- 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 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
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
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
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
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.
This section enables user to configure different types of ports available in API Gateway. Below ports are supported
- 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 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
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
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 +
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.
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
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
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.
- For now (till 10.5), Command Central support is limited only to a few aforementioned product configurations
- 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
- 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
- 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
- For details on starting API Gateway using externalized configurations, refer Starting API Gateway using externalized configurations