Bridging Container Orchestration and Autonomous AI: The Cognee Portainer Connector

#opensource

Managing modern cloud-native architectures is fraught with container sprawl. Across distributed development teams, thousands of microservice containers, Swarm stacks, and Kubernetes deployments run simultaneously across local workstations, staging clusters, and remote edge gateways.

While Portainer (boasting over 33,000+ GitHub stars) provides a premier GUI and management plane for containerized infrastructure, the rich architectural context inside those containers—such as exposed ports, volume mount topologies, restart policies, and Docker Compose definitions—remains siloed inside dashboards and daemon sockets.

With the release of the Portainer Connector for Cognee, developers can now seamlessly stream their live container infrastructure directly into Cognee, transforming raw DevOps telemetry into an AI-queryable knowledge graph and memory layer.

Why Portainer + Cognee?

Autonomous AI coding agents, DevOps assistants, and Site Reliability Engineers (SREs) frequently require real-time infrastructure answers that static codebases cannot provide:

"Which containers in our staging cluster have port 6379 open without authentication?"
"Show me the compose definition and volume mounts for the caching stack."
"Are any edge nodes running outdated container base images?"
"What microservices depend on the internal messaging broker?"

By connecting Portainer to Cognee:

Semantic Container Discovery: Natural language searches across container names, image tags, network ports, and storage volumes.
Topology Synthesis: Cognee's cognify() pipeline automatically extracts graph relationships between environments, stacks, and containers.
Orphan Cleanup: Decommissioned containers or deleted stacks are automatically forgotten thanks to Cognee's write_disposition="replace".
Idempotent Synchronization: Deterministic document hashing ensures re-running the connector updates existing graph nodes without duplicate entities.

Architectural Deep Dive

The Portainer Cognee connector is built to production standards:

Cluster & Environment Discovery: Maps all registered Docker standalone engines, Swarm managers, Kubernetes clusters, and remote Edge agents.
Stack & Compose Ingestion: Extracts stack names, deployment statuses, and raw docker-compose YAML definitions into memory.
Container Catalog: Ingests container names, image digests, running states, health statuses, port forwardings, and volume mounts.
Resilient HTTP Communication: Built-in exponential backoff with jitter on HTTP 429 rate limits and 5xx transient server errors.
Credential Sanitization: The connector automatically masks tokens, passwords, and API keys ([REDACTED_PORTAINER_CREDENTIAL]) in logs and exception traces.

Quickstart Guide

1. Installation

Install Cognee and the community Portainer connector:

pip install cognee cognee-community-connector-portainer

Or using uv:

uv add cognee cognee-community-connector-portainer

2. Ingesting Infrastructure into Memory

import asyncio
import os
import cognee
from cognee_community_connector_portainer import (
    PortainerConfig,
    portainer_connector,
)

async def main():
    # 1. Configure the connector
    config = PortainerConfig(
        api_url=os.getenv("PORTAINER_URL", "https://portainer.local:9443"),
        api_key=os.getenv("PORTAINER_API_KEY", "ptr_your_api_key"),
        include_containers=True,
        include_stacks=True,
    )

    print("Fetching Portainer environment & container telemetry...")
    documents = await portainer_connector(config)
    print(f"Retrieved {len(documents)} infrastructure documents.")

    # 2. Ingest into Cognee memory
    print("Ingesting into Cognee...")
    await cognee.add(documents, dataset_name="infrastructure_topology")
    await cognee.cognify(dataset_name="infrastructure_topology")

    # 3. Query container and cluster topology with natural language
    query = "What containers are currently running with exposed ports?"
    print(f"\nQuerying Cognee: '{query}'")
    results = await cognee.search(query, dataset_name="infrastructure_topology")

    for r in results:
        print(f"\nMemory Result: {r}")

if __name__ == "__main__":
    asyncio.run(main())

What Does Ingested Memory Look Like?

The connector parses complex Docker daemon JSON into clean, structured Markdown reports optimized for embedding and graph extraction:

# Container Runtime State: Primary Docker Cluster (ID: 1)

**Total Containers**: 2

## Container Catalog
### Container: /redis-master
- **Container ID**: `abc123456789`
- **Image**: `redis:7-alpine`
- **State / Status**: `running` (Up 4 days, healthy)
- **Port Forwarding**: 6379->6379/tcp
- **Volume Mounts**: `/var/lib/redis` -> `/data`

When Cognee processes this markdown through cognify(), it constructs knowledge graph nodes representing:

Environments (e.g., Primary Docker Cluster)
Containers (e.g., /redis-master)
Images (e.g., redis:7-alpine)
Relationships (e.g., Primary Docker Cluster -> RUNS -> /redis-master, /redis-master -> MOUNTS -> /data, /redis-master -> EXPOSES -> 6379)

Summary & Open Source

The Portainer connector is an open-source contribution to the Cognee Community ecosystem.

Cognee Core: https://github.com/topoteretes/cognee
Community Connectors: https://github.com/topoteretes/cognee-community
Portainer: https://github.com/portainer/portainer

Try it out today to bring intelligent container topology memory to your DevOps workflows!

DEV Community