Application dependencies in Deploy

This topic describes how to define dependencies among different versions of applications in Deploy.

When you set up the deployment of an application, Deploy automatically includes the correct versions of other dependent applications. Application dependencies work with other Deploy features such as staging, satellites, rollbacks, updates, and undeployment. You define dependencies at the deployment package level.

Versioning requirements

To define application dependencies in Deploy:

• You must use Semantic Versioning (SemVer) 2.0.0 for deployment package names
• Deployment package names can contain numbers, letters, periods (.), and hyphens (-)

In the SemVer scheme, a version number is expressed as major.minor.patch. Example: 1.2.3 All three parts of the version number are required.

You can also append a hyphen to the version number, followed by numbers, letters, or periods. Example: 1.2.3-beta In the SemVer scheme, this notation indicates a pre-release version.

Examples of deployment package names that use the SemVer scheme are:

• 1.0.0
• 1.0.0-alpha
• 1.0.0-alpha.1

Application dependencies without Semantic Versioning

You can also create a simple, one-to-one dependency on a deployment package that does not use the Semantic Versioning naming convention.

This type of application dependency does not support version ranges. The syntax for the simple dependency contains only the package name without the square brackets or parentheses that are used in Semantic Versioning. For example: 1.0.0, 1.0-beta, App1.

Version ranges

You can use parentheses and square brackets to indicate version dependency ranges. The range formats are:

Format	Description	Example
[version1,version2]	The application depends on any version between version1 and version2, including both versions. Note: version1 and version2 can be the same value	AppA depends on AppB [1.0.0,2.0.0], so AppA works with AppB 1.0.0, 1.5.5, 1.9.3, and 2.0.0
(version1,version2)	The application depends on any version between version1 and version2, excluding both versions	AppA depends on AppB (1.0.0,2.0.0), so AppA works with AppB 1.5.5 and 1.9.3, but does not work with AppB 1.0.0 or 2.0.0
[version1,version2)	The application depends on any version between version1 and version2, including version1 and excluding version2	AppA depends on AppB [1.0.0,2.0.0), so AppA works with AppB 1.0.0, 1.5.5, and 1.9.3, but does not work with AppB 2.0.0
(version1,version2]	The application depends on any version between version1 and version2, excluding version1 and including version2	AppA depends on AppB (1.0.0,2.0.0], so AppA works with App B 1.5.5, 1.9.3, and 2.0.0, but does not work with AppB 1.0.0
version1	The application depends on version1 and only version1	AppA depends on AppB 1.0.1, so AppA works only with AppB 1.0.1

Simple dependency example

In this example there are two applications called WebsiteFrontEnd and WebsiteBackEnd. WebsiteFrontEnd version 1.0.0 requires WebsiteBackEnd version 2.0.0. To define this dependency in the Deploy interface:

1. Go to the Explorer.
2. Expand Applications > WebsiteFrontEnd and double-click the 1.0.0 deployment package.
3. In the Application Dependencies section, add the key WebsiteBackEnd and the value [2.0.0,2.0.0]. This is the Semantic Versioning (SemVer) format that indicates that WebsiteFrontEnd 1.0.0 depends on WebsiteBackEnd 2.0.0, and only 2.0.0 (not any older or newer version).

When you set up a deployment of WebsiteFrontEnd 1.0.0, Deploy will automatically include WebsiteBackEnd 2.0.0.

For an extended example of dependencies, see Advanced application dependencies example.

You can define a dependency on an application that does not yet exist in the Deploy repository. You can also specify a version range that cannot be met by any versions that are currently in the repository.

This allows you to import applications even before all dependencies can be met. Using this method, you can import - but not deploy - a front-end package before its required back-end package is ready. However, this means that you must be careful to enter the correct versions.

You can also modify the declared dependencies of a deployment package even after it has been deployed. In this case, Deploy will not perform any validation. It is not recommended to modify dependencies after deployment.

Check dependencies in Deploy

For detailed information on the way Deploy verifies dependencies, see How Deploy checks application dependencies.

Deploy uses the Dependency Resolution property of the deployment package that you choose when setting up the deployment to select the other application versions. You can set the dependency resolution property to:

