Lifecycle Coordinator Promotion: Sample Topologies

This section provides a set of complete sample topologies demonstrating various patterns and configurations.

Table of Contents

• Overview
• Simple two-environment topology with local tenants
• Simple two-environment topology with remote tenants
• Three-environment topology with local and remote tenants
• Three-tenant topology with Fanout
• Conditional topology with environment configuration
• Three-tenant topology using Join feature
• Two-environment topology with disconnected production environment

Overview

The examples in this document build on the information in the Lifecycle Coordinator Promotion Guide, particularly the Topology API section.

It's best to review that document, to get a general understanding of how the promotion feature works, before trying out the API on your tenants.

To create and implement a topology, you'll need to:

1. Have more than one instance of the Community Manager developer portal.
2. Choose the applicable example in this document and customize as needed. For example, for two Smoke tenants or two SaaS tenants, use the Simple two-environment topology with local tenants example.
3. Run the API to implement the product lifecycle topology, using the customized JSON as the body of the POST message. For more information, see Using the Topology API.
4. Log in to the Community Manager developer portal and go to an API Details page to view the Lifecycle Manager pane to the right. of the page.

For additional information on how the Promotion feature appears in the Community Manager developer portal, see:

• Promotion Feature (information for Site Admins)
• Promoting an API to the Next Environment (for API Admins)
• Promoting an App to the Next Environment (for app developers)

Note: In the examples in this document, Local means that the tenants reside on the same API Platform instance as Lifecycle Coordinator. Remote tenants would be tenants residing on a different API Platform instance than Lifecycle Coordinator, in which case communication between Lifecycle Coordinator and the tenant is via REST. For example, two tenants in the same Smoke environment would be local to each other.

Simple two-environment topology with local tenants

In this example, tenant1 has been designated as the authentication tenant, meaning that users logging into the topology library via the Lifecycle Coordinator user interface are authenticated for tenant1.

Line numbers have been added for reference purposes. If you are copying and pasting, remove the line numbers, or use this linked file: promotion_two_environment_local.txt.

01) {
02)   "name":"Topology1",
03)   "properties":[
04)     {
05)       "name":"authentication-tenant-id",
06)       "value":"tenant1"
07)     }
08)   ],
09)   "environments":[
10)     {
11)       "name":"development",
12)       "displayName":"Development",
13)       "tenant":"DevelopmentTenant",
14)       "promotionProfiles":[
15)         {
16)           "name":"Default Production Promotion",
17)           "targetEnvironment":"production"
18)         }
19)       ]
20)     },
21)     {
22)       "name":"production",
23)       "displayName":"Production",
24)       "tenant":"ProductionTenant"
25)     }
26)   ],
27)   "tenants":[
28)     {
29)       "name":"DevelopmentTenant",
30)       "id":"tenant1",
31)       "credentials":{
32)         "email":"administrator1@mycompany.com",
33)         "password":"password"
34)       }
35)     },
36)     {
37)       "name":"ProductionTenant",
38)       "id":"tenant2",
39)       "credentials":{
40)         "email":"administrator2@mycompany.com",
41)         "password":"password"
42)       }
43)     }
44)   ]
45) }

Essentially this JSON defines two tenants, defines two environments, and defines the hierarchy for promoting from one environment to another.

In the above, to customize for your own implementation, update the following values as needed:

• Line 2, name: The name of the topology. Used internally; must be unique. Simple and intuitive is best.
• Line 11, name: An internal description for the first environment in the promotion hierarchy: an internal value. In this example, development.
• Line 12, displayName: The value for the name of the first tenant, that is displayed in the Community Manager developer portal when a user sees the promotion panel and promotion hierarchy. For an illustration, see Promotion panel in the Developer Portal UI: API Designer. In this example, Development.
• Line 17, targetEnvironment: An internal value that defines the environment to which resources will be promoted. In this example, production. Note that the same value is used again on line 22 where the target environment is defined.
• Line 22, name: An internal description for the second environment in the promotion hierarchy: an internal value. In this example, production. Note that in this example the second environment is the target for the first, so this value is the same as the value specified for targetEnvironment on Line 17. Resources promoted from the first environment are promoted to the second.
• Line 23, displayName: The value for the name of the second tenant, that is displayed in the Community Manager developer portal when a user sees the promotion panel and promotion hierarchy. For an illustration, see Promotion panel in the Developer Portal UI: API Designer. In this example, Production.
• Line 24, tenant: An internal value for the name of the tenant. Value must match the value for name in Line 37. In this example: ProductionTenant.
• Line 30, tenants section, id for first tenant: The TenantID. Generally the part of the URL that is after the protocol and before the hostname.
• Lines 32–33, email and password: Login credentials for the first tenant.
• Line 37, name: An internal value for the first tenant. Same value as the value for the tenant property on line 24.
• Line 38, tenants section, id for second tenant: Same as Line 30 above, for the second tenant.
• Lines 40–41, email and password: Login credentials for the second tenant.

