Lifecycle Coordinator Promotion Guide

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

Sample Topologies

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. Approval Processes (2018.0.0 and later)
    8. Policy Mapping (8.4.16 and later)
    9. Resource Mappings (Scope Mapping) (2018.0.0 and later)
    10. Asset Notifications (8.4.17 and later)
    11. 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. Environment Configuration
    1. API Implementation Profiles
  8. Topology API
    1. Finding the Topology API Documentation
    2. Using the Topology API
  9. Lifecycle Manager Console
    1. Logging In
    2. Viewing Assets and Iterations
    3. Promotion Requests
  10. Support for Decoupled Environments in a Topology
  11. Defaulting API Settings using Runtime Configurations (8.4.17 and later)
    1. Creating a Runtime Configuration Asset
    2. Publishing a Runtime Configuration Asset
  12. Appendix A: Promoting Orchestrated APIs
    1. Referenced Services
  13. Appendix B: Support for client apps (2018.0.0 and later)
  14. Appendix C: Promotion tips and best practices

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

For versions prior to 2018.0.0, 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.

In version 2018.0.0 and later, Lifecycle Coordinator is part of the main Akana API Platform ZIP file; you don't need any additional ZIP file.

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.
To be able to access the Lifecycle Coordinator user interface, a user must be registered in the tenant that's specified as the userAuthenticationSource and must also be assigned one or both of these roles, in Policy Manager: LC User or LC Administrator. See Who can use the Lifecycle Coordinator UI?

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. Updated for 2018.0.0.

When a source and target environment exist in the same API Platform instance, it is necessary to assign new unique IDs (keys) to the internal objects, such as services, that make up an API or app being promoted. This is because the keys must be unique across the API Platform instance, regardless of which tenant they exist in.

By default, Lifecyle Coordinator determines whether to preserve the keys of the promoted objects, or to assign new keys, based on whether the source and target environments exist in the same API Platform instance:

  • If the source and target environments coexist in the same API Platform instance, the platform assigns new keys.
  • If the source and target environments are in different API Platform instances, the platform preserves the original keys from the source environment.

In certain situations, it might be necessary to override the default key handling behavior. For example, assume that environment A is in one API Platform instance and environments B and C coexist in another API Platform instance. If a topology is configured to promote from environment A to environments B and C in parallel, the default key handling algorithm will attempt to assign the same keys to objects promoted to each environment, B and C. The result would be that one of the promotions would fail. In this case, you can override the default key handling behavior by setting the preserve-keys property on one of the Promotion Profiles involved. For example, the Promotion Profiles for environment A would be configured as shown below.

"promotionProfiles": [
{
    "name": "B Promotion",
    "targetEnvironment": "B"
  },
  {
    "name": "C Promotion",
    "targetEnvironment": "C",
    "properties" : [
      {"name":"preserve-keys","value":"false"}
    ]
  } 
]

With this approach, the promoted keys in environment B would match those of the source, while environment C would have new keys assigned, eliminating conflict between the two co-located target environments.

Note: Be cautious in using the preserve-keys property. If the source and target environments are on the same API Platform instance, and the property is set to true, promotions will fail.

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

This section includes:

Tenant Definitions

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

In the promotion profile, you can indicate that authentication for the underlying Lifecycle Repository library is delegated to a 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.

