> ## Documentation Index
> Fetch the complete documentation index at: https://ryvn.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation Dependencies

> Control the order installations come up in an environment and which installation a release's version range applies to.

Installation dependencies declare that one installation must be ready before another installs for the first time. They are set per environment, on the installation itself or on a service inside a blueprint. Unlike [release dependencies](/docs/configure/release-metadata#service-dependencies), they carry no version bounds.

Use them when:

* A new environment needs installations to come up in a specific order (a database before the app that migrates it).
* A service's [release dependency](/docs/configure/release-metadata#service-dependencies) should be checked against one specific installation rather than every installation of that service in the environment.

<Info>
  Release dependencies are used to declare a dependency on specific version(s) of a service.
  Installation dependencies declare an installation ordering requirement.
</Info>

## How they behave

* **First install only.** Ryvn holds the first install until every dependency is `UP_TO_DATE`. After that, upgrades, configuration changes, and secret rotations deploy even while a dependency is being reinstalled or has failed.
* **Narrowing.** If the installation's release depends on a service and `dependencies` names installations of that service, the release's version range is checked against the named installations only, in both directions.
* **No new constraints.** An installation dependency never adds a version bound and never blocks its target from upgrading or uninstalling on its own.
* **Bypasses.** Force deploys, rollbacks, retries, and version pins skip dependency checks.
* **Uninstall order.** When a blueprint installation is uninstalled, dependents are removed before the installations they depend on.

While an installation is waiting, it reports a dependency issue such as `installation dependency postgres-main is not ready (INSTALLING)` and installs automatically once the dependency is ready.

## Configuring on an installation

Add `dependencies` to any `ServiceInstallation` (server, job, Helm chart, or Terraform). Each entry sets exactly one key:

| Key | Meaning |
| - | - |
| `serviceInstallation` | Name of an installation in the same environment. That installation must be ready. |
| `service` | Name of a service. Any ready installation of that service in the environment satisfies it. |

```yaml theme={null}
kind: ServiceInstallation
metadata:
  name: web-production
spec:
  service: web
  environment: production
  dependencies:
    - serviceInstallation: postgres-main     # this installation must be ready
    - serviceInstallation: postgres-replica  # several installations of one service is fine
    - service: redis                         # any ready redis installation
```

Prefer `serviceInstallation` when it matters which one. A `service` entry that matches several installations is satisfied by any ready one, and the sync warns so you can name one.

An entry can't name the installation itself, its own service, repeat another entry, or form a cycle with other installations' dependencies. Dependencies resolve by name, so renaming or deleting a target stops it resolving; a sync that renames an installation warns about every installation still using the old name.

Changing only `dependencies` doesn't redeploy an installation. It re-checks a first install or upgrade that is waiting.

See the `dependencies` property reference on [server](/docs/iac/installations/server#dependencies), [job](/docs/iac/installations/job#dependencies), [Helm chart](/docs/iac/installations/helm-chart#dependencies), and [Terraform](/docs/iac/installations/terraform#dependencies) installations, and the worked examples in [Installation dependencies](/docs/guides/examples/service-dependency-constraints#installation-dependencies).

## Passing from a blueprint

A blueprint declares dependencies on its service children with the same `dependencies` field. The blueprint owns them: every installation the blueprint creates gets the list, and blueprint upgrades keep it in sync. Refer to sibling children by their `alias` or `name`.

```yaml theme={null}
kind: Blueprint
metadata:
  name: full-stack-app
spec:
  installations:
    - service: postgres
      alias: db
      name: '{{ ParentInstallationName }}-db'

    - service: web
      name: '{{ ParentInstallationName }}'
      dependencies:
        - serviceInstallation: db            # sibling child, by alias
        - service: redis                     # any ready redis in the environment
      lifecycle:
        postInstall:
          - run: migrate

    - service: migrate
      name: '{{ ParentInstallationName }}-migrate'
```

When the blueprint installs, Ryvn resolves each entry to what the child's installation will look up:

* A `serviceInstallation` naming a sibling child becomes that child's installation name, so it works with templated names, preview suffixes, and children that have been excluded from blueprint updates.
* A `service` entry whose service the blueprint declares exactly once becomes a named entry, so narrowing applies to that child.
* Anything else passes through and is looked up in the environment. A hub blueprint can depend on an installation or service the customer owns this way.

Values can use blueprint templates such as `{{ input "database_name" }}`, like other child fields. Templates are rendered first, so a rendered value that matches a sibling's alias or name resolves to that sibling.

### Validation

Dependencies on children are checked when the blueprint is published, with the same rules as standalone installations (one key per entry, no self-reference, no duplicates, no cycles between children). In addition:

* `dependencies` are only supported on `service:` children, not on nested `blueprint:` children.
* Depending on a child whose `condition` the dependent doesn't share warns, because the target may be switched off. When it is, the dependent waits with `installation dependency <name> not found; install <name> or remove it from dependencies`, and the blueprint installation reports `INSTALLING`.
* A `service` entry for a service the blueprint declares under two or more names warns, because any ready one will satisfy it.

### Blueprint-managed installations

An installation created by a blueprint can't have its dependencies edited directly; the blueprint owns them. To change them, edit the blueprint, or [exclude the installation](/docs/iac/installations/blueprint#excludedinstallations) from blueprint updates first. Re-including it restores the blueprint's list.

Dependency changes show up in blueprint and installation plans as a `dependencies` field change, and a planned create shows the resolved targets in its desired spec.