Best Practices

Short operating rules for Polycrate workspaces and blocks: workspace layout and naming, one environment per workspace, block versioning, metadata, actions and workflows, container, security and logging.

Best Practices

Short operating rules for workspaces and blocks. Schema and field references live in the concept pages — this page only covers "how we do it".

Workspace organization

Location and structure

Store workspaces under $HOME/.polycrate/workspaces/<organization>/<workspace>/ so that polycrate workspace list, polycrate workspace clone and the usual paths work.

acme-production-1/
├── workspace.poly
├── secrets.poly          # or secrets.poly.age
├── CHANGELOG.poly
├── Dockerfile.poly       # optional
├── inventory.yml         # optional, one inventory per workspace
├── blocks/
├── artifacts/
└── README.md

Naming

Scheme: <org>-<purpose>-<count> (e.g. acme-production-1). Organization names are slugified (acme, not ACME Corp.).

→ Regex and rules: Naming conventions

One environment = one workspace

No environment variables or templates in .poly files. Production and staging are separate workspaces with their own literal values.

# acme-production-1/workspace.poly
name: acme-production-1
organization: acme
blocks:
  - name: my-app
    from: cargo.ayedo.cloud/acme/k8s/my-app:1.0.0
    config:
      replicas: 3

→ Why no substitution: Configuration

Git and changelog

• Run polycrate git sync regularly (or add/commit/pull/push).
• Track workspace changes in CHANGELOG.poly; show them with polycrate workspace changelog.

→ Git

Inventory and Kubeconfig

Per workspace one inventory (inventory.yml in the root) and one kubeconfig (artifacts/secrets/kubeconfig.yml). kubeconfig.from / inventory.from on block instances are legacy.

→ Inheritance · Artifacts

Blocks

Versions

• Always use an explicit tag in from:: …/block:1.2.3, never bare / :latest in production.
• An installed block version is a singleton in the workspace — after blocks pull, adjust all instances, then validate:

polycrate validate workspace-poly ./workspace.poly

→ Details: Dependencies – Singletons · Blocks

Metadata, examples, CVE

Field catalogs and schema belong in the block documentation:

Short rules for template blocks (Hub/catalogue):

• Set display_name, icon_url, kind/type/flavor, app_version, upstream URLs.
• At least one example in examples.poly.
• For CVE matching: maintain vulnerability.products.
• After blocks push (CLI ≥ 0.51.3): API display_name = registry URL; the human-readable title stays in block.poly for Hub/local use.

Block scoping

One app block = one app = one chart = one namespace. Dependencies (DB, cache) as separate blocks. Maintain CHANGELOG.poly on the block (SemVer, Conventional Commit type).

Pass Polycrate labels under block.labels through to Helm/manifests.

Actions and workflows

Common action names: install, uninstall, update, backup/restore, status, validate. Critical steps with prompt:; in CI use --force. Keep actions idempotent (Ansible).

Workflows for recurring chains (deploy-production, backup-databases); only set allow_failure deliberately when needed.

→ Actions · Workflows

Container

The image is Ubuntu/Debian (apt-get, not apk). Additional tools via Dockerfile.poly. Extra mounts: polycrate run … --mount host:container.

→ The Polycrate Container · Configuration – Container

Security

• Dedicated SSH keys per workspace under artifacts/secrets/ (created by workspace init); do not copy personal keys.
• Encrypt sensitive workspaces: polycrate workspace encrypt.
• Secrets only in secrets.poly (or .age), never in workspace.poly. No env substitution in .poly.

→ Workspace encryption · SSH

Logging

polycrate --loglevel 2 run my-block install

→ CLI reference

Configuration (reference)

YAML anchors in workspace.poly are technically possible but not recommended (CLI/API rewrite the file). Set recurring values literally.

→ Configuration

See also

• Blocks
• Configuration
• Dependencies
• Naming conventions
• Workspaces
• Production example