Your First Productive Polycrate Workspace: A Checklist for Getting Started

TL;DR

• A well-named, clearly structured Polycrate workspace is half the battle: a consistent name (e.g., acme-corp-automation) and a simple directory structure prevent chaos before it starts.
• Start with a few well-chosen blocks – depending on the role, e.g., Linux patching, Windows baseline management, or Kubernetes deployment – and consistently pin block versions instead of ever using :latest.
• Enable workspace encryption early, set up Git, and build your first custom block – this checklist makes onboarding reproducible and auditable.
• Common pitfalls include unencrypted secrets, hosts: localhost instead of correct inventories, and missing version pins; with Polycrate and best practices, you avoid these mistakes from the start.
• ayedo supports you with Polycrate, practical best practices, projects, and consulting to turn your first workspace into a sustainable automation platform.

Why the First Workspace Matters

The first productive workspace is more than a test balloon. It sets the stage for how you will automate in the future:

• How consistently your teams work
• How well you meet compliance requirements like the GDPR effective since 05/25/2018
• How easily colleagues can take over and extend automations

Many start with plain Ansible and a quick ansible-playbook on their laptop – and months later face a zoo of playbooks, Python versions, and inventories. Ansible is powerful, but without guardrails, complexity grows faster than you’d like.

Polycrate gives Ansible a clear structure:

• Execution runs in a container → no local Python or Ansible chaos
• Workspace as a central project → guardrails against playbook sprawl
• Blocks as reusable building blocks → sharable automation across teams and registries

This post provides a concrete checklist for your first productive workspace – including name, structure, initial blocks, encryption, Git, and team onboarding.

Workspace Name and Structure: Best Practices from Day 1

Naming Concept

A good workspace name is:

• Descriptive
• Stable over years
• Independent of individuals or short-term projects

Proven pattern:

• {company}-{area}-automation or
• {company}-{product}-platform

Examples:

• acme-corp-automation (company-wide automation)
• acme-retail-platform (platform team for retail business)

Avoid: Names with personal references or environments (max-dev-playground, ansible-test).

Directory Structure

A typical workspace according to the best practices for Polycrate workspaces looks like this:

acme-corp-automation/
  workspace.poly
  inventory.yml
  artifacts/
    secrets/
      kubeconfig.yml        # if you use K8s
  blocks/
    linux-patch/
      block.poly
      patch.yml
    windows-baseline/
      block.poly
      baseline.yml
    k8s-deploy-app/
      block.poly
      deploy.yml
  .git/

• workspace.poly defines the workspace and block instances
• inventory.yml (YAML!) is the central inventory for all Ansible playbooks
• blocks/ contains your local blocks with block.poly and playbooks in the same directory
• artifacts/secrets/ is the obvious place for encrypted files (via Polycrate workspace encryption)

Example workspace.poly

name: acme-corp-automation
organization: acme

blocks:
  - name: linux-patch
    from: linux-patch
    config:
      target_hosts: "linux_servers"

  - name: windows-baseline
    from: windows-baseline
    config:
      target_hosts: "windows_servers"

  - name: k8s-deploy-app
    from: k8s-deploy-app
    config:
      kubeconfig_path: ""

Important:

• from: points to the subdirectory under blocks/ for local blocks
• No fields like source: or version: in the block entry (the version is in the block definition or registry tag)
• config at workspace level is not a free-form key-value map—only documented fields (e.g. toolchain image, paths); see Configuration. Set SSH users per host in inventory.yml (e.g. ansible_user)
• There is no Jinja evaluation in workspace.poly (no {{ workspace.secrets[...] }}). Put sensitive values for kubeconfig_path in secrets.poly (merged with workspace.poly), not as templates in workspace.poly
• Replace the empty kubeconfig_path: "" placeholder via secrets.poly or after you know the real path

The First Custom Block: From Zero to Productive Action

Let’s start with a minimal but productive example for Linux admins: a block for patching all Linux servers.

block.poly: Linux-Patching

name: linux-patch
version: 0.1.0
kind: generic

config:
  target_hosts: "linux_servers"

actions:
  - name: patch
    description: "Patch Linux servers"
    playbook: patch.yml

• version of the block is explicitly set – never work unversioned
• config.target_hosts defines the host group the playbook targets
• The action patch clearly describes what happens: patching via Ansible

inventory.yml: Define Target Systems

all:
  children:
    linux_servers:
      hosts:
        server01.acme-corp.com:
          ansible_user: ubuntu
        server02.acme-corp.com:
          ansible_user: ubuntu
    windows_servers:
      hosts:
        win01.acme-corp.com:
          ansible_user: Administrator
          ansible_connection: winrm
          ansible_port: 5986
          ansible_winrm_server_cert_validation: ignore

This inventory is located at the workspace root (inventory.yml). Polycrate automatically sets ANSIBLE_INVENTORY to this file; you don’t need to configure anything further in the block.

Ansible Playbook: patch.yml

