Integrations

Overview of the Polycrate CLI integrations: configuration management and deployment, containers and orchestration, remote access, version control and AI integration, with an integration matrix, typical patterns and best practices.

Integrations

Polycrate integrates seamlessly with a wide range of tools and platforms for infrastructure as code, configuration management, container orchestration and cloud provisioning. These integrations let you manage complex infrastructures and applications with a unified workflow.

Overview

graph TB
    Polycrate[Polycrate] --> Ansible[Ansible]
    Polycrate --> Kubernetes[Kubernetes]
    Polycrate --> Docker[Docker & Docker Compose]
    Polycrate --> SSH[SSH]
    Polycrate --> Git[Git]
    Polycrate --> MCP[MCP Server]

    Ansible -->|provisions| Hosts[Linux hosts]
    Ansible -->|deploys| DockerApps[Docker apps]
    Ansible -->|deploys| K8sApps[Kubernetes apps]

    Kubernetes -->|manages| Clusters[K8s clusters]
    Kubernetes -->|deploys with| Helm[Helm charts]

    Docker -->|deploys| Containers[Containers]
    Docker -->|orchestrates| Stacks[Docker Compose stacks]

    SSH -->|connects to| Hosts
    Git -->|synchronizes| Workspace[Workspace]
    MCP -->|connects| AI[AI assistants]

Available integrations

Configuration management & deployment

Ansible

The primary integration for configuration management and deployment. Polycrate offers first-class support for Ansible playbooks as actions.

Features:

Run Ansible playbooks as actions
Automatic inventory integration
Snapshot variables as Ansible extra vars
SSH key management
Framework roles for common tasks
Kubernetes deployment with Ansible
Docker Compose management with Ansible

Use cases:

Provision and configure Linux servers
Deploy applications (Docker, K8s, bare metal)
Fix configuration drift
Multi-host orchestration

→ To the Ansible documentation

Containers & orchestration

Kubernetes

Native integration with Kubernetes clusters for application deployment and cluster management.

Features:

Kubeconfig management per block
Helm chart integration
Namespace management
Ingress configuration
Persistence management
Monitoring integration
Multi-cluster support

Use cases:

Deploy Kubernetes applications
Install and upgrade Helm charts
Manage cluster configuration
Apply Kubernetes manifests

→ To the Kubernetes documentation

Observability — Logs & metrics

Since Polycrate CLI 0.46.0, platform logs and PromQL metrics can be queried directly from the terminal — the CLI uses the Polycrate API as a proxy to VictoriaLogs and VictoriaMetrics.

Features:

polycrate logs with LogsQL passthrough and --follow
polycrate metrics for instant and range queries
Org/workspace/block scoping from the loaded workspace.poly
JSON output for CI and scripting

Use cases:

Troubleshooting without Grafana access
Metrics checks before or after deployments
Agent and CI workflows with machine-readable output

→ To the observability documentation

Docker & Docker Compose

Integration with Docker for container management and Docker Compose stacks.

Features:

Start/stop Docker containers
Deploy Docker Compose stacks
Image building
Registry integration
Manage container networks

Use cases:

Deploy Docker Compose stacks on servers
Manage container-based applications
Orchestrate multi-container setups

→ To the Docker Compose examples

Remote access & connectivity

SSH

Integration with SSH for direct access to hosts and Ansible connections.

Features:

Automatic SSH key management
SSH shortcut: polycrate ssh HOSTNAME
SSH agent integration
Passphrase support ⚠️ Experimental
SSH control master for persistent connections
Host cache for performance

Use cases:

Quick access to Ansible inventory hosts
Debugging on remote servers
Manual operations on hosts

→ To the SSH documentation

Version control

Git

Native Git integration based on go-git – without an external Git installation.

Features:

Built-in Git commands: status, add, commit, push, pull, sync
Colored status output
Conflict detection before pull
Automatic use of the SSH key from the workspace
Auto-commit after actions (optional)

Use cases:

Version workspace changes
Team collaboration
Fast sync workflow with a single command
GitOps workflows

→ To the Git documentation

AI integration

MCP Server

Two separate MCP servers (Model Context Protocol) for AI assistants such as Claude and Cursor.

CLI MCP (polycrate mcp, local):

Browse and filter blocks in the Hub
Fetch block details, README and changelogs
Schemas and documentation for workspace development

API MCP (remote, API key):

Live data of the organization (workspaces, alerts, clusters)
Read logs and metrics, Kubernetes objects
No writes, no secrets

→ CLI MCP · API MCP (platform)

Integration matrix

