Merge branch 'dev' of github.com:fosrl/newt into dev

Author: oschwartz10612

.env.example

@@ -0,0 +1,5 @@
+# Copy this file to .env and fill in your values
+# Required for connecting to Pangolin service
+PANGOLIN_ENDPOINT=https://example.com
+NEWT_ID=changeme-id
+NEWT_SECRET=changeme-secret

Dockerfile

@@ -1,5 +1,8 @@
 FROM golang:1.25-alpine AS builder
 
+# Install git and ca-certificates
+RUN apk --no-cache add ca-certificates git tzdata
+
 # Set the working directory inside the container
 WORKDIR /app
 
@@ -13,7 +16,7 @@ RUN go mod download
 COPY . .
 
 # Build the application
-RUN CGO_ENABLED=0 GOOS=linux go build -o /newt
+RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /newt
 
 FROM alpine:3.22 AS runner
 
@@ -22,6 +25,9 @@ RUN apk --no-cache add ca-certificates tzdata
 COPY --from=builder /newt /usr/local/bin/
 COPY entrypoint.sh /
 
+# Admin/metrics endpoint (Prometheus scrape)
+EXPOSE 2112
+
 RUN chmod +x /entrypoint.sh
 ENTRYPOINT ["/entrypoint.sh"]
-CMD ["newt"]
+CMD ["newt"]

README.md

@@ -33,61 +33,108 @@ When Newt receives WireGuard control messages, it will use the information encod
 
 ## CLI Args
 
+### Core Configuration
+
 -   `id`: Newt ID generated by Pangolin to identify the client.
 -   `secret`: A unique secret (not shared and kept private) used to authenticate the client ID with the websocket in order to receive commands.
 -   `endpoint`: The endpoint where both Gerbil and Pangolin reside in order to connect to the websocket.
-
--   `mtu` (optional): MTU for the internal WG interface. Default: 1280
--   `dns` (optional): DNS server to use to resolve the endpoint. Default: 9.9.9.9
+-   `blueprint-file` (optional): Path to blueprint file to define Pangolin resources and configurations.
+-   `no-cloud` (optional): Don't fail over to the cloud when using managed nodes in Pangolin Cloud. Default: false
 -   `log-level` (optional): The log level to use (DEBUG, INFO, WARN, ERROR, FATAL). Default: INFO
--   `enforce-hc-cert` (optional): Enforce certificate validation for health checks. Default: false (accepts any cert)
+
+### Docker Integration
+
 -   `docker-socket` (optional): Set the Docker socket to use the container discovery integration
