Upgrade process

Overall, the upgrade process consists of the following steps:

  • Obtain a new version of the Deployit software (the main product and/or plugins) from XebiaLabs.
  • Read the new version's release notes so you are aware of the new functionality and possible upgrade considerations.
  • Read the new version's upgrade manual (this document) so you are aware of possible upgrade considerations.
  • Stop the current version of Deployit if it is still running, making sure there are no running tasks active.
  • Create a brand-new installation directory for the new version of Deployit so the existing version is still available in case of problems.
  • Extract the new Deployit software release into the new installation directory.
  • Copy the data from the previous Deployit installation directory into the new installation directory.
  • Start the new version of Deployit.

See the section Performing the Upgrade below for a detailed explanation of these steps.

Upgrade notes

  • It is possible to skip Deployit versions when upgrading. Deployit will sequentially apply any upgrades for the intermediate (skipped) versions. Please read the specific upgrade instructions for each of the versions carefully.
  • The new version of Deployit may not be compatible with the existing version of your plugins. If this is the case, you'll need to download an updated version of your plugin as well. Please read the specific upgrade instructions for each of the versions carefully.
  • If a repository upgrade is required, Deployit will detect that it is running against an old repository and will automatically execute an upgrade when it is first started. The server log will contain extensive logging of the repository upgrade process.
  • Plugin versions are related to the version of Deployit that they are compatible with. For instance, WAS plugin version 3.6.0 requires at least Deployit server version 3.6.0. This version of the WAS plugin should also work in Deployit 3.7.0 unless stated otherwise in this document.

Performing the upgrade

To begin upgrading Deployit, first unpack the distribution archive. The distribution archive contains the following:

  • A server archive.
  • A CLI archive.

The release notes are stored in the server's doc directory. Please read them carefully before performing the upgrade.

Upgrading the Server

To upgrade an existing Deployit server installation, do the following:

  1. Create a directory for the new Deployit server installation, including the new Deployit server version number in the directory name.
  2. Extract the server archive in this directory.
  3. Stop the Deployit server.
  4. Copy the contents of the conf directory from the previous installation into the new installation directory.
  5. Copy the entire repository directory from the previous installation into the new installation directory.
  6. Copy the contents of the importablePackages directory from the previous installation into the new installation directory.
  7. Unless new versions of your plugins were provided with the new Deployit version, copy the contents of the plugins directory from the previous installation into the new installation directory.
  8. Copy the contents of the ext directory from the previous installation into the new installation directory.
  9. DO NOT copy the contents of the hotfix directory (unless instructed) because hotfixes are version specific.
  10. If you added libraries to Deployit's lib directory (for instance, database drivers), copy the additional libraries from the previous installation into the new installation directory.
  11. If you have made any changes to the Deployit server startup scripts (server.sh or server.cmd), manually re-do these changes in the new installation directory.
  12. Start the Deployit server interactively to allow any automatic repository upgraders to run.
  13. If you normally run the Deployit server as a service, stop it again and start it as you normally do.

Note: please make sure that the plugins and extensions in the old Deployit installation are compatible with the new Deployit server version.

This completes upgrading of the Deployit server.

Upgrading the CLI

To upgrade an existing Deployit CLI installation, do the following:

  1. Create a directory for the new Deployit CLI installation, including the new Deployit CLI version number in the directory name.
  2. Extract the CLI archive in this directory.
  3. Unless new versions of your plugins were provided with the new Deployit version, copy the contents of the plugins directory from the previous installation into the new installation directory.
  4. Copy the contents of the ext directory from the previous installation into the new installation directory.
  5. DO NOT copy the contents of the hotfix directory (unless instructed) because hotfixes are version specific.
  6. If you have made any changes to the Deployit CLI startup scripts (cli.sh or cli.cmd), copy these from the bin directory in the previous installation into the new installation directory.

This completes upgrading of the Deployit CLI.

Specific upgrade notes

This section describes specific considerations for migrating from or to a particular Deployit version:

Upgrading to Deployit 3.9.90

Need JDK 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.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 behaviour 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 behaviour 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')

