Migrating from a Staging to a Production Environment

Contents

Overview

The Policy Studio enables you to manage Configuration Profiles for Oracle Enterprise Gateways in development, test, and production environments. You can use the Profile Management tab on the Enterprise Gateway Dashboard to transfer and migrate policies from one environment to another.

For example, a Configuration Profile is first designed in a development environment by a developer. The developer deploys this Configuration Profile to a Process in the development environment. Using the Policy Studio, the developer can create a version for each significant change they make to the Configuration Profile, which enables them to roll back to a previous version if required.

When the developer has finished, a test engineer takes the Configuration Profile from development and deploys it to a process in the QA environment to perform system testing. During testing, the developer may be required to make changes to the Configuration Profile, and pass them to the QA environment. The QA engineer merges these changes into the test Configuration Profile, creating a new version for each significant update. Finally, when testing is complete, the final version of the Configuration Profile is deployed to a production environment.

This topic describes the recommended steps for moving a Configuration Profile from one environment to another. The approach is the same regardless of moving from development to test, or from test to production. This topic refers to the source and target environment, where both the source and target may be development, test, or production. It describes how a new Configuration Profile is transferred from one environment to another, and how incremental changes are made and need to be merged from one environment to another.

Accessing Environments

You can use a single Policy Center server to manage all Configuration Profiles and Processes across development, test, and production environments. However, in some cases, the various environments are on completely different networks. In this case, separate instances of the Policy Center server may be required.

To perform a transfer or merge of a Configuration Profile from one environment to another, the source and target Configuration Profiles must be available in the same Policy Center server instance. The User performing the merge must be permitted to load both Configuration Profiles into the Profile Editor tab in the Profile Management screen.

You can transfer Configuration Profiles between Policy Center instances in test and production environments by first exporting the Configuration Profile using the Policy Studio connected to the Policy Center server in the test environment. You can then import the Configuration Profile to create a new Configuration using the Policy Studio connected to the Policy Center server in the production environment.

Configuration that Differs between Environments

For example, assume that all policies in the Configuration Profile are the same between the source and target environments (for example, test and production). The only items that differ between environments are those that refer to external resources because there are both test and production instances of these items. Differences are to be expected in the following configuration entities:

  • Hosts, ports, and URLs to external resources (for example, database connections, LDAP directories, back-end Web Services, and so on)
  • Connection credentials to external resources (for example, username/password, SSL keys, and certificates)
  • Keys and certificates (for example, for signing a message, or for SSL connectivity between the Process and clients)

Naming Configuration Entities

To keep a merge operation as straightforward as possible, the names of all configuration entities should be the same in both the source and target environment. For example, policy name should be the same and the names of filters in policies should also be the same.

The differences between configuration entities must be kept at the lowest level possible. For example, you have an HTTP Basic authentication filter that authenticates the username and password against a database repository. When configuring this filter, enter a name for the filter, a name for the repository, and a name for the database connection. All of these names should be the same in the source and target Configuration Profiles.

However, when configuring the details of the database connection, the URL, Username, and Password fields differ between environments. You could, enter the name of the database connection differently in the source and target Configuration Profiles (for example, Test System Database and Production System Database). However, Oracle recommends that you name the database connection as the same in both (for example, System Database). This keeps the differences at the lowest level possible, which makes the merge operation easier.

All certificates should have an associated environment-independent alias name. The alias name should be the same in both the source and target environments. Note that the default alias name is the distinguished name of the certificate, which should not be used when merging Configuration Profiles from a source to a target environment.

For example, assume that the Enterprise Gateway server SSL certificate in the testing environment has a distinguished name of CN=test-host.acme.com, C=ie. The production Enterprise Gateway server SSL certificate has a distinguished name of CN=production-host.acme.com, C=ie. By assigning an alias of Server SSL Certificate, the certificate used for the same purpose in the test and production environments can be identified using the same alias name. The alias name is assigned when a certificate is created or imported, and can be updated at any time using the Certificates panel.

Initial Transfer from Source to Target Environment

Assume that the source Configuration Profile is available to the User in their Policy Center server instance. For information on how to transfer Configuration Profiles managed by multiple server instances, see Accessibility of Environments. Initially, there is no target Configuration Profile because this is the initial transfer of a Configuration Profile (the first time to set up an environment). To perform an initial transfer of configuration from a source to a target environment, do the following:

Create a copy of the source configuration
Perform the following steps:

  1. On the Profile Management tab, select the source Configuration Profile, right-click, and select Create via Copy.
  2. Enter a name for the new Configuration Profile (for example, Production Configuration).
  3. Enter an optional comment (for example, Copied from Testing Configuration).
  4. Click OK.

Update external resources to point to the target environment
You now have a target Configuration Profile, but it is not yet ready to deploy to the target Process. Right-click the new target Configuration Profile, and select Edit to load the Configuration Profile into the Profile Editor tab.

