Dependencies

How Polycrate resolves block dependencies via from: in workspace.poly: interactive dependency prompt, --blocks-auto-pull, manual pulls, dependency sources, block versions as singletons and troubleshooting.

Dependencies

Polycrate supports block dependencies through the from: reference in workspace.poly. When a block instance inherits from a template block, that block is automatically treated as a dependency.

How do dependencies work?

In workspace.poly, block instances reference template blocks via from::

# workspace.poly
blocks:
  - name: my-postgres
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1  # <- Dependency
    config:
      namespace: production

In this example the registry block cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1 is a dependency. Polycrate detects this automatically and pulls the block when needed.

Dependency resolution

Interactive dependency prompt

Since version 0.28.0 Polycrate shows an interactive prompt when missing or outdated block dependencies are detected while loading a workspace.

Detected states:

Status Meaning Action
[MISSING] Block is not installed Block is pulled
[UPGRADE] Installed version is older than requested Update to the new version
[DOWNGRADE] Installed version is newer than requested ⚠️ Warning + confirmation required

Example prompt:

┌─────────────────────────────────────────────────────────────────────────────┐
│  Block Dependency Issues                                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│  The following block dependencies need to be resolved:                      │
│                                                                             │
│  ● cargo.ayedo.cloud/ayedo/k8s/cert-manager:v2.0.0          [MISSING]      │
│    └─ required by: cert-manager                                             │
│                                                                             │
│  ● cargo.ayedo.cloud/ayedo/k8s/ingress-nginx:v1.5.0         [UPGRADE]      │
│    └─ installed: v1.4.0 → requested: v1.5.0                                │
│                                                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│  ▸ Install/Update all                                                       │
│    Solve manually                                                           │
└─────────────────────────────────────────────────────────────────────────────┘

Options:

  1. Install/Update all - Resolve all dependencies automatically
  2. Solve manually - Shows the commands required for manual resolution

CI/CD environments:

In non-interactive environments (CI/CD pipelines, pipes) a detailed error message with all required commands is printed automatically:

Block dependency issues found:

  MISSING: cargo.ayedo.cloud/ayedo/k8s/cert-manager:v2.0.0
    required by: cert-manager

  UPGRADE: cargo.ayedo.cloud/ayedo/k8s/ingress-nginx
    installed: v1.4.0 → requested: v1.5.0

To resolve, run:
  polycrate block pull cargo.ayedo.cloud/ayedo/k8s/cert-manager:v2.0.0
  polycrate block pull cargo.ayedo.cloud/ayedo/k8s/ingress-nginx:v1.5.0

Or use: polycrate run --blocks-auto-pull <block>.<action>

Polycrate automatically detects common CI/CD environments (GitHub Actions, GitLab CI, Jenkins, CircleCI, etc.) and disables interactive prompts.

Automatic resolution with --blocks-auto-pull

Alternatively, you can use the --blocks-auto-pull flag. Polycrate then automatically pulls all missing dependencies without a prompt:

# On every workspace interaction
polycrate run my-postgres install --blocks-auto-pull

# On workflow execution
polycrate workflows run deploy-stack --blocks-auto-pull

With --blocks-auto-pull, all blocks referenced in workspace.poly are automatically pulled from the registry if they are not present locally.

Non-interactive mode

With the --non-interactive flag you can explicitly disable interactive prompts:

polycrate run my-block install --non-interactive

In this mode an error is printed for missing dependencies instead of a prompt.

Pulling dependencies manually

You can also pull dependencies manually:

# Pull block from registry (full path required)
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1

# Pull from your own registry
polycrate blocks pull registry.my-org.com/infra/postgres:1.2.0

Dependencies in workspace.poly

All dependencies are defined in workspace.poly:

# workspace.poly
name: my-workspace

blocks:
  # Cluster block (template from registry)
  - name: k8s
    from: registry.my-org.com/blocks/k8s/cluster:1.0.0

  # Database block (template from registry)
  - name: postgres
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1
    kubeconfig:
      from: k8s  # Uses the kubeconfig of the k8s block
    config:
      namespace: databases

  # App block (local template block)
  - name: my-app
    from: my-app-template  # Local block in blocks/my-app-template/
    kubeconfig:
      from: k8s

Dependency sources

Dependencies are defined in workspace.poly and can come from different sources:

1. Local template blocks

# workspace.poly
blocks:
  - name: my-app
    from: base-app  # Local block in blocks/base-app/

If base-app exists in the local workspace (in blocks/base-app/), it is used directly as the template.

2. Registry blocks

# workspace.poly
blocks:
  - name: my-app
    from: registry.my-org.com/blocks/k8s/base-app:1.0.0

If the block is not present locally, it is pulled from the specified registry.

Practical workflows

Workflow 1: project setup with dependencies

# 1. Clone the workspace
git clone https://github.com/myorg/my-workspace.git
cd my-workspace

# 2. Pull all dependencies automatically (with full registry paths in workspace.poly)
polycrate run my-app install --blocks-auto-pull

# Or manually:
# polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1
# polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/redis:0.1.5
# polycrate run my-app install

Workflow 2: updating a dependency