--   `ping-interval` (optional): Interval for pinging the server. Default: 3s
--   `ping-timeout` (optional): Timeout for each ping. Default: 5s
--   `updown` (optional): A script to be called when targets are added or removed.
--   `tls-client-cert` (optional): Client certificate (p12 or pfx) for mTLS. See [mTLS](#mtls)
--   `tls-client-cert` (optional): Path to client certificate (PEM format, optional if using PKCS12). See [mTLS](#mtls)
--   `tls-client-key` (optional): Path to private key for mTLS (PEM format, optional if using PKCS12)
--   `tls-ca-cert` (optional): Path to CA certificate to verify server (PEM format, optional if using PKCS12)
 -   `docker-enforce-network-validation` (optional): Validate the container target is on the same network as the newt process. Default: false
--   `health-file` (optional): Check if connection to WG server (pangolin) is ok. creates a file if ok, removes it if not ok. Can be used with docker healtcheck to restart newt
+
+### Accpet Client Connection 
+
 -   `accept-clients` (optional): Enable WireGuard server mode to accept incoming newt client connections. Default: false
     -   `generateAndSaveKeyTo` (optional): Path to save generated private key
     -   `native` (optional): Use native WireGuard interface when accepting clients (requires WireGuard kernel module and Linux, must run as root). Default: false (uses userspace netstack)
         -   `interface` (optional): Name of the WireGuard interface. Default: newt
         -   `keep-interface` (optional): Keep the WireGuard interface. Default: false
--   `blueprint-file` (optional): Path to blueprint file to define Pangolin resources and configurations.
--   `no-cloud` (optional): Don't fail over to the cloud when using managed nodes in Pangolin Cloud. Default: false 
+
+### Metrics & Observability
+
+-   `metrics` (optional): Enable Prometheus /metrics exporter. Default: true
+-   `otlp` (optional): Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT. Default: false
+-   `metrics-admin-addr` (optional): Admin/metrics bind address. Default: 127.0.0.1:2112
+-   `metrics-async-bytes` (optional): Enable async bytes counting (background flush; lower hot path overhead). Default: false 
+-   `region` (optional): Optional region resource attribute for telemetry and metrics.
+
+### Network Configuration
+
+-   `mtu` (optional): MTU for the internal WG interface. Default: 1280
+-   `dns` (optional): DNS server to use to resolve the endpoint. Default: 9.9.9.9
+-   `ping-interval` (optional): Interval for pinging the server. Default: 3s
+-   `ping-timeout` (optional): Timeout for each ping. Default: 5s
+
+### Security & TLS
+
+-   `enforce-hc-cert` (optional): Enforce certificate validation for health checks. Default: false (accepts any cert)
+-   `tls-client-cert` (optional): Client certificate (p12 or pfx) for mTLS or path to client certificate (PEM format). See [mTLS](#mtls)
+-   `tls-client-key` (optional): Path to private key for mTLS (PEM format, optional if using PKCS12)
+-   `tls-ca-cert` (optional): Path to CA certificate to verify server (PEM format, optional if using PKCS12)
+
+### Monitoring & Health
+
+-   `health-file` (optional): Check if connection to WG server (pangolin) is ok. creates a file if ok, removes it if not ok. Can be used with docker healtcheck to restart newt
+-   `updown` (optional): A script to be called when targets are added or removed.
 
 ## Environment Variables
 
 All CLI arguments can be set using environment variables as an alternative to command line flags. Environment variables are particularly useful when running Newt in containerized environments.
 
+### Core Configuration
+
 -   `PANGOLIN_ENDPOINT`: Endpoint of your pangolin server (equivalent to `--endpoint`)
 -   `NEWT_ID`: Newt ID generated by Pangolin (equivalent to `--id`)
 -   `NEWT_SECRET`: Newt secret for authentication (equivalent to `--secret`)
--   `MTU`: MTU for the internal WG interface. Default: 1280 (equivalent to `--mtu`)
--   `DNS`: DNS server to use to resolve the endpoint. Default: 9.9.9.9 (equivalent to `--dns`)
+-   `CONFIG_FILE`: Load the config json from this file instead of in the home folder.
+-   `BLUEPRINT_FILE`: Path to blueprint file to define Pangolin resources and configurations. (equivalent to `--blueprint-file`)
+-   `NO_CLOUD`: Don't fail over to the cloud when using managed nodes in Pangolin Cloud. Default: false (equivalent to `--no-cloud`)
 -   `LOG_LEVEL`: Log level (DEBUG, INFO, WARN, ERROR, FATAL). Default: INFO (equivalent to `--log-level`)
+
+### Docker Integration
+
 -   `DOCKER_SOCKET`: Path to Docker socket for container discovery (equivalent to `--docker-socket`)
--   `PING_INTERVAL`: Interval for pinging the server. Default: 3s (equivalent to `--ping-interval`)
--   `PING_TIMEOUT`: Timeout for each ping. Default: 5s (equivalent to `--ping-timeout`)
--   `UPDOWN_SCRIPT`: Path to updown script for target add/remove events (equivalent to `--updown`)
--   `TLS_CLIENT_CERT`: Path to client certificate for mTLS (equivalent to `--tls-client-cert`)
--   `TLS_CLIENT_CERT`: Path to client certificate for mTLS (equivalent to `--tls-client-cert`)
--   `TLS_CLIENT_KEY`: Path to private key for mTLS (equivalent to `--tls-client-key`)
--   `TLS_CA_CERT`: Path to CA certificate to verify server (equivalent to `--tls-ca-cert`)
 -   `DOCKER_ENFORCE_NETWORK_VALIDATION`: Validate container targets are on same network. Default: false (equivalent to `--docker-enforce-network-validation`)
--   `ENFORCE_HC_CERT`: Enforce certificate validation for health checks. Default: false (equivalent to `--enforce-hc-cert`)
--   `HEALTH_FILE`: Path to health file for connection monitoring (equivalent to `--health-file`)
+
+### Accept Client Connections
+
 -   `ACCEPT_CLIENTS`: Enable WireGuard server mode. Default: false (equivalent to `--accept-clients`)
 -   `GENERATE_AND_SAVE_KEY_TO`: Path to save generated private key (equivalent to `--generateAndSaveKeyTo`)
 -   `USE_NATIVE_INTERFACE`: Use native WireGuard interface (Linux only). Default: false (equivalent to `--native`)
 -   `INTERFACE`: Name of the WireGuard interface. Default: newt (equivalent to `--interface`)
 -   `KEEP_INTERFACE`: Keep the WireGuard interface after shutdown. Default: false (equivalent to `--keep-interface`)
--   `CONFIG_FILE`: Load the config json from this file instead of in the home folder.
--   `BLUEPRINT_FILE`: Path to blueprint file to define Pangolin resources and configurations. (equivalent to `--blueprint-file`)
--   `NO_CLOUD`: Don't fail over to the cloud when using managed nodes in Pangolin Cloud. Default: false (equivalent to `--no-cloud`)
+
+### Monitoring & Health
+
+-   `HEALTH_FILE`: Path to health file for connection monitoring (equivalent to `--health-file`)
+-   `UPDOWN_SCRIPT`: Path to updown script for target add/remove events (equivalent to `--updown`)
+
+### Metrics & Observability
+
+-   `NEWT_METRICS_PROMETHEUS_ENABLED`: Enable Prometheus /metrics exporter. Default: true (equivalent to `--metrics`)
+-   `NEWT_METRICS_OTLP_ENABLED`: Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT. Default: false (equivalent to `--otlp`)
+-   `NEWT_ADMIN_ADDR`: Admin/metrics bind address. Default: 127.0.0.1:2112 (equivalent to `--metrics-admin-addr`)
+-   `NEWT_METRICS_ASYNC_BYTES`: Enable async bytes counting (background flush; lower hot path overhead). Default: false (equivalent to `--metrics-async-bytes`)
+-   `NEWT_REGION`: Optional region resource attribute for telemetry and metrics (equivalent to `--region`)
+
+### Network Configuration
+
+-   `MTU`: MTU for the internal WG interface. Default: 1280 (equivalent to `--mtu`)
+-   `DNS`: DNS server to use to resolve the endpoint. Default: 9.9.9.9 (equivalent to `--dns`)
+-   `PING_INTERVAL`: Interval for pinging the server. Default: 3s (equivalent to `--ping-interval`)
+-   `PING_TIMEOUT`: Timeout for each ping. Default: 5s (equivalent to `--ping-timeout`)
+
+### Security & TLS
+
+-   `ENFORCE_HC_CERT`: Enforce certificate validation for health checks. Default: false (equivalent to `--enforce-hc-cert`)
+-   `TLS_CLIENT_CERT`: Path to client certificate for mTLS (equivalent to `--tls-client-cert`)
+-   `TLS_CLIENT_KEY`: Path to private key for mTLS (equivalent to `--tls-client-key`)
+-   `TLS_CA_CERT`: Path to CA certificate to verify server (equivalent to `--tls-ca-cert`)
 
 ## Loading secrets from files
 

docker-compose.metrics.collector.yml

@@ -0,0 +1,41 @@
+services:
+  newt:
+    build: .
+    image: newt:dev
+    env_file:
+      - .env
+    environment:
+      - NEWT_METRICS_PROMETHEUS_ENABLED=false   # important: disable direct /metrics scraping
+      - NEWT_METRICS_OTLP_ENABLED=true          # OTLP to the Collector
+      # optional:
+      # - NEWT_METRICS_INCLUDE_TUNNEL_ID=false
+  # When using the Collector pattern, do NOT map the Newt admin/metrics port
+  # (2112) on the application service. Mapping 2112 here can cause port
+  # conflicts and may result in duplicated Prometheus scraping (app AND
+  # collector being scraped for the same metrics). Instead either:
+  #  - leave ports unset on the app service (recommended), or
+  #  - map 2112 only on a dedicated metrics/collector service that is
+  #    responsible for exposing metrics to Prometheus.
+  # Example: do NOT map here
+  # ports: []
+  # Example: map 2112 only on a collector service
+  # collector:
+  #   ports:
+  #     - "2112:2112"  # collector's prometheus exporter (scraped by Prometheus)
+
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:latest
+    command: ["--config=/etc/otelcol/config.yaml"]
+    volumes:
+      - ./examples/otel-collector.yaml:/etc/otelcol/config.yaml:ro
+    ports:
+      - "4317:4317"   # OTLP gRPC
+      - "8889:8889"   # Prometheus Exporter (scraped by Prometheus)
+
+  prometheus:
+    image: prom/prometheus:latest
+    volumes:
+      - ./examples/prometheus.with-collector.yml:/etc/prometheus/prometheus.yml:ro
+    ports:
+      - "9090:9090"
+

docker-compose.metrics.yml

@@ -0,0 +1,56 @@
+name: Newt-Metrics
+services:
+  # Recommended Variant A: Direct Prometheus scrape of Newt (/metrics)
+  # Optional: You may add the Collector service and enable OTLP export, but do NOT
+  # scrape both Newt and the Collector for the same process.
+
+  newt:
+    build: .
+    image: newt:dev
+    env_file:
+      - .env
+    environment:
+      OTEL_SERVICE_NAME: newt
+      NEWT_METRICS_PROMETHEUS_ENABLED: "true"
+      NEWT_METRICS_OTLP_ENABLED: "false"   # avoid double-scrape by default
+      NEWT_ADMIN_ADDR: ":2112"
+      # Base NEWT configuration
+      PANGOLIN_ENDPOINT: ${PANGOLIN_ENDPOINT}
+      NEWT_ID: ${NEWT_ID}
+      NEWT_SECRET: ${NEWT_SECRET}
+      LOG_LEVEL: "DEBUG"
+    ports:
+      - "2112:2112"
+
+  # Optional Variant B: Enable the Collector and switch Prometheus scrape to it.
+  # collector:
+  #   image: otel/opentelemetry-collector-contrib:0.136.0
+  #   command: ["--config=/etc/otelcol/config.yaml"]
+  #   volumes:
+  #     - ./examples/otel-collector.yaml:/etc/otelcol/config.yaml:ro
+  #   ports:
+  #     - "4317:4317"   # OTLP gRPC in
+  #     - "8889:8889"   # Prometheus scrape out
+
+  prometheus:
+    image: prom/prometheus:v3.6.0
+    volumes:
+      - ./examples/prometheus.yml:/etc/prometheus/prometheus.yml:ro
+    ports:
+      - "9090:9090"
+
+  grafana:
+    image: grafana/grafana:12.2.0
+    container_name: newt-metrics-grafana
+    restart: unless-stopped
+    environment:
+      - GF_SECURITY_ADMIN_USER=admin
+      - GF_SECURITY_ADMIN_PASSWORD=admin
+    ports:
+      - "3005:3000"
+    depends_on:
+      - prometheus
+    volumes:
+      - ./examples/grafana/provisioning/datasources:/etc/grafana/provisioning/datasources:ro
+      - ./examples/grafana/provisioning/dashboards:/etc/grafana/provisioning/dashboards:ro
+      - ./examples/grafana/dashboards:/var/lib/grafana/dashboards:ro