You must manually find all configuration entities that refer to external resources in the source environment and update them to point to resources in the target environment.

Deploy to the target environment
Having gone through each environment-specific configuration entity and reconfigured it to point to a target environment resource, you must now create a new version using the Commit Version menu option. You are now ready to deploy the target Configuration Profile to the target Process in the target environment (for example, the Enterprise Gateway in the production environment).

In the Policy Studio, select the target Process on the Deployment Details tab on the Enterprise Gateway Dashboard. Select the Configuration Profile, and click the Deploy button to deploy the Configuration Profile to the Process.

Configuration that may need to be Modified

The following list highlights the configuration entities that may need to be modified:

Certificates, Keys, and URLs:
Certificates, keys, and CRLs differ between source and target environments. As described above, each certificate should have the same alias name in the source and target environments. Use the Certificate tree node to view all certificates in the opened Configuration Profile in the Profile Editor tab. Select each certificate, and click the Edit button. Import the target environment certificate, (or key and certificate), and save the changes. Leave the alias name unchanged.

The following configuration entities may refer to certificates:

  • HTTPS Interface
  • File Logger
  • Database Logger
  • The following Filters:
    SAML Assertion Insertion filters, SAML PDP filters, WS-Security Username Token filters, XML-Signature Generation and Verification filters, CRL(static) filter, Certificate Chain filter, Find Certificate filter, Connection filter
  • The following External Connections:
    OCSP Connection, XKMS Connection, URL Sets (Entrust, OCSP, SAML PDP, XKMS)

Using the alias name, the reference to the Certificate appears constant across the source and target environments (the alias name is displayed). No changes need to be applied to the configuration entities listed above.

CRLs:
All static CRLs that are specific to the source environment must be removed and replaced with the target environment CRLs. This must be done using the Static CRL filter.

External Connections:
An easy way to find a lot of the external resources is to open the External Connections profile in the Profile Editor tab. All child nodes (with the exception of the Authentication Repository Profiles) potentially point to resources that are environment-specific. Take care when updating these resources to leave the Name fields the same (only update the fields that really need to be changed).

Alert Systems:
The system that a Process sends an alert to is an external resource (Email, SNMP, OPSEC, Windows Event Log, and Local Syslog or Remote Syslog). Use the Alerts node in the opened External Connections profile in the Profile Editor tab to update these items to point to resources in the target environment. As before, leave all Name fields unchanged. Update all other fields as required.

UDDI Registry Connection:
The UDDI Registry Connections are currently only used by the Policy Studio to locate WSDL files. The connections contained in a Configuration Profile may need to be updated to point to a UDDI registry in the target environment. In the Core Configuration profile, right-click the Web Service node under the Web Service Repository node, and select the Register Web Service menu option. Select the WSDL from UDDI option, and click the Browse UDDI button. Edit all Registry Connections from the first wizard page, ensuring that the Registry Name field remains unchanged. Update all other fields as required.

Remote Host:
Remote Host configuration may differ between source and target Configuration Profiles. You can find Remote Hosts under the Process node in the Core Configuration on the Profile Editor tab. Modify these manually to point to a target environment server after copying the source Configuration Profile.

JMS Service:
JMS Service configuration may differ between source and target Configuration Profiles. JMS Services can be found under the Process node in the Core Configuration on the Profile Editor tab. Modify these manually to point to a target environment server after copying the source Configuration Profile. Note that a JMS Service is referred to as the Messaging system filter. This is updated in the filter automatically.

Static Router Filter:
The Static Router filter Host field refers to the back-end Web Service to which messages are routed. This hostname may differ between source and target environments. Oracle recommends that you do not enter a physical hostname here, instead enter the name of a Remote Host that maps to the physical host. You can configure Remote Hosts by right-clicking the Process node in the Core Configuration on the Profile Editor tab. The Remote Host configuration differs between the source and target environments, while the Static Router remains constant. Note that the Name field value of the Remote Host must be the same in both environments.

SMTP Filter:
The SMTP filter refers directly to the SMTP server. You must modify this filter manually to point to a target environment server if the copied source Configuration Profile contains this filter.

Comparison of Source and Target after Initial Transfer

