filter: postgres statistics network filter

CODEOWNERS

@@ -40,6 +40,8 @@ extensions/filters/common/original_src @snowp @klarose
 /*/extensions/tracers/xray @marcomagdy @lavignes @mattklein123
 # mysql_proxy extension
 /*/extensions/filters/network/mysql_proxy @rshriram @venilnoronha @mattklein123
+# postgres_proxy extension
+/*/extensions/filters/network/postgres_proxy @fabriziomello @cpakulski @dio
 # quic extension
 /*/extensions/quic_listeners/ @alyssawilk @danzh2010 @mattklein123 @mpwarres @wu-bin
 # zookeeper_proxy extension

api/BUILD

@@ -211,6 +211,7 @@ proto_library(
         "//envoy/extensions/filters/network/local_ratelimit/v3:pkg",
         "//envoy/extensions/filters/network/mongo_proxy/v3:pkg",
         "//envoy/extensions/filters/network/mysql_proxy/v3:pkg",
+        "//envoy/extensions/filters/network/postgres_proxy/v3alpha:pkg",
         "//envoy/extensions/filters/network/ratelimit/v3:pkg",
         "//envoy/extensions/filters/network/rbac/v3:pkg",
         "//envoy/extensions/filters/network/redis_proxy/v3:pkg",

api/envoy/extensions/filters/network/postgres_proxy/v3alpha/BUILD

@@ -0,0 +1,9 @@
+# DO NOT EDIT. This file is generated by tools/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"],
+)

api/envoy/extensions/filters/network/postgres_proxy/v3alpha/postgres_proxy.proto

@@ -0,0 +1,25 @@
+syntax = "proto3";
+
+package envoy.extensions.filters.network.postgres_proxy.v3alpha;
+
+import "udpa/annotations/migrate.proto";
+import "udpa/annotations/status.proto";
+import "udpa/annotations/versioning.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.filters.network.postgres_proxy.v3alpha";
+option java_outer_classname = "PostgresProxyProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_status).work_in_progress = true;
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Postgres proxy]
+// Postgres Proxy :ref:`configuration overview
+// <config_network_filters_postgres_proxy>`.
+// [#extension: envoy.filters.network.postgres_proxy]
+
+message PostgresProxy {
+  // The human readable prefix to use when emitting :ref:`statistics
+  // <config_network_filters_postgres_proxy_stats>`.
+  string stat_prefix = 1 [(validate.rules).string = {min_len: 1}];
+}

api/versioning/BUILD

