Back to Hub

cargo.ayedo.cloud/ayedo/k8s/polycrate-operator

Registry block

polycrate block pull cargo.ayedo.cloud/ayedo/k8s/polycrate-operator:0.57.1

Polycrate Operator

Deploy the Polycrate Operator to Kubernetes for automatic discovery and API synchronization.

→ Official Documentation

Overview

The Polycrate Operator is a Kubernetes controller that:

  • Discovers resources in your cluster (Endpoints, Apps, Nodes, Backups, Certificates, Artifacts)
  • Syncs discovered resources to the Polycrate API for centralized management
  • Monitors endpoints for availability and health checks
  • Tracks container images used across your workloads

Quick Start

# Install the operator
polycrate run polycrate-operator install

# Check status
polycrate run polycrate-operator status

# View configuration
polycrate run polycrate-operator info

Prerequisites

  • Kubernetes cluster with kubectl access
  • Kubeconfig is automatically provided by Polycrate
  • For API Sync: Valid Polycrate API token

Actions

Action Description
install Install the Polycrate Operator to Kubernetes
uninstall Remove the Polycrate Operator from Kubernetes
status Show Operator deployment status
info Show Operator configuration

Configuration

Basic Settings

Setting Default Description
namespace polycrate Kubernetes namespace for the operator

Image Configuration

Setting Default Description
image_registry cargo.ayedo.cloud Container registry
image_name library/polycrate Image name
image_tag (from app_version) Optional: Override image tag (defaults to block.app_version)

Image Credentials (Private Registries)

config:
  image_credentials:
    enabled: false
    name: polycrate-registry
    registry: cargo.ayedo.cloud
    username: ""
    password: ""

Deployment Resources

Defaults (raised for CNPG backup discovery / large clusters — Spec 273):

config:
  deployment:
    replicas: 1
    resources:
      requests:
        cpu: "100m"
        memory: "256Mi"
      limits:
        cpu: "1000m"
        memory: "1Gi"

OperatorConfig Settings

The operator_config section defines the OperatorConfig Custom Resource that controls operator behavior.

→ OperatorConfig Documentation

API Sync

Synchronize discovered resources to the Polycrate API.

→ API Sync Documentation