Simple two-environment topology with remote tenants

Notes:

• Since no tenant has been designated as the authentication tenant, the topology will default to using a local tenant with the id lifecycle_coordinator for authentication via the Lifecycle Coordinator user interface
• The tenant definitions include an address property, indicating that they are remote.

{
  "name":"Topology1",
  "environments":[
    {
      "name":"development",
      "displayName":"Development",
      "tenant":"DevelopmentTenant",
      "promotionProfiles":[
        {
          "name":"Default Production Promotion",
          "targetEnvironment":"production",
          "rules":[
          ],
          "properties":[
            {
              "name":"match-policies-by-name",
              "value":"true"
            }
          ]
        }
      ]
    },
    {
      "name":"production",
      "displayName":"Production",
      "tenant":"ProductionTenant"
    }
  ],
  "tenants":[
    {
      "name":"DevelopmentTenant",
      "id":"tenant1",
      "address":"http://tenant1:9940",
      "credentials":{
        "email":"administrator1@mycompany.com",
        "password":"password"
      }
    },
    {
      "name":"ProductionTenant",
      "id":"tenant2",
      "address":"http://tenant2:9940",
      "credentials":{
        "email":"administrator2@mycompany.com",
        "password":"password"
      }
    }
  ]
}

Three-environment topology with local and remote tenants

Notes:

• The tenants tenant1 and tenant2 are local; the production tenant (tenant3) is remote.
• The local tenant tenant1 has been designated as the authentication tenant.
• The promotion profiles for development to test promotion and test to production promotion indicate that policies, scripts and processes should all match on name when an API is promoted with such dependencies.

{
  "name":"Topology1",
  "properties":[
    {
      "name":"authentication-tenant-id",
      "value":"tenant1"
    }
  ],
  "environments":[
    {
      "name":"development",
      "displayName":"Development",
      "tenant":"DevelopmentTenant",
      "promotionProfiles":[
        {
          "name":"Default Test Promotion",
          "targetEnvironment":"test",
          "properties":[
            {
              "name":"match-policies-by-name",
              "value":"true"
            },
            {
              "name":"match-scripts-by-name",
              "value":"true"
            },
            {
              "name":"match-processes-by-name",
              "value":"true"
            }
          ]
        }
      ]
    },
    {
      "name":"test",
      "displayName":"Test",
      "tenant":"TestTenant",
      "promotionProfiles":[
        {
          "name":"Default Production Promotion",
          "targetEnvironment":"production",
          "properties":[
            {
              "name":"match-policies-by-name",
              "value":"true"
            },
            {
              "name":"match-scripts-by-name",
              "value":"true"
            },
            {
              "name":"match-processes-by-name",
              "value":"true"
            }
          ]
        }
      ]
    },
    {
      "name":"production",
      "displayName":"Production",
      "tenant":"ProductionTenant"
    }
  ],
  "tenants":[
    {
      "name":"DevelopmentTenant",
      "id":"tenant1",
      "credentials":{
        "email":"administrator1@mycompany.com",
        "password":"password"
      }
    },
    {
      "name":"TestTenant",
      "id":"tenant2",
      "credentials":{
        "email":"administrator2@mycompany.com",
        "password":"password"
      }
    },
    {
      "name":"ProductionTenant",
      "id":"tenant3",
      "address":"http://tenant3:9940",
      "credentials":{
        "email":"administrator3@mycompany.com",
        "password":"password"
      }
    }
  ]
}

Three-tenant topology with Fanout

Notes:

• Since no tenant has been designated as the authentication tenant, the topology will default to using a local tenant with the id lifecycle_coordinator for authentication via the Lifecycle Coordinator user interface
• Tenant1 is local, while the two production tenants (tenant2 and tenant3) are remote.
• The development environment has two parallel unfiltered promotion-profiles, meaning that assets promoted from the development environment will proceed in parallel to both production1 and production2 environments.

