Lifecycle Coordinator Promotion Guide

Provides information about how to use the Lifecycle Coordinator feature to manage the promotion feature.

API Platform Version: 8.4.3 and later

Table of Contents

  1. Overview
  2. Core Components and Component Interaction
  3. Topology Model
    1. Topology
    2. Tenants
    3. Environments
    4. Promotion Profiles
    5. Asset Filters
    6. Rules
    7. Asset Model
  4. Lifecycle Coordinator Installation
    1. Getting the installation ZIP file
    2. Installing the Lifecycle Coordinator feature
    3. Checking for database-specific requirements
    4. Securing the Topology REST API
    5. Remote container address (com.soa.promotion)
    6. Properties to secure the Topology REST API (com.akana.lifecycle.coordinator) (8.4.15 and later)
    7. Unique ID Mapping behavior
    8. Default "From Email" setting
    9. Tenant Synchronization Interval (8.4.16 and later)
  5. Topology Configuration
    1. Tenants
    2. Environments
    3. Promotion Profiles
    4. Rules
    5. Filters
    6. Organization Mapping (8.4.13 and later)
    7. Policy Mapping (8.4.16 and later)
    8. Asset Notifications (8.4.17 and later)
    9. Properties (8.4.17 and later)
  6. Deployment Zone Configurations (8.4.12 and later)
    1. Using Filters with Deployment Zone Configurations
    2. Default Endpoint Propagation
    3. Using Rules with Deployment Zone Configurations
    4. Duplicate Endpoints
  7. Topology API
    1. Finding the Topology API Documentation
    2. Using the Topology API
  8. Lifecycle Manager Console
    1. Logging In
    2. Viewing Assets and Iterations
    3. Promotion Requests
  9. Default API Settings using Runtime Configurations (8.4.17 and later)
    1. Creating a Runtime Configuration Asset
    2. Publishing a Runtime Configuration Asset

Overview

Promotion is the process of propagating versions of a software asset, such as an API, through a series of environments that correspond to the stages of the asset's lifecycle. For example, an API might originate in a development environment, be promoted on to a QA test environment, and finally be promoted to the production environment. Each environment has its own data model that is controlled independently. The Lifecycle Coordinator is a separate configurable component that governs the promotion process and the transfer of data between environments.

Back to top

Core Components and Component Interaction

The core components in the promotion process are as follows:

Promotion Package

The Promotion Package holds the data that needs to be promoted from the Source Environment to the Target Environment. The package contains two different artifacts:

  • The environment data: The portion of the Source Environment's data model that needs to be promoted.
  • A manifest: Contains configuration details that can be manipulated by rules within the Coordinator before importing the package into the target environment.

Source Environment

The Source Environment is the data container that holds the original information that needs to be promoted to the Target Environment. The Source Environment can be managed by its own product instance or it can be managed as a single tenant in a multi-tenant product instance.

Target Environment

The Target Environment is the data container that is the destination of the promoted data from the Source Environment. The Target Environment can be managed by its own product instance or it can be managed as a single tenant in a multi-tenant product instance.

Lifecycle Coordinator

The Lifecycle Coordinator is the component that requests an extraction, or export, of a promotion package from a Source Environment and then initiates the population, or import, of the promotion package to a Target Environment.

The Coordinator processes the manifests contained in the Promotion Package and in the Target Environment's promotion response to maintain a model that reflects the relationship between objects in both environments. On subsequent promotions of the same objects from the Source Environment the Coordinator consults its model and generate a new manifest that will be delivered to the Target Environment.

The Lifecycle Coordinator is a separate component from the environments but can be co-deployed on the same instance.

Component Interaction

Component interaction

When promotion is requested from the Source Environment, the Lifecycle Coordinator exports a Promotion Package from that Environment and imports the package in the Target Environment.

The Lifecycle Coordinator persists its own model of objects and their relationships in all the environments it has performed promotions for. The Coordinator consults its model to see if the objects identified in the Promotion Package's manifest are already present. If the objects are not in the model, the Coordinator adds them. If the objects are in the model the Coordinator extracts the corresponding object IDs of the Target Environment and create a new manifest with the Target Environment's object IDs.

The Lifecycle Coordinator initiates an import of the Promotion Package in the Target Environment using an Import API. The Target Environment uses the manifest to identify the objects in its own data model that are in the Promotion Package; if objects already exist, a Modify action is performed. If the Promotion Package objects are new to the Target Environment an Add action is performed. The object IDs in the manifest are used in the Target Environment, not the object IDs found in the export content, which are still the IDs found in the Source Environment.

Upon completion of the Import API call a response is returned to the Lifecycle Coordinator. A manifest is included in that response that identifies the objects and relationships that were the result of the import in the Target Environment. The Lifecycle Coordinator processes this manifest and updates its own model for subsequent promotion calls.

The Lifecycle Coordinator can be deployed in a container separate from the API Platform(s) it governs promotions over. In this deployment, the interactions between the Lifecycle Coordinator and API Platform(s) are performed using RESTful interfaces. The Coordinator can promote between environments in the same system:

Environments in the same system

Or the Coordinator can promote between environments in separate systems.

Environments in different systems

The Lifecycle Coordinator can also be deployed in the same container as the API Platform. Whether multiple tenants are associated with Environments or just one tenant the deployment and interaction is the same. All interactions are performed using in-memory interfaces.

Back to top

Topology Model

Topology

A Topology defines a sequence of Environments and the specific behavior for promotion between these Environments.

Promotion behavior between environments

Tenants

Tenants are defined at the top level of the Topology and represent a Community Manager (CM) tenant that may be local (within the same container) or remote from the Lifecycle Coordinator. Tenants are referenced by Environments via an id assigned to the tenant in its definition. While an Environment must reference a tenant, the same Tenant may be referenced by more than one Environment. Tenants contain information allowing the Lifecycle Coordinator to communicate with the associated CM Tenant, this includes the tenant's address, name and admin credentials.