Setting Default Description
enabled false Enable API synchronization
api_url "" Polycrate API URL (e.g., https://api.polycrate.io)
sync_interval_seconds 60 Sync interval in seconds
credentials.secret_name polycrate-api-token Kubernetes Secret containing API token
credentials.token_key token Key in Secret containing the token
credentials.api_token "" API token value (set via secrets.poly)

Example:

# workspace.poly
config:
  operator_config:
    api_sync:
      enabled: true
      api_url: "https://api.polycrate.io"
      sync_interval_seconds: 60
      credentials:
        secret_name: polycrate-api-token
        token_key: token

# secrets.poly (encrypted)
blocks:
  - name: cargo.ayedo.cloud/ayedo/k8s/polycrate-operator
    config:
      operator_config:
        api_sync:
          credentials:
            api_token: "your-api-token-here"

Note: The API token should be stored in secrets.poly which can be encrypted with polycrate secrets encrypt. Since 0.29.0, workspace_id and organization_id are automatically resolved from the Agent Token.

Local Cluster Registration

Register the cluster where the operator runs with the Polycrate API.

Setting Default Description
enabled false Enable local cluster registration
cluster_name "" Name for the cluster (if not set, uses existing API cluster)

Discovery Features

Endpoint Discovery

Discover endpoints from Kubernetes Ingress resources.

→ Endpoint Discovery Documentation

Setting Default Description
enabled true Enable endpoint discovery
watch_namespaces [] Limit to specific namespaces (empty = all)
ignore_namespaces [kube-system, ...] Namespaces to exclude
ingress_classes [] Filter by Ingress classes (empty = all)
gateway_classes [] Filter HTTPRoute discovery by parent GatewayClass (empty = all)
default_check_interval 60 Default health check interval in seconds

App Discovery (K8sApp)

Discover applications from Polycrate meta-secrets (.poly suffix).

→ App Discovery Documentation

Setting Default Description
enabled true Enable K8sApp discovery
watch_namespaces [] Limit to specific namespaces (empty = all)
ignore_namespaces [kube-system, ...] Namespaces to exclude

Node Discovery

Discover and track Kubernetes nodes.

Setting Default Description
enabled true Enable node discovery
label_selector "" Filter nodes by label selector

Backup Discovery

Discover backups from Velero and CloudNativePG.

→ Backup Discovery Documentation

Setting Default Description
enabled true Enable backup discovery
velero_namespace velero Namespace where Velero is installed
ignore_namespaces [] Namespaces to exclude
cnpg_enabled true Enable CloudNativePG backup discovery

Certificate Discovery

Discover TLS certificates from cert-manager.

→ Certificate Discovery Documentation

Setting Default Description
enabled true Enable certificate discovery
watch_namespaces [] Limit to specific namespaces (empty = all)
ignore_namespaces [kube-system, cert-manager, ...] Namespaces to exclude
issuer_filter.include_issuers [] Only include these issuers (empty = all)
issuer_filter.exclude_issuers [] Exclude these issuers

Artifact Discovery

Discover container images from running Pods.

→ Artifact Discovery Documentation

Setting Default Description
enabled true Enable artifact discovery
watch_namespaces [] Limit to specific namespaces (empty = all)
ignore_namespaces [kube-system, ...] Namespaces to exclude
registry_filter.include_registries [] Only include these registries (empty = all)
registry_filter.exclude_registries [registry.k8s.io, k8s.gcr.io] Exclude these registries
pod_label_selector "" Filter pods by label selector
stale_cleanup_minutes 60 Remove stale artifacts after this time
cache_ttl_minutes 5 K8sApp cache TTL

Endpoint Monitoring Agent

Built-in endpoint health monitoring without external agents.

→ Agent Documentation

Setting Default Description
enabled false Enable endpoint monitoring agent
agent_id_prefix polycrate Prefix for agent identification
check_interval_seconds 60 Default check interval
icmp_enabled true Enable ICMP ping checks (requires security.add_capabilities: [NET_RAW])

HTTP Check Defaults

Setting Default Description
timeout_seconds 10 HTTP request timeout
follow_redirects true Follow HTTP redirects
max_redirects 5 Maximum redirects to follow
user_agent Polycrate-Operator-Agent/1.0 User-Agent header

Example:

config:
  operator_config:
    agent:
      enabled: true
      check_interval_seconds: 30
      http_check_defaults:
        timeout_seconds: 5
        follow_redirects: true

Resource Cleanup

Automatic cleanup of stale discovered resources.

Setting Default Description
enabled true Enable stale resource cleanup
stale_threshold_minutes 30 Delete resources not seen for this duration

Metrics

Prometheus/VictoriaMetrics scraping configuration.

Setting Default Description
metrics.enabled true Create VMServiceScrape CR for metrics collection

When enabled and the VictoriaMetrics Operator CRD vmservicescrapes.operator.victoriametrics.com is installed, a VMServiceScrape CR is created so VictoriaMetrics can scrape the operator metrics endpoint (:8080/metrics). If the CRD is missing, install/deploy skips the scrape manifest (and removes any stale artifact) so the rest of the operator install still succeeds.

Example Configuration

Full example with API sync enabled:

blocks:
  - name: polycrate-operator
    from: cargo.ayedo.cloud/ayedo/k8s/polycrate-operator
    config:
      namespace: polycrate

      deployment:
        replicas: 1
        # resources: defaults are 100m/256Mi request, 1000m/1Gi limit

      operator_config:
        name: default

        api_sync:
          enabled: true
          api_url: "https://api.polycrate.io"
          sync_interval_seconds: 30
          # workspace_id and organization_id are auto-resolved from API token (since 0.29.0)

        local_cluster:
          enabled: true
          cluster_name: "production-cluster"

        endpoint_discovery:
          enabled: true
          ignore_namespaces:
            - kube-system
            - kube-public
          default_check_interval: 30

        agent:
          enabled: true
          check_interval_seconds: 30

        artifact_discovery:
          enabled: true
          registry_filter:
            include_registries:
              - cargo.ayedo.cloud
              - docker.io

Troubleshooting

View Operator Logs

kubectl logs -f deployment/polycrate-operator -n polycrate

Check OperatorConfig Status

kubectl get operatorconfig -n polycrate
kubectl describe operatorconfig default -n polycrate

View Discovered Resources

# Endpoints
kubectl get endpoints.polycrate.io -A

# K8sApps
kubectl get k8sapps -A

# Artifacts (cluster-scoped)
kubectl get artifacts

# Certificates
kubectl get certificates.polycrate.io -A

# Backups
kubectl get backups.polycrate.io -A

Links