Version-specific upgrade notes

Upgrade instructions

For upgrade instructions, refer to Upgrade XL Deploy.

Important: If you plan to skip versions when you upgrade, ensure that you read the version-specific upgrade notes for each intermediate version. You may be required to perform manual actions as part of the upgrade.

Version-specific upgrade notes

These sections describe specific considerations for migrating from or to a particular XL Deploy/Deployit version:

• Upgrading to XL Deploy 5.0.1
• Upgrading to XL Deploy 5.0.0
• Upgrading to XL Deploy 4.5.5
• Upgrading to XL Deploy 4.5.4
• Upgrading to XL Deploy 4.5.3
• Upgrading to XL Deploy 4.5.1
• Upgrading to XL Deploy 4.5.0
• Upgrading to XL Deploy 4.0.2
• Upgrading to XL Deploy 4.0.0
• Upgrading to Deployit 3.9.90
• Upgrading to Deployit 3.9.5
• Upgrading to Deployit 3.9.4
• Upgrading to Deployit 3.9.3
• Upgrading to Deployit 3.9.2
• Upgrading to Deployit 3.9.0
• Upgrading to Deployit 3.8.4
• Upgrading to Deployit 3.8.3
• Upgrading to Deployit 3.8.0
• Upgrading to Deployit 3.7.0
• Upgrading to Deployit 3.6.0
• Upgrading from Deployit 3.0.x or earlier

Important: If you plan to skip versions when you upgrade, ensure that you read the version-specific upgrade notes for each intermediate version. You may be required to perform manual actions as part of the upgrade.

Deprecated items

Each new version may deprecate some functionality or features in favor of newer ways of working. If functionality is marked as deprecated for a specific version, the old functionality is still available (so you can still upgrade hassle-free), but it will be removed in the next version.

Deprecated items are indicated as follows:

Or

Upgrading to XL Deploy 5.0.1

Security configuration has been consolidated

Spring Security configuration settings that were previously stored in the internal deployit-context.xml file have been moved to the <XLDEPLOY_HOME>/conf/deployit-security.xml file. This change consolidates the Spring Security configuration and makes it easier to integrate XL Deploy security with external user authentication.

Important: When upgrading, do not copy the <XLDEPLOY_HOME>/conf/deployit-security.xml from your previous installation of XL Deploy. Use the deployit-security.xml file that is included with XL Deploy 5.0.1 and manually update it with any customizations that are specific to your environment (such as your LDAP credentials).

Satellite module is disabled by default

In XL Deploy 5.0.1, the satellite module is disabled by default. You can enable satellites in the <XLDEPLOY_HOME>/conf/system.conf file. For more information about enabling satellites, refer to Configure XL Deploy to communicate with satellites.

Important: When upgrading from XL Deploy 5.0.0, do not copy system.conf from a previous installation. If you have previously made custom modifications to system.conf, you must merge your modifications after upgrading to 5.0.1.

Upgrading to XL Deploy 5.0.0

It is not possible to upgrade from a beta version of XL Deploy 5.0.0 to the final version. Please upgrade from XL Deploy 4.5.x to 5.0.0.

New license required

XL Deploy 5.0.0 requires a new license (V3). Download your license at https://dist.xebialabs.com.

New plugins required

XL Deploy 4.5.x plugins are not compatible with XL Deploy 5.0.0. Download the latest versions of plugins at https://dist.xebialabs.com.

XL Deploy 5.0.0 introduces the XLDP plugin format, which is a ZIP archive that bundles the plugin with all of its dependencies. Plugins ending with a .xldp extension are installed in the plugins folder.

Important: When you upgrade to a plugin in XLDP format, ensure that you remove the previous version of the plugin (in JAR format).

New installation and startup scripts

The server.sh and server.cmd scripts have been replaced with:

• run.sh and run.cmd: Install and start XL Deploy
• install-service.sh and install-service.cmd: Install XL Deploy as a service or daemon
• uninstall-service.sh and uninstall-service.cmd: Uninstall the XL Deploy service or daemon

New hotfix directories

Two directories have been added under the hotfix directory, to provide better support for server and plugin hotfixes:

• hotfix/lib: Contains hotfixes for the XL Deploy server
• hotfix/plugins: Contains hotfixes for plugins