A Tenant that is local may also indicate that it should be used to as an authentication source for users approving promotion requests with the Lifecycle Coordinator.

Environments

An Environment represents a logical container to which an asset is deployed at a specific stage of its lifecycle. An Environment must specify the Tenant that supports it.

Environments also define the possible transitions to the next Environment in the form of Promotion Profiles. At this time, only a single target Environment can be specified in the promotion chain (Environment fan-out is not currently supported).

Promotion Profiles

Promotion Profiles represent a transition to the next (target) Environment. A promotionProfile specifies a target Environment and optionally a set of Rules to be applied to the manifest of the promotion package of the asset prior to promotion into the target Environment. A promotionProfile might also, optionally, specify an Asset Filter. This allows multiple promotionProfiles to be defined within an Environment with mutually exclusive filters, each with a different rule set. When promotion of an asset is requested from a source Environment, and more than one promotionProfile exists, the promotionProfile with an Asset Filter that the asset complies with is used. In the case where only one promotionProfile exists (with no Asset Filter specified), that promotionProfile is automatically selected for the promotion.

Asset Filters

Asset Filters contain a set of criteria for the custom properties of the assets being promoted. For example, an API asset may use a custom property indicating that it is PCI compliant. An Asset Filter can define criteria for that property such that only API assets that are PCI compliant will match the filter. This Asset Filter can then be assigned to a Promotion Profile such that a different set of Rules are applied to PCI-compliant and non-compliant API assets.

Note: the use of Asset Filters requires custom properties to be enabled for the tenants involved in the promotion.

Rules

A Promotion Profile may optionally contain a set of rules to guide the need for changes in relationships and properties when assets are promoted. A rule consists of a condition and a behavior. The rule is provided a context when evaluated made up of an asset's properties. The condition of the rule is a Boolean expression evaluated against that context. The behavior of the rule is an expression that alters that context. The expression language used by the rule engine is JEXL. A set of syntax examples can be found at https://commons.apache.org/proper/commons-jexl/reference/syntax.html. Each asset in a promotion package is run through the rule engine. If any asset meets the condition of the rule, the behavior is performed against it. Some examples of rules are below.

Condition Behavior Description
vsep.containerKey = "ND1" vsep.containerKey = "ND2" Changes hosting relationship from ND1 to ND2
apiversion.implType = "Sandbox" vsep.containerKey = "ND2" Changes hosting relationship for sandbox implementations
vsep.containerKey = "ND1" && vsep.listenerName = "http" vsep.containerKey = "ND2"; vsep.listenerName = "https" Changes both the container and listener
psep.url.startsWith("http://oldhost") psep.url.replace("http://oldhost", "http://newhost") Changes the host of a target endpoint
apiversion.tags.contains("secret") apiversion.tags.add("probation") Adds a tag based on the presence of another.
classifier:internal = "true" vsep.containerKey = "ND3" Sets container based on the value of a custom classifier

Asset Model

The Lifecycle Coordinator component is an extension of the Lifecycle Repository core functionality. As such, it uses an internal asset model to represent the topology and the assets promoted through the topology. Within the Lifecycle Coordinator, promotion requests result in the submission of an asset into the target environment, allowing for customized governance to be defined for this process.

In this section:

Topology Asset Model

The topology asset model reflects the conceptual topology model defined earlier in this document with asset types for Environment, Tenant and Promotion Profile. The following diagram shows the asset structure for a Topology with three Environments (each box representing an asset):

Topology asset model, three environments

In addition to the relationships shown, Tenant assets contain connection information and credentials as classifiers while Promotion Profile assets hold Rules as a JSON artifact. Asset Filters are managed implicitly and optionally referenced by Promotion Profile assets.

Promotable Asset Model

Promotable assets such as APIs are represented by specific asset-types. These asset types reference an Environment asset and contain Iteration assets representing each promotion of that asset. Note that there is a difference between versions of assets such as APIs and iterations: a single version of an API may be promoted multiple times, resulting in multiple iterations of that version. In the following asset diagram, the asset AnAPI (v1) has been promoted from development to integration test and then to production environments once, followed by another promotion from development to integration test. This resulted in two iterations in the development and integration test environments with a single iteration at production. Notice that the iteration at production indicates that its source iteration is iteration 1 in integration test, even though there is a newer iteration (iteration 2) in that environment.

Promotable asset model

Iterations contain several items:

  • A timestamp indicating when the promotion took place
  • The user that requested the promotion
  • The status of the promotion. Values for the status are:
    • Promotion Pending: Promotion has been requested but has not been completed. It may be pending one or more approvals.

      Note: In the case where an approval process is in place and a promotion request is rejected, the Iteration will remain in a Promotion Pending state. However, the API platform UI will show it as Promotion Rejected, allowing promotion to be requested again.

    • Promoted: Promotion has completed.
    • Promotion Failed: There was a failure in the promotion process. Promotion can be requested again for assets in this state. The next promotion attempt will replace the failed iteration.

    Note: The API Platform UI also indicates a Not Promoted state. This corresponds to an asset not yet existing in the target environment. Such assets will not be present in Lifecycle Coordinator.

  • The promotion package that was imported into the target environment is held as an artifact called archive.zip.
  • In the case of a promotion failure the iteration includes a short summary of the exception causing the failure.
  • A relationship to the source iteration in the source environment
  • A relationship to the previous iteration (if one exists) in the target environment
  • A relationship to the Promotion Profile selected for promotion of the asset.
OrgGroup Assignment
API Platform Version: 8.4.13 and later