- name: Patch Linux Servers
  hosts: "{{ block.config.target_hosts }}"
  become: true
  gather_facts: true

  tasks:
    - name: Update package cache
      ansible.builtin.apt:
        update_cache: true
        cache_valid_time: 3600

    - name: Upgrade all packages
      ansible.builtin.apt:
        upgrade: dist
        autoremove: true

Important:

• No hosts: localhost and no connection: local – this would only affect the Polycrate container
• hosts is pulled from the block configuration and points to a group from inventory.yml
• Idempotency: Running the playbook multiple times does not lead to unexpected side effects

Execution with Polycrate

polycrate run linux-patch patch

This fundamentally differs from plain Ansible:

• No ansible-playbook -i inventory.yml patch.yml on a locally configured system
• No debate over Python 2.7 vs. 3.x, pip versions, or global ansible.cfg
• Ansible runs in a container, whose toolchain you define centrally – identical on all workstations

More on Ansible integration can be found in the official documentation:
https://docs.ayedo.de/polycrate/ansible/

Which Blocks First? Recommendations by Target Audience

For Linux Admins

Goal: Make routine tasks stable and reproducible.

Recommended first blocks:

1. linux-patch (as above)
2. User and SSH key management (linux-users)
3. Basic hardening (e.g., CIS or company-specific minimum standards)

For hardening, consider using an official block from PolyHub (hub.polycrate.io) or building a custom block that reflects internal policies.

For Windows Admins

Goal: Automate standard tasks around AD, GPO, and software deployment.

Typical starting blocks:

1. windows-baseline: Base roles, PowerShell policy, agents
2. windows-software-deploy: Standard software via Ansible win_* modules
3. ad-user-mgmt: User and group maintenance via Ansible modules for Active Directory

A block.poly for windows-baseline might look like this:

name: windows-baseline
version: 0.2.0
kind: generic

config:
  target_hosts: "windows_servers"

actions:
  - name: apply
    description: "Apply Windows baseline"
    playbook: baseline.yml

The playbooks use hosts: "{{ block.config.target_hosts }}" and the windows_servers group from the inventory – just like in the Linux example.

For Kubernetes and Platform Teams

Goal: Automate cluster operations via Ansible and additional tools (kubectl, Helm).

Useful first blocks:

1. k8s-deploy-app: Deliver application (manifests or Helm charts)
2. k8s-cert-manager (often useful, via PolyHub block with pinned version)
3. k8s-backup-ops: Recurring backup/restore tasks

A block.poly that uses a kubeconfig from the workspace:

name: k8s-deploy-app
version: 0.1.0
kind: generic

config:
  kubeconfig_path: ""

actions:
  - name: deploy
    description: "Deploy app to cluster"
    playbook: deploy.yml

In the playbook, you work with hosts: localhost and connection: local, because the API calls (e.g., kubernetes.core.k8s) go directly from the Polycrate container to the cluster – this is correct here, as the target endpoint is an API, not the container itself. More details can be found in the Kubernetes documentation:
https://docs.ayedo.de/polycrate/kubernetes/

Checklist: From Empty Git Repo to Productive Workspace

These steps have proven effective for getting started:

1. Create Git Repository

   • git init acme-corp-automation
   • .gitignore for local artifacts, e.g., *.retry, temporary files
   • Set up remote (GitHub, GitLab, internal Git platform)

2. Create Workspace

   • Create directory, write workspace.poly (see above)
   • Create inventory.yml and enter initial hosts – cleanly separated by groups

3. Create First Block

   • Under blocks/linux-patch/ create block.poly and patch.yml
   • Set version in block (version: 0.1.0)
   • Test playbook: polycrate run linux-patch patch

4. Enable Workspace Encryption
   Polycrate comes with built-in encryption using age.
   Typical process:

   polycrate workspace encrypt

   • Polycrate guides you through the key setup
   • Files like artifacts/secrets/kubeconfig.yml are stored encrypted
   • You don’t need an external vault – for many teams, the built-in solution is more than sufficient

5. Consistently Pin Block Versions

   • Custom blocks: maintain version field in block.poly
   • Registry blocks (example with a fictional company registry): always with tag:

     - name: nginx-ingress
       from: registry.acme-corp.com/acme/infra/nginx-ingress:0.3.1

     Never use :latest – this is the most common source of “suddenly everything is different”.

6. Integrate PolyHub Blocks (Where Appropriate)

   • Standard topics like ingress, monitoring, logging can often come as ready-made building blocks from PolyHub
   • Company-specific topics (policies, naming conventions, internal APIs) are better represented in custom blocks
     Documentation on the registry:
     https://docs.ayedo.de/polycrate/registry/
     Overview of official blocks:
     https://docs.ayedo.de/polycrate/polyhub/ and https://hub.polycrate.io/

