Lifecycle Coordinator Promotion Guide

Provides information about how to use the Lifecycle Coordinator feature to manage promotion of assets, such as apps and APIs, from one environment to another, such as from Development to Testing.

Table of Contents

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.

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.

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 can 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

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.

Lifecycle Coordinator Installation

For installation information, refer to Lifecycle Coordinator Installation.

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. Because these are local tenants, the address attribute is not included.

{
  "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"
    }
  ]
}

For additional sample topologies, see Lifecycle Coordinator Promotion: Sample Topologies.

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.

    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

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.

Configuring a tenant to support LDAP login (2019.1.5 and later)

In versions prior to 2019.1.5, Lifecycle Coordinator only supported logging in to a Community Manager developer portal tenant via the Local Domain.

In the tenant definition, the credentials are defined as email and password property values, as shown in the example below.

"credentials":{
  "email":"administrator2@example.com",
  "password":"password2"
}

In 2019.1.5 and later, you can configure Lifecycle Coordinator to support logging in via LDAP instead of the local domain.

To allow Lifecycle Coordinator to log in to the Community Manager developer portal via LDAP, include the ldapDomain property in the tenant definition, at the same level as the credentials property. The value of the ldapDomain property must match the domain name configured in Policy Manager.

Example tenant definition using the ldapDomain property and user and password credentials:

"tenants":[
  {
    "id": "tenant2",
    "name": "ProductionTenant",
    "address": "http://open.acmepaymentscorp.com:9910",
    "local": false,
    "consoleAddress": "http://open.acmepaymentscorp.com:9910/atmosphere",
    "ldapDomain": "acmepaymentscorp",
    "credentials": {
      "user": "my_username",
      "password": "my_secure_password"
    },
    "userAuthenticationSource": false
  }

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":[
      {
        "classifier-name":"pci-compliant",
        "values":[
          {
            "value":"true"
          }
        ]
      }
    ]
  },
  {
    "name":"PCI Non-Compliant",
    "classifier-criteria":[
      {
        "classifier-name":"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}' "
        }
      ]
    }
  ]
}

Approval Processes

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.

Organization Mapping

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

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 Community Manager 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.

Resource Mappings (Scope Mapping)

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.

API Visibility Mapping

API Platform Version: 2019.1.0 and later

A PromotionProfile can include a set of ResourceMappings that can be used to tailor the visibility of an API version when the API is promoted to the target environment.

For example, in the source tenant the API version visibility might be set to Public, but you might want to set it to Private in the target tenant. You could accomplish that with the rule shown below.

"rules":[
  {
    "scope":"apiVersion",
    "condition":"apiVersion.visibility == 'Public'",
    "action":"apiVersion.visibility = 'Private'"
  }
]

App Visibility Mapping

API Platform Version: 2019.1.0 and later

A PromotionProfile can include a set of ResourceMappings that can be used to tailor the visibility of an app version when the app is promoted to the target environment.

For example, in the source tenant the app version visibility might be set to Registered Users, but you might want to set it to Private in the target tenant. You could accomplish that with the rule shown below.

"rules":[
  {
    "scope":"appVersion",
    "condition":"appVersion.visibility == 'Registered Users'",
    "action":"appVersion.visibility = 'Private'"
  }
]

Asset Notifications

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

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

You can set the following properties on a PromotionProfile:

For examples, see Properties: examples.

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.

Default: false.

match-policies-by-name

Adding this property, with 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.

Default: false.

preserve-outbound-identities

API Platform Version: 2019.1.0 and later

Adding this property, with a value of true, indicates that the outbound identities of an existing service are not changed as a result of the promotion process.

For example, without this property present, the target API identity mapping is overwritten with the values set in the source API. With the property set to true, the identities in the target API are not affected by promoting the API. The original values are preserved in the target API.

Default: false.

preserve-shared-secret

API Platform Version: 2019.1.2 and later

