{"id":26472507,"url":"https://github.com/philipschmid/flow-generator-app","last_synced_at":"2026-04-10T21:13:27.721Z","repository":{"id":282714422,"uuid":"948961441","full_name":"PhilipSchmid/flow-generator-app","owner":"PhilipSchmid","description":"Network flow generator (TCP and UDP) for Kubernetes network testing purposes","archived":false,"fork":false,"pushed_at":"2026-04-09T12:03:46.000Z","size":218,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-09T13:25:51.137Z","etag":null,"topics":["cilium","flows","hubble","kubernetes","netflow","network","networking","test","testing"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PhilipSchmid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-15T11:06:39.000Z","updated_at":"2026-04-09T12:03:49.000Z","dependencies_parsed_at":"2025-03-16T14:24:37.588Z","dependency_job_id":"ed664bf4-70aa-42a7-85bb-a0a766c38b66","html_url":"https://github.com/PhilipSchmid/flow-generator-app","commit_stats":null,"previous_names":["philipschmid/flow-generator-app"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/PhilipSchmid/flow-generator-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilipSchmid%2Fflow-generator-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilipSchmid%2Fflow-generator-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilipSchmid%2Fflow-generator-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilipSchmid%2Fflow-generator-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PhilipSchmid","download_url":"https://codeload.github.com/PhilipSchmid/flow-generator-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilipSchmid%2Fflow-generator-app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31659209,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T17:19:37.612Z","status":"ssl_error","status_checked_at":"2026-04-10T17:19:13.364Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cilium","flows","hubble","kubernetes","netflow","network","networking","test","testing"],"created_at":"2025-03-19T21:12:18.148Z","updated_at":"2026-04-10T21:13:27.715Z","avatar_url":"https://github.com/PhilipSchmid.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flow Generator\n\n![Build and push Docker image](https://github.com/philipschmid/flow-generator-app/actions/workflows/build.yaml/badge.svg) ![CI](https://github.com/philipschmid/flow-generator-app/actions/workflows/ci.yaml/badge.svg)\n\nThis project provides a server and client to generate network flows (TCP and UDP) for Kubernetes network testing (e.g., for Cilium and Hubble). The server echoes back received data, while the client generates configurable flows to simulate network traffic.\n\n## Features\n\n- **Multi-protocol support**: TCP and UDP traffic generation\n- **Flexible configuration**: Extensive command-line flags and environment variables\n- **Production-ready**: Built-in Prometheus metrics and OpenTelemetry tracing\n- **High performance**: Concurrent flow handling with configurable limits\n- **Kubernetes-native**: Ready-to-use manifests for deployment\n- **Developer-friendly**: Live reload, comprehensive testing, and CI/CD pipelines\n\n## Quick Start\n\n### Using Pre-built Docker Images\n\n```bash\n# Run the echo server\ndocker run -p 8080:8080 -p 8082:8082 -p 9090:9090 ghcr.io/philipschmid/echo-server:latest\n\n# Run the flow generator\ndocker run ghcr.io/philipschmid/flow-generator:latest --server host.docker.internal\n```\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/PhilipSchmid/flow-generator-app.git\ncd flow-generator-app\n\n# Build binaries\nmake build\n\n# Run quick test\nmake quick-test\n```\n\nFor detailed development instructions, see [DEVELOPMENT.md](DEVELOPMENT.md).\n\n## Configuration\n\n### Environment Variables\n\nAll configuration options can be set via environment variables with the `FLOW_GENERATOR_` prefix:\n\n```bash\nexport FLOW_GENERATOR_LOG_LEVEL=debug\nexport FLOW_GENERATOR_METRICS_PORT=9090\n```\n\n### Server Configuration\n\nThe echo server (`echo-server` / `ghcr.io/philipschmid/echo-server:latest`) accepts the following options:\n\n| Flag | Environment Variable | Default | Description |\n|------|---------------------|---------|-------------|\n| `--log_level` | `FLOW_GENERATOR_LOG_LEVEL` | `info` | Log level (debug, info, warn, error) |\n| `--log_format` | `FLOW_GENERATOR_LOG_FORMAT` | `human` | Log format (human, json) |\n| `--metrics_port` | `FLOW_GENERATOR_METRICS_PORT` | `9090` | Prometheus metrics port |\n| `--health_port` | `FLOW_GENERATOR_HEALTH_PORT` | `8082` | Health check server port |\n| `--tracing_enabled` | `FLOW_GENERATOR_TRACING_ENABLED` | `false` | Enable OpenTelemetry tracing |\n| `--jaeger_endpoint` | `FLOW_GENERATOR_JAEGER_ENDPOINT` | `http://localhost:14268/api/traces` | Jaeger collector endpoint |\n| `--tcp_ports_server` | `FLOW_GENERATOR_TCP_PORTS_SERVER` | `8080` | Comma-separated TCP ports |\n| `--udp_ports_server` | `FLOW_GENERATOR_UDP_PORTS_SERVER` | `\"\"` | Comma-separated UDP ports |\n\n### Client Configuration\n\nThe flow generator (`flow-generator` / `ghcr.io/philipschmid/flow-generator:latest`) accepts the following options:\n\n| Flag | Environment Variable | Default | Description |\n|------|---------------------|---------|-------------|\n| `--server` | `FLOW_GENERATOR_SERVER` | `localhost` | Target server address |\n| `--rate` | `FLOW_GENERATOR_RATE` | `10` | Flows per second |\n| `--max_concurrent` | `FLOW_GENERATOR_MAX_CONCURRENT` | `100` | Maximum concurrent flows |\n| `--protocol` | `FLOW_GENERATOR_PROTOCOL` | `both` | Protocol (tcp, udp, both) |\n| `--tcp_ports` | `FLOW_GENERATOR_TCP_PORTS` | `8080` | Comma-separated TCP ports |\n| `--udp_ports` | `FLOW_GENERATOR_UDP_PORTS` | `\"\"` | Comma-separated UDP ports |\n| `--min_duration` | `FLOW_GENERATOR_MIN_DURATION` | `1.0` | Minimum flow duration (seconds) |\n| `--max_duration` | `FLOW_GENERATOR_MAX_DURATION` | `10.0` | Maximum flow duration (seconds) |\n| `--constant_flows` | `FLOW_GENERATOR_CONSTANT_FLOWS` | `false` | Disable flow randomization |\n| `--flow_timeout` | `FLOW_GENERATOR_FLOW_TIMEOUT` | `0` | Total runtime limit (0 = unlimited) |\n| `--flow_count` | `FLOW_GENERATOR_FLOW_COUNT` | `0` | Maximum flows to generate (0 = unlimited) |\n| `--payload_size` | `FLOW_GENERATOR_PAYLOAD_SIZE` | `0` | Fixed payload size (bytes) |\n| `--min_payload_size` | `FLOW_GENERATOR_MIN_PAYLOAD_SIZE` | `0` | Minimum payload size (bytes) |\n| `--max_payload_size` | `FLOW_GENERATOR_MAX_PAYLOAD_SIZE` | `0` | Maximum payload size (bytes) |\n| `--mtu` | `FLOW_GENERATOR_MTU` | `1500` | Maximum Transmission Unit |\n| `--mss` | `FLOW_GENERATOR_MSS` | `1460` | Maximum Segment Size |\n\nAdditional options for both server and client:\n- `--log_level`, `--log_format`: Logging configuration\n- `--tracing_enabled`, `--jaeger_endpoint`: Tracing configuration\n\n## Usage Examples\n\n### Basic TCP Echo Test\n\n```bash\n# Start server\n./bin/echo-server --tcp_ports_server=8080\n\n# Generate flows\n./bin/flow-generator --server=localhost --tcp_ports=8080 --rate=10\n```\n\n### Multi-Port Mixed Protocol Test\n\n```bash\n# Start server with multiple ports\n./bin/echo-server --tcp_ports_server=8080,8443 --udp_ports_server=53,123\n\n# Generate mixed traffic\n./bin/flow-generator \\\n  --server=localhost \\\n  --tcp_ports=8080,8443 \\\n  --udp_ports=53,123 \\\n  --protocol=both \\\n  --rate=20 \\\n  --max_concurrent=200\n```\n\n### Kubernetes Deployment\n\nDeploy the pre-configured examples:\n\n```bash\n# Constant flow pattern\nkubectl apply -f k8s/server-constant.yaml\nkubectl apply -f k8s/client-constant.yaml\n\n# Random flow pattern\nkubectl apply -f k8s/server-random.yaml\nkubectl apply -f k8s/client-random.yaml\n```\n\n### Constant Flow Mode\n\nFor predictable traffic patterns:\n\n```bash\n./bin/flow-generator \\\n  --server=localhost \\\n  --tcp_ports=8080 \\\n  --rate=5 \\\n  --max_concurrent=50 \\\n  --constant_flows=true\n```\n\nThis generates exactly 5 flows per second, each lasting 10 seconds (50/5), maintaining a steady state of 50 concurrent flows.\n\n## Monitoring\n\n### Health Checks\n\nThe echo server exposes health check endpoints on a dedicated port (default: 8082):\n\n```bash\n# Liveness probe - basic health check\ncurl http://localhost:8082/health\n\n# Readiness probe - indicates service is ready to accept traffic\ncurl http://localhost:8082/ready\n```\n\n### Prometheus Metrics\n\nBoth server and client expose Prometheus metrics on the configured port (default: 9090):\n\n```bash\ncurl http://localhost:9090/metrics\n```\n\nKey metrics include:\n- `tcp_connections_active`: Current active TCP connections\n- `udp_packets_received_total`: Total UDP packets received\n- `flows_generated_total`: Total flows generated by client\n- Request/response counts and bytes per protocol/port\n\n### OpenTelemetry Tracing\n\nEnable distributed tracing:\n\n```bash\n./bin/echo-server --tracing_enabled=true --jaeger_endpoint=http://jaeger:14268/api/traces\n```\n\n## Architecture\n\nThe project follows a clean architecture pattern:\n\n- **cmd/**: Application entry points (server and client)\n- **internal/**: Private application code\n  - **config/**: Configuration management with validation\n  - **handlers/**: Protocol-specific request handlers\n  - **server/**: Server implementations with manager pattern\n  - **metrics/**: Prometheus metrics collection\n  - **health/**: Health check server for liveness/readiness probes\n  - **logging/**: Structured logging utilities\n  - **tracing/**: OpenTelemetry integration\n  - **version/**: Version information management\n\n## Development\n\nThis project includes comprehensive development tools:\n\n- **Live reload**: `make dev` for rapid development\n- **Cross-platform builds**: `make build-all`\n- **Testing**: Unit tests, benchmarks, and integration tests\n- **CI/CD**: Automated testing, security scanning, and multi-platform Docker builds\n\nSee [DEVELOPMENT.md](DEVELOPMENT.md) for detailed development instructions.\n\n## Known Limitations\n\n### Deep Packet Inspection (DPI) and Protocol Simulation\n\nThe flow-generator-app simulates Layer 7 (L7) protocols by utilizing well-known ports (e.g., port 80 for HTTP, port 53 for DNS). However, it does not implement actual L7 protocol logic. The server simply echoes back any data it receives without adhering to specific protocol formats.\n\n**Impact:**\n- **DPI Tools**: May fail to recognize traffic as the intended protocol, potentially classifying it as \"Unknown\"\n- **Network Policies**: L7-aware policies may not work as expected due to the lack of proper protocol formatting\n\n## Contributing\n\nContributions are welcome! Please see [DEVELOPMENT.md](DEVELOPMENT.md#contributing) for guidelines.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilipschmid%2Fflow-generator-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilipschmid%2Fflow-generator-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilipschmid%2Fflow-generator-app/lists"}