7. Write Team Readme

   • Short description: purpose of the workspace
   • Examples:

     polycrate run linux-patch patch
     polycrate run windows-baseline apply
     polycrate run k8s-deploy-app deploy

   • Notes on workspace encryption and onboarding

With this checklist, you will quickly have a workspace that is:

• Reproducible
• Version-controlled
• Encrypted
• Team-capable

– not just an experiment on your own laptop.

Common Mistakes When Starting – and How to Avoid Them

1. Using hosts: localhost for Real Servers

   • Problem: Ansible runs in the Polycrate container and only changes this – the container is deleted afterwards
   • Solution: Always use groups from inventory.yml (linux_servers, windows_servers, etc.); no connection: local when managing hosts over SSH/WinRM

2. Storing secrets unencrypted in Git

   • Problem: Compliance, security, GDPR (since 05/25/2018)—plaintext credentials in Git are unacceptable today
   • Solution: Enable workspace encryption early; put sensitive files under artifacts/secrets/ and manage them encrypted

3. Not pinning block versions

   • Problem: A PolyHub update or local block change breaks existing deployments
   • Solution: Always set versions in block.poly and explicit registry tags; roll out changes via new versions

4. Building too many blocks at once

   • Problem: You lose oversight before any block is truly stable
   • Solution: Start with 1–3 core blocks (Linux patching, Windows baseline, one K8s deployment), then modularize further

5. Playbooks not named for teams

   • Problem: In a few months nobody remembers what misc.yml did
   • Solution: Clear names (patch.yml, baseline.yml, deploy.yml) and matching action names (patch, apply, deploy)

Team Onboarding: Bringing Colleagues into the Workspace

Polycrate should not be a single-person tool but a shared platform. Teams report good results with:

1. Simple entry commands

   • README front page: “How to run patching”
   • Copy-paste commands:

     polycrate run linux-patch patch

   • No Ansible CLI knowledge required—Polycrate abstracts complexity via actions

2. Role-based onboarding

   • Linux admins: focus on linux-patch and linux-users
   • Windows admins: windows-baseline, windows-software-deploy
   • K8s team: k8s-deploy-app, plus official K8s blocks from PolyHub as needed
     This creates ownership: “This is my area, and I can act on it.”

3. Shared guardrails

   • Conventions for block names, action names, playbook layout
   • Decide what comes from PolyHub vs. stays internal
     Documented best practices help a lot.

4. Training and pairing

   • Short sessions where a senior colleague shows how a new block is created
   • Pairing early so more people can change blocks without friction

With Polycrate you have the right foundation: containerized execution fixes the dependency problem, the block model adds structure and guardrails, and workspace encryption makes compliance easier without heavyweight external tools.

Frequently Asked Questions

Do I need Ansible and Python on every admin machine?

No. Polycrate solves this by running Ansible fully in the container. Locally you only need Polycrate and a container runtime (e.g. Docker or Podman). Ansible version, Python packages, and extra tools (kubectl, Helm, Azure CLI, etc.) are defined centrally in the toolchain container—everyone uses the same environment.

Can I reuse my existing Ansible playbooks?

Yes. In many starter projects we put existing playbooks into new blocks instead of rewriting everything:

• Migrate inventory to inventory.yml in the workspace
• Adjust hosts to reference groups and/or block configuration
• Replace ansible-playbook invocations with polycrate run BLOCK ACTION

The value comes from structure (blocks, workflows) and containerized execution. For a deeper migration we can plan together as part of our consulting.

What does ayedo do in Polycrate starter projects?

Typically:

• Joint definition of workspace structure and naming
• Building 2–4 core blocks (Linux, Windows, optionally Kubernetes/cloud)
• Introducing workspace encryption and Git workflows
• Supporting team onboarding (workshops, pairing, reviews)

The goal is always that your team can evolve Polycrate independently—we provide the scaffold and know-how. For questions, use our contact form or https://ayedo.de/kontakt/

More questions: FAQ

Next Steps

At the end of this series you have not a finished product but a toolkit: With a first clean workspace, clear blocks, and consistent versioning, you have a foundation that lasts.

Polycrate addresses hurdles many teams see with plain Ansible:

• The dependency problem goes away because the full toolchain runs in the container—consistent across workstations.
• The block model gives playbooks a structure you can version, share, and reuse—across the team or via registries like PolyHub.
• Workspace encryption with age simplifies handling sensitive data and helps meet compliance (e.g. GDPR since 05/25/2018) without introducing a separate vault product.

As the team behind Polycrate, ayedo supports you in this phase—from the first productive workspace to company-wide automation platforms. Our consulting offerings combine platform engineering practice with compliance, security, and enterprise architecture.

Whether you want to unify Linux and Windows administration, integrate Kubernetes clusters, or establish policy as code for audits—we define a workspace and block landscape that fits your organization.

If you do not want to plan your first productive workspace alone, or want to migrate existing Ansible cleanly into Polycrate, get in touch—with real examples from your day-to-day work.

Workshops and formats: Workshops · tailored support: Consulting.