@@ -92,6 +92,7 @@ proto_library(
         "//envoy/extensions/filters/network/local_ratelimit/v3:pkg",
         "//envoy/extensions/filters/network/mongo_proxy/v3:pkg",
         "//envoy/extensions/filters/network/mysql_proxy/v3:pkg",
+        "//envoy/extensions/filters/network/postgres_proxy/v3alpha:pkg",
         "//envoy/extensions/filters/network/ratelimit/v3:pkg",
         "//envoy/extensions/filters/network/rbac/v3:pkg",
         "//envoy/extensions/filters/network/redis_proxy/v3:pkg",

docs/root/configuration/listeners/network_filters/network_filters.rst

@@ -19,6 +19,7 @@ filters.
   local_rate_limit_filter
   mongo_proxy_filter
   mysql_proxy_filter
+  postgres_proxy_filter
   rate_limit_filter
   rbac_filter
   redis_proxy_filter

docs/root/configuration/listeners/network_filters/postgres_proxy_filter.rst

@@ -0,0 +1,92 @@
+.. _config_network_filters_postgres_proxy:
+
+Postgres proxy
+================
+
+The Postgres proxy filter decodes the wire protocol between a Postgres client (downstream) and a Postgres server
+(upstream). The decoded information is currently used only to produce Postgres level statistics like sesions,
+statements or transactions executed, among others. This current version does not decode SQL queries. Future versions may
+add more statistics and more advanced capabilities. When the Postgres filter detects that a session is encrypted, the messages are ignored and no decoding takes
+place. More information:
+
+* Postgres :ref:`architecture overview <arch_overview_postgres>`
+
+.. attention::
+
+   The `postgres_proxy` filter is experimental and is currently under active development.
+   Capabilities will be expanded over time and the configuration structures are likely to change.
+
+
+.. warning::
+
+   The `postgreql_proxy` filter was tested only with
+   `Postgres frontend/backend protocol version 3.0`_, which was introduced in
+   Postgres 7.4. Earlier versions are thus not supported. Testing is limited
+   anyway to not EOL-ed versions.
+
+   .. _Postgres frontend/backend protocol version 3.0: https://www.postgresql.org/docs/current/protocol.html
+
+
+
+Configuration
+-------------
+
+The Postgres proxy filter should be chained with the TCP proxy as shown in the configuration
+example below:
+
+.. code-block:: yaml
+
+    filter_chains:
+    - filters:
+      - name: envoy.filters.network.postgres_proxy
+        typed_config:
+          "@type": type.googleapis.com/envoy.extensions.filters.network.postgres_proxy.v3alpha.PostgresProxy
+          stat_prefix: postgres
+      - name: envoy.tcp_proxy
+        typed_config:
+          "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
+          stat_prefix: tcp
+          cluster: postgres_cluster
+
+
+.. _config_network_filters_postgres_proxy_stats:
+
+Statistics
+----------
+
+Every configured Postgres proxy filter has statistics rooted at postgres.<stat_prefix> with the following statistics:
+
+.. csv-table::
+  :header: Name, Type, Description
+  :widths: 2, 1, 2
+
+  errors, Counter, Number of times the server replied with ERROR message
+  errors_error, Counter, Number of times the server replied with ERROR message with ERROR severity
+  errors_fatal, Counter, Number of times the server replied with ERROR message with FATAL severity
+  errors_panic, Counter, Number of times the server replied with ERROR message with PANIC severity
+  errors_unknown, Counter, Number of times the server replied with ERROR message but the decoder could not parse it
+  messages, Counter, Total number of messages processed by the filter
+  messages_backend, Counter, Total number of backend messages detected by the filter
+  messages_frontend, Counter, Number of frontend messages detected by the filter
+  messages_unknown, Counter, Number of times the filter successfully decoded a message but did not know what to do with it
+  sessions, Counter, Total number of successful logins
+  sessions_encrypted, Counter, Number of times the filter detected encrypted sessions
+  sessions_unencrypted, Counter, Number of messages indicating unencrypted successful login
+  statements, Counter, Total number of SQL statements
+  statements_delete, Counter, Number of DELETE statements
+  statements_insert, Counter, Number of INSERT statements
+  statements_select, Counter, Number of SELECT statements
+  statements_update, Counter, Number of UPDATE statements
+  statements_other, Counter, "Number of statements other than DELETE, INSERT, SELECT or UPDATE"
+  transactions, Counter, Total number of SQL transactions
+  transactions_commit, Counter, Number of COMMIT transactions
+  transactions_rollback, Counter, Number of ROLLBACK transactions
+  notices, Counter, Total number of NOTICE messages
+  notices_notice, Counter, Number of NOTICE messages with NOTICE subtype
+  notices_log, Counter, Number of NOTICE messages with LOG subtype
+  notices_warning, Counter, Number ofr NOTICE messags with WARNING severity
+  notices_debug, Counter, Number of NOTICE messages with DEBUG severity
+  notices_info, Counter, Number of NOTICE messages with INFO severity
+  notices_unknown, Counter, Number of NOTICE messages which could not be recognized
+
+

docs/root/intro/arch_overview/other_protocols/other_protocols.rst

@@ -8,3 +8,4 @@ Other protocols
   mongo
   dynamo
   redis
+  postgres

docs/root/intro/arch_overview/other_protocols/postgres.rst

@@ -0,0 +1,31 @@
+.. _arch_overview_postgres:
+
+Postgres
+==========
+
+Envoy supports a network level Postgres sniffing filter to add network observability. By using the
+Postgres proxy, Envoy is able to decode `Postgres frontend/backend protocol`_ and gather
+statistics from the decoded information.
+
+The main goal of the Postgres filter is to capture runtime statistics without impacting or
+generating any load on the Postgres upstream server, it is transparent to it. The filter currently
+offers the following features:
+
+* Decode non SSL traffic, ignore SSL traffic.
+* Decode session information.
+* Capture transaction information, including commits and rollbacks.
+* Expose counters for different types of statements (INSERTs, DELETEs, UPDATEs, etc). 
+  The counters are updated based on decoding backend CommandComplete messages not by decoding SQL statements sent by a client.
+* Count frontend, backend and unknown messages.
+* Identify errors and notices backend responses.
+
+The Postgres filter solves a notable problem for Postgres deployments:
+gathering this information either imposes additional load to the server; or
+requires pull-based querying for metadata from the server, sometimes requiring
+external components or extensions. This filter provides valuable observability
+information, without impacting the performance of the upstream Postgres
+server or requiring the installation of any software.
+
+Postgres proxy filter :ref:`configuration reference <config_network_filters_postgres_proxy>`.
+
+.. _Postgres frontend/backend protocol: https://www.postgresql.org/docs/current/protocol.html

docs/root/version_history/current.rst

@@ -15,6 +15,7 @@ Changes
   `google.api.HttpBody <https://github.com/googleapis/googleapis/blob/master/google/api/httpbody.proto>`_.
 * http: fixed a bug where the upgrade header was not cleared on responses to non-upgrade requests.
   Can be reverted temporarily by setting runtime feature `envoy.reloadable_features.fix_upgrade_response` to false.
+* network filters: added a :ref:`postgres proxy filter <config_network_filters_postgres_proxy>`.
 * router: allow retries of streaming or incomplete requests. This removes stat `rq_retry_skipped_request_not_complete`.
 * tracing: tracing configuration has been made fully dynamic and every HTTP connection manager
   can now have a separate :ref:`tracing provider <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.Tracing.provider>`.

source/extensions/extensions_build_config.bzl

@@ -92,6 +92,7 @@ EXTENSIONS = {
     "envoy.filters.network.local_ratelimit":            "//source/extensions/filters/network/local_ratelimit:config",
     "envoy.filters.network.mongo_proxy":                "//source/extensions/filters/network/mongo_proxy:config",
     "envoy.filters.network.mysql_proxy":                "//source/extensions/filters/network/mysql_proxy:config",
+    "envoy.filters.network.postgres_proxy":             "//source/extensions/filters/network/postgres_proxy:config",
     "envoy.filters.network.ratelimit":                  "//source/extensions/filters/network/ratelimit:config",
     "envoy.filters.network.rbac":                       "//source/extensions/filters/network/rbac:config",
     "envoy.filters.network.redis_proxy":                "//source/extensions/filters/network/redis_proxy:config",

source/extensions/filters/network/postgres_proxy/BUILD

@@ -0,0 +1,51 @@
+licenses(["notice"])  # Apache 2
+
+#package(default_visibility = ["//visibility:public"])
+
+# PostgresSQL proxy L7 network filter.
+# Public docs: docs/root/configuration/network_filters/postgres_proxy_filter.rst
+
+load(
+    "//bazel:envoy_build_system.bzl",
+    "envoy_cc_extension",
+    "envoy_cc_library",
+    "envoy_package",
+)
+
+envoy_package()
+
+envoy_cc_library(
+    name = "filter",
+    srcs = [
+        "postgres_decoder.cc",
+        "postgres_filter.cc",
+    ],
+    hdrs = [
+        "postgres_decoder.h",
+        "postgres_filter.h",
+        "postgres_session.h",
+    ],
+    repository = "@envoy",
+    deps = [
+        "//include/envoy/network:filter_interface",
+        "//include/envoy/server:filter_config_interface",
+        "//include/envoy/stats:stats_interface",
+        "//include/envoy/stats:stats_macros",
+        "//source/common/buffer:buffer_lib",
+        "//source/common/network:filter_lib",
+    ],
+)
+
+envoy_cc_extension(
+    name = "config",
+    srcs = ["config.cc"],
+    hdrs = ["config.h"],
+    repository = "@envoy",
+    security_posture = "requires_trusted_downstream_and_upstream",
+    deps = [
+        ":filter",
+        "//source/extensions/filters/network:well_known_names",
+        "//source/extensions/filters/network/common:factory_base_lib",
+        "@envoy_api//envoy/extensions/filters/network/postgres_proxy/v3alpha:pkg_cc_proto",
+    ],
+)

source/extensions/filters/network/postgres_proxy/config.cc

@@ -0,0 +1,34 @@
+#include "extensions/filters/network/postgres_proxy/config.h"
+
+namespace Envoy {
+namespace Extensions {
+namespace NetworkFilters {
+namespace PostgresProxy {
+
+/**
+ * Config registration for the Postgres proxy filter. @see NamedNetworkFilterConfigFactory.
+ */
+Network::FilterFactoryCb
+NetworkFilters::PostgresProxy::PostgresConfigFactory::createFilterFactoryFromProtoTyped(
+    const envoy::extensions::filters::network::postgres_proxy::v3alpha::PostgresProxy& proto_config,
+    Server::Configuration::FactoryContext& context) {
+  ASSERT(!proto_config.stat_prefix().empty());
+
+  const std::string stat_prefix = fmt::format("postgres.{}", proto_config.stat_prefix());
+
+  PostgresFilterConfigSharedPtr filter_config(
+      std::make_shared<PostgresFilterConfig>(stat_prefix, context.scope()));
+  return [filter_config](Network::FilterManager& filter_manager) -> void {
+    filter_manager.addFilter(std::make_shared<PostgresFilter>(filter_config));
+  };
+}
+
+/**
+ * Static registration for the Postgres proxy filter. @see RegisterFactory.
+ */
+REGISTER_FACTORY(PostgresConfigFactory, Server::Configuration::NamedNetworkFilterConfigFactory);
+
+} // namespace PostgresProxy
+} // namespace NetworkFilters
+} // namespace Extensions
+} // namespace Envoy

source/extensions/filters/network/postgres_proxy/config.h

@@ -0,0 +1,34 @@
+#pragma once
+
+#include "envoy/extensions/filters/network/postgres_proxy/v3alpha/postgres_proxy.pb.h"
+#include "envoy/extensions/filters/network/postgres_proxy/v3alpha/postgres_proxy.pb.validate.h"
+
+#include "extensions/filters/network/common/factory_base.h"
+#include "extensions/filters/network/postgres_proxy/postgres_filter.h"
+#include "extensions/filters/network/well_known_names.h"
+
+namespace Envoy {
+namespace Extensions {
+namespace NetworkFilters {
+namespace PostgresProxy {
+
+/**
+ * Config registration for the Postgres proxy filter.
+ */
+class PostgresConfigFactory
+    : public Common::FactoryBase<
+          envoy::extensions::filters::network::postgres_proxy::v3alpha::PostgresProxy> {
+public:
+  PostgresConfigFactory() : FactoryBase{NetworkFilterNames::get().Postgres} {}
+
+private:
+  Network::FilterFactoryCb createFilterFactoryFromProtoTyped(
+      const envoy::extensions::filters::network::postgres_proxy::v3alpha::PostgresProxy&
+          proto_config,
+      Server::Configuration::FactoryContext& context) override;
+};
+
+} // namespace PostgresProxy
+} // namespace NetworkFilters
+} // namespace Extensions
+} // namespace Envoy