Note: Hotfixes in the hotfix directory will not be loaded. All hotfixes must be placed in hotfix/lib or hotfix/plugins.

Tasker configuration

With the introduction of the satellite feature, the configuration file for the task execution engine has become more generic. For that reason it has been renamed to system.conf. This file now contains the configuration for the task execution engine and XL Satellite. Notice that the naming of configuration properties has slightly changed.

For example, what used to be deployit.task.recovery-dir is now task.recovery-dir. When upgrading to XL Deploy 5.0.0, copying tasker.conf is not needed. Please apply any customizations manually to the new system.conf.

Deployed property resolution

In XL Deploy 5.0.0, the way that XL Deploy resolves properties for deployeds and deployed applications when doing deployment updates has changed.

Previously, XL Deploy would fall back to the previous deployed value if it determined that the property was explicitly set, or when the deployable did not have a value for the property.

Now, if XL Deploy cannot resolve a property during an update of a deployed application, it will prompt you to provide the value that is missing.

In detail, the new behavior is:

1. If the deployable has the property
   1. If the value of the deployable's property is not set (that is, it is null or empty collection)
      1. Try to resolve the property from the dictionary, using the <deployed type>.<property name> key
   2. Else if the property is set on the deployable
      1. Resolve the value from the deployable property using the dictionary
         1. If the placeholder resolution fails, set the empty value on the property
         2. Else if the placeholders were resolved, set the resolved value on the property
2. Else if the deployable does not have the property and the deployed does not have a default value for the property
   1. Try to resolve the property from the dictionary using the <deployed type>.<property name> key
   2. If the previous step does not set a value on the deployed (that is, it is null or empty collection)
      1. Set the value from the previous deployed
3. Else use the default value for the deployed's property

Database plugin rollback behavior

The rollback mechanism in the Database plugin has been improved. Instead of executing all rollback scripts during a rollback, XL Deploy tracks which installation scripts were executed successfully and only executes their associated rollback scripts.

Generic plugin behavior

The MODIFY behavior of the generic.CopiedArtifact has been improved. While older versions did not allow modification when preserveExistingFiles was set to true, now any files specified in the CI will be overwritten and all other files on the same path will be preserved.

Items removed in XL Deploy 5.0.0

For information about items that were removed in XL Deploy 5.0.0, refer to:

• Items deprecated in 4.5.1
• Items deprecated in 4.5.0

Tip: For detailed information about migrating away from items that were removed, refer to Migrate to XL Deploy 5.0.0.

Items deprecated in XL Deploy 5.0.0

Upgrading to XL Deploy 4.5.5

Security configuration has been consolidated

Spring Security configuration settings that were previously stored in the internal deployit-context.xml file have been moved to the <XLDEPLOY_HOME>/conf/deployit-security.xml file. This change consolidates the Spring Security configuration and makes it easier to integrate XL Deploy security with external user authentication.

Important: When upgrading, do not copy the <XLDEPLOY_HOME>/conf/deployit-security.xml from your previous installation of XL Deploy. Use the deployit-security.xml file that is included with XL Deploy 4.5.5 and manually update it with any customizations that are specific to your environment (such as your LDAP credentials).

Upgrading to XL Deploy 4.5.4

Generic plugin behavior

The MODIFY behavior of the generic.CopiedArtifact has been improved. While older versions did not allow modification when preserveExistingFiles was set to true, now any files specified in the CI will be overwritten and all other files on the same path will be preserved.

Upgrading to XL Deploy 4.5.3

Automatic repository upgrade

The first time this version of XL Deploy is started with a repository created with an older version of XL Deploy, the following upgraders will automatically upgrade the repository:

• Deployit453FolderChecksums: This upgrader updates the checksum property of all udm.FolderArtifact type artifacts. Artifacts with a custom checksum value will be ignored, while others will have a new SHA-1 checksum calculated according to an algorithm which takes into account empty files and file paths.

Changes to deployed object in rules

The behavior of the deployed object in the planning and script contexts has changed. Previously, deployed pointed to the current or previous deployed, depending on the operation.

In XL Deploy 4.5.3, in the case of a CREATE, MODIFY, or NOOP operation, deployed points to the "current" deployed that the delta variable refers to. In the case of DESTROY, deployed is not available.

