Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

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

PreviousService Roles
NextWorkflows

Last updated

Was this helpful?