Automation Examples

Simple examples of using automation to install the platform.

Note: Always use the automation recipes for the major product version that you're using.

Table of Contents

Overview

Creating a basic container:

Creating a PM/CM container:

Creating an ND container:

Registering the ND container:

Additional resource information:

Overview:

Automation recipe examples: overview

General notes about the examples included in this document:

  • In these examples, the user home directory is /home/user. Substitute your own directory.
  • In this example, the value for the install directory (INSTALL_DIR property) is /home/user/akana. Substitute your own install directory.
  • You can encrypt passwords. This example does not use encryption.

Creating a basic container:

Creating a basic container: overview

In this example we will create a basic container using automation, at the Linux command line. This example uses a core automation recipe, bootstrap.json. This recipe is also part of many other recipes that perform more complex actions, so it's a good exercise to run it on its own.

The scenario includes:

  1. Downloading and unzipping the installation files
  2. Setting up specific files and properties so that the script will work correctly. This includes:
    • Putting the logging file in place to enable logging.
    • Writing the properties file.
  3. Using the automation script to run a basic recipe to create the container.
  4. Opening the Akana Administration Console user interface for the container in the browser.

Download and extract the installation files

As with any installation, you'll need to download the correct files and unzip them in the correct sequence in your installation directory.

For detailed instructions on downloading and extracting the files, refer to the sections in the installation documentation. For example, for 2020.2.x:

For abbreviated instructions for the specific files used in these examples, see Downloading and extracting the installation files.

The illustration below shows copying the files from another location so that the four files are in the akana directory.

Setting up the files

Put the logging file in place to enable logging

When running a recipe, logging is very helpful to track down problems or monitor the progress of a recipe. The recipe scripts use SLF4J logging, and since no default implementation is shipped with the scripts, it is sometimes necessary to provide one. To deploy a logger implementation, you'd need to copy the file to a location accessible to the automation script.

So, the next step is to copy the slf4j-simple-1.7.19.jar logger file, which is part of the installation, to the $INSTALL_DIR/lib/script folder.

For this example, from the /home/user/akana folder, run the following:

cp lib/ext/slf4j-simple-1.7.19.jar lib/script/

For an example of calling an automation script and using logging, see Registering the ND container: automation script.

Set up the properties file

For this example, we're going to define a few key properties via a properties file, which the automation script will reference.

The filename and location don't matter as long as you reference the file correctly in the automation script. In this example, we're creating a file named bootstrap.properties in the /bin directory.

First, in the /home/user/akana/bin folder, create the properties file. For example:

vi bootstrap.properties

Add the below contents to the file:

INSTALL_DIR=/home/user/akana
CONTAINER_NAME=pm01
DEFAULT_PORT=9900

Save the file.

Note: For information about how you could provide these properties at the command line, see Providing property values at the command line below.

Determining values for properties used in the recipe

The recipes needs certain values, such as the name of your installation directory and the name of the container you're creating.

In a manual installation, you provide these values in the installation wizard user interface. When using a recipe you can provide them:

  1. In a properties file. See the example above.
  2. System properties. Usually passed in at the command line using -D. See Providing property values at the command line.
  3. As environment variables.

In this example of creating a basic container, the values are defined in a properties file.

There are two scenarios for property values:

  • Variables that have no default: if the value is not provided the recipe will fail.

    Examples: INSTALL_DIR, CONTAINER_NAME.

  • Variables that have default values defined in the recipe. If you want to use a different value you'll have to provide it. If not, the default value is used.

    Example: In the bootstrap.json recipe, the default port is defined as 9900 (line 16). In this example of creating a basic container, we explicitly specify port 9900 in the properties file; however, since port 9900 is the default, it isn't really necessary to specify a port.

Run the recipe using the automation script

In this example, the properties file is bootstrap.properties.

Therefore, the script command to run from the /akana/bin folder is:

./jython.sh -Dorg.slf4j.simpleLogger.logFile=System.out -m akana.container --recipe ../recipes/bootstrap.json --props bootstrap.properties

The result of running the automation script is shown below.

Running the script

You can see that the container was successfully created and started, as indicated above.

Run the Akana Administration Console in the browser

You can now access the Akana Administration Console via the browser: {hostname}:{port}/admin/login.html.

Log in, using the default username and password (administrator/password) unless you specified a different username and password.

To verify the container name, after login, go to the System tab. The container name is displayed in the panel header, as shown below. In this example the container name is pm01 (see Set up the properties file above).

Running the Akana Administration Console for the container

You've now created a basic container using automation. This is the equivalent of completing Step 3 in the manual installation instructions (see Step 2-3: Run Configurator to create the first container).

Creating a PM/CM container:

PM/CM container: overview

By following the steps in Creating a basic container above, you'll get some practical experience of running an automation recipe. However, there are no features installed in the basic container.

