agent Configuration

The PiVirt Agent is configured via a declarative YAML configuration file located at /etc/pivirt-agent/config.yaml. It manages ConnectRPC gateway settings, PiTrust mTLS credentials, and upstream backend connections.

Configuration File

Location: /etc/pivirt-agent/config.yaml

Complete Example

# Server configuration
server:
  connectrpc:
    addr: "0.0.0.0:8443"
    tls:
      cert_file: "/etc/pivirt-agent/tls/server.crt"
      key_file: "/etc/pivirt-agent/tls/server.key"
      ca_file: "/etc/pivirt-agent/tls/ca.crt"
      client_ca_file: "/etc/pivirt-agent/tls/ca.crt"

  grpc_internal:
    addr: "0.0.0.0:9000"
    # Inter-node gRPC with PiTrust mTLS

  metrics:
    addr: "0.0.0.0:8444"
    path: "/metrics"

# PiTrust PKI & mTLS
tls:
  enabled: true
  ca_file: "/etc/pivirt/certs/ca-chain.pem"
  cert_file: "/etc/pivirt/certs/agent-client.crt"
  key_file: "/etc/pivirt/certs/agent-client.key"
  verify_peer: true
  require_client_cert: true

# Service discovery
service_discovery:
  type: "etcd"
  etcd:
    endpoints:
      - "https://etcd-0.pilab.hu:2379"
      - "https://etcd-1.pilab.hu:2379"
      - "https://etcd-2.pilab.hu:2379"
    ca_file: "/etc/pivirt-agent/etcd/ca.crt"
    cert_file: "/etc/pivirt-agent/etcd/client.crt"
    key_file: "/etc/pivirt-agent/etcd/client.key"
    prefix: "/pivirt/services"

# Backend services
backends:
  pivirtd:
    endpoint: "unix:///run/pivirtd/pivirtd.sock"
    timeout: "30s"
    retry:
      max_attempts: 3
      backoff: "100ms"

  iscsiman:
    endpoint: "unix:///run/iscsiman/iscsiman.sock"
    timeout: "10s"

  osinfodb:
    endpoint: "https://osinfodb.pilab.hu:8443"
    timeout: "30s"

# Authentication
auth:
  oidc:
    issuer_url: "https://auth.pilab.hu/realms/pivirt"
    client_id: "pivirt-agent"

  rbac_policy: "/etc/pivirt-agent/rbac.yaml"

# Logging
logging:
  level: "info"
  format: "json"
  output: "stdout"
  sampling:
    initial: 100
    thereafter: 100

# Tracing
tracing:
  enabled: true
  endpoint: "http://jaeger.pilab.hu:14268/api/traces"
  sampling_rate: 0.1

Configuration Sections

server

connectrpc.addr - ConnectRPC endpoint (default: 0.0.0.0:8443)
connectrpc.tls.* - TLS configuration for external clients
grpc_internal.addr - Internal gRPC endpoint (default: 0.0.0.0:9000)
metrics.addr - Metrics endpoint (default: 0.0.0.0:8444)

tls

enabled - Enable TLS / mTLS
ca_file - Path to PiTrust CA bundle (ca-chain.pem or PiRootR1.pem)
cert_file - Path to issued X.509 certificate
key_file - Path to private key
verify_peer - Require peer certificate verification
require_client_cert - Require client certificate for mTLS

service_discovery

type - Discovery backend (etcd, consul, dns)
etcd.endpoints - etcd cluster endpoints
etcd.prefix - Key prefix for service registration

backends

pivirtd.endpoint - pivirtd gRPC endpoint
iscsiman.endpoint - iscsiman gRPC endpoint
osinfodb.endpoint - osinfodb endpoint

auth

oidc.issuer_url - OIDC provider URL
oidc.client_id - OIDC client ID
rbac_policy - RBAC policy file path

logging

level - Log level (debug, info, warn, error)
format - Log format (json, text)
output - Output destination (stdout, stderr, file path)

tracing

enabled - Enable distributed tracing
endpoint - Tracing backend endpoint
sampling_rate - Trace sampling rate (0.0-1.0)

Environment Variables

PIVIRT_AGENT_SERVER_CONNECTRPC_ADDR="0.0.0.0:8443"
PIVIRT_AGENT_TLS_ENABLED="true"
PIVIRT_AGENT_SERVICE_DISCOVERY_TYPE="etcd"
PIVIRT_AGENT_LOGGING_LEVEL="info"

Validation

pivirt-agent --config /etc/pivirt-agent/config.yaml --validate

Hot Reload

pivirt-agent reload