<a id="reference-architecture"></a>

# Architecture

This page explains the architecture of the Falco operators and how the components interact to provide runtime security monitoring.

## Overview

The Falco operators consist of two charms that work together to provide comprehensive runtime security monitoring:

- **Falco operator**: A subordinate charm that deploys Falco on machines or Kubernetes nodes
- **Falcosidekick K8s operator**: A Kubernetes charm that receives alerts from Falco and forwards them to various outputs

## Charm deployment architecture

The following diagram shows the complete end-to-end architecture with Falcosidekick, observability, and TLS:

In this architecture:

1. **Alert generation**: Falco detects security events and sends alerts to Falcosidekick through the `http-endpoint` relation
2. **Alert forwarding**: Falcosidekick receives alerts and forwards them to OpenTelemetry Collector using the `send-loki-logs` relation
3. **Log aggregation**: OpenTelemetry Collector sends logs to Loki in the COS model using cross-model relations
4. **Visualization**: Grafana queries Loki to display security alerts in dashboards
5. **TLS termination**: Either self-signed certificates (development) or Gateway API Integrator with Lego (production) provides HTTPS

## Data flow

The following diagram illustrates the data flow from a security event to visualization:

## Integration

The charms support the following integration:

### Falco operator

- **`general-info` (requires)**: Attaches to a principal charm to monitor the same host
- **`cos-agent` (provides)**: Exposes metrics and logs for collection by Grafana Agent or OpenTelemetry Collector
- **`http-endpoint` (requires)**: Connects to Falcosidekick to send security alerts

### Falcosidekick K8s operator

- **`certificates` (requires)**: Obtains TLS certificates for HTTPS
- **`grafana-dashboard` (provides)**: Provides pre-configured Grafana dashboards
- **`http-endpoint` (provides)**: Receives alerts from Falco instances
- **`ingress` (requires)**: Exposes the service through an ingress controller
- **`logging` (requires)**: Forwards internal application logs to Loki
- **`metrics-endpoint` (provides)**: Exposes Prometheus metrics for scraping
- **`send-loki-logs` (requires)**: Forwards alerts to OpenTelemetry Collector