# 1. Check which instances use the block
grep -r "cloudnative-pg" workspace.poly

# 2. Pull the new version (overwrites the old version!)
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.4.0

# 3. Adjust ALL block instances in workspace.poly:
#    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.4.0

# 4. Validate the workspace (YAML syntax, without block resolve)
polycrate validate workspace-poly ./workspace.poly

# 5. Test
polycrate run my-postgres install

Important: If several instances use the same template block, all from: references must be updated, otherwise dependency resolution fails.

Workflow 3: CI/CD with dependencies

# .github/workflows/deploy.yml
name: Deploy

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Install Polycrate
        run: |
          curl -sSL https://get.polycrate.io | bash

      - name: Deploy with auto-pull
        run: |
          polycrate run my-app install --blocks-auto-pull

Dependency management best practices

1. Use explicit versioning

Use specific versions for stable dependencies:

# workspace.poly
blocks:
  # ✅ Good: explicit, specific version
  - name: my-postgres
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1

  # ❌ Bad: latest (can break unexpectedly)
  - name: my-postgres-bad
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:latest

  # ❌ Bad: no version (risks unexpected updates)
  - name: my-postgres-risky
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg

Why explicit versions are critical:

  • Reproducibility: identical behavior on every polycrate block pull
  • No surprises: no accidental up-/downgrade
  • Team consistency: all team members work with the same version
  • Rollback safety: in case of problems you know exactly which version to return to

2. Local copies for customizations

If you need to customize a dependency, pull it locally:

# Pull the dependency locally
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1

# It is now in blocks/cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg/
# You can customize it (e.g. modify playbooks)

# workspace.poly - the block automatically uses the local copy
blocks:
  - name: my-postgres
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1  # Uses the local copy if present

3. Private registries

For private/proprietary blocks use private registries:

# workspace.poly
blocks:
  - name: my-internal-app
    from: registry.mycompany.com/apps/base-app:1.0.0

Authentication via: 

# Docker registry login
docker login registry.mycompany.com

# Polycrate uses the Docker credentials
polycrate blocks pull registry.mycompany.com/apps/base-app:1.0.0

4. Dependency documentation

Document dependencies in the workspace README:

# my-workspace

## External dependencies

| Block | Template | Version | Description |
|-------|----------|---------|--------------|
| `my-postgres` | `cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg` | `1.2.0` | PostgreSQL database |
| `my-app` | `registry.mycompany.com/apps/base-app` | `1.0.0` | Internal app |

## Installation

    polycrate run my-postgres install --blocks-auto-pull

Troubleshooting

Dependency not found

Error: Block 'postgres-base' not found

Solution: 

# Pull manually with the full registry path
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1

# Or use auto-pull (with the full registry path in workspace.poly)
polycrate run my-app install --blocks-auto-pull

Block versions are singletons

Example: several instances, one version:

# workspace.poly - both instances share the same template block
blocks:
  - name: app-database
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1  # ← Share
    config:
      namespace: app

  - name: analytics-database
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1  # ← the same block!
    config:
      namespace: analytics

What happens on an update:

# Pull the new version - OVERWRITES the existing block!
polycrate block pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.4.0

After the pull, all instances must be updated:

# workspace.poly - adjust ALL from: references!
blocks:
  - name: app-database
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.4.0  # ← Updated

  - name: analytics-database
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.4.0  # ← Updated

No parallel versions of the same block

A gradual rollout or a canary with two different tags of the same registry block in one workspace.poly is not supported: the workspace works with exactly one installed version of this template.

Instead:

  • Different workspace (or clone) for tests with a newer from: version
  • Sequentially: raise the version in all from: lines, pull, validate (polycrate validate workspace-poly ./workspace.poly), deploy
  • Separate environments (e.g. staging vs. production), each with its own workspace.poly and one consistent version per environment

Registry not reachable

Error: Failed to pull from registry

Solution (OCI registry):

# Network and authentication for the registry you pull from
# (hostname from your from: path, e.g. cargo.ayedo.cloud)
docker login cargo.ayedo.cloud
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1

The Polycrate Hub (web interface for search and documentation) is not a Docker registry endpoint and does not replace docker login. Authentication for pulling block images always happens against the OCI registry given in the from: path.

Hub URL only for the Hub website/API (browse, metadata), not for pulls:

export POLYCRATE_HUB_URL=https://hub.polycrate.io

An "alternative Hub" URL does not change which registry polycrate blocks pull fetches images from – only the from: path in workspace.poly is authoritative for that.

Polycrate Hub

Publicly available blocks provided by ayedo can be found in the Polycrate Hub:

hub.polycrate.io

Among other things, the Hub offers:

  • Ready-made blocks for common use cases (Postgres, Redis, Nginx, etc.)
  • Versioned releases for stable deployments
  • Documentation for every block
  • Search to find suitable blocks

Relation to other concepts

  • Inheritance: dependencies are based on from: inheritance
  • Registry: dependencies are pulled from OCI registries
  • Polycrate Hub: catalog and documentation of public blocks (not identical to the OCI registry)
  • Blocks: dependencies are blocks used by other blocks