• LATEST: Select the highest possible version in the dependency range of each application that will be deployed . This is the default setting.
• EXISTING: If the version of an application that is currently deployed to the environment satisfies the dependency range, do not select a new version.

The LATEST option ensures that you always deploy the latest version of each application, while the EXISTING option ensures that you only update applications when they no longer satisfy your dependencies, enabling you to have the smallest deployment plan possible.

Tip: You can use a placeholder in the Dependency Resolution property to set a different dependency resolution value per environment. For more information, see Using placeholders in Deploy.

Dependency resolution example

Your system contains the following applications and dependencies:

Application	Versions	Dependencies
AppA	1.0.0	AppB [3.0.0,4.0.0]
AppA	2.0.0	AppB [3.0.0,4.0.0]
AppB	3.0.0	None
AppB	4.0.0	None

Your environment contains AppA 1.0.0 and AppB 3.0.0 and you want to update AppA to version 2.0.0. If the dependency resolution for AppA 2.0.0 is set to:

• LATEST: you will deploy AppA 2.0.0 and AppB 4.0.0.
• EXISTING: you will deploy AppA 2.0.0 only. This is because the existing deployed application, AppB 3.0.0, satisfies AppA's dependency range.

Note: In this example, the dependency resolution set on the AppB deployment packages is ignored because Deploy uses the value from the deployment package that you choose when you set up the deployment.

Deploying dependencies in the correct order

When deploying applications with dependencies, the order in which the applications will be deployed might be important. For example, if application A depends on application B, you want to deploy application B before A. You can achieve this by using the sequential-by-dependency orchestrator. This orchestrator will deploy all applications in reverse topological order to ensure that dependent applications are deployed first. By default, all steps for all applications will be interleaved.

To support more advanced use cases, you can combine the sequential-by-dependency orchestrator with other orchestrators such as the sequential-by-deployment-group orchestrator.

Note: If orchestrators are configured on the deployment packages, Deploy only uses the orchestrators of the package that you choose when setting up the deployment. The orchestrators on the other packages are ignored.

Dependencies and permissions

When you set up a deployment, Deploy checks the permissions of all applications that will be deployed because of dependencies. You must the have read permission on all dependent applications.

For the environment, you must have one or more of the following permissions:

• deploy#initial: Permission to deploy a new application
• deploy#upgrade: Permission to upgrade a deployed application
• deploy#undeploy: Permission to undeploy a deployed application

Dependencies and composite packages

Composite packages cannot declare dependencies on other applications. A deployment package can declare a dependency on a composite package. This composite package must be installed and not just its components.

Consider this scenario:

• You want to deploy a deployment package that declares a dependency on composite package AppC version [1.0.0,1.0.0].
• AppC version 1.0.0 consists of deployment packages AppD version 3.1.0 and AppE version 5.2.2.

If AppD 3.1.0 and AppE 5.2.2 are deployed on the environment but AppC 1.0.0 is not, then you will not be able to deploy the package.

When you deploy a composite package, the dependency check is skipped. This means that if its constituents declare any dependencies, these will not be checked. In the example scenario above, if AppD version 3.1.0 declares any dependencies, the composite package can still be deployed to an empty environment.

Migrating from composite packages to dependencies

When you deploy an application with dependencies, you have better visibility about what you are deploying than if you use composite packages to group applications. When dependencies are used, the deployment workspace, the deployment plan, and the deployment report show the versions of all applications that were deployed, updated, or undeployed.

A simple way to migrate from composite packages to application dependencies is to create a normal deployment package without any deployables, and then configure its dependencies to point to the other packages that you would have added to the composite package. When you deploy the empty package, Deploy will automatically pick up the required versions of the other applications.

Undeploying application with dependencies

When undeploying an application in Deploy, you can automatically undeploy all of its direct or transient dependencies by setting the Undeploy Dependencies property to TRUE on the deployment package or in the deployment properties. If this property is set to:

• TRUE, dependent applications will be undeployed even if they were originally deployed manually.
• FALSE, the application will be undeployed, but its dependencies will remain deployed.

Tip: You can use a placeholder in the Undeploy Dependencies property to set a different value per environment. For more information, see Using placeholders in Deploy.