Now it's time to take it a step further, creating a container with multiple features installed and multiple properties set.

There are these differences in the procedure:

  • You're running a different automation recipe, pm-cm-all.json.
  • Because it's a more complex recipe, you'll need to provide a lot more properties.

You'll also need to have your database set up. Depending on the database type and version you're using, you might also need to put a driver in place and/or modify some database settings first. Refer to these sections of the installation instructions:

Steps for setting up a PM/CM container

The sequence of steps is the same for running any recipe, as described in detail in Creating a basic container above:

  1. Download and extract the installation files (once per installation).
  2. Put the logging file in place to enable logging (once per installation).
  3. Set up the properties file (per recipe). For this example, define the properties listed in Properties file for PM/CM container below.
  4. Run the recipe using the automation script (per recipe). For this example, use the script shown in PM/CM container: automation script below.

Properties file for PM/CM container

In your installation folder, look in the /recipes subfolder at the pm-cm-all.json recipe.

For this example, because the recipe is doing a lot more, you must provide additional properties. To see which properties you need to define for a recipe, just look through the recipe, and any other recipes that it might be referencing.

Because we're going to run several recipes, these examples use the recipe name for the properties file. For the PM container, the recipe is pm-cm-all.json, so the properties file is pm-cm-all.properties. The filename doesn't matter as long as it's correct in the script.

In the /home/user/akana/bin folder, create the properties file. For example:

vi pm-cm-all.properties

In the file, provide values for all the properties referenced by the recipe. An example is shown below.

INSTALL_DIR=/home/user/akana
PRODUCT_HOME=/home/user/akana
CONTAINER_NAME=pmcm01
TENANT_ID=atmosphere
TENANT_NAME=atmosphere
TENANT_HOST=ubu1664qa-17.akana.roguewave.com
TENANT_CONSOLE_HOST=ubu1664qa-17.akana.roguewave.com
TENANT_VHOSTS=ubu1664qa-17.akana.roguewave.com
TENANT_EMAIL=administrator@atmosphere
TENANT_PASSWORD=password
TENANT_THEME=hermosa
TENANT_THEME_IMPL=default
DB_NAME=UBU1664QA17
DB_TYPE=oracle
DB_INSTANCE=db1
DB_PORT=1521
DB_ADMIN_USERNAME=SYSTEM
DB_ADMIN_PASSWORD=rd57chv
DB_USERNAME=UBU1664QA17
DB_PASSWORD=password
DB_SERVER=akanaeng-oracle12cr2-1.aws.akana.roguewave.com
DB_DRIVER_LOCATION=file:///home/user/ojdbc8.jar
DB_SCHEMA_TIMEOUT=4000000000

Note: The example above references the location for the ojdbc8.jar file, needed for an Oracle database. If you're using Oracle, you'd have to have the driver in place and update the path appropriately. If you're using another type of database, you may or may not need to provide a driver. Refer to the Database drivers section of the installation documentation. There might be other steps you need to have in place for your database. Check the information in the links provided in PM/CM container: overview above.

PM/CM container: automation script

In this example, the recipe is pm-cm-all.json and the properties file is pm-cm-all.properties.

Therefore, the script command to run from the /akana/bin folder is:

./jython.sh -Dorg.slf4j.simpleLogger.logFile=System.out -m akana.container --recipe ../recipes/pm-cm-all.json --props pm-cm-all.properties

When the recipe has successfully completed, you'll see a message such as the below:

pm-cm-all.json, successful completion

PM/CM container: results

You can now access the Akana Administration Console for the container: {hostname}:{port}/admin/login.html, as shown below.

You can see from the Installed Features page that Community Manager is installed and all pending tasks are complete.

Running the Akana Administration Console for the pm-cm-all container

In this example, you can also access the Policy Manager and Community Manager via the browser, as shown below.

Policy Manager: {hostname}:{port} (default credentials, used in this example, are administrator/password).

Running Community Manager for the pm-cm-all container

Community Manager: {hostname}:{port}/atmosphere/#/home/login (default credentials, used in this example, are administrator@atmosphere/password).

Running the Community Manager developer portal

Creating an ND container:

ND container: overview

Next, we're going to create the Network Director container. We can then register the ND container so that it can communicate with the PM/CM container.

  • Recipe: nd-cm-all.json
  • Properties file in this example: nd-cm-all.properties

Steps for setting up an ND container

The sequence of steps is the same for running any recipe, as described in detail in Creating a basic container above:

  1. Download and extract the installation files (once per installation).
  2. Put the logging file in place to enable logging (once per installation).
  3. Set up the properties file (per recipe). For this example, define the properties listed in Properties file for ND container below.
  4. Run the recipe using the automation script (per recipe). For this example, use the script shown in ND container: automation script below.

Properties file for ND container

Properties file (nd-cm-all.properties):