{
  "name":"Topology1",
  "environments":[
    {
      "name":"development",
      "displayName":"Development",
      "tenant":"DevelopmentTenant",
      "promotionProfiles":[
        {
          "name":"Production 1 Promotion",
          "targetEnvironment":"production1"
        },
        {
          "name":"Production 2 Promotion",
          "targetEnvironment":"production2"
        }
      ]
    },
    {
      "name":"production1",
      "displayName":"Production1",
      "tenant":"ProductionTenant1"
    },
    {
      "name":"production2",
      "displayName":"Production2",
      "tenant":"ProductionTenant2"
    }
  ],
  "tenants":[
    {
      "name":"DevelopmentTenant",
      "id":"tenant1",
      "credentials":{
        "email":"administrator1@mycompany.com",
        "password":"password"
      }
    },
    {
      "name":"ProductionTenant1",
      "id":"tenant2",
      "address":"http://tenant2:9940",
      "credentials":{
        "email":"administrator2@mycompany.com",
        "password":"password"
      }
    },
    {
      "name":"ProductionTenant2",
      "id":"tenant3",
      "address":"http://tenant3:9950",
      "credentials":{
        "email":"administrator3@mycompany.com",
        "password":"password"
      }
    }
  ]
}

Conditional topology with environment configuration

Notes:

• tenant1 has been designated as the authentication tenant, meaning that users logging into the topology library via the Lifecycle Coordinator user interface are authenticated for tenant1.
• All tenants in the topology are local.
• The topology defines two filters based on the internal classifier. These filters are used on the two promotion-profiles in the development environment, to route the promotion to one of the two production environments based on the value of the internal classifier.
• Deployment Zone mappings are defined on each of the promotion-profiles, to map from the deployment zone used in development to the correct deployment zone in production. These mappings are different for each of the two promotion-profiles.
• The development environment defines a configuration to control the configuration of APIs created in the initial environment:
  • The environment configuration defines two distinct apiImplementationProfiles filtered by the internal classifier.
  • The apiImplementationProfiles deploy the API implementations in distinct deployment zones.
  • The DetailedAuditPolicy is applied to internal API implementations as well as a number of settings on the API implementation such as debugModeEnabled.
  • The path property on each apiImplementationProfile uses a parameter replacement approach to set a path for the implementations that incorporate the name of the API as well as an internal/external qualifier.

{
  "name":"Topology1",
  "properties":[
    {
      "name":"authentication-tenant-id",
      "value":"tenant1"
    }
  ],
  "filters":[
    {
      "name":"internal",
      "classifier-criteria":[
        {
          "classifier-name":"internal",
          "values":[
            {
              "value":"true"
            }
          ]
        }
      ]
    },
    {
      "name":"external",
      "classifier-criteria":[
        {
          "classifier-name":"internal",
          "values":[
            {
              "value":"false"
            }
          ]
        }
      ]
    }
  ],
  "environments":[
    {
      "name":"development",
      "displayName":"Development",
      "tenant":"DevelopmentTenant",
      "promotionProfiles":[
        {
          "name":"Internal Production Promotion",
          "targetEnvironment":"internal-prod",
          "filterNames":[
            "internal"
          ],
          "deploymentZoneConfigurations":[
            {
              "sourceDeploymentZoneName":"Dev1",
              "targetDeploymentZoneNames":[
                "IntProd"
              ]
            }
          ]
        },
        {
          "name":"External Production Promotion",
          "targetEnvironment":"external-prod",
          "filterNames":[
            "external"
          ],
          "deploymentZoneConfigurations":[
            {
              "sourceDeploymentZoneName":"Dev2",
              "targetDeploymentZoneNames":[
                "ExtProd"
              ]
            }
          ]
        }
      ],
      "configuration":{
        "apiImplementationProfiles":[
          {
            "name":"Internal API Profile",
            "type":"Live",
            "filterNames":[
              "internal"
            ],
            "deploymentZones":[
              "Dev1"
            ],
            "allowAnonymousAccess":"false",
            "approvalRequired":"true",
            "debugModeEnabled":"true",
            "virtualServicePolicies":[
              {
                "policyName":"DetailedAuditing"
              }
            ],
            "virtualHost":"InternalHost.com",
            "path":"/{catalog_asset.name_normalized}/internal"
          },
          {
            "name":"External API Profile",
            "type":"Live",
            "filterNames":[
              "external"
            ],
            "deploymentZones":[
              "Dev2"
            ],
            "virtualHost":"ExternalHost.com",
            "path":"/{catalog_asset.name_normalized}/external"
          }
        ]
      }
    },
    {
      "name":"internal-prod",
      "displayName":"Internal Prod",
      "tenant":"ProductionTenant1"
    },
    {
      "name":"external-prod",
      "displayName":"External Prod",
      "tenant":"ProductionTenant2"
    }
  ],
  "tenants":[
    {
      "name":"DevelopmentTenant",
      "id":"tenant1",
      "credentials":{
        "email":"administrator1@mycompany.com",
        "password":"password"
      }
    },
    {
      "name":"ProductionTenant1",
      "id":"tenant2",
      "credentials":{
        "email":"administrator2@mycompany.com",
        "password":"password"
      }
    },
    {
      "name":"ProductionTenant2",
      "id":"tenant3",
      "credentials":{
        "email":"administrator3@mycompany.com",
        "password":"password"
      }
    }
  ]
}