Deployit 3.7 Deployit 3.8
c.x.d.p.api.deployment.execution.Step c.x.d.p.api.flow.Step
c.x.d.p.api.deployment.execution.Step.Result c.x.d.p.api.flow.StepExitCode
c.x.d.p.api.deployment.execution.DeploymentStep c.x.d.p.api.flow.Step
c.x.d.p.api.deployment.execution.DeploymentExecutionContext c.x.d.p.api.flow.ExecutionContext
c.x.d.p.api.inspection.InspectionExecutionContext c.x.d.p.api.flow.ExecutionContext
c.x.d.p.api.inspection.InspectionPlanningContext c.x.d.p.api.inspection.InspectionContext
c.x.d.p.overthere.ExecutionContextOverthereProcessOutputHandler c.x.d.p.overthere.DefaultProcessOutputHandler

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:

Feature Pre-3.7 3.7 Conversion
Admin password Deployit did not need the administrator password. Deployit needs the administrator password. The administrator password must be set manually in the deployit.conf file before starting Deployit 3.7.
Local permissions defined per CI Local permissions can be defined on any CI, if the permission is applicable. Local permissions can only be defined on root nodes or core.Directory CIs. Deployit automatically migrates permissions from pre-3.7 repositories to 3.7, creating new directory CIs as needed.
Permission assignment Permissions are assigned to users (when using the repository as user store) or LDAP principals (users or groups). Permissions are assigned to roles managed within Deployit. Deployit automatically migrates principals from pre-3.7 repositories to 3.7, creating new roles as needed.
Permissions that are both global as well as local Several permissions (deploy#initial, deploy#upgrade, deploy#undeploy, import#initial, import#upgrade, task#skip_step, task#move_step) can be assigned both globally as well as locally. These permissions can only be assigned locally on root nodes or directory CIs. Deployit automatically migrates these permissions from pre-3.7 repositories to 3.7.
deny permissions Permissions can explicitly be denied on any level. Denying permissions is no longer possible. Deployit does not migrate deny permissions. An equivalent security configuration must be created manually after the upgrade.
Permission to delete packages repo#edit permission allowed deleting of packages. New permission import#remove is introduced to allow deleting of packages. Permission repo#edit is still required to edit CIs. Deployit automatically assigns import#remove to roles that had repo#edit permission in the pre-3.7 repository.

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:

3.6 example 3.7 XML element 3.7 XML properties 3.7 example
userProvider="ldap://localhost:389/ou=system" security:ldap-server url and root properties <security:ldap-server id="ldapServer" url="ldap://localhost:389/" root="ou=system"/>
userFilter="(&(uid={USERNAME})(objectClass=inetOrgPerson))" security:ldap-authentication-provider user-search-filter user-search-filter="(&(uid={0})(objectClass=inetOrgPerson))"
userSearchBase="dc=example,dc=com" security:ldap-authentication-provider user-search-base user-search-base="dc=example,dc=com"
groupFilter="(memberUid={USERNAME})" security:ldap-authentication-provider group-search-filter group-search-filter="(memberUid={0})"
groupSearchBase="ou=groups,dc=example,dc=com" security:ldap-authentication-provider group-search-base group-search-base="ou=groups,dc=example,dc=com"
java.naming.security.principal="cn=admin,dc=example,dc=com" security:ldap-server manager-dn <security:ldap-server id="ldapServer" url="ldap://localhost:389/" manager-dn="cn=admin,dc=example,dc=com" manager-password="secret"/>
java.naming.security.credentials="secret" security:ldap-server manager-password <security:ldap-server id="ldapServer" url="ldap://localhost:389/" manager-dn="cn=admin,dc=example,dc=com" manager-password="secret"/>
useSSL security:ldap-server url Use the LDAPS protocol in the url, for example: <security:ldap-server id="ldapServer" url="ldaps://localhost:686/"/>
principalProvider=com.xebialabs.deployit.security.LdapPrincipalProvider n/a n/a This element is no longer required.

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.

Copyright XebiaLabs B.V. 2009-2013. All rights reserved.