There are two ways you can do this:

  1. By using the userAuthenticationSource property.

    You can set the Boolean userAuthenticationSource property within a Tenant definition to indicate that the tenant will be used for authentication.

    Only one tenant can have the userAuthenticationSource property set to true, and that tenant must be local to the Lifecycle Coordinator. This delegates user definition and authentication to the specified local tenant (a tenant in the same container that Lifecycle Coordinator is deployed in).

    An example is shown below.

    { 
      "name":"DevelopmentTenant",
      "id":"tenant1",
      "credentials":{ 
        "email":"administrator1@roch.soa.local",
        "password":"password1"
      },
      "userAuthenticationSource":true
    },
  2. By setting a tenant ID using the topology-scoped authentication-tenant-id property. (2018.0.0 and later)

    In version 2018.0.0, Lifecycle Coordinator relies on the Akana API Platform for user authentication. Since Lifecycle Coordinator is often deployed separately from tenants in the topology, it might be necessary to delegate authentication and user management to a local tenant that is not in the topology.

    A tenant specified with the authentication-tenant-id property must be local, but doesn't need to be part of the topology.

    An example is shown below.

    {
      "name": "Topology1",
      "properties": [
        {"name":"authentication-tenant-id","value":"authtenant"}
      ],
    ...

If neither of these approaches is used to specify the authentication tenant, the authentication tenant ID defaults to 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

Approval Processes

API Platform Version: 2018.0.0 and later

Simple approval processes involving one or two approver roles can be defined within a PromotionProfile using the approvalProcesses property to call out (in order) the approval roles for the promotion to the target environment. For example, the following PromotionProfile definition for transition to the production environment requires approval from a user with the Architect role, followed by approval from a user with the Promotion Manager role.

{
  "name": "Default Production Promotion",
  "targetEnvironment": "production",
  "approvalProcesses": [
    {
      "type": "api",
      "approvals": [
        "Architect",
        "Promotion Manager"
      ]
    }
  ]
}

The specification of roles in the approvals property causes the specified roles to be implicitly created in the topology library, where users can then be assigned to the roles.

This declarative approach to approval definition is intended to address simple approval processes that do not required property-based filtering, require more than two approval roles, or require special pre- or post-processing tasks. To define advanced approval processes such as this, use Configuration Designer.

Note that if any PromotionProfile in the topology definition defines an approvalProcess, Lifecycle Coordinator assumes that it is managing all submission processes and custom roles for the underlying library and overwrites any customization of those processes or manually defined roles. If the PromotionProfile includes advanced process configuration, do not include approvalProcesses in the topology definition.

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

Resource Mappings (Scope Mapping)

API Platform Version: 2018.0.0 and later

A PromotionProfile can, optionally, include a set of ResourceMappings that can be used to tailor the propagation and validation of resource references representing the scopes assigned to an API and its operations as the API is promoted to the target environment.

A ResourceMapping consists of a sourceResource and a targetResource property, each specifying either the name or ID of a resource in the respective environment. The following PromotionProfile shows an example of a ResourceMapping that maps a resource (scope) by name.

{
  "name": "Default Production Promotion",
  "description": "Dev to production default profile",
  "targetEnvironment": "production",
  "resourceMappings": [
    {
      "sourceResource": {"resourceName" : "DevScope1"},
      "targetResource": {"resourceName" : "ProdScope1"}
    }
  ]
}

Resource mapping can also be done with unique IDs. In the example below, the ResourceMapping uses the unique IDs of the source and target resources.

{
  " sourceResource ":{
    "resourceId":"aa6d2ae0-299d-47d1-a899-f7e6be1b781a.tenant1"
  },
  " targetResource ":{
    "resourceId":"3456bae0-299d-47d1-7799-f7e6be1b221a.tenant2"
  }
}
Default Mapping

By default, Lifecycle Coordinator maps resources (scopes) based on matching names. This means that references from an API to a scope in the source environment will be mapped to a scope of the same name (if it exists) in the target environment regardless of the IDs of the scopes. You can change this default behavior by setting the match-resources-by-name property on the PromotionProfile to false as shown below.

{
  "name": "Default Production Promotion",
  "description": "Dev to production default profile",
  "targetEnvironment": "production",
  "properties": [
    {"name": "match-resources-by-name","value": "false"}
  ]
}
Resource Validation

By default, if a resource referenced by an API or its operations does not match a resource in the target environment (either by ID, by resource mapping, or by default name matching behavior), promotion of the API will proceed without error with the resource reference removed from the promoted API.

You can change this behavior by setting the validate-api-resources property on the PromotionProfile to true, as shown in the example below.

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

With the validate-api-resources property set to true, promotion of an API with an unmatched resource reference will be aborted. A validation error is displayed to the user attempting to promote the resource.

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

Environment Configuration

The configuration property of an Environment is used to customize behavior of assets, such as APIs, that are created or updated in the tenant that the environment is associated with. You can use an environment's configuration to define templating aspects of API implementations. This is similar to the behavior described in the section Defaulting API Settings using Runtime Configurations. This is because the environment configuration automates the creation of Runtime Configuration assets in the tenant library. Further information on the defaulting behavior described here can be found in that section.

The following is a complete example of an Environment Configuration definition.

{
  "name": "development",
  "displayName": "Development",
  "description": "Development environment",
  "tenant": "DevelopmentTenant",
  "configuration": {
    "apiImplementationProfiles": [
      {
        "name": "Internal API Profile",
        "type": "Live",
        "filterNames": [
          "internal"
        ],
        "deploymentZones": [
          "DZ9941"
        ],
        "virtualServicePolicies": [
          {
            "policyName": "DetailedAuditing"
          }
        ],
        "virtualHost": "InternalHost.com",
        "path": "/{catalog_asset.name_normalized}",
        "allowAnonymousAccess": "true"
      },
      {
        "name": "External API Profile",
        "type": "Live",
        "filterNames": [
          "external"
        ],
        "deploymentZones": [
          "DZ9942"
        ],
        "virtualHost": "ExternalHost.com",
        "path": "/{catalog_asset.name_normalized}/external",
        "allowAnonymousAccess": "false",
        "approvalRequired": "true"
      }
    ]
  }
}

API Implementation Profiles

A Configuration contains an apiImplementationProfiles collection. An apiImplementationProfile is used to define the defaults for all API Implementations in the tenant that match the type and filter of the apiImplementationProfile. In the example above, the apiImplementationProfile Internal API Profile will apply to the Live implementations of APIs whose custom properties match the internal filter (defined in the filters property of the topology), while the External API Profile will apply to Live implementations of APIs that match the external filter. Note that the two options for the type property are Live and Sandbox.

An apiImplementationProfile collection can specify:

  • The Deployment Zones that an API Implementation is to be deployed to:

    Specify the deployment zone names in the deploymentZones property (for additional details, see Deployment Zone Configuration.

  • The policies that are to be applied to the Implementation:

    Specify either the policyName or policyId for each policy to be applied.

  • The policies that are to be applied to the physical service of a proxy Implementation (not shown in example above):

    Specify either the policyName or policyId for each policy to be applied within a physicalServicePolicies property.

  • The virtual host for the implementation's endpoints:

    Specify using the virtualHost property.

  • The path for the implementation's endpoints:

    Specify using the path property.

  • Whether the API implementation allows anonymous access:

    Specify in the Boolean allowAnonymousAccess property.

  • Whether access to the API implementation requires approval:

    Specify in the Boolean requiresApproval property.

  • Whether debug mode should be enabled for the API implementation (not shown in example above):

    Specify in the Boolean debugModeEnabled property.

Back to top

Deployment Zone Configuration

The deploymentZones property of an apiImplementationProfile is used to specify which deployment zones and optionally which listeners within a deployment zone should support an API's endpoints. In the simplest case, a deployment zone can be specified with no additional details, as in this example:

{
  "name" : "DZ9941"
}

In this example, APIs that are using this apiImplementationProfile will be deployed to all listeners within the designated deployment zone.

The following example goes a step further and specifies a specific listener within the deployment zone that should be used:

{
  "name": "DZ9941",
  "listeners": [
    {
      "name": "default-http0"
    }
  ]
}

Additionally, listener-specific settings can be defined as in this example:

{
  "name": "DZWest",
  "listeners": [
    {
      "name": "default-http",
      "public": "false",
      "virtualHost": "listenerscopedhost",
      "path": "listenerscopedpath"
    },
    {
      "name": "default-https",
      "useImplementationKeyforSSL": "true"
    }
  ]
}

In this case, two listeners were specified within the DZWest deployment zone. Endpoints deployed in the default-http listener will:

  • Be set to private.
  • Use a listener-specific host name (which overrides the virtualHost property set in the apiImplementationProfile).
  • Use a listener-specific path (which overrides the path property set in the apiImplementationProfile).

Endpoints deployed in the default-https listener are set to use the API Implementation's Key/Certificate for SSL, but will be public by default and will use the virtualHost and path of the containing apiImplementationProfile (if virtualHost and path are specified).

Note: If a deployment zone configuration results in a duplicate endpoint being produced, that endpoint will be omitted from the API.

Replacement Parameters

A limited number of replacement parameters are available for use in setting the virtualHost and path properties at the apiImplementationProfile and listener level of an Environment configuration. To use these parameters, specify the parameter name within braces {<parameter>} within either the virtualHost or path properties. For example:

"path" : "{api.name_normalized}_{api.version_normalized}"

At runtime, the platform replaces these parameters with information from the API. In the above example, an API with name CurrencyConverter and version 1 would result in a path of currencyconverter_1.

The following replacement parameters are currently available:

  • api.name

    The actual name of the API.

  • api.version

    The actual version of the API.

  • api.name.normalized

    The api name, normalized for use as an NM token.

  • api.version.normalized

    The api version, normalized for use as an NM token.

  • api.physical_url_path.live

    The path of the first physical endpoint for the live implementation of the API. This is only applicable when the API implementation is using the proxy pattern.

  • api.physical_url_path.sandbox

    The path of the first physical endpoint for the sandbox implementation of the API. This is only applicable when the API implementation is using the proxy pattern.

  • api.property

    The value of the specified custom API property. For example, if an API has the property classification set to restricted, the parameter {api.property.classification} will resolve to restricted.

Note: A parameter that cannot be resolved or is not recognized will remain in the unresolved form.

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

Support for Decoupled Environments in a Topology

In a standard topology, Lifecycle Coordinator communicates directly with the environments in the topology to:

  • Periodically retrieve context information for the environment (read).
  • Import a promoted asset to the environment (write).

However, in some situations, an environment (generally a production environment) might be physically isolated from Lifecycle Coordinator and other internal systems for security purposes.

Lifecycle Coordinator supports this scenario by allowing tenants to be designated as not connected. This is done using the connected property, as in this example tenant definition:

{
  "name": "ProductionTenant",
  "id": "prod",
  "connected" : "false"
}

In the case where a tenant is marked as not connected, only the tenant's name and id must be specified. Credentials and address are omitted, since Lifecycle Coordinator does not communicate with that tenant.

When a tenant is marked as not connected, Lifecycle Coordinator assumes that it is on a remote system and that the preserve-keys mode is applicable.

Normally, a tenant that is not connected is the final environment in the promotion path.

Because Lifecycle Coordinator cannot communicate directly with a tenant that is not connected, some external system or user must facilitate the exchange of data between Lifecycle Coordinator and the decoupled tenant. The two scenarios are:

Updating Environment Context information

Lifecycle Coordinator needs to have some understanding of the target environment supported by a decoupled tenant so that it can validate for the existence of dependencies when an asset is promoted to that environment. To accomplish this, the promotion context information must be fetched from the decoupled tenant with a GET call to the getEnvironmentPromotionContext operation of the TenantAdministrationAPI on the isolated system.

{host:port}/api/tenants/{tenant id}/{environment name}/promotion/context?includeServiceInfo=true&includeAPIInfo=true

Content-type is application/json.

For example:

GET http://tenant3:9940/api/tenants/tenant3/production/promotion/context?includeServiceInfo=true&includeAPIInfo=true

The resulting JSON document can then be passed as the request body to the TopologyAPI updateEnvironmentContext method on the Lifecycle Coordinator system using a PUT call to:

{host:port}/lc/api/topologies/Topology1/environments/{environment name}/context

For example:

PUT http://localhost:9920/lc/api/topologies/Topology1/environments/production/context

This process should be repeated when any relevant context information in the decoupled environment changes. For example, a new policy or organization is added in the decoupled tenant.

Promoting Assets

Since Lifecycle Coordinator cannot directly call the import API on the decoupled tenant, you'll need to take some extra steps to promote to that environment.

To promote assets for a decoupled tenant
  1. Request promotion of the API to the decoupled environment in the normal way, using the API Platform user interface or via the TopologyAPI promote operation (see Topology API).

    When the promotion is complete, the status of the asset for the decoupled environment shows as promoted. In this case, the promoted status indicates that all processing of the archive has been completed and the archive is ready for importing into the target environment.

  2. Use the getPackage method in the TopologyAPI to retrieve the processed import package from Lifecycle Coordinator:
    GET {host:port}/lc/api/topologies/{topology-name}/environments/{environment-name}/assets/{asset-id}/package

    In this operation, {asset-id} is either an API version ID or App version ID. For example:

    GET http://localhost:9920/lc/api/topologies/Topology1/environments/production/assets/ffc4ba19-c5cb-4e9d-ae39-78ab6e0efc84.tenant1/package

    This returns the archive as a ZIP file.

  3. On the isolated system, upload the archive ZIP file to the decoupled tenant in one of these ways:

Back to top

Defaulting API Settings using Runtime Configurations

API Platform Version: 8.4.17 and later

Note: As of the 2018.0.0 release, the behavior in this section can now be defined within the topology directly, using the Environment Configuration element. See Environment Configuration.

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 Filters

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 in the Runtime Configuration are added to any existing policies on the implementation or physical service. However, you can customize the default behavior to control policy replacement behavior.

Here are a couple of examples of how this could be used:

  • Adding a policy: Let's say there is a two-environment topology, dev and prod, and the topology is configured so that policies from dev are preserved when promoting, but you also want to make sure that the production-level security policy is in place for all APIs that are PCI-compliant. You could set up a Runtime Configuration with a pci = true filter that specifies the production-level security policy, but you probably wouldn't want to remove other policies the API may have. In this scenario, you could set the preserve-existing-policies property to true. The new policy is in addition to any existing policies.
  • Replacing existing policies: Let's say you want to completely automate the assignment of policies to APIs, managing it entirely based on properties set on the API. In this case, you could set the preserve-existing-policies property to false. The Runtime Configuration would then overwrite any policies that were manually set or were in the promotion from an earlier environment. The policies in the Runtime Configuration would replace all existing policies.

There are two ways that you can customize policy replacement behavior:

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.

Setting the preserve-existing-policies property

You can customize the Apply Runtime Configuration API post-processing task using the Configuration Designer 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 the example below, the preserve-existing-policies property is set to false in an environment configuration of a topology.

"configuration": {
  "properties" : [
    {"name":"preserve-existing-policies","value":"false"}
  ],
  "apiImplementationProfiles": [ 
  ...
  ]
}

Setting the ENV:preserve-existing-policies property in the repository library (2018.0.0 and later)

In the example below, the ENV:preserve-existing-policies library property is set directly in the LPC document of the repository library.

<library-properties>
  <property name="ENV:preserve-existing-policies">
    <value>false</value>
  </property>
</library-properties>
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 Classifier

The path classifier supports the Lifecycle Manager concept of context parameters. It is used to set the context path for every endpoint in the implementation. This allows aspects of the API, such as the API name or the values of custom properties, to be used within the path.

If you leave the path classifier unset, the default API context path, assigned by the API portal, applies to the API created by the runtime configuration. However, you can use one or more of the path classifiers to control the context path for the API created using the configuration. See examples below.

The following parameters are available to be used for the path classifier:

  • {catalog_asset.id}

    Indicates that the path should include the asset ID (APIID, App ID, or UserID, depending on the asset that the Runtime Configuration is applied to).

  • {catalog_asset.name}

    Indicates that the path should include the asset name (for example, App03). If you're not sure what the asset name is, check in the Lifecycle Coordinator, as shown below. In this example, the asset name is Training-1.

    Path classifier example -- input

  • {catalog_asset.name_normalized}

    Indicates that the path should include the API's name, with normalization applied for any spaces or other characters that are not URL-safe. For normalization rules, see Normalization in Classifiers below.

  • {catalog_asset.version}

    Indicates that the asset path should include the version.

  • {catalog_asset.version_normalized}

    Indicates that the asset path should include the version, with normalization applied for any spaces or other characters that are not URL-safe. For example, version 1 becomes version_1. For normalization rules, see Normalization in Classifiers below.

  • {catalog_asset.property.<property name>}

    Indicates that the value of a specific property defined for the API should be used in the context path.

  • {catalog_asset.classifier.<classifier name>}

    Indicates that the value of a specific classifier defined for the API should be used in the context path. For example, 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.

  • {catalog_asset.group.name}

    The group name, as defined in the Lifecycle Coordinator user interface, corresponds to the organization name as defined in the developer portal. If this classifier is used, the group/organization name is included in the API context path. See example below.

Note: The above is a list of key path classifiers. For a complete list, refer to the Lifecycle Manager Configuration guide.

Example #1: No path classifier set

If no path is specified in the Runtime Configuration, the default path is assigned when the API is created in the developer portal. An example is shown below.

Path classifier example -- unset

Example #2: Three classifier values

In the example below, three values are concatenated: {catalog_asset.group.name}, {catalog_asset.version_normalized}, and {catalog_asset.name_normalized}.

In the Runtime Configuration:

Path classifier example -- concatenated with three

The resulting API path, as displayed on the API Details page in the developer portal, is shown below.

Path classifier example -- concatenated with three: result

Example #3: Four classifier values

In the example below, four values are concatenated: {catalog_asset.group.name}, {catalog_asset.classifier.<classifier name>}, {catalog_asset.version_normalized}, and {catalog_asset.name_normalized}.

Path classifier example -- concatenated with three

The resulting API path, as displayed on the API Details page in the developer portal, is shown below.

Path classifier example -- concatenated with three

Normalization in Classifiers

If you use a path classifier that includes normalization, the following rules are applied.

  • Uppercase is changed to lowercase, so all letters are lowercase.
  • Any characters other than the below are removed:
    • letters
    • numbers
    • Period (.)
    • Dash (-)
    • Underscore (_)
    • Colon (:)

For example, a space in an API name or API version name would be removed.

Deployment Zones

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. This section includes:

Basic Deployment Zone Configuration

API Platform Version: 8.4.18 and later

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.

Advanced Deployment Zone Configuration

API Platform Version: 2018.0.0 and later

While the Deployment Zones classifier mentioned above can specify deployment zones for an API to be deployed to, it is sometimes necessary to also specify listeners within a deployment zone as well as specific settings for each listener. If this level of granularity is needed, the Deployment Zones classifier should be left unset and instead the Deployment Zone Configuration artifact in the Runtime Configuration asset should be used. This artifact should be a JSON document containing a JSON array of deploymentZone properties in the same format as shown for the deploymentZones property of an Environment Configuration (link to Environment Configuration section). Here is a sample Deployment Zones Configuration document:

[
  {
    "name": "DZ9921"
  },
  {
    "name": "DZ9941",
    "listeners": [
      {
        "name": "default-http0",
        "public": "false",
        "virtualHost": "{api.property.internal}",
        "path": "{api.name_normalized}_{api.version_normalized}"
      },
      {
        "name": "default-https",
        "useImplementationKeyforSSL": "true"
      }
    ]
  }
]

Note that only the deployment zone name is required in each deploymentZone property. Also be aware that there is no configuration-time validation of the information specified in the Deployment Zones Configuration document, so care must be taken to ensure that it is in sync with the actual deployment zones and listeners defined in the API platform instance.

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

Appendix A: Promoting Orchestrated APIs

API Platform Version: 2018.0.0 and later

Unlike a standard proxy-pattern API, APIs implemented as orchestrations could have dependencies on scripts, processes, or services not contained within the API itself. When promotion is requested for an orchestrated API, all such external dependencies are checked to make sure they exist in the target environment. If there are unmet dependencies, the promotion is aborted and a notification specifying the unmet dependencies is provided to the user.

In the case of external scripts and processes, the promotion process attempts to match the referenced script or process in the target environment based on the key of the object.

Mapping of processes and scripts between environments can be specified within a Promotion Profile using the processMappings and scriptMappings properties respectively. The processMappings and scriptMappings properties allow you to correlate source and target scripts/processes either by ID or by name.

This section includes the following examples of defining process and script mappings:

Defining process and script mappings by using IDs

In the example Promotion Profile below, processes and script mappings are defined using IDs.

{
  "name": "Default Production Promotion",
  "targetEnvironment": "production",
  "scriptMappings":[
    {
      "sourceScript" : {"scriptId" : "script:7f4fbb16-8389-11e8-af80-80b01a868d88"},
      "targetScript" : {"scriptId" : "script:fb51d840-8399-11e8-af80-80b01a868d88"}
    }
  ],
  "processMappings":[
    {
      "sourceProcess" : {"processId" : "bpel:8c862595-8389-11e8-af80-80b01a868d88"},
      "targetProcess" : {"processId" : "bpel:b2ad95b6-839b-11e8-af80-80b01a868d88"}
    }
  ]
}
Defining process and script mappings by using names

In the example below, processes and script mappings are defined by name.

{
  "name": "Default Production Promotion",
  "targetEnvironment": "production",
  "scriptMappings":[
    {
      "sourceScript" : {"scriptName" : "Dev Script A"},
      "targetScript" : {"scriptName" : "Prod Script A"}
    }
  ],
  "processMappings":[
    {
      "sourceProcess" : {"processName" : "Dev Process A"},
      "targetProcess" : {"processName" : "Prod Process A"}
    }
  ]
}
Defining process and script mappings by using the match-processes-by-name and match-scripts-by-name properties on the Promotion Profile

Optionally, the properties match-processes-by-name and match-scripts-by-name can be set on the Promotion Profile, to allow the promotion logic to map referenced scripts or processes based on the name rather than the key of the object. For example, the example below shows a Promotion Profile allowing matching of both processes and scripts by name.

{
  "name": "Default Production Promotion",
  "description": "Dev to production default profile",
  "targetEnvironment": "production",
  "properties" : [
    {"name":"match-scripts-by-name","value":"true"},
    {"name":"match-processes-by-name","value":"true"}
  ]
}

Referenced Services

An orchestration of an API operation might use invocation actions to call out to other services. Such invocations specify the target service, operation, and endpoint to use in the invocation. The target service of an invocation must exist in the target environment prior to promoting the orchestrated API. There are two scenarios:

  • Remote tenants, where keys are preserved across environments: A service with a matching key must already exist in the target environment.
  • Local tenants, where keys are mapped across environments: The API containing the target service must have been previously promoted using Lifecycle Coordinator.

The most common case of service invocation is a call to a physical service. Often, the URL of a physical service is modified for use in the target environment using rules in the Promotion Profile. In this case, the URL of the endpoint of the invocation should be similarly modified. The following example shows the rules that would be defined in a Promotion Profile for changing the host name of physical service URLs along with the invocation references (using the serviceRef scope).

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

Back to top

Appendix B: Support for client apps

API Platform Version: 2018.0.0 and later

Currently, the API Platform allows contracts to be established between apps and APIs, but does not support direct API to API access. This can be mitigated through the use of a pattern where an API is represented with a client App. With this approach, each API has an accompanying client app that is used to establish access to other APIs for the represented API. Contracts between a client app and another API are logically contracts between the source and target APIs, allowing for full dependency analysis of composite APIs.

You can configure the API Platform Repository plug-in to support the client app pattern by adding the Create Client App task to the post-processing phase of the API submission process. For additional information about configuring a submission process, contact Rogue Wave Technical Support. This task will cause a client app to be created as each API is created. The client app will be named as {api name}_app and a client-app property will be set on the represented API pointing to the client app. The generated client app will, in turn, have a represented-api property to point back to the API.

Note that the Create Client App task can be configured to run based on the setting of a custom property on the API, such as isConsumer, allowing the creator of the API to determine whether a client app is needed.

Promotion Support

When an API with an accompanying client app is promoted using Lifecycle Coordinator, the client app will also be promoted to the target environment as well as any contracts it has to other APIs. These contracts will be validated prior to API promotion in the same manner as the dependencies for a standard app are validated prior to app promotion.

Back to top

Appendix C: Promotion tips and best practices

When making changes to an asset in the hierarchy, always make changes in the Dev environment (or whichever environment is first in the promotion chain). If you make changes in a later environment, they will be lost on a subsequent iteration.

Back to top