Three-tenant topology using Join feature

Notes:

• Since no tenant has been designated as the authentication tenant, the topology will default to using a local tenant with the id lifecycle_coordinator for authentication via the Lifecycle Coordinator user interface
• All tenants are remote.
• The topology defines two filters based on the internal classifier. These filters are used on the two promotion-profiles in the development environment to route the promotion either to the test environment in the case of an external asset or directly to the production environment in the case of an internal asset. Since the test environment also has a promotionProfile defined pointing to the production environment, the two routes can be thought of as joining at the production environment.

{
  "name":"Topology1",
  "filters":[
    {
      "name":"internal",
      "classifier-criteria":[
        {
          "classifier-name":"internal",
          "values":[
            {
              "value":"true"
            }
          ]
        }
      ]
    },
    {
      "name":"external",
      "classifier-criteria":[
        {
          "classifier-name":"internal",
          "values":[
            {
              "value":"false"
            }
          ]
        }
      ]
    }
  ],
  "environments":[
    {
      "name":"development",
      "displayName":"Development",
      "tenant":"DevelopmentTenant",
      "promotionProfiles":[
        {
          "name":"Test Promotion",
          "targetEnvironment":"test",
          "filterNames":[
            "external"
          ]
        },
        {
          "name":"Direct Prod Promotion",
          "targetEnvironment":"production",
          "filterNames":[
            "internal"
          ]
        }
      ]
    },
    {
      "name":"test",
      "displayName":"Test",
      "tenant":"TestTenant",
      "promotionProfiles":[
        {
          "name":"Default Production Promotion",
          "targetEnvironment":"production"
        }
      ]
    },
    {
      "name":"production",
      "displayName":"Production",
      "tenant":"ProductionTenant"
    }
  ],
  "tenants":[
    {
      "name":"DevelopmentTenant",
      "id":"tenant1",
      "address":"http://tenant1:9920",
      "credentials":{
        "email":"administrator1@mycompany.com",
        "password":"password"
      }
    },
    {
      "name":"TestTenant",
      "id":"tenant2",
      "address":"http://tenant2:9940",
      "credentials":{
        "email":"administrator2@mycompany.com",
        "password":"password"
      }
    },
    {
      "name":"ProductionTenant",
      "id":"tenant3",
      "address":"http://tenant3:9950",
      "credentials":{
        "email":"administrator3@mycompany.com",
        "password":"password"
      }
    }
  ]
}

Two-environment topology with disconnected production environment

Notes:

• Since no tenant has been designated as the authentication tenant, the topology will default to using a local tenant with the id lifecycle_coordinator for authentication in the Lifecycle Coordinator user interface.
• DevelopmentTenant is a standard connected remote tenant.
• ProductionTenant is marked as "connected" : "false" indicating that it is disconnected and Lifecycle Coordinator should not attempt to make calls to it. Note that only the name and id of the disconnected tenant is necessary in the tenant definition.
• Since Lifecycle Coordinator will assume a preserve-keys mode when promoting to the disconnected environment, the production environment is likely a clone of the development environment, so it will be common that the source and target tenants have the same id.
• Note there is no difference in the environment configuration from a standard topology, the designation of a tenant as disconnected affects only the tenant definition.
• The promotion to production specifies that policies should be matched by name.

{
  "name":"Topology1",
  "environments":[
    {
      "name":"development",
      "displayName":"Development",
      "tenant":"DevelopmentTenant",
      "promotionProfiles":[
        {
          "name":"Default Production Promotion",
          "targetEnvironment":"production",
          "properties":[
            {
              "name":"match-policies-by-name",
              "value":"true"
            }
          ]
        }
      ]
    },
    {
      "name":"production",
      "displayName":"Production",
      "tenant":"ProductionTenant"
    }
  ],
  "tenants":[
    {
      "name":"DevelopmentTenant",
      "id":"tenant1",
      "address":"http://tenant1:9920",
      "credentials":{
        "email":"administrator1@mycompany.com",
        "password":"password"
      }
    },
    {
      "name":"ProductionTenant",
      "id":"tenant1",
      "connected":"false"
    }
  ]
}