In the case of a MODIFY, DESTROY, or NOOP operation, the new previousDeployed object points to the "previous" deployed that the delta variable refers to. In the case of CREATE, previousDeployed is not available.

For more information, refer to Getting started with XL Deploy rules and Objects and properties available to rules.

Changes to FreeMarker variables for os-script step

In FreeMarker templates used by the os-script step, ${deployed.file} now evaluates to the uploaded file. This means that you can use the following expressions:

• ${deployed.file.path}: Complete path of the uploaded file. For example, /tmp/ot-12345/generic_plugin.tmp/PetClinic-1.0.ear.
• ${deployed.file.name}: Name of the uploaded file. For example, PetClinic-1.0.ear.
• ${deployed.file}: toString of the uploaded file. For example, ssh:sftp://root@jboss-51:22/tmp/ot-12345/generic_plugin.tmp/PetClinic-1.0.ear.
• ${deployed.deployable.file.path}: Complete path of the uploaded deployable file (without placeholder replacement). For example, /tmp/ot-12345/generic_plugin.tmp/PetClinic-1.0.ear.

Note that if you have previously used ${deployed.file.name} in a template, you may need to change it to ${deployed.file.path}.

For more information, refer to the Steps Reference.

Deprecations

Upgrading to XL Deploy 4.5.1

Security upgrade

Spring and Spring Security were upgraded to version 3.2, so if you use deployit-security.xml, you must update it by removing the version specification of XSD files:

• Change .../spring-beans-3.1.xsd to .../spring-beans.xsd
• Change .../spring-security-3.1.xsd to .../spring-security.xsd

Items deprecated in XL Deploy 4.5.1

Upgrading to XL Deploy 4.5.0

Increased PermGen space

The Permanent Generation memory (PermGen) allocation for XL Deploy has been increased. The default value of PermGen was increased from 128 MB to 256 MB. The value is specified in bin/server.sh and bin/server.cmd.

Exposing password properties in exported package

Before XL Deploy 4.5.0, a package export showed all password properties of deployables, unencrypted and not obfuscated. This is no longer the case. Currently, the default is only to export password properties whose values looks like a placeholder (e.g. {{PASSWORD}}) and to remove the value for the passwords that are not using placeholders.

To control whether password properties should be exported, you can use the following two properties:

• udm.Version.exportAllPasswords: If set to true, all passwords will be exported. Its default value is false, that means no passwords are exported by default.
• udm.Version.exportOnlyPasswordPlaceholders: If set to true, only passwords that looks like placeholders (i.e. starting and ending with double curly braces) will be exported, and the rest will be exported as empty string. Its default value is true.

You can change the default values of these properties using conf/deployit-defaults.properties file.

If passwords were removed from the exported DAR archive, you will not be able to import it again, as password properties are by default required properties. To fix this you can choose one of the following solutions:

• Use placeholders instead of actual values for the passwords, as placeholders are by default kept as they are in the exported package. This is the recommended practice.
• Set udm.Version.exportAllPasswords to true before doing the export. This way, all the passwords are exported to the package manifest.
• Add the missing passwords by manually editing the manifest file from the exported DAR archive.

Importing a package with undefined CI properties in manifest

In the previous versions, the package importer ignored the undefined CI properties used in the manifest and continued importing the package without raising a warning or error. Because of that, when upgrading to a new version of a plugin with different / changed CI properties, there is no indication that an existing package may be invalid. The error was only discovered at deployment time.

Starting with the current version of XL Deploy, this situation can be handled in two ways. The default behavior is to print a warning in the logs when importing a package with undefined CI properties. The alternative behavior is to throw an exception and fail the package import.

You can change the default behavior by setting the value of udm.Version.ignoreUndefinedPropertiesInManifest to true in conf/deployit-defaults.properties file.

Items deprecated in XL Deploy 4.5.0

General deprecations

• Support for Internet Explorer 8 and Internet Explorer 9 will be removed in XL Deploy 5.0.0.
• Support for the MANIFEST.MF format for XL Deploy manifests is deprecated. Please migrate to the deployit-manifest.xml format.
• The following orchestrators are deprecated:

  default	(no orchestrator)
  container-by-container-serial	sequential-by-container
  composite-package	sequential-by-composite-package
  group-based	sequential-by-deployment-group

Deprecations in REST services