INSTALL_DIR=/home/user/akana
DEFAULT_PORT=9905
CONTAINER_NAME=nd01
PM_PORT=9900
PM_HOST=ubu1664qa-17.akana.roguewave.com

ND container: automation script

In this example, the recipe is nd-cm-all.json and the properties file is nd-cm-all.properties.

Therefore, the script command to run from the /akana/bin folder is:

./jython.sh -Dorg.slf4j.simpleLogger.logFile=System.out -m akana.container --recipe ../recipes/nd-cm-all.json --props nd-cm-all.properties

When the recipe has successfully completed, you'll see a message such as the below:

pm-cm-all.json, successful completion

ND container: results

You can now access the Akana Administration Console for the ND container. In this example: {hostname}:9905/admin/login.html.

You can see from the Installed Features page that Network Director is installed and all pending tasks are complete.

Running the Akana Administration Console for the ND container

The next step is to register the ND container with PM.

Registering the ND container:

Registering the ND container: overview

Next, we're going to run another automation recipe to register the ND container with the PM/CM container.

  • Recipe: register-container.json
  • Properties file in this example: register-container.properties

Note: If you want to register an ND container to a cluster, and create the cluster at the same time, see Using the register-container recipe to create a cluster and register an ND container at the same time.

Steps for registering the ND container

The sequence of steps is the same for running any recipe, as described in detail in Creating a basic container above:

  1. Download and extract the installation files (once per installation).
  2. Put the logging file in place to enable logging (once per installation).
  3. Set up the properties file (per recipe). For this example, define the properties listed in Properties file for registering the ND container below.
  4. Run the recipe using the automation script (per recipe). For this example, use the script shown in Registering the ND container: automation script below.

Properties file for registering the ND container

Properties file (register-container.properties):

TENANT_ID=atmosphere
ORG_KEY=uddi:soa.com:registryorganization
PM_PORT=9900
CONTAINER_NAME=nd01
INSTALL_DIR=/home/user/akana

In the above, TENANT_ID and ORG_KEY are both provided. You must provide one of these two, but to provide both is optional. The ORG_KEY value can be specific to the tenant.

Registering the ND container: automation script

./jython.sh -Dorg.slf4j.simpleLogger.logFile=System.out -m akana.container --recipe ../recipes/register-container.json --props register-container.properties

Registering the ND container: results

When the recipe has successfully completed, you'll see a message such as the below.

Register Container recipe successful

Now, log in to Policy Manager on the PM/CM container (in this example, {hostname}:9900).

You'll see that the ND container is now registered, as shown below.

ND container is registered

Additional resource information:

Providing property values at the command line

For consistency, it's a good idea to provide properties in a properties file (see Set up the properties file).

However, you could also provide properties at the command line when running the script.

Let's say you want to provide two basic properties, INSTALL_DIR and CONTAINER_NAME, which we used to create the basic container in the first example above. Your recipe.properties file would look like this:

INSTALL_DIR=/home/user/akana
CONTAINER_NAME=pm01

Your command line instruction for running the script would look something like this:

./jython.sh -Dorg.slf4j.simpleLogger.logFile=System.out -m akana.container 
--recipe ../recipes/bootstrap.json --props bootstrap.properties

However, you could instead provide the above two properties at the command line. In this example, from the /home/user/akana/bin folder, you'd provide the following at the command line:

./jython.sh -Dorg.slf4j.simpleLogger.logFile=System.out -DINSTALL_DIR=.. -m akana.container --name pm01 --home .. --recipe ../recipes/bootstrap.json

In the above:

  • ./jython.sh

    Calls the jython script

  • -Dorg.slf4j.simpleLogger.logFile=System.out

    Sets the logging. See Simple Logger.

  • -DINSTALL_DIR=..

    Sets the INSTALL_DIR property value to one folder up (the /home/user/akana folder in this example)

  • -m akana.container

    Specifies the module being run

  • --name pm01

    Specifies that the script should create a container named pm01

  • --home ..

    Sets the home directory

  • --recipe ../recipes/bootstrap.json

    Specifies the recipe to run

Downloading and extracting the installation files

Instructions for downloading and extracting the files are in the installation documentation: for example, see Installing the Akana API Platform 2020.2.x (Step 2-1 and Step 2-2). Abbreviated instructions are below.

The download files

The examples in this document create containers for version 2020.2.4. The files for this example, after you've unzipped the original download file, are below.

This file... Installs...
akana-platform-linux-jre_2020.2.4.zip The Akana Platform, the underlying infrastructure to all Akana products.
akana-api-platform_2020.2.4.zip The Akana API Platform, the API management product, which runs on the underlying Akana Platform.

The illustration below shows copying the files from another location so that the four files are in the akana directory.

Extracting the files