Tool	Primary Use Case	Action Type	Config Format	State Management
Ansible	Config Management	Playbook	YAML	Idempotent
Kubernetes	Container Orchestration	Kubectl/Helm	YAML	Declarative
Docker Compose	Multi-Container Apps	Ansible	YAML	Imperative
SSH	Remote Access	Direct	-	Stateless
Git	Version Control	CLI Commands	-	Commits
MCP	AI Integration	Server	JSON	Stateless

Typical integration patterns

Pattern 1: Infrastructure → Ansible configuration

graph LR
    Infra[Infrastructure block] -->|provisions| Hosts[Linux hosts]
    Infra -->|generates| Inv[Inventory artifact]
    Inv -->|used by| Ansible[Ansible block]
    Ansible -->|configures| Hosts

Infrastructure block creates hosts (e.g. via cloud provider APIs)
Action generates the Ansible inventory
Ansible block uses the generated inventory for configuration

Example:

# workspace.poly
blocks:
  # Infrastructure block creates servers
  - name: infrastructure
    from: registry.my-org.com/blocks/infra/base:1.0.0
    # Action "provision" writes/updates inventory.yml in the workspace root

  # Ansible block for server configuration
  - name: configure-servers
    from: registry.my-org.com/blocks/ansible/webserver:1.0.0
    # uses the same workspace-wide inventory.yml

Both blocks work against the shared inventory.yml in the workspace root.

Pattern 2: Kubernetes cluster → apps

graph LR
    Cluster[Cluster block] -->|creates| K8s[K8s cluster]
    Cluster -->|generates| KC[Kubeconfig artifact]
    KC -->|used by| App1[App block 1]
    KC -->|used by| App2[App block 2]
    App1 -->|deploys to| K8s
    App2 -->|deploys to| K8s

Cluster block creates the Kubernetes cluster
Kubeconfig is stored as an artifact
App blocks inherit the kubeconfig and deploy to the cluster

Example:

# workspace.poly
name: my-workspace

blocks:
  # Cluster block generates the kubeconfig
  - name: prod-cluster
    from: registry.my-org.com/blocks/cloud/eks:1.0.0

  # App block inherits the kubeconfig from the cluster
  - name: my-app
    from: registry.my-org.com/blocks/k8s/my-app:1.0.0
    kubeconfig:
      from: prod-cluster  # uses the kubeconfig from the cluster block

Pattern 3: Multi-stage deployment

graph TB
    Start[Start] --> Infra[Infrastructure: Provision]
    Infra --> Inv[Generate Inventory]
    Inv --> Ansible[Ansible: Configure]
    Ansible --> K8s[Deploy to Kubernetes]
    K8s --> Verify[Verify Deployment]

Complete deployment with several integrations in one workflow:

# In workspace.poly
name: my-workspace

blocks:
  - name: infrastructure
    # ...
  - name: configure-servers
    # ...
  - name: my-app
    # ...

workflows:
  - name: deploy-complete-stack
    steps:
      - name: provision-infrastructure
        block: infrastructure
        action: provision

      - name: generate-inventory
        block: infrastructure
        action: generate-inventory

      - name: configure-servers
        block: configure-servers
        action: install  # Ansible

      - name: deploy-application
        block: my-app
        action: deploy

Best practices

1. Separation of concerns

Separate infrastructure, configuration and application into separate blocks:

infrastructure-block
  └── generates inventory
        ↓
configure-block (Ansible)
  └── prepares servers
        ↓
app-block (K8s / Docker)
  └── deploys application

2. Artifact-based communication

Use artifacts for communication between integrations:

Infrastructure → inventory artifact → Ansible
Kubernetes setup → kubeconfig artifact → app deployment
Config generator → config files → application

3. Idempotency

All integrations should be idempotent:

Ansible playbooks: use state: present, not imperative commands
Kubernetes: use kubectl apply, not create

4. Error handling

Implement rollback strategies in workflows:

workflows:
  - name: deploy-with-rollback
    steps:
      - name: backup
        block: database
        action: backup

      - name: deploy
        block: app
        action: install
        allow_failure: false  # stop on error

      - name: verify
        block: app
        action: health-check

      # On error: rollback
      - name: rollback
        block: app
        action: rollback

Next steps

Explore the individual integrations in detail:

For configuration management: Ansible documentation
For container orchestration: Kubernetes documentation
For remote access: SSH documentation
For version control: Git documentation
For AI assistants: CLI MCP · API MCP
For security & compliance: Block scanning documentation

Or learn how to create workflows that orchestrate several integrations.