Skip to content

Latest commit

 

History

History
471 lines (362 loc) · 13.1 KB

_usage.adoc

File metadata and controls

471 lines (362 loc) · 13.1 KB

Usage

Setup Environment

Install Axway Tools

The Maven Plugin for API Gateway requires the installation of the Package & Deployment Tools of the Axway API Gateway. If you want to edit the projects PolicyStudio has to be installed also. Please checkout the Axway documentation on how to install the software.

It is recommended to install the tools under the same directory. This directory is used by the plugin as the Axway Home directory.

[folder] axway-home
  [folder] apigateway
  [folder] policystudio

Configure Plugin

It is required to configure the Axway Home directory by specifying the property axway.home. Due to the location is individual for each developer, configure the property in your personal ~/.m2/settings.xml file.

~/.m2/settings.xml
<settings
  xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"
>
	<profiles>
		<profile>
			<id>axway</id>
			<activation>
				<activeByDefault>true</activeByDefault>
			</activation>
			<properties>
				<axway.home>c:/axway</axway.home> <!--(1)-->
			</properties>
		</profile>
	</profiles>
	<activeProfiles>
		<activeProfile>axway</activeProfile>
	</activeProfiles>
</settings>

  1. Specify the location of your Axway installation here.

Alternatively the Axway home directory can be specified via the -D option of Maven command:

$ mvn -Daxway.home=c:/axway package

Create Project

To setup a new API Gateway project, create an empty folder and create a Maven pom.xml file. Set the desired packaging type and add the API Gateway plugin (see below).

Following packaging types are supported:

  • axway-policy-archive

  • axway-server-archive

  • axway-deployment-archive

pom.xml
<project
  xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
>
  <!-- ... -->
  <packaging>axway-policy-archive</packaging> <!--(1)-->

  <build>
    <plugins>
      <plugin> <!--(2)-->
        <groupId>com.axway.maven.plugins</groupId>
        <artifactId>apigw-maven-plugin</artifactId>
        <version>{mvn-plugin-ver}</version>
        <extensions>true</extensions>
      </plugin>
    </plugins>
  </build>
 </project>

  1. The packing type axway-policy-archive marks it as a policy project. Other packaging types available.

  2. Use Maven Plugin for API Gateway for this project.

To initialize the project invoke the following command in your project directory:

$ mvn apigw:init

According to your packaging type the project is initialized with a default directory structure and a default project template.

If your project requires policies from other project, add the according dependencies to your pom.xml file.

pom.xml
<dependencies>
  <dependency> <!--(1)-->
    <groupId>com.example</groupId>
    <artifactId>common</artifactId>
    <version>1.0.0</version>
    <type>axway-policy-archive</type> <!--(2)-->
  </dependency>
</dependencies>

  1. Add the dependency.

  2. Set the packaging type of the dependent artifact.

Edit Project

To edit the project just invoke the goal apigw:policystudio.

$ mvn apigw:policystudio
📎

If PolicyStudio is started the first time in the project directory it has to be initialized first.

In this case you will be prompted to close PolicyStudio right after startup. So, just close PolicyStudio and invoke the Maven goal apigw:policystudio again. You have to do this only once.

This will download all dependent projects, configure the dependencies and will start PolicyStudio. For convenience the recently used projects are preset to your project. So just click on the links.

To ensure that the latest version of dependent projects are used use the apigw:policystudio goal in combination with the clean goal.

$ mvn clean apigw:policystudio
📎

As Deployment Projects don’t have policies to be edited, the goal is not supported for projects of packaging type axway-deployment-archive.

Package & Install Project

Cleanup

All artifacts and temporarily files are generated in the target folder. Use the goal clean to delete the target folder and to cleanup all generated artifacts.

$ mvn clean

Build Project Artifact

To build the project artifacts use the package goal.

$ mvn clean package

This will build the projects archives (policy archive, server archive or deployment archive) depending on the project type.

Install Artifact

To install the generated project archive to the local Maven repository use the install goal.

$ mvn clean install

To deploy the generated project archive to the remote repository use the deploy goal.

$ mvn clean deploy

Deploy Project to API Gateway

To install the project to a gateway instance the goal apigw:deploy is used. It only supports a standard deployment. Deployment of static files or JARs are not supported.

For deployment following properties are used:

Property Description Mandatory

axway.anm.host

Host of the Admin Node Manager.

yes

axway.anm.port

Port of the Admin Node Manager (default: 8090).

no

axway.anm.user

User to connect to the Admin Node Manager (default: admin).

no

axway.anm.password

Password of the user.

yes

axway.deploy.group

Name of the group the project is deployed to.

yes

axway.passphrase.pol

Passphrase for .pol and .env packages.

no

axway.passphrase.fed

Passphrase for .fed packages.

no

axway.passphrase.deploy

Passphrase for deployment group.

no

axway.config.envs

Path to environmentalized fields configuration file.

yes

axway.config.certs

Path to certificates configuration file.

no

axway.config.props

Path to properties configuration file.

no

axway.config.props.files

Comma separated list of paths to properties configuration files.

no

axway.config.secrets.file

Path to secrets file.

no

axway.config.secrets.key

Path to key file to decrypt/encrypt values of secrets file.

yes, if secrets file is specified

Example:

$ mvn -Daxway.anm.host=localhost -Daxway.anm.password=changeme -Daxway.deploy.group=test -Daxway.config.envs=gateway.config.json clean apigw:deploy

Policy Projects

For policy projects the test server which is included in the project is deployed.

Steps:

  1. Execute package lifecycle.

  2. Build .pol and .env packages.

  3. Build and configure .fed package.

  4. Deploy .fed package to gateway

Server Projects

For server projects the generated .pol and .env packages are deployed.