Adding this property, with a value of true, indicates that the shared secret of an existing app in the target environment, is not changed as a result of the promotion process.

Without this property present, the app shared secret value in the target environment is overwritten with the app shared secret value from the source environment. With this property set to true, the shared secret value in the target app is not affected by promoting the app. The original value is preserved in the target app.

Default: false.

disable-consumer-app-check

API Platform Version: 2019.1.2 and later

In some scenarios, you might want to set up your platform so that when an API is added, a consumer app is created automatically.

In this scenario, if you are using fanout (promoting to more than one environment), you might choose to promote the consumer app to one environment but not another.

The disable-consumer-app-check property allows you to disable the check, so that the API is promoted without the consumer app.

Adding this property, with a value of true, indicates that the promotion process will not check for a consumer app and will not fail if the consumer app is not present.

Default: false. If this property is not present, or is set to false, the existing consumer app promotion behavior is applied.

In the example below, the promotion profile promotes to two different environments. The disable-consumer-app-check property is set to true for one target environment, and is set to false for the other.

  "environments": [
    {
      "name": "dev1",
      "displayName": "dev1",
      "description": "Development environment",
      "tenant": "dev1",
      "initialEnvironment": true,
      "promotionProfiles": [
        {
          "name": "Default Testing Promotion",
          "description": "Dev to Testing default profile",
          "targetEnvironment": "test1",
          "properties" : [
            {"name":"match-policies-by-name","value":"true"},{"name":"disable-consumer-app-check","value":"true"}
          ]
        },
        {
          "name": "Default Testing Promotion 2",
          "description": "Dev to Testing 2 default profile",
          "targetEnvironment": "test2",
          "properties" : [
            {"name":"match-policies-by-name","value":"true"},{"name":"disable-consumer-app-check","value":"false"}
          ]
        }
    ]},
    {
      "name": "test1",
      "displayName": "test1",
      "description": "Testing environment",
      "tenant": "test1"
    },
    {
      "name": "test2",
      "displayName": "test2",
      "description": "Testing environment 2",
      "tenant": "test2"
    }
  ],

Properties: examples

Example #1: sets the export-pki value.

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

Example #2: Sets match-policies-by-name and preserve-outbound-identities.

{
  "name":"Topology",
  "environments":[
    {
      "name":"dev1",
      "displayName":"dev1",
      "description":"Development environment",
      "tenant":"dev1",
      "initialEnvironment":true,
      "promotionProfiles":[
        {
          "name":"Default Testing Promotion",
          "description":"Dev to Testing default profile",
          "targetEnvironment":"test1",
          "properties":[
            {
              "name":"match-policies-by-name",
              "value":"true"
            },
            {
              "name":"preserve-outbound-identities",
              "value":"true"
            }
          ]
        }
      ]
    },
    {
      "name":"test1",
      "displayName":"test1",
      "description":"Testing environment",
      "tenant":"test1"
    }
  ],
  "tenants":[
    {
      "name":"dev1",
      "userAuthenticationSource":true,
      "id":"dev1",
      "credentials":{
        "email":"administrator@open.akana.com",
        "password":"password"
      }
    },
    {
      "name":"test1",
      "id":"test1",
      "address":"http://open.akana.com:9910",
      "consoleAddress":"http://open.akana.com:9910/atmosphere",
      "credentials":{
        "email":"administrator@open.akana.com",
        "password":"password"
      }
    }
  ]
}