When promotion is requested for an asset such as an API, the asset is assigned an owning OrgGroup within Lifecycle Coordinator. These OrgGroups correspond to the asset's Organization in the corresponding API Platform environment. This approach allows promotion approvers to be assigned at an organizational level within the Lifecycle Coordinator topology.

Note: OrgGroups are synchronized with the tenant Organization when a topology is created or updated. If an asset is promoted with an Organization for which there is no corresponding OrgGroup, Lifecycle Coordinator synchronizes the Organizations for the corresponding tenant in an attempt to resolve the missing OrgGroup.

Back to top

Lifecycle Coordinator Installation

This section includes:

Getting the installation ZIP file

If you're installing Lifecycle Coordinator, you'll need a specific ZIP file in addition to the main ZIP files for Akana API Platform installation.

Log in to the Rogue Wave Support Center (https://library.roguewave.com).

In the My Resources section, click Product Downloads, then click Akana - Product Downloads. Download the applicable lifecyclemanagerplatform_8.4.xx.xxxxx.zip file for Lifecycle Manager; for example, lifecyclemanagerplatform_8.4.16.02264.zip file.

Installing the Lifecycle Coordinator feature

For an on-premise installation of the Akana API Platform, the Lifecycle Coordinator feature must be separately installed from the Akana Administration Console:

Lifecycle Coordinator feature

Installing Lifecycle Coordinator implicitly installs the Lifecycle Repository feature as well. After selecting Lifecycle Coordinator for installation, the user is guided through a number of configuration tasks for the Lifecycle Repository feature.

Checking for database-specific requirements

Depending on the database version you're using, there might be additional steps you need to take. You should perform these steps after installation and before the additional configuration steps.

For details of the requirements for specific database types and versions, refer to the database notes section of the Akana API Platform installation documentation. Specifically, there are notes for Microsoft SQL Server and MySQL relating to installation of Lifecycle Repository.

Complete any applicable steps before continuing.

Securing the Topology REST API

There is also a task to secure the Topology REST API, as shown below.

Set Topology API Credentials task

This sets up the credentials for basic authentication on calls to the Topology REST API.

Remote container address (com.soa.promotion)

If the Lifecycle Coordinator is installed remotely, a URL to the remote container hosting the Lifecycle Coordinator instance must be configured for each container hosting tenants from which promotion can be requested.

To set this up:

  1. In the Akana Administration Console, open the Configuration tab.
  2. Select the com.soa.promotion category.
  3. Set the remote.promoter.address property to the host address of the container hosting the Lifecycle Coordinator instance. An example is shown below.

    Setting remote.provider.address

  4. Save the changes.

Properties to secure the Topology REST API (com.akana.lifecycle.coordinator)

API Platform Version: 8.4.15 and later

You can set up the global configuration properties for Lifecycle Coordinator in the Akana Admin Console.

With the three properties listed below, you can configure the Topology REST API to require basic authentication for all requests.

  1. In the Akana Administration Console, open the Configuration tab.
  2. Select the com.akana.lifecycle.coordinator category.
  3. Set the properties. For details, see com.akana.lifecycle.coordinator properties below.
  4. Save the changes.
com.akana.lifecycle.coordinator properties
lifecycle.coordinator.config.apiUser
This field and the next are used to set the global basic authentication credentials for the Topology REST API. If this property is left empty, the Topology API will not require authentication of requests.
lifecycle.coordinator.config.apiPassword properties
If a value was set for lifecycle.coordinator.config.apiUser, specify the password.
lifecycle.coordinator.config.enableTenantScopedAuthentication
Boolean. Used to allow delegation of authentication to the primary tenant in the topology being acted on. The primary tenant is the tenant marked as the userAuthenticationSource in the topology. If no tenant is marked as the userAuthenticationSource, the initial tenant in the topology is used for authentication.

The following table summarizes the authentication behavior.

Global Credentials Set Tenant Scoped Authentication Enabled Behavior
No N/A Requests are not authenticated
Yes false Requests must specify global credentials
Yes true

Requests can specify either of these:

  • The email and password of a site admin user in the primary tenant of the topology being acted on.
  • The global credentials

Note: Requests for the getTopologies method (GET /lc/api/topologies) must specify the global credentials since there is no specific topology being acted on.

Unique ID Mapping behavior

API Platform Version: 8.4.14 and later

The property lifecycle.coordinator.config.preserveKeys in the com.akana.lifecycle.coordinator configuration category is used to configure the default behavior for preserving the unique IDs of an API's constituent elements as the API is promoted across environments.

If this property is set to true, the unique IDs of the underlying Services and Organization are preserved. If it's set to false, these elements will be assigned new unique IDs when they are promoted, and a mapping between the keys used in each environment will be stored with the topology in Lifecycle Coordinator.

Note:  If multiple tenants referenced in the same topology exist in the same API Platform instance (that is, share the same database), the value should be changed to false, since there might be some overlap in key values. If preserveKeys is set to true, any overlap in key values would cause promotion errors.

Default "From Email" setting

You can set the default from email address used in emails sent from Lifecycle Coordinator, in the repository.config.defaultFromEmail property of the com.soa.repository configuration category.

You can also override the from email address for a specific topology. To do this, go into the topology library as an admin user or superuser, click Support Center, click Configure Library and set the Sender Email field, as shown below.

Setting From Email in LM

Tenant Synchronization Interval

API Platform Version: 8.4.16 and later

Lifecycle Coordinator periodically updates cached policy and organization information for tenants referenced in a topology. The specific interval for this update is controlled by the following property:

Configuration category
com.soa.repository
Configuration property
repository.config.tenantSyncInterval
Explanation:
Sets the interval between updates to cached policy and organizational information. The value is set in milliseconds.
Default value:
300000 (5 minutes)

Back to top

Topology Configuration

The Lifecycle Coordinator feature provides a REST API for maintaining topologies. This allows topologies to be defined in JSON structure. The following example shows the definition of a topology consisting of two environments supported by two local tenants.

{
  "name":"Topology1",
  "tenants":[
    {
      "name":"DevelopmentTenant",
      "id":"tenant1",
      "credentials":{
        "email":" administrator1@example.com ",
        "password":"password1"
      }
    },
    {
      "name":"ProductionTenant",
      "id":"tenant2",
      "userAuthenticationSource":true,
      "credentials":{
        "email":"administrator2@example.com",
        "password":"password2"
      }
    }
  ],
  "environments":[
    {
      "name":"development",
      "displayName":"Development",
      "description":"Development environment",
      "tenant":"DevelopmentTenant",
      "promotionProfiles":[
        {
          "name":"Default Production Promotion",
          "description":"Dev to production default profile",
          "targetEnvironment":"production"
        }
      ]
    },
    {
      "name":"production",
      "displayName":"Production",
      "description":"Production environment",
      "tenant":"ProductionTenant"
    }
  ]
}

Tenants

Tenant definitions in the topology provide the Lifecycle Coordinator the necessary information to communicate with the specified tenant. Tenants can be either local (on the same container as the Lifecycle Coordinator) or remote. When defining a tenant:

  • Local tenant: Specify the tenantId in the id property, as in the topology example above.
  • Remote tenant: In addition to the tenantId in the id property as above, specify the address of the tenant in the address field.

The example below shows both values:

{
  "name":"ProductionTenant",
  "id":"tenant2",
  "address":"http://myProductionTenant:9900",
  "credentials":{
    "email":"administrator2@example.com",
    "password":"password2"
  }
}

Note: The address value is unique to the tenant. It corresponds to the value specified for the address parameter when the tenant was created.

Tenant Names

Tenants require a name property which is used to identify the tenant by environments within the topology. This name must be unique within the topology, but need not correspond to the actual tenant name.

Delegated Authentication

The Boolean userAuthenticationSource property is used to indicate that authentication for the underlying Lifecycle Repository library console is to be delegated to the specified tenant. This means that users of the specified tenant can log in to the topology library using their email and password for that tenant.

Only one tenant can have the userAuthenticationSource property set to true, and that tenant must be local to the Lifecycle Coordinator.

Tenant Properties (8.4.18 and later)

Tenant definitions can contain optional properties, as shown in the example below.

{
  "name":"ProductionTenant",
  "id":"tenant2",
  "address":"http://myProductionTenant:9900",
  "credentials":{
    "email":"administrator2@example.com",
    "password":"password2"
  },
  "properties":[
    {
      "name":"virtual-address",
      "value":"http://myCompany:9950"
    }
  ]
}

The optional properties available for a tenant are:

  • virtual-address: This property can be used when the URL used to access a remote tenant is different from the tenant's address attribute. For example, this property would be used if the tenant is fronted by a load balancer. If the virtual-address property is provided, the URL set in the value of this property is used for all communications with the tenant.

Environments

Environments reference a corresponding tenant and hold one or more promotionProfiles representing transitions to other environments.

Environment Names

The name property for an environment must be unique within the topology and should not be changed once defined. This is because this name is used as a key for mapping information between environments stored by the Lifecycle Coordinator. Given the invariability of the environment name, a displayName property is also supported. The display name is what appears to users in the API Platform UI and may be changed without affecting mapping information.

Promotion Profiles

Promotion Profiles are defined within the promotionProfiles property of an Environment. The targetEnvironment property of a PromotionProfile must correspond to the name of another Environment in the Topology.

A PromotionProfile can optionally specify one or more filters by specifying filter names within the filterNames array property.

Rule definitions might optionally be provided using the rules array property.

Note: A PromotionProfile cannot create a cycle between Environments.

Rules

Rules are defined inline within the rules array property of a PromotionProfile. Each Rule consists of a scope property indicating the property in the archive manifest it applies to, an optional condition property indicating the conditions for which the Rule applies and a required action property indicating the action to perform on the manifest property.

Examples in this section:

  • Rule example #1: changes the hostname for the physical service endpoint.
  • Rule example #2: changes the name of the OAuth provider for a promoted API in the target environment.
Rule example #1

In this example, the rule changes the host name of the physical service endpoint (psep) for an API:

{
  "scope":"psep",
  "condition":"psep.url.indexOf(\"foo.com\") > 0",
  "action":"psep.url = psep.url.replace(\"foo.com\",\"bar.com\")"
}

Note the use of '\' to escape the double quotes in the condition and action.

Rule example #2

The example below changes the name of the OAuth provider for a promoted API in the target environment.

Note: Only use this rule if the configuration of the source and target OAuth Providers is identical, including scope definition. If the configuration is not identical, using this rule might cause promotion errors.

{
  "scope" : "vs",
  "condition" : "vs.oauthProvider == 'SourceProvider'",
  "action" : "vs.oauthProvider = 'TargetProvider'"
}

Filters

The filters property of a Topology allows asset filters to be defined for use in PromotionProfile selection. Filters contain criteria which apply to the classifiers associated with an asset.

Filters correspond to the custom properties for an API in the API Platform UI.

The following example defines filters used to differentiate between APIs that are PCI compliant and those that are not based on a pci-compliant classifier:

[
  {
    "name":"PCI Compliant",
    "classifier-criteria":[
      {
        "classifierName":"pci-compliant",
        "values":[
          {
            "value":"true"
          }
        ]
      }
    ]
  },
  {
    "name":"PCI Non-Compliant",
    "classifier-criteria":[
      {
        "classifierName":"pci-compliant",
        "values":[
          {
            "value":"false"
          }
        ]
      }
    ]
  }
]

With these filters defined, different transition paths between source and target Environments can be defined as in the following example promotionProfiles property for an Environment:

{
  "promotionProfiles":[
    {
      "name":"PCI Production Promotion",
      "targetEnvironment":"Production",
      "filterNames":[
        "PCI Compliant"
      ],
      "rules":[
        {
          "scope":"vsep",
          "action":"vsep.containerKey = '{pci-container-key}' "
        }
      ]
    },
    {
      "name":"Non-PCI Production Promotion",
      "targetEnvironment":"Production",
      "filterNames":[
        "PCI Non-Compliant"
      ],
      "rules":[
        {
          "scope":"vsep",
          "action":"vsep.containerKey = '{standard-container-key}' "
        }
      ]
    }
  ]
}

Back to top

Organization Mapping

API Platform Version: 8.4.13 and later

Lifecycle Coordinator attempts to assign APIs in the target environment tenant to an Organization matching the name of the Organization in the source environment tenant. If it doesn't find an Organization of the same name, it assigns the API to the tenant Organization.

Within a promotion profile, you can define a rule to create a mapping of Organizations when promoting to the target environment. To do this, define a rule that modifies the api.orgName property.

For example, you could add the following rule to the rules of a PromotionProfile to map APIs from the source Organization GroupA to the target Organization GroupB.

{
  "scope":"api",
  "condition":"api.orgName == 'GroupA'",
  "action":"api.orgName = 'GroupB'"
}

Policy Mapping

API Platform Version: 8.4.16 and later

A Promotion Profile can optionally contain a set of PolicyMappings that you can use to tailor the propagation and validation of policy references when an API is promoted to the target environment. You can use PolicyMappings to:

  • Map a policy reference in the source environment to a policy in the target environment.
  • Remove a policy reference altogether when an API is promoted.

A PolicyMapping has one of these two properties:

  • sourcePolicy—Used to identify a specific policy in the source environment by either name or unique id.
  • sourcePolicyFilter—Used to specify a group of policies by type or subtype.

Additionally, a PolicyMapping can specify a targetPolicy in the target environment either by name or unique id. If a PolicyMapping does not specify a targetPolicy property, references to policies matching the sourcePolicy or sourcePolicyFilter property are ignored when an API is propagated to the next environment.

The following PromotionProfile shows an example of a PolicyMapping that maps references to the DetailedAuditPolicy in the source environment to the BasicAuditPolicy in the target environment:

{
  "name": "Default Production Promotion",
  "description": "Dev to production default profile",
  "targetEnvironment": "production",
  "rules": [],
  "policyMappings": [
    {
      "sourcePolicy": {
        "policyName": "DetailedAuditing"
      },
      "targetPolicy": {
        "policyName": "BasicAuditing"
      }
    }
  ]
}

In this example, the PolicyMapping uses the unique ids of the source and target policies:

{
  "sourcePolicy": {
    "policyId": "urn:uuid:852afbc5-101e-11e8-887b-abe2ebb3db33"
  },
  "targetPolicy": {
    "policyId": "urn:uuid:763b7ca5-304f-16e8-457b-c542e456db33"
  }
}

You can accomplish a one-to-many mapping of policies using a policy filter:

{
  "sourcePolicyFilter": {
    "policyType": "Operational Policy",
    "policySubtype" : "policy.auditservice"
  },
  "targetPolicy": {
    "policyName": "BasicAuditing"
    }
}

A specific policy is disabled on promotion by omitting the targetPolicy property in the PolicyMapping:

{
  "sourcePolicy": {
    "policyName": " DetailedAuditing "
  }
}
Default Mappings

Policies that are available by default within a tenant, such as DetailedAuditing, BasicAuditing, and CORSAllowAll, are implicitly mapped to the corresponding default policies in the target tenant and do not need an explicit PolicyMapping. You can think of this default mapping as being of the form:

{
  "sourcePolicy": {
    "policyId": "<source tenant id>-<policy name>"
  },
  "targetPolicy": {
    "policyId": "<target tenant id>-<policy name>"
  }
}
Tenant name change: original-tenant-name property

Default policy mappings are determined based on the tenant name. If the name of a tenant was changed since its original creation (in the Developer Portal, Admin > Site), it's important to include the original tenant name in the tenant definition in the topology, using the original-tenant-name property. An example is shown below.

{ 
  "id": "devtenant", 
  "name": "DevelopmentTenant", 
  "address": "http://devacmepaymentscorptenant:9457", 
  "properties": [ 
    { 
      "name": "original-tenant-name", 
      "value": "Tenant1" 
    } 
  ], 
  ... 
}
Policy Validation

When an API is promoted, policy references must do one of the following:

  • Reference a default policy, such as DetailedAuditing
  • Match the unique ID of an existing policy in the target environment
  • Match a PolicyMapping defined for the selected PromotionProfile

If none of the above criteria are met, a validation error is returned to the promoting user and the promotion is aborted.

Back to top

Asset Notifications

API Platform Version: 8.4.17 and later

A PromotionProfile can optionally specify updates to be made to instances of an API, within environments of a topology, on completion of a successful promotion. These updates are implemented as changes to the values of custom properties on the API within a specified environment.

For example, let's assume a topology consisting of three environments: Development, Test, and Production. The goal is to mark the instances of an API in the Development and Test environments as in production once the API is successfully promoted to the Production environment.

Steps:

  1. The Development and Test tenants could be configured to support an in-production Boolean custom property.
  2. Then, the PromotionProfile representing the promotion from Test to Production would specify the property to update, the value to set the property to, and the environments in which the property is to be set.

This is shown in the following PromotionProfile declaration:

{
  "name":"Default Production Promotion",
  "targetEnvironment":"production",
  "assetNotifications":[
    {
      "propertyName":"in-production",
      "propertyValue":"true",
      "environments":[
        "development",
        "test"
      ]
    }
  ]
}

This feature relies on custom properties having been enable for the notified tenants, and on the specified property existing on the target API.

Properties

API Platform Version: 8.4.17 and later

A PromotionProfile can optionally specify properties to further refine export/import behavior. These are defined in an optional properties element, as in the following example:

{
  "name":"Default Production Promotion",
  "description":"Dev to production default profile",
  "targetEnvironment":"production",
  "properties":[
    {
      "name":"export-pki",
      "value":"true"
    }
  ]
}

You can set the following properties on a PromotionProfile:

  • export-pki

    This option indicates that the PKI keys and certificate for an API will be included in the promotion if they exist. Note that if the target environment for a promotion is on a different container from the source environment, the API's certificate or an ancestor in the chain must be trusted by the target container's certificate authority, or it will be ignored when importing the API.

    A value of true indicates that PKI keys and certificate should be promoted. The default value for this property is false.

  • match-policies-by-name

    Setting this property to a value of true indicates that custom policies in the source and target environments are to be implicitly mapped by policy name (regardless of their unique keys).

    For example, without this property present, an API referencing a policy named MyCustomAuditingPolicy in the source environment will fail validation even if there is a policy with the same name in the target environment, unless there is a policy mapping explicitly defined between the policies. With the property set to true, the API will pass validation and will be assigned the policy with the same name in the target environment.

Deployment Zone Configurations

API Platform Version: 8.4.12 and later

Within a promotion profile, deployment zone configurations can be used to tailor the propagation of an API's endpoints to the target environment. During API promotion, applicable deployment zone configurations are selected based on:

  • The name of an API endpoint's deployment zone in the source environment.
  • Optionally, filters that apply to the metadata of the API.

A deployment zone configuration contains a list of deployment zone names in the target environment. When a deployment zone configuration is determined to be applicable for an endpoint of the API being promoted, the endpoint is populated into the specified target environment deployment zones.

Note: The target deployment zone must have a listener that matches the listener name of the endpoint. If necessary, use rules in the deployment zone configuration to adjust listener names.

The structure of the deployment zone configurations allows endpoints in a source environment to be fanned out to a target environment. For example, a staging environment might only support a single deployment zone while the production environment supports many deployment zones across different geographic regions.

Consider the following example PromotionProfile:

{
  "name":"Default Production Promotion",
  "targetEnvironment":"production",
  "deploymentZoneConfigurations":[
    {
      "sourceDeploymentZoneName":"StagingDZ",
      "targetDeploymentZoneNames":[
        "ProdWestDZ",
        "ProdEastDZ"
      ]
    }
  ]
}

In this example, a single deployment zone configuration has been defined to propagate endpoints in in the StagingDZ1 deployment zone in the source environment to both ProdWestDZ and ProdEastDZ in the target environment.

Using Filters with deployment zone configurations

The filtering capability of deployment zone configurations allows for target deployment zones to be determined based on the metadata of the API. For example, security metadata associated with the API might determine the specific deployment zones that the API is deployed to.

In the following example, the filters named PII and Not PII are used in selecting the deployment zones an API's endpoints are propagated to in the target environment, based on whether the API is marked as processing personal identity information.

"deploymentZoneConfigurations": [
  {
    "filterNames": [
      "pii"
    ],
    "sourceDeploymentZoneName": "StagingDZ",
    "targetDeploymentZoneNames": [
      "PIIDZ"
    ]
  },
  {
    "filterNames": [
      "not-pii"
    ],
    "sourceDeploymentZoneName": "StagingDZ",
    "targetDeploymentZoneNames": [
      "NotPIIDZ"
    ]
  }
]

For the above example, the filters in the topology are defined as shown below.

"filters": [
  {
    "name": "pii",
    "classifier-criteria": [
      {
        "classifierName": "pii",
        "values": [
          {
            "value": "true"
          }
        ]
      }
    ]
  },
  {
    "name": "not-pii",
    "classifier-criteria": [
      {
        "classifierName": "pii",
        "values": [
          {
            "value": "false"
          }
        ]
      }
    ]
  }
]

Default Endpoint Propagation

If an endpoint's source deployment zone doesn't match a defined deployment zone configuration, the promotion processing will propagate the endpoint to a deployment zone in the target environment with the same name, if one exists. You can think of this as an implicit deployment zone configuration for every deployment zone in the source environment of the form:

{
  "sourceDeploymentZoneName":"{source DeploymentZone name}",
  "targetDeploymentZoneNames":[
    "{source DeploymentZone name}"
  ]
}

You can disable endpoints from a source deployment zone completely by defining a deployment zone configuration that specifies no target deployment zone names. For example:

{
  "sourceDeploymentZoneName":"TestDZ",
  "targetDeploymentZoneNames":[

  ]
}

Using Rules with deployment zone configurations

A deployment zone configuration can optionally contain RuleDefinitions to be applied to the properties of the endpoints being promoted with this deployment zone configuration.

At this level, you can use rules to alter a listener name, the endpoint's path, or its vanity host. The properties available for modification are:

listenerName
The name of the endpoint's listener; for example, http. It must match a listener associated with the target deployment zone.
path
The endpoint-specific path. If the endpoint in the source environment did not have an endpoint-specific path, this will be set to NO_VALUE. A rule can set the path property to another value, or to NO_VALUE indicating that the target endpoint will not have a specific path.
vanityHostName
A host name (CNAME) specific to the endpoint. If the endpoint in the source environment did not have a vanity host name, this will be set to NO_VALUE. A rule can set the vanityHostName property to another value, or to NO_VALUE which indicates that the target endpoint will not have a vanity host name.
DISABLED
This property provides a means of disabling an endpoint via a rule. If you set the value of DISABLED to true, the endpoint is not propagated to the target environment.

In the example shown below, a rule is provided with a deployment zone configuration that will disable the propagation of endpoints that do not have a vanity host name in the source environment.

{
  "sourceDeploymentZoneName":"StagingDZ",
  "targetDeploymentZoneNames":[
    "ProdDZ"
  ],
  "rules":[
    {
      "scope":"vsep",
      "condition":"vsep.vanityHostName == 'NO_VALUE'",
      "action":"vsep.DISABLED = 'true'"
    }
  ]
}

Duplicate Endpoints

Care should be taken to avoid duplicating endpoints across environments using the same underlying Gateways. This situation can occur if the target deployment zone has the same underlying Gateway as the source deployment zone (leading to the same host name and port) and has no options set for altering the Gateway host name or path. This situation will result in the promotion of the API failing.

There are several ways you can help make sure there are no duplicate endpoints:

  • Enable random prefixes in the target deployment zone.
  • Provide a custom hostname for the Gateway in the target deployment zone that differs from the source deployment zone.
  • Use a rule in the deployment zone configuration to alter the vanity host name or path of the endpoints being promoted.

Back to top

Topology API

In this section:

  • Finding the Topology API Documentation
  • Using the Topology API

Finding the Topology API Documentation

You can find the Topology API documentation in the following locations:

  • In your deployment:
    • Once the Lifecycle Coordinator feature is deployed, a REST API for maintaining topologies is available from the path /lc/api/topologies relative to the container's URL. For example:

      http://myHost:9900/lc/api/topologies

    • You can find Swagger documentation for this API in the container deployment:

      $INSTALL_DIR/docs/restApiDocs/api-platform/swagger-Topology_API.html

  • On the Akana docs site.

Using the Topology API

The first step is to create a Topology. This is done by POST-ing the complete Topology JSON document to ...lc/api/topologies. This can be done programmatically or with a browser plugin such as Firefox RESTClient:

Creating the topology

Note the inclusion of the content-type and basicAuth headers.

Updates to the topology can be performed on the topology as a whole, or on specific properties within the document. For example, the Rules for a PromotionProfile can be updated with a PUT of an array of Rules such as:

[
  {
    "scope":"psep",
    "condition":"psep.url.indexOf(\"foo.com\") > 0",
    "action":"psep.url = psep.url.replace(\"foo.com\",\"bar.com\")"
  }
]

To:

http://myHost:9900/lc/api/topologies/{topology-name}/environments/{environment-name}/profiles/{promotionProfile-name}/rules

Back to top

Lifecycle Manager Console

The Lifecycle Manager (LM) console is useful for accessing promoted assets and their iterations as well as approving promotion requests. Within Lifecycle Manager, a topology is represented as a library and the elements of a Topology along with the entities being promoted are represented as assets.

Logging In

The first step is to log in to the library that corresponds with the topology. There are two options:

  • If the admin user password has been set, you can log into the library as the Lifecycle Repository super user at the URL below:
    {container-base-url}/lm/application/access/suLogin.do
  • If the topology was configured to delegate authentication to a local tenant, you can log in at the URL below, using the tenant email and password for a user in the designated local tenant:
    {container-base-url}/lm/application/access/challenge.do

Viewing Assets and Iterations

The left pane of the LM console contains a search box which can be used for finding assets by name:

Finding assets by name

The search results include separate LM assets for each environment to which a promotable entity has been promoted or is pending promotion. Clicking on an asset in the search results brings up a details page:

Published asset, Details page

In this case, the Current Iteration relationship is referencing the third iteration of this API asset. Click on the iteration asset name to view details about the iteration, as shown below.

Iteration details

Here you can see the following details for this iteration:

  • The time the iteration was promoted
  • The user who requested the promotion
  • The status of the promotion
  • The actual archive.zip (after rule processing) that was imported into the target environment
  • The response from the Import
  • A relationship to the previous iteration for this environment
  • A relationship to the source iteration in the previous environment
  • A relationship to the PromotionProfile that was used to promote the iteration

Additionally, in the case of a promotion failure (generally due to an invalid rule) error details are stored in the Artifacts section of the iteration asset:

Error details

Promotion Requests

The configuration of the topology library can optionally be customized to require approvals for a promotion request. For assistance with customization, contact Akana Professional Services.

In this scenario, a user with the required authorization role has a pending request notification message in the left pane after logging into the LM console:

Pending requests

Clicking on the details for that request allows the user to approve the request:

Approving a pending request

Clicking approve allows the promotion to succeed or proceed to the next role approval.

Rejecting Requests

A user may choose to reject the request by clicking on rejection properties and then clicking reject. In this case, the Iteration asset remains in a Promotion Pending state, however, the API Platform UI shows the state of the promotion as Promotion Rejected and allows the promotion to be requested again.

Back to top

Default API Settings using Runtime Configurations

API Platform Version: 8.4.17 and later

The behavior described in this section is not part of Lifecycle Coordinator, but can be used to augment the capabilities of Lifecycle Coordinator to further tailor the configuration of APIs within each environment of a topology.

The intent of the Runtime Configurations feature is to allow templates for API implementation properties to be established and selectively applied based on custom property filters. This is accomplished through customization of the Lifecycle Manager library in which custom properties for a tenant are configured. This configuration requires a working knowledge of the Lifecycle Manager application and the Configuration Designer Tool.

As with the topology definition, it's best if Runtime Configuration assets are set up during the initial configuration of the environment. Changes to a Runtime Configuration do not retroactively affect pre-existing APIs unless those APIs are updated through the API Platform UI or subsequent promotions.

Creating a Runtime Configuration Asset

You can use the Lifecycle Manager user interface to create assets of type Runtime Configuration. The following image shows the Lifecycle Manager edit page for a Runtime Configuration asset:

Creating a Runtime Configuration asset

The following aspects of a Runtime Configuration asset determine its behavior when applied to an API implementation:

Owning Group

Groups within the Lifecycle Manager library reflect the Organizations of the associated tenant. The Owning Group chosen when creating a Runtime Configuration asset determines the organizational scope that the Runtime Configuration applies to.

For example, if the tenant organization has two child organizations A and B, a Runtime Configuration asset assigned to Group A is applicable to APIs in organization A but not to APIs in organization B. If you choose the tenant organization as the owning group, the Runtime Configuration is applicable to all APIs within the tenant.

Asset Filter

You can further scope the applicability of Runtime Configuration assets by using asset filters. Asset filters are defined in the Library Process Configuration document (LPC) for the library, and specify criteria for the custom properties of the API (known as classifiers within Lifecycle Manager). For example, the filter below selects APIs with the PII custom property set to true:

<asset-filter name="PII APIs">
  <classifier-criteria classifier-category="asset-type">
    <value-set>
      <value>API</value>
    </value-set>
  </classifier-criteria>
  <classifier-criteria classifier-category="pii">
    <value-set>
      <value>true</value>
    </value-set>
  </classifier-criteria>
</asset-filter>

When selecting a value for the Asset Filter classifier, a list of asset filters defined in the LPC as well as implicit filters for the defined asset types in the library will be shown. The filter in the example above would appear as LPC:PII APIs. Selecting the implicit filter asset-type:API indicates that the Runtime Configuration is applicable to all APIs within its owning group.

Note that any filter chosen for a Runtime Configuration should include criteria specifying API as the asset-type.

Implementation Type

This classifier specifies the type of API implementation the Runtime Configuration applies to. The choices are Live and Sandbox.

Policies

A Runtime Configuration asset provides three classifiers that you can use to select policies to be applied to applicable API implementations. These classifiers are:

  • Operational Policy
  • Compliance Policy
  • Service Level Policy

When choosing values for these classifiers, the application will present a list of policies available for the associated tenant with the specified policy type. You can choose one or more policies for each classifier.

Additionally, there are three classifiers that allow you to select policies for the physical service supporting an API implementation using the proxy pattern. These classifiers are:

  • Operational Policy (Physical Service)
  • Compliance Policy (Physical Service)
  • Service Level Policy (Physical Service)

Policy Replacement Behavior

The default behavior for setting policies on an API implementation or physical service is additive, meaning that policies specified by the Runtime Configuration will be added to any existing policies on the implementation or physical service.

Using Configuration Designer, it is possible to customize the Apply Runtime Configuration API post-processing task by setting the Preserve Existing Policies property to false. This indicates that any existing policies on the implementation or physical service that are not specified in the Runtime Configuration will be removed, and replaced by those in the Runtime Configuration.

When the Preserve Existing Policies property is set to false, you can specify the value of NONE for any of the policy classifiers. This indicates that all policies should be removed from the implementation or physical service.

In any case, if a policy classifier has no value in the Runtime Configuration, no action will be taken with the policies associated with the implementation or physical service.

Virtual Host

This classifier is used to set the vanity host name for every endpoint in the implementation. Leaving this classifier unset indicates that the host name of the endpoints should not be modified.

Path

This classifier is used to set the context path for every endpoint in the implementation. Leaving this classifier unset indicates that the context path of the endpoints should not be modified.

Parameter Replacement

The path classifier supports the Lifecycle Manager concept of context parameters. This allows aspects of the API such as the API name or values of custom properties to be used within the path.

For example, setting the path value to /{catalog_asset.name_normalized} indicates that the path should consist of the API's name. If an API had a custom classifier called visibility set to a value external, using a value of /rest/{catalog_asset.classifier.visibility} for the path would result in endpoint paths set to /rest/external.

The available parameters are specified in the Lifecycle Manager Configuration guide (available on the Akana Library site, in the Documentation folder for your Lifecycle Manager installation). Note that the context asset for parameter resolution is the API asset.

Deployment Zones
API Platform Version: 8.4.18 and later

A Runtime Configuration asset can include a Deployment Zones classifier. This allows deployment zones to be designated for deployment of API implementations that match the filter of the Runtime Configuration asset.

When the Deployment Zones classifier is edited, a list of Deployment Zones defined in the associated tenant is displayed. Any number of these deployment zones can be selected. Then, matching API implementations are deployed in the selected deployment zones.

If the Deployment Zones classifier is left empty, the deployment zones of a matching API implementation will not be affected. However, setting the classifier to a value of NONE will result in matching API implementations having no deployment zones enabled.

Settings designated in the Path and Virtual Host classifiers are applied to the endpoints in the designated deployment zones.

Deployment Zone Replacement Behavior

By default, the deployment zones specified on the Runtime Configuration asset replace those already enabled for a matching API implementation.

Using Configuration Designer, it is possible to customize the Apply Runtime Configuration API post-processing task by setting the Preserve Existing Deployment Zones property to true. This indicates that any existing deployment zones enabled for a matching API implementation will be merged with those specified on the Runtime Configuration asset.

Allow Anonymous Access

This classifier is used to set the allow anonymous access value of the implementation. Leaving this classifier unset indicates that the allow anonymous access value of the implementation should not be modified.

Approval Required

This classifier is used to set the approval required value of the implementation. It is only applicable when allow anonymous access is set to false. Leaving this classifier unset indicates that the approval required value of the implementation should not be modified.

Debug Mode Enabled

This classifier is used to set the debug mode enabled value of the implementation. Leaving this classifier unset indicates that the debug mode enabled value of the implementation should not be modified.

Publishing a Runtime Configuration Asset

When edit is complete on a Runtime Configuration asset, it must be submitted. Once any necessary approvals are complete, the Runtime Configuration is published, and is immediately active.

Back to top