Steps:

  1. Execute package lifecycle.

  2. Build and configure .fed package from .pol and .env packages.

  3. Deploy .fed package to gateway

Deployment Projects

For deployment projects the .fed package of the generated artifact is deployed.

Steps:

  1. Execute package lifecycle.

  2. Deploy .fed package to gateway

Configuration Files

The location of configuration files can be specified via the <configuration> element of the plugin or via Maven properties or via the -D parameter of the Maven command line.

Environmentalized Fields

pom.xml
<!- ... ->
<plugin>
  <groupId>com.axway.maven.plugins</groupId>
  <artifactId>apigw-maven-plugin</artifactId>
  <version>{mvn-plugin-ver}</version>
  <extensions>true</extensions>
  <configuration>
    <configConfigFile>${basedir}/src/main/axwgw/gateway.config.json</configConfigFile> <!--(1)-->
  </configuration>
</plugin>
<!- ... ->

  1. Location of the configuration file for environmentalized fields.

Command Line
$ mvn package -Daxway.config.envs=gateway.config.json

Certificates

pom.xml
<!- ... ->
<plugin>
  <groupId>com.axway.maven.plugins</groupId>
  <artifactId>apigw-maven-plugin</artifactId>
  <version>{mvn-plugin-ver}</version>
  <extensions>true</extensions>
  <configuration>
    <configCertsFile>${basedir}/src/main/axwgw/gateway.certs.json</configCertsFile> <!--(1)-->
  </configuration>
</plugin>
<!- ... ->

  1. Location of the configuration file for certificates.

Command Line
$ mvn package -Daxway.config.certs=gateway.certs.json

Configure Properties

The Maven plugin supports three options to specify configuration properties:

  1. Embedded in the configuration files for environmentalized fields or for certificates.

  2. Via a configuration file specified by the property axway.config.props or via the <configPropertyFile> element in the <configuration> element of the plugin. This is the master configuration file.

  3. Via configuration files specified by the <configPropertyFiles> element in the <configuration> element of the plugin.

  4. Via configuration files specified by a comma separated list of the property axway.config.props.files. These are called the additionally configuration files.

Properties are read in the order listed above. If a property exists in multiple configuration files the value of the latest configuration file is used.

For deployment projects, the location of the mandatory configuration file for environmentalized fields is implicitly set to ${basedir}/src/main/axwgw/gateway.config.json. The file will be created during the initialization of the project (goal apigw:init).

The location of the configuration files can be specified in the <configuration> element of the plugin (see below) or can be passed via the command line.

Examples:

pom.xml
<!- ... ->
<plugin>
  <groupId>com.axway.maven.plugins</groupId>
  <artifactId>apigw-maven-plugin</artifactId>
  <version>{mvn-plugin-ver}</version>
  <extensions>true</extensions>
  <configuration>
    <configPropertyFile>${basedir}/gateway.prop.json</configPropertyFile> <!--(1)-->
    <configPropertyFiles> <!--(2)-->
      <configPropertyFile>${basedir}/prop-a.json</configPropertyFile>
      <configPropertyFile>${basedir}/prop-b.json</configPropertyFile>
    </configPropertFiles>
  </configuration>
</plugin>
<!- ... ->

  1. Location of a configuration file for properties.

  2. Location of a list of configuration files for properties.

Command Line
$ mvn package -Daxway.config.props=a.json -Daxway.config.props.files=b.json,c.json

Miscellaneous

Standalone Configuration Tools

The plugin includes some Python based scripts to configure environment specific .fed files. The scripts can also be used as standalone tools. The goal apigw:tools extracts the included script to the ${project.build.directory}/tools directory.

Command Line
$ mvn apigw:tools

Encrypt Secrets File

To create an empty secrets file or to add properties to secrets file, the goal apigw:encrypt can be used. A file containing a key is used to initially create the secrets file. The same key file as used to create the file has to be used to decrypt values.

Key File

The key file contains any arbitrary sequence of bytes. It is treated as a binary file.

If you edit this file with a text editor be aware of the encoding and the end of line sequence. In this case use ASCII characters in a single line (no line feed at the end) to prevent any incompatibility with other line end formats or editor encodings.

gateway.crypt.json
{
  "secrets": { (1)
    "__": "3QjoMSfhSelmvMlvcgCdyHf+oTyVnHlyneA3stpN0iQKJ1BUIrY9OA==", (2)
    "my.password": "encrypt:changeme", (3)
  }
}

  1. The secrets property is requried.

  2. Marker to check the passphrase. Don’t delete or change it.

  3. The prefix encrypt: indicates that the value changeme has to be encrypted by the encrypt tool.

Command Line
$ mvn apigw:encrypt -Daxway.config.secrets.file=gateway.crypt.json -Daxway.config.secrets.key=secrets.key

Maven Goals

This section provides a short overview of the goals supported by the Maven plugin.

Table 1. Maven Goals
Goal Description P[1] S[2] D[3]

apigw:init

Initialize the project.

yes

yes

yes

apigw:policystudio

Open PolicyStudio to edit the project.

yes

yes

no

clean

Cleanup all generated artifacts.

yes

yes

yes

package

Build the archive according to the type of the project.

yes

yes

yes

install

Build and install the project archive to the local Maven repository.

yes

yes

yes

deploy

Build and deploy the project archive to the remote Maven repository.

yes

yes

yes

apigw:tools

Extract the scripts of the configuration tools to the target directory.

yes

yes

yes

apigw:deploy

Deploy project to a gateway.

yes

yes

yes

apigw:encrypt

Encrypt plain values of secrets file.

yes

yes

yes
1. Supported by Policy Project
2. Supported by Server Project
3. Supported by Deployment Project