• The REST endpoint /security/check/{permission}/{ciID} will no longer support HEAD requests. Instead, use a GET request, which returns a Boolean value instead of an HTTP status.
• Endpoint /task will be removed. Use the /task/v2 endpoint instead.
• The related object types TaskState and TaskWithSteps will be removed and superseded by TaskWithBlock, BlockState, and StepBlockState.
• From the /deployment endpoint:

  /deployment/preview	/deployment/previewblock
  /deployment/preview/{stepNumber}	/deployment/previewblock/{blockId}/{stepNr}
  /deployment/generate/all	/deployment/prepare/deployeds (note that this has slightly different semantics)

Deprecations in the CLI

• The tasks object is deprecated. Use task2 instead.
• The related object types TaskState and TaskWithSteps will be removed and superseded by TaskWithBlock, BlockState, and StepBlockState.
• From the deployment object:

  deployment.taskPreview(Deployment deployment)	deployment.taskPreviewBlock(Deployment deployment)
  deployment.stepPreview(Deployment deployment, Integer stepNumber)	deployment.taskPreviewBlock(Deployment deployment, String blockId, Integer stepNumber)
  deployment.generateAllDeployments(Deployment deployment)	deployment.prepareAutoDeployeds(Deployment deployment) (note that this has slightly different semantics)
  deployment.deploy(Deployment deployment)	deployment.getDeployTask(Deployment deployment)
  deployment.undeploy(String deployedApplication)	deployment.createUndeployTask(String deployedApplication)
  deployment.rollbackTask(String taskId)	deployment.getRollbackTask(String taskId)
  deployment.createTask(Deployment deployment)	deployment.getDeployTask(Deployment deployment).getId()

• From the repository object:

  repository.getArchivedTasks()	repository.getArchivedTasksList()
  repository.getArchivedTasks(String beginDate, String endDate)	repository.getArchivedTasksList(String beginDate, String endDate)

• From the deployit object, the following calls will be deprecated:

  deployit.retrieveTaskInfo(String taskId)	task2.get(String taskId)
  deployit.listUnfinishedTasks()	task2.getMyCurrentTasks()
  deployit.listAllUnfinishedTasks()	task2.getAllCurrentTasks()
  deployit.discover(ConfigurationItem ci)	deployit.createDiscoveryTask() together with deployit.retrieveDiscoveryResults()

Deprecations in plugins

• The following FreeMarker-related methods will be deprecated from CIs in the Generic plugin:

  Namespace com.xebialabs.deployit.plugin.generic.freemarker
  constructor CiAwareObjectWrapper(ArtifactUploader uploader)
  constructor CiAwareObjectWrapper(ArtifactUploader uploader, boolean maskPasswords)
  constructor CiTemplateModel(ConfigurationItem ci, CiAwareObjectWrapper wrapper)
  constructor CiTemplateModel(ConfigurationItem ci, CiAwareObjectWrapper wrapper, boolean maskPasswords)