In the /home/user/akana folder, unzip the files in this sequence, always choosing to overwrite existing files if they already exist:

  • unzip -o akana-platform-linux-jre_2020.2.4.zip
  • unzip -o akana-api-platform_2020.2.4.zip

Cluster support

To define your cluster, you can use automation recipes to capture the configuration of an existing container, as covered in Running Recipes Remotely and Extracting and Analyzing Recipes. Then, you can run an automation recipe against each member of the cluster.

The approach is the same as running a recipe remotely against any container, whether the container is clustered or not.

Some advantages of using automation for managing clusters:

  • This approach supports the trend towards "configuration as code"—recipes and configuration can be managed as first-class artifacts.
  • Recipes can be executed remotely, allowing for fine-grained control of cluster members.
  • The use of recipes allows configuration tasks to be automated across the cluster, in addition to remote management of container configuration properties.

Note: If you want to register an ND container to a cluster, and create the cluster at the same time, see Using the register-container recipe to create a cluster and register an ND container at the same time.

Setting up an SMTP email host using an automation recipe

Valid in Version: 2020.2.0 and later.

The example below shows how you can configure an SMTP email host by using an automation recipe rather than using the Policy Manager user interface.

Navigation to complete this task in Policy Manager: Configure > Email > Modify SMTP Email Host. For more information, see To set up the SMTP Email Host.

To configure an SMTP email host, via the user interface or via a recipe, you'll need the values shown below.

In the user interface... In the recipe...
Host name or IP address SMTP_HOST
Port SMTP_PORT
SSL Required (yes/no) SMTP_SSL (true/false, default is false)
Use STARTTLS (yes/no) SMTP_TLS (true/false, default is false)
From Address SMTP_FROM
Authenticated (yes/no) SMTP_AUTH

If Authenticated=yes:

Username and Password

SMTP_USERNAME

SMTP_PASSWORD

To do this via a recipe you'll need the following assets:

  • The recipe: smtp-settings.json, located in the /recipes/tasks folder in your installation files.
  • A properties file with the properties and values set up. See the example smtp.properties file below.

Follow these basic steps:

  1. Create the properties file. For an example, see Creating an SMTP server: sample properties file below. If needed, add additional values from the table above (for example, port number).
  2. Run the recipe at the command line. See Creating an SMTP server: running the recipe below.
  3. Review the results in Policy Manager. See Creating an SMTP server: viewing the result in Policy Manager below.

Creating an SMTP server: sample properties file

The content of the smtp.properties file used in this example is shown below.

SMTP_HOST=akana-qa-25.aws.akana.roguewave.com
SMTP_FROM=recipetest@automation.com
SMTP_AUTH=true
SMTP_USERNAME=smtp-user
SMTP_PASSWORD=mypassword

Creating an SMTP server: running the recipe

The command to run this recipe is shown below.

./jython.sh -m akana.recipe --recipe ../recipes/tasks/smtp-settings.json --url http://akana-qa-41.aws.akana.roguewave.com:7900 --user administrator --password mypassword --props smtp.properties

Creating an SMTP server: viewing the result in Policy Manager

Log in to Policy Manager and go to Configure > Email > Modify SMTP Email Host. The result of running the example in this use case is shown below.

Setting up an SMTP server via automation -- viewing the results in Policy Manager.

Using the register-container recipe to create a cluster and register an ND container at the same time

Section Registering the ND container above gives an example of using the register-container recipe to register a Network Director container that has already been created.

You can also use this recipe to register a Network Director container to a cluster that doesn't yet exist, creating the new cluster and registering the Network Director container at the same time.

In this scenario, you'll need to provide the following additional properties:

CLUSTER_NAME={cluster_name}
CREATE_CLUSTER=true
CLUSTER_URL={cluster URL including name:host}

In this section:

Registering a Network Director container and creating a cluster (HTTP): properties

The example below shows the contents of the properties file, nd_new_cluster.properties, used for this recipe. This example creates a cluster named cl1 and registers a Network Director container named eapNd to the new cluster.

INSTALL_DIR=abs:..
DEFAULT_PORT=7905
CONTAINER_NAME=eapNd
PM_PORT=7900
PM_HOST=localhost
ORG_KEY=uddi:soa.com:registryorganization
CREATE_CLUSTER=true
CLUSTER_URL=default-http0:http://${hostname()}:7905/
CLUSTER_NAME=cl1
CLUSTER_KEY=cl1

Note: In the INSTALL_DIR property above, the The abs directive ensures that the path provided is an absolute path. See Property Substitution (Directives section).

Registering a Network Director container and creating a cluster (HTTP): running the recipe

The command to run this recipe is shown below.

./jython.sh -m akana.container --recipe ../recipes/register-container.json --props nd_new_cluster.properties

Note: You can also include the optional -Dorg.slf4j.simpleLogger.logFile=System.out if you want logging. See Put the logging file in place to enable logging.