Product Release Dependencies Extension

This extension specifies dependencies on other Apollo Product Releases. Given several Product Releases and their manifests, Apollo can construct a dependency graph and validate that a cluster's versions match all declared constraints. As new versions are released, upgrades which continue to satisfy all constraints can be safely applied.

Copied!
1
2
3
4
5
6
7
8
9
extensions:
  product-dependencies:              # An unordered list of Product Release dependencies
   - product-group: org.postgresql   # (required) The dependency's product-group (as per its Apollo Product Spec manifest)
     product-name: postgresql        # (required) The dependency's product-name (as per its Apollo Product Spec manifest)
     minimum-version: 9.3.6          # (required) An orderable version indicating the lowest allowed
                                     #            version (inclusive) for this dependency
     maximum-version: 9.6.x          # (required) A version matcher indicating the highest allowed version
                                     #            (inclusive) for this dependency
     optional: false                 # (optional) Whether the dependency is optional. Defaults to false.

Orderable versions and version matchers are defined in Product Version Specification.

Version Compatibility

The optional minimum-version and maximum-version fields act as constraints specifying which versions of its dependencies are supported. A dependency version v is supported if and only if it satisfies both the lower and the upper bounds:

• minimum-version is an orderable version such that v >= minimum-version
• maximum-version is a version matcher matching some release version upper-bound such that upper-bound >= v

The recommended-version, if specified, must be compatible with the given minimum and maximum version bound and indicates the recommended version of the dependency.

In the postgresql example above, the following versions would satisfy the dependency specification: 9.3.6, 9.4.0, 9.4.2-rc1, 9.6.0-rc1, and 9.6.1-22-g1a2b3c4. The following examples do not satisfy the version range: 9.2.0 (too low), 10.0.0 (too high), 11.1.2-rc2 (too high), 9.7.0-1-gabcdef (too high), 9.5.0-custom-branch (non-orderable).

Optional Dependencies

Some Product Releases can be deployed in multiple valid setups. Some of those setups might require a given dependency, while others might not. The optional field can be used to indicate to Apollo that a given dependency might not be present in some valid setups. However, if the dependency is present in the Environment, its version must be within the declared range of versions.

Apollo will ensure that optional dependencies are either not present, or satisfy the constraints as documented above. Note that this means optional dependencies will not block the uninstallation of any Entity.

No other conclusions should be made based on the presence of optional dependencies. Specifically, not all setups that respect optional dependencies should be considered valid by default. In reality, only a small subset of them might be valid.

As an example, consider a service "nice-service" that is able to store its underlying data in either Postgres or Cassandra, but only one of them. Such service should declare optional dependencies on both Postgres and Cassandra to ensure that the absence of either of them does not block its management by Apollo and to ensure that the service actually being used for data storage is in a compatible version. However, it should not be assumed that "nice-service" can function correctly with neither Postgres or Cassandra, even though both are listed as optional. When managing "nice-service" with Apollo, an Environment editor should declare either Postgres or Cassandra to be managed by Apollo to ensure that the appropriate Product Release dependencies are respected for that setup.

The set of valid setups in which "nice-service" can be deployed should be separately defined by a Product editor. The place and format in which those are specified are out of scope of the documentation of the Product Release dependencies manifest extension.

Install ordering

When installing Entities with Product dependencies, Apollo complies with the following rules:

• If a Product Release declares a required dependency that is not part of a circular required dependency, it will not be installed until all the required dependencies are successfully installed. For example, if Product A depends on Product B, and there are no dependency chains between B and A, then Apollo will install B before it installs A.
• Apollo does not provide guarantees regarding the order of installation for a Product Release's required dependencies. For example, if Product A depends on Products B and C, and there are no dependencies between B and C, then it is nondeterministic whether B or C will be installed first.
• Apollo does not guarantee that a Product Release's optional dependencies will be installed before the Product Release itself. For example, if Product A has an optional dependency on Product B, then Apollo might install A before installing B.
• Apollo does not guarantee the order of installation for circular required dependencies. For example, if Product A depends on Product B, Product B depends on Product C, and Product C depends on Product A, then Apollo might not install B before installing A.