• From the Remoting plugin:

  Namespace `com.xebialabs.deployit.plugin.overthere
  class AutoFlushingExecutionContextOverthereProcessOutputHandler
  class DefaultExecutionOutputHandler
  class ExecutionContextOverthereProcessOutputHandler
  class DefaultExecutionOutputHandler (also)

Deprecations relevant for extenders

• If you have written Java Contributors, PrePlanProcessors, or PostPlanProcessors, these need to be static methods.

• For control tasks, the generic delegate type is deprecated. Use shellScript instead.

• All Java-backed control task delegates need to be static methods.

• You can no longer use getSyntheticProperties(...), putSyntheticProperties(...), or setSyntheticProperties(...) on CIs. Use getProperty(), etc.

• Every custom CI will be required to extend BaseConfigurationItem (or a subclass thereof).

• If you are writing your own Steps, note that in the Generic plugin's BaseStep class:

  method evaluateTemplate(String templatePath, Map<String, Object> vars)

  method evaluateTemplate(String templatePath, Map<String, Object> vars, boolean maskPasswords

• The namespace com.xebialabs.deployit.plugin.api.execution is deprecated:

  com.xebialabs.deployit.plugin.api.execution.Step

  com.xebialabs.deployit.plugin.api.flow.Step

  com.xebialabs.deployit.plugin.api.execution.ExecutionContext

  com.xebialabs.deployit.plugin.api.flow.ExecutionContext

  com.xebialabs.deployit.plugin.api.execution.ExecutionListener

  com.xebialabs.deployit.engine.spi.execution.ExecutionStateListener

• The namespace com.xebialabs.deployit.plugin.api.deployment.execution is deprecated:

  com.xebialabs.deployit.plugin.api.deployment.execution.DeploymentStep

  com.xebialabs.deployit.plugin.api.flow.Step

  com.xebialabs.deployit.plugin.api.deployment.execution.DeploymentExecutionContext

  com.xebialabs.deployit.plugin.api.flow.ExecutionContext

• If you have implemented your own orchestrators, note that all constructors without the description argument are deprecated. Use the variants that include them as their first arguments. This holds for these classes:

  • CompositeOrchestration
  • InterleavedOrchestration
  • ParallelOrchestration
  • SerialOrchestration
  • ... and their factory methods in the Orchestrations class

• If you have written your own importer, in the ImportedPackage class, note that:

  In class com.xebialabs.deployit.server.api.importer.Importer
  constructor ImportedPackage(PackageInfo packageInfo)
  constructor ImportedPackage(PackageInfo packageInfo, Application application, Version version)
  method getDeploymentPackage()
  method getVersion()

• When creating new CIs, note that:

  com.xebialabs.deployit.plugin.api.reflect.Descriptor.newInstance()

  com.xebialabs.deployit.plugin.api.reflect.Descriptor.newInstance(String id)

• The following Java classes have been deprecated:

  • com.xebialabs.deployit.cli.api.legacy.FullTaskInfo
  • com.xebialabs.deployit.cli.api.legacy.FullTaskInfos
  • com.xebialabs.deployit.cli.api.legacy.StepInfo
  • com.xebialabs.deployit.cli.api.legacy.TaskInfo

Upgrading to XL Deploy 4.0.2

Security upgrade

• Spring and Spring Security were upgraded to version 3.2, so if you use deployit-security.xml, you must update it by removing the version specification of XSD files:
  • Change .../spring-beans-3.1.xsd to .../spring-beans.xsd
  • Change .../spring-security-3.1.xsd to .../spring-security.xsd

Upgrading to XL Deploy 4.0.0

New license necessary

We made changes to the license system as a result a new license file is needed to run XL Deploy. You can download your license from https://dist.xebialabs.com/. The license needs to be installed into the conf directory.

Note: Ensure the license file is not changed in any way, that will corrupt the license. Some mail programs may corrupt the license file unless wrapped in a ZIP.

Java 7

XL Deploy requires Java 7 to run.

Plugin compatibility

The following old plugins are not compatible with XL Deploy 4.0.0:

• glassfish-plugin 3.9.x
• ec2-plugin 3.9.x
• cloud-plugin 3.9.x
• wls-plugin 3.9.x
• jbossdm-plugin 3.9.x
• wp-plugin 3.9.x
• was-plugin-extensions 3.9.x

Use of cp, tar, copy and xcopy

XL Deploy 4.0.0 uses version 2.4.2 of the remoting framework Overthere that introduces a new feature to copy files on a remote machine in an efficient manner. Overthere 2.4.2 does this by using the following commands to copy file and directories (where {0} is replaced with the path of the source file or directory and {1} is replaced with the path of the target file or directory):

• File copy on Unix and z/OS: cp -p {0} {1}
• Directory copy on Unix and z/OS:
  • XL Deploy 4.0.0: tar cC {0} . | tar xmC {1} .
  • XL Deploy 4.0.1 and up: cd {1} ; tar -cf - -C {0} . | tar xpf -
• File copy on Windows: copy {0} {1} /y
• Directory copy on Windows: xcopy {0} {1} /i /y /s /e /h /q

This functionality is used in three places in XL Deploy:

• When a file or directory is staged, it will be uploaded to the staging directory at the start of the deployment and then, when a step uses it, it will be copied to the target directory or the temporary directory (depending on the plugin) using one the commands specified above.
• The behavior of the File Plugin has been modified to more atomic:
  1. If staging is enabled, the file or directory will be uploaded to the staging directory at the beginning of the deployment and then copied from the staging directory to the target directory (using one the commands specified above) during the actual deployment.
  2. If staging is not enabled, the file or directory will be uploaded to the temporary directory and immediately copied from there to the target directory (using one the commands specified above) in a single step.
• The behavior of the generic.CopiedArtifact type of the Generic Model Plugin has been modified in a similar manner. This means all plugins that extend this behavior, e.g. the Tomcat Plugin or the JBossAS plugin for 5.x and 6.x, are also affected by this.

Prior to XL Deploy 4.0.0, the behavior of the File Plugin and of generic.CopiedArtifact was to copy the file or directory directly to the target path. From XL Deploy 4.0.1 and up, this behavior can be re-enabled by setting the hidden property copyDirectlyToTargetPath to true

For example, to revert the File Plugin to its pre-4.0.0 behavior, add the following line to the conf/deployit-defaults.properties file and restart the XL Deploy server:

file.DeployedArtifactOnHost.copyDirectlyToTargetPath=true

Orchestrators

The kind of the orchestrator property on the udm.DeployedApplication type has been changed from STRING to LIST_OF_STRING, because it is now possible to compose orchestrators. If you have CLI scripts that assign a single String value to this property this will still work, because it will be put into the list as the only element. If you have scripts that depend on reading the value, the script must be changed to expect a list of string when reading the property.

UI functionality has been moved

The pause button and the skip button in task execution screen were moved into a context menu on the steps.

Deprecations in XL Deploy 4.0.0

The following orchestrators have been deprecated and will be removed in an upcoming (major) release.

• container-by-container-serial, replaced by the sequential-by-container orchestrator.
• composite-package, replaced by the sequential-by-composite-package orchestrator.
• group-based, replaced by the sequential-by-deployment-group orchestrator.

Upgrading to Deployit 3.9.90

Java 7

From this version onwards Deployit will require Java 7 to run. All pre-existing plugins are compatible with this version of Java and it should not be needed to rebuild them.

Upgrading to Deployit 3.9.5

Security upgrade

• Spring and Spring Security were upgraded to version 3.2, so if you use deployit-security.xml, you must update it by removing the version specification of XSD files:
  • Change .../spring-beans-3.1.xsd to .../spring-beans.xsd
  • Change .../spring-security-3.1.xsd to .../spring-security.xsd

Upgrading to Deployit 3.9.4

Support for deployment package level properties

Support for deployment package level properties has been added in Deployit 3.9.4 to make it possible to set values for deployment properties from the udm.DeploymentPackage.

Support for native Windows WinRM

Support for the native Windows WinRM implementation, i.e. the winrs command, has been implemented in Deployit 3.9.4 to make the setup of WinRM easier for users running the Deployit server on a Windows platform. The existing Java implementation that is internal to Deployit is still available for users running the Deployit server on Unix or Windows.

Because of this, the WINRM connection type has been renamed to WINRM_INTERNAL and the new WINRM_NATIVE connection type can be used to select the native Windows WinRM implementation. The WINRM_HTTP and WINRM_HTTPS connection types that were duplicates of the WINRM connection type have been removed.

Please update any scripts or procedure that create overthere.CifsHost CIs will have to be updated to reflect the new connection types:

• Replace WINRM with WINRM_INTERNAL.
• Replace WINRM_HTTP with WINRM_INTERNAL and winrmEnableHttps set to false.
• Replace WINRM_HTTPS with WINRM_INTERNAL and winrmEnableHttps set to true.

You do not have to upgrade the contents of your repository. The UpgradeToRemotingPlugin394 upgrader mentioned below will take care of that.

Automatic repository upgrade

The first time this version of Deployit is started with a repository created with an older version of Deployit, the following upgraders will automatically upgrade the repository:

• Deployit394Checksums: Deployit 3.9 introduced the checksum property which stores SHA-1 checksums of artifacts. The SHA-1 algorithm in some cases generated too short checksum strings. This upgrader will recalculate all incorrect checksums.
• UpgradeToRemotingPlugin394: This upgrader converts the connection type properties of all overthere.CifsHost properties in the repository as follows:
  • Replaces WINRM with WINRM_INTERNAL.
  • Replaces WINRM_HTTP with WINRM_INTERNAL and sets winrmEnableHttps to false.
  • Replaces WINRM_HTTPS with WINRM_INTERNAL and sets winrmEnableHttps to true.
  • Replaces WINRS (only available in hotfix versions of Deployit) with WINRM_NATIVE.

Upgrading to Deployit 3.9.3

Automatic repository upgrade

The first time this version of Deployit is started with a repository created with an older version of Deployit, the following upgraders will automatically upgrade the repository:

• Deployit393ReportsView: Deployit 3.9.3 introduces the new global report#view permission to control how is allowed to view the reports tab. This upgrader will grant all roles that have the login permission the report#view permission.

Upgrading to Deployit 3.9.2

DEPL-4652

An autoPrepareDeployeds method has been added to the deployment object in the CLI and the corresponding REST API that works as follows:

• For an initial deployment without any deployeds, it is identical to a call to generateAllDeployeds.
• For an initial deployment with at least one deployed, the behavior is as below.
• For an update deployment, keep existing mappings but:
  • Add mappings for new deployables, if allowed by types and tags.
  • Add mappings for new containers, if allowed by types and tags.
  • Remove mappings for old deployables, without a warning.

Upgrading to Deployit 3.9.0

Upgrading plugins

Plugins provided by XebiaLabs for Deployit version 3.8 will work in Deployit 3.9. There is no need to upgrade plugins when you are upgrading to Deployit 3.9.

Custom plugins built in Java against the Deployit plugin API will need to take the following change into account:

• class ReadOnlyRepository returned from the DeploymentPlanningContext.getRepository() call has been replaced by class Repository. The new Repository class provides an extension on the original ReadOnlyRepository class.

Recompiling the plugin Java source code against the new plugin API should bring your plugin up-to-date.

Checksum property

In Deployit 3.9, a new system property called checksum has been introduced on configuration items of type udm.BaseDeployableArtifact. This property influences how Deployit will calculate upgrades of deployments (See: Packaging Manual). If you've previously defined a property called checksum on your configuration items, please rename it to avoid clashes with the newly introduced checksum property.

Importing (old style manifests)

On importing it is now possible to pass in a CI-Name for non-artifact configuration items. The behavior for both Artifacts and non-Artifacts is now the same, both will be stored under the CI-Name value if it is given, and fallback to the Manifest entry name Name.

Upgrading to Deployit 3.8.4

DEPLOYITPB-4188

In versions of Deployit prior to 3.8.4, the envVars property on the generic.Container type of the generic-plugin (and therefore also on the sql.SqlClient type of the database-plugin and its subtypes) was resolved using FreeMarker. From Deployit 3.8.4 onwards this is no longer done as their values should refer to Unix or Windows environment variables which will be resolved by the shell.

Upgrading to Deployit 3.8.3

Automatic repository upgrade

The first time this version of Deployit is started with a repository created with an older version of Deployit, the following upgraders will automatically upgrade the repository:

• Deployit383AclClear: The upgrader that runs when upgrading from a pre-3.7.0 version of Deployit to a version below Deployit 3.9.3 (Deployit37Security, see below) left behind incorrect rep:policy nodes in the repository (DEPLOYITPB-4141). This upgrader removes those nodes.

Upgrading to Deployit 3.8.0

Automatic repository upgrade

The first time this version of Deployit is started with a repository created with an older version of Deployit, the following upgraders will automatically upgrade the repository:

• Deployit38ConfigurationRoot: This upgrader creates the new Configuration root that is supported by Deployit 3.8.0 and up.

Release Dashboard

The Release Dashboard feature has changed to make it easy to reuse a deployment pipeline for many applications. A new CI has been introduced, release.DeploymentPipeline which is stored under the new Configuration root node. Each application that should be used in the Release Dashboard can link to the required deployment pipeline.

When starting Deployit 3.8 for the first time, any deployment pipelines configured in 3.7 will be converted to 3.8 deployment pipeline CIs.

Placeholder scanning

Placeholder scanning in archives (EAR, WAR, etc.) is now disabled by default. To enable it, edit deployit-defaults.properties and add the following line:

udm.BaseDeployableArchiveArtifact.scanPlaceholders=true

Custom Java plugins

If you have custom Java plugins written against the Deployit 3.7 API, you may need to make some changes to take advantage of the new features in Deployit 3.8.

Deployit 3.8 has changed the API to manage deployments and tasks. Java plugins that use the UDM Plugin-API from Deployit 3.7 will continue to work using a legacy layer. However, if your Java plugin extends classes from the Generic plugin or Python plugin, you may need to update your Java code, since these plugins now use the new API. Here's a table of replacements (read 'c.x.d.p' as 'com.xebialabs.deployit.plugin')

Upgrading to Deployit 3.7.0

• Deployit 3.7 contains an updated security implementation. Data from a pre-3.7 repository will automatically be converted to the new security model. See the section below for a complete description of the security upgrade.
• New versions of the following plugins are needed:
  • WAS
  • WLS
  • Tomcat
  • JBoss

Security upgrade

Permissions and repository

Starting with Deployit 3.7, Deployit needs to know the admin user's password to access the repository. This must be entered in the deployit.conf file prior to starting the new Deployit server. Note that the password in the configuration file is encrypted by the Deployit server when it starts.

The main change in the Deployit 3.7 security model is that local security permissions are stored only on root nodes and core.Directory CIs. During the upgrade, Deployit will convert pre-3.7-style permissions to the new permission system and automatically create directories to attach the relevant permissions to. The server log contains a description of the old security information that was found and how this was translated to the new permission system.

Permissions in Deployit are now assigned to roles instead of directly to principals. Deployit itself contains the definitions of roles and the principals they map to. Deployit will create a role for every user it finds during the upgrade.

It is also no longer possible to globally grant certain permissions. Permissions deploy#initial, deploy#upgrade, deploy#undeploy, import#initial, import#upgrade, task#skip_step, task#move_step can now only be granted on a directory CI. Deployit will convert these global permissions into directory permissions during the upgrade.

Deployit 3.7 no longer allows deny permissions. Instead, permissions should be segregated using the new core.Directory grouping CIs. The deny permissions are not migrated by Deployit and an equivalent configuration must be created manually.

Permission repo#edit no longer allows deleting of packages. From 3.7 onwards, new permission import#remove is required to be allowed to delete packages.

In summary, these are the security changes in Deployit 3.7:

LDAP

Configuration of LDAP security has also changed. The configuration in 3.7 is specified in a file called deployit-security.xml. The 3.6-style LDAP configuration in the jackrabbit-jaas.config file can be migrated easily to the 3.7 format. The following table describes the mapping of the 3.6-style LDAP setup to the new 3.7 setup:

See the System Administration Manual for more details on the available LDAP configuration options.

If you used Deployit 3.6 with LDAP, you will have modified the conf/jackrabbit-repository.xml file. For 3.7, the Security snippet must be:

<Security appName="Jackrabbit">
        <SecurityManager class="org.apache.jackrabbit.core.DefaultSecurityManager" workspaceName="security" />
        <AccessManager class="org.apache.jackrabbit.core.security.DefaultAccessManager" />

        <LoginModule class="org.apache.jackrabbit.core.security.authentication.DefaultLoginModule">
                <param name="anonymousId" value="anonymous" />
                <param name="adminId" value="admin" />
        </LoginModule>
</Security>

Additional upgrade steps

After completing the upgrade procedure described in Upgrading the Server above, perform the following additional steps:

1. Edit the deployit.conf file and enter the admin password to property admin.password.
2. If you use LDAP, migrate the LDAP configuration to the deployit-security.xml configuration file.
3. Create a backup of your repository.
4. Start the Deployit server. When the server starts, Deployit will migrate the security information from the 3.6 repository to the 3.7 structure. In this process, Deployit will automatically create a role for each user in Deployit as well as special core.Directory CIs to assign permissions to.
5. Log into Deployit as the admin user and inspect the changes to the repository.
6. Open the Admin tab to create meaningful role assignments.
7. Open the Repository tab to create meaningful directory names.

Completing the migration

After the Deployit automated upgrade completes, log in to the Deployit GUI with various credentials to ensure that the security setup was correctly migrated. It is now possible to see the security permissions on directory CIs in the Repository Browser.

Upgrading to Deployit 3.6.0

• Deployit 3.6 is a drop-in replacement for Deployit 3.5. No repository migration is needed.
• New versions of the following plugins are needed:
  • WAS plugin
  • WLS plugin

Upgrading from Deployit 3.0.x or earlier

Deployit and the plugins were changed extensively in version 3.5. As a consequence, it is not possible to automatically migrate from a 3.0 or earlier version to version 3.5 or later. If you want to perform this type of upgrade, please contact the XebiaLabs support team.