Deployment Zone Configurations

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": [
      {
        "classifier-name": "pii",
        "values": [
          {
            "value": "true"
          }
        ]
      }
    ]
  },
  {
    "name": "not-pii",
    "classifier-criteria": [
      {
        "classifier-name": "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.

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":[
          {
            "name":"DZ9941"
          }
        ],
        "virtualServicePolicies": [
          {
            "policyName": "DetailedAuditing"
          }
        ],
        "virtualHost": "InternalHost.com",
        "path": "/{catalog_asset.name_normalized}",
        "allowAnonymousAccess": "true"
      },
      {
        "name": "External API Profile",
        "type": "Live",
        "filterNames": [
          "external"
        ],
        "deploymentZones":[
          {
            "name":"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.

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.

Topology API

In this section:

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, in the generated REST API documentation. Choose the correct version and then scroll down or search on the page for the Topology API.

Using the Topology API

This section includes a few examples of using different operations from the Topology API. For more information refer to the Topology API documentation referenced above. Operations covered here:

Create a topology

The first step is to create a topology. To do this, use the POST operation to send the topology information in JSON format. You can do this programmatically or with a browser plugin such as Firefox RESTClient as shown in the example below.

Creating the topology

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

In the above:

  • HTTP operation: POST.
  • URL: {protocol}://{hostname}/lc/api/topologies.

    For example: https://janemead01.apiportal-smoke.akana.com/lc/api/topologies

  • Body: Construct as needed. For example, Simple two-environment topology with local tenants with values updated as needed.
  • Content-Type: application/json
  • Authorization: Basic Auth (authentication is via your login credentials, which are sent with the API call) or as specified for your installation.

View information about a topology

To view information about an existing topology, you'll need the name of the topology you already created. Properties of the API call:

  • HTTP operation: GET.
  • URL: {protocol}://{hostname}/lc/api/topologies/{topology_name}

    For example: https://janemead01.apiportal-smoke.akana.com/lc/api/topologies/Topology1

  • Accept: application/json
  • Authorization: Basic Auth (authentication is via your login credentials, which are sent with the API call) or as specified for your installation.

Update topology rules

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

In the above:

  • HTTP operation: PUT.
  • URL: {protocol}://{hostname}/lc/api/topologies/{topology-name}/environments/{environment-name}/profiles/{promotionProfile-name}/rules

    For example: https://janemead01.apiportal-smoke.akana.com/lc/api/topologies/Topology1/environments/Development/profiles/PromotionProfile_01/rules

  • Body: As shown in the example above. Update values as needed.
  • Content-Type: application/json
  • Authorization: Basic Auth (authentication is via your login credentials, which are sent with the API call) or as specified for your installation.

Authentication on the Topology API

there are two ways to secure the Topology API:

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.

In this section:

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.

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 Finding the Topology API documentation).

    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:

"Client app" approach to supporting API to API contracts

The API Platform allows contracts to be established between apps and APIs, but does not support direct API to API access. In most cases this is not needed. However, API to API access is supported in the underlying infrastructure, and if it's needed you can support it by using a pattern where an API is represented with a client App.

Let's say you're migrating from the underlying infrastructure (Policy Manager) to Community Manager, and your implementation includes API to API contracts. You can use a configuration in Lifecycle Repository to designate whether an API is Consumer or not. If it is, Lifecycle Repository automatically creates an app with the API. This app is tied to the API and replaces the "API to API contracts" concept in Policy Manager. When the API is promoted, the Client App is automatically promoted with it.

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.

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. 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.

For additional information about configuring a submission process, contact Akana Technical Support.

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.

Note: If you want to promote an app that has been given access to an API (contract has been created), this is not the approach to use. For information about the steps to take in this scenario, see Promotion sequence for app with API contract.

Defaulting API Settings using Runtime Configurations

The Runtime Configuration section which was previously in the Promotion Guide is now in a separate document with other content relating to custom properties.

Runtime Configuration 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.

For details, see Defaulting API Settings using Runtime Configurations (Lifecycle Repository documentation).

Appendix A: Promoting Orchestrated APIs

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\")"
  }
]

Appendix B: Promotion tips and best practices

This section includes:

Make changes in earlier environment

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.

Promotion sequence for app with API contract

If you want to promote an app that has been given access to an API (contract has been created), follow this sequence:

  1. First, promote the API to the target environment.
  2. Then, promote the app. At that point, the contract is promoted with the app.