It is useful to perform a Compare between the source and target Configuration Profiles to familiarize yourself with the Difference tree. The Configuration Profiles should be equal, with the exception of the environment-specific configuration entities described above. Select both the source and target Configuration Profiles on the Profile Repository tab or the Profile Editor tab, right-click, and select Compare. The Difference tree shows the following differences:

  • Additions and Deletions of Certificates
  • Conflicts between entities that refer to certificates (for example, Connection filter, signing filters, HTTPS interfaces)
  • Conflicts between database connections
  • Conflicts between LDAP directories
  • Conflicts between SiteMinder, or SOA Security Manager connections
  • Conflicts between Tivoli connections
  • Conflicts between all types of URL sets and ClearTrust connection sets (child nodes are marked as Additions and Deletions)
  • Conflicts between any Alert systems
  • Conflicts between syslog loggers
  • Conflicts between Remote Hosts
  • Conflicts between UDDI Registry Connections
  • Conflicts between Messaging system (JMS) filters
  • Conflicts between SMTP filters
  • Additions and Deletions of JMS Services

Hiding External Connection Conflicts
You can hide known entity types that are deemed to be External Connection types. Right-click the tree, and select View Nodes, and ensure that the External Connection Conflicts option is unselected. The following differences are now hidden from the tree view:

  • Conflicts between database connections
  • Conflicts between LDAP directories
  • Conflicts between SiteMinder, or SOA Security Manager connections
  • Conflicts between Tivoli connections
  • Conflicts between all types of URL sets and ClearTrust connection sets (child nodes are marked as Additions and Deletions)
  • Conflicts between any Alert systems
  • Conflicts between Remote Hosts
  • Conflicts between UDDI Registry Connections

This list contains the conflicts that you should be able to ignore as you merge more and more changes from the source to the target. These conflicts hold the environment-specific connection configuration information.

You are left with the following differences being displayed (when External Connection Conflicts are filtered out):

  • Additions and Deletions of Certificates
  • Conflicts between entities that refer to certificates (for example, Connection filter, signing filters, HTTPS interfaces)
  • Conflicts between syslog loggers
  • Conflicts between Messaging system (JMS) filters
  • Conflicts between SMTP filters
  • Additions and Deletions of JMS Services

When you merge more changes between the source and target Configuration Profiles, you must be careful with the Certificates and those entities that refer to Certificates. The source Certificates always appear as Additions, and the target Certificates as Deletions. You most likely never want to delete the target Certificates during a merge operation, so you should make sure that these are never selected in the Difference tree for merging.

You also most likely do not want to import any more source Certificates, so these Additions should be unselected. However, you may wish to import an entity that refers to a source Certificate. You may perform the import without the Certificate, but you must ensure to manually edit that entity after the merge and select a target Certificate.

The other differences relating to loggers, JMS, and SMTP filters must be handled carefully. In some cases, you may not wish to merge these changes from the source to the target. The data displayed in the Difference table for each of these nodes should be examined and a decision then made whether the difference is one you wish to merge or not.

Merging Updates from Source to Target Environment

After the initial transfer of the configuration from the source to the target environment, it is likely that modifications to the configuration need to pass from the source to the target over time. When you wish to add changes from a source Configuration Profile to an existing target Configuration Profile, you must ensure (as before in the initial transfer use case) that both configurations are accessible to the user, who can load both Configuration Profiles into the Profile Editor tab. For details on how to transfer configurations managed by multiple instances, see the Accessing Environments.

You must select both the source and target Configuration Profiles in the Profile Repository or Profile Editor tab, right-click, and select Compare. By default, all differences are displayed in the tree, and only the Additions are selected for merging. You should you carry out the following steps:

  1. Right-click the tree, select the View Nodes option, and ensure that the External Connection Conflicts option is unselected. This hides the configuration entities that are known to refer to external resources, and exist in both the source and target Configuration Profiles. Filtering these differences from the view allows you to concentrate on the differences you wish to merge.
  2. Examine each node marked as an Addition, Deletion, or Conflict, and select those you wish to merge.
  3. A new External Connection type may need to be merged into the target Configuration Profile. In this case, ensure that it is manually updated after the merge in the same way as described for the initial transfer of the Configuration Profile over to the target environment. If an existing External Connection type is removed in the merge, no manual intervention should be required. Addition and Deletions of External Connection types are not filtered from the tree view by unselecting the External Connection Conflicts option in the View Nodes menu.
  4. Click the Merge button.
  5. Switch to the Profile Editor tab, and ensure the merged entities are now in your target Configuration Profile.
  6. When the target Configuration Profile has been checked to ensure all changes are in order, you must create a new version using the Commit Version menu option.
  7. The updated target Configuration Profile is now available to deploy to a target Process.

Note:
The following entity types are treated as External Connections by the View Nodes and Merge Nodes menu option filters:

  • SiteMinderConnection
  • TransactionMinderConnection
  • TivoliSettings
  • LdapDirectory
  • UrlSet
  • ConnectionSet
  • DbConnection
  • EmailAlertSystem
  • NTAlertSystem
  • OpsecAlertSystem
  • SnmpAlertSystem
  • SyslogAlertSystem
  • RemoteHost
  • RegistryConnection
  • Certificate
  • JMSService
  • SyslogServer
  • SMTPServer