> For the complete documentation index, see [llms.txt](https://docs.pyck.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pyck.cloud/development/networking.md). # Networking Requirements Network requirements and firewall rules for pyck.cloud SaaS service Audience: System Administrator ## Overview This document outlines the network requirements and firewall configurations needed to integrate with pyck's SaaS service at pyck.cloud. pyck uses multiple protocols over standard HTTPS ports and requires support for long-lived connections. ## Protocols and Ports pyck consolidates all communication through standard web ports: * **Port 80 (HTTP)**: Used exclusively for redirecting browsers to HTTPS * **Port 443 (HTTPS)**: All application traffic runs on this port using multiple protocols: * HTTPS (standard HTTP/2 and HTTP/1.1) * gRPC (over HTTP/2) * WebSockets (for real-time bidirectional communication) ### Long-Lived Connections **Important**: Your network infrastructure must support long-lived connections: * WebSocket connections may remain open for extended periods * gRPC streaming connections can be persistent * Proxy servers and firewalls must be configured to: * Not terminate idle connections prematurely * Support WebSocket protocol upgrades * Handle HTTP/2 traffic properly for gRPC * Maintain connection state for streaming protocols ## pyck.cloud SaaS Service When using pyck's SaaS offering, additional network considerations apply due to the dynamic, auto-scaling infrastructure. Traffic flows in two directions, and each direction is whitelisted differently: * **Client → server** (your network to pyck): whitelist by **domain** (`*.pyck.cloud`), because backend IPs change constantly. * **Server → client** (pyck into your network): whitelist by **IP**, using the fixed set published at `ips.pyck.cloud`. ### Outbound Traffic to pyck (Client → Server) For all traffic originating from your network to pyck: * **Whitelist all outgoing traffic to `*.pyck.cloud`**: Every pyck endpoint lives under `pyck.cloud` or a subdomain. Because the SaaS platform is auto-scaling and its backend IPs change frequently, you must allow egress by **domain** (`*.pyck.cloud`) rather than by fixed IP. * **Port 443 (HTTPS)**: Required for all API and application access. * **Port 80 (HTTP)**: Optional, only used for browser redirects to HTTPS. Some endpoints are **client → server only** — your systems connect out to them, but they never call back into your network. For example, `debug.pyck.cloud` is used purely for outbound diagnostic sessions. These endpoints: * Are already covered by whitelisting egress to `*.pyck.cloud`. * Are **not** published in the `ips.pyck.cloud` A record, because pyck never initiates connections into your network from them. ### Inbound Traffic from pyck (Server → Client) When pyck needs to reach systems in your network (callbacks, webhooks, and other server-initiated traffic): * **Source IPs**: All such traffic originates from the fixed set of IPs published at `ips.pyck.cloud`. This set includes pyck's **egress proxy**, through which pyck routes its outbound calls to customer networks. * **Protocols**: HTTPS, gRPC, WebSockets (all over port 443). * **Firewall Rules**: Whitelist all IPs from `ips.pyck.cloud` (including the proxy) for **inbound** connections on port 443. **IP Address Discovery**: * Domain: `ips.pyck.cloud` * Published as both A records (individual IPs) and TXT records (comma-separated list) * Query both record types to get the complete list of IPs Example DNS queries: ```bash # Get A records dig A ips.pyck.cloud # Get TXT record with comma-separated IPs dig TXT ips.pyck.cloud ``` Only endpoints that can initiate connections into your network appear in `ips.pyck.cloud`. Client → server-only endpoints such as `debug.pyck.cloud` are intentionally excluded. ### Dynamic Infrastructure and Auto-Scaling pyck SaaS runs on Kubernetes with auto-scaling enabled: * **Host Changes**: Backend hosts may change frequently * **Typical Frequency**: Hosts can change every few minutes during normal operation * **High Load**: Under high load conditions, changes can occur as frequently as every 5 minutes * **DNS TTL**: Always respect the TTL values returned by pyck DNS servers * **Recommendation**: Do not cache DNS responses longer than the specified TTL ## Troubleshooting ### Connection Timeouts If experiencing connection timeouts: * Verify load balancer timeout settings (should be 10+ minutes) * Check that WebSocket upgrades are not being blocked * Ensure HTTP/2 is enabled for gRPC traffic ### IP Address Changes If callbacks from pyck.cloud are being blocked: * Re-query `ips.pyck.cloud` to get the latest IP list * Verify your DNS cache respects TTL values * Check firewall logs for blocked connection attempts * Update whitelist rules with the current IP addresses ### Protocol Issues If specific features are not working: * Verify HTTP/2 support is enabled (required for gRPC) * Check that WebSocket protocol upgrades are allowed * Ensure TLS 1.2 or higher is supported * Confirm no middleboxes are blocking or modifying traffic --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.pyck.cloud/development/networking.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.