Blocks, Actions, and Workspaces: The Modular Principle of Polycrate

TL;DR

• Polycrate structures Ansible automation into three building blocks: Blocks, Actions, and Workspaces – eliminating the classic playbook sprawl and making automation discoverable and shareable.
• Blocks come with their own configuration, playbooks, templates, and artifacts. Workspace configuration overrides block defaults via deep-merge – ideal for reusable standards plus project-specific customizations.
• All blocks run in containers: No local Ansible setup, no Python version turbulence, and a unified toolchain for the entire team. Distribution is via an OCI registry and the PolyHub.
• Compared to Ansible Roles, Polycrate Blocks are self-contained, versionable, shareable via registries, and provide a clear execution and configuration framework – including workflows for more complex processes.
• ayedo develops Polycrate and provides a practical platform with official block collections in the PolyHub and documentation on Polycrate Blocks that scales from individual admins to large platform teams.

Block, Action, Workspace: The Core Principle

Polycrate builds on Ansible but gives automation a clearer form. Three concepts are central:

• Block: A self-contained module with block.poly, playbooks, templates, and artifacts.
• Action: A named entry point into a block (e.g., configure, patch, deploy) that executes exactly one playbook.
• Workspace: The project context in which blocks are instantiated, configured, combined, and orchestrated in workflows.

Important: Polycrate always runs Ansible in a container. This solves the classic dependency problem:

• No local Ansible installation
• No Python version conflicts
• No heterogeneous tool setups in the team

Instead of complex Ansible CLI calls like:

ansible-playbook -i inventory.yml site.yml -e "env=prod" --tags "patch"

you start a defined action:

polycrate run linux-baseline patch

The action knows its playbook, configuration, and container context. This is good DX/UX – even colleagues without deep Ansible knowledge can safely execute automations.

Blocks are described in detail in the official documentation on Polycrate Blocks.

Block Anatomy in Detail

Let's look at a specific block that deploys Linux baseline configuration and patches. Directory structure in the workspace:

acme-corp-automation/
  workspace.poly
  inventory.yml
  blocks/
    linux-baseline/
      block.poly
      patch.yml
      harden.yml
      templates/
        motd.j2
      artifacts/
        baseline-report.md

block.poly: Definition, Configuration, and Actions

# blocks/linux-baseline/block.poly
name: linux-baseline
version: 0.1.0
kind: generic

config:
  os:
    family: linux
    reboot_after_patch: true
  packages:
    common:
      - vim
      - curl
      - htop
  motd:
    enabled: true
    text: "Managed by Polycrate – ACME Corp"

actions:
  - name: patch
    playbook: patch.yml
    description: "Installs updates and optionally reboots"
  - name: harden
    playbook: harden.yml
    description: "Applies basic hardening (SSH, Sysctl, MOTD)"

Key points:

• config: Default values of the block. These are later overridden or supplemented in the workspace.
• actions: Each action refers to exactly one playbook in the same directory.
• version: Version of the block template – important once the block is shared via a registry.

Inventory in the Workspace

The inventory is always in the workspace root as a YAML file inventory.yml. Polycrate automatically sets ANSIBLE_INVENTORY.

# inventory.yml
all:
  hosts:
    server01.acme-corp.com:
      ansible_user: ubuntu
    server02.acme-corp.com:
      ansible_user: ubuntu

The inventory is YAML in the workspace root (not a classic INI-style hosts file).

Ansible Playbook: Using block.config.*

The patch.yml accesses the block configuration:

# blocks/linux-baseline/patch.yml
- name: Patch Linux with Polycrate
  hosts: all
  become: true
  gather_facts: true

  vars:
    reboot_after_patch: "{{ block.config.os.reboot_after_patch }}"

  tasks:
    - name: Update APT Cache
      ansible.builtin.apt:
        update_cache: true
      when: ansible_facts.os_family == "Debian"

    - name: Upgrade all packages (Debian/Ubuntu)
      ansible.builtin.apt:
        upgrade: dist
        autoremove: true
      when: ansible_facts.os_family == "Debian"

    - name: Install YUM/DNF updates (RHEL/CentOS)
      ansible.builtin.yum:
        name: "*"
        state: latest
      when: ansible_facts.os_family in ["RedHat", "Rocky", "AlmaLinux", "CentOS"]

    - name: Optional reboot after patches
      ansible.builtin.reboot:
        msg: "Reboot triggered by Polycrate linux-baseline.patch"
        reboot_timeout: 600
      when: reboot_after_patch | bool

The magic happens at block.config.os.reboot_after_patch: This variable does not come from vars_files or -e, but directly from block.poly or workspace configuration.

Configuration Inheritance and Deep-Merge

For a block to be truly reusable, it needs meaningful defaults – but also the ability to be overridden project-specifically. This is where Polycrate's config inheritance (deep-merge) comes in.

Block Defaults in block.poly

As seen above:

config:
  os:
    family: linux
    reboot_after_patch: true
  packages:
    common:
      - vim
      - curl
      - htop
  motd:
    enabled: true
    text: "Managed by Polycrate – ACME Corp"

Workspace Instance with Overrides

In the workspace, define how the block should look specifically for ACME Corp:

# workspace.poly
name: acme-corp-automation
organization: acme

blocks:
  - name: linux-baseline
    from: cargo.ayedo.cloud/ayedo/infra/linux-baseline:0.3.1
    config:
      os:
        reboot_after_patch: false
      packages:
        common:
          - vim
          - curl
          - htop
          - jq
      motd:
        text: "ACME Corp – Managed Linux Server"

Important:

• from: is the OCI registry reference including the version tag (:0.3.1). Once the block is available locally (on the first polycrate run … you can confirm automatic installation from the registry; polycrate blocks pull remains optional), it lives under blocks/cargo.ayedo.cloud/ayedo/infra/linux-baseline/ (the path under blocks/ mirrors the URL).
• Under config:, you override and extend the block defaults.

Deep-Merge Principle

Polycrate deeply merges block config and workspace config. This means:

• Maps are recursively merged.
• Scalar values are overwritten.
• Lists are replaced by default, not appended (best practices see Best Practices for Blocks).

For our example, the effective configuration at runtime is:

# Effective block.config.* in the action linux-baseline.patch
os:
  family: linux              # from block.poly
  reboot_after_patch: false  # overridden in workspace
packages:
  common:                    # list completely replaced
    - vim
    - curl
    - htop
    - jq
motd:
  enabled: true              # from block.poly
  text: "ACME Corp – Managed Linux Server"  # overridden in workspace

This achieves:

• A reusable standard block (e.g., maintained by a platform team)
• Fine tenant/project-specific customizations in the workspaces
• Clear separation between block definition and usage

More details on inheritance can be found in the documentation on Inheritance in Polycrate.

Polycrate Variables in the Ansible Playbook

Polycrate provides a range of variables in every action without you having to explicitly pass them:

• block.config.* – the merged block configuration (as shown above)
• workspace.* – information and configuration of your workspace
• action.* – metadata about the currently running action

An extended example:

# blocks/linux-baseline/harden.yml
- name: Linux Baseline Hardening with Polycrate
  hosts: all
  become: true
  gather_facts: false

  tasks:
    - name: Disable SSH Root Login
      ansible.builtin.lineinfile:
        path: /etc/ssh/sshd_config
        regexp: '^PermitRootLogin'
        line: 'PermitRootLogin no'
        create: false
        backup: true

    - name: Set MOTD if enabled
      ansible.builtin.copy:
        content: "{{ block.config.motd.text }}"
        dest: /etc/motd
      when: block.config.motd.enabled | bool

    - name: Log Workspace Name
      ansible.builtin.lineinfile:
        path: /var/log/polycrate.log
        line: "Hardened by workspace {{ workspace.name }} via action {{ action.name }}"
        create: yes

Here, all three levels come together:

• block.config.motd.* – block or workspace-specific configuration
• workspace.name – e.g., acme-corp-automation
• action.name – e.g., harden

When working with secrets (e.g., SSH keys, certificates), these typically reside under artifacts/secrets/ in the workspace and are protected by the integrated Workspace Encryption with age. In the playbook, they are available via workspace.secrets['filename'].

From Action to Command: Execution with polycrate run

You can start the harden action above simply by:

cd acme-corp-automation

polycrate run linux-baseline harden

Polycrate ensures:

• A container with Ansible and the defined toolchain is started
• The workspace is mounted into the container
• Environment variables (e.g., ANSIBLE_INVENTORY) are set
• Variables block, workspace, action are provided in the play
• The action's playbook (e.g. harden.yml in the block directory, typically blocks/cargo.ayedo.cloud/ayedo/infra/linux-baseline/ once the block is available locally) is executed against the defined inventory

With plain Ansible, you would need to:

• Provide Ansible and dependencies locally
• Manually manage ansible.cfg and inventory paths
• Assemble and pass extra variables yourself

With Polycrate, this context is modeled in block and workspace.

More on Ansible integration is described in the official Ansible Integration of Polycrate.

Versioning and Distribution via OCI Registry

You use the same registry reference (cargo.ayedo.cloud/...) to share and version blocks—in your team or via PolyHub.

Polycrate uses OCI registries—the same protocol as Docker/OCI container images. The from line in the workspace is the canonical source; the version is always a tag at the end (:0.3.1).

Key points:

• Never use :latest—you want reproducible automation and controlled updates.
• For local development (before push), you create the block under blocks/<name>/—once published, you still reference it in workspace.poly with the full registry URL (see Inheritance).

Pushing and Pulling Blocks from the Registry

As a block author, you want to share your work:

# In the block directory
cd acme-corp-automation/blocks/linux-baseline

# Push to the registry (version is in block.poly)
polycrate blocks push cargo.ayedo.cloud/acme/infra/linux-baseline

On another system or in another workspace, you can then use the same block:

# Make block available locally from registry (optional – often the first polycrate run is enough)
polycrate blocks pull cargo.ayedo.cloud/acme/infra/linux-baseline:0.1.0

You often do not need an explicit polycrate blocks pull: if the block is missing locally, Polycrate detects that on the first polycrate run … and asks whether to install the block automatically. Then reference it in workspace.poly with this URL. This is shareable automation in its purest form: built once, usable many times – in your team.