diff --git a/docs/draft/api-reference/network-policies.md b/docs/draft/api-reference/network-policies.md new file mode 100644 index 000000000..105df97df --- /dev/null +++ b/docs/draft/api-reference/network-policies.md @@ -0,0 +1,89 @@ +# NetworkPolicy in OLMv1 + +## Overview + +OLMv1 uses [Kubernetes NetworkPolicy](https://kubernetes.io/docs/concepts/services-networking/network-policies/) to secure communication between components, restricting network traffic to only what's necessary for proper functionality. This document explains how `NetworkPolicy` is implemented for the core components: `catalogd` and `operator-controller`. + + +## NetworkPolicy Implementation + +NetworkPolicy is implemented for both catalogd and operator-controller components to: + +* Restrict incoming (ingress) traffic to only required ports and services +* Control outgoing (egress) traffic patterns + +Each component has a dedicated NetworkPolicy that applies to its respective pod through label selectors: + +* For catalogd: `control-plane=catalogd-controller-manager` +* For operator-controller: `control-plane=operator-controller-controller-manager` + +### Catalogd NetworkPolicy + +- Ingress Rules +Catalogd exposes three services, and its NetworkPolicy allows ingress traffic to the following TCP ports: + +* 7443: Metrics server for Prometheus metrics +* 8443: Catalogd HTTPS server for catalog metadata API +* 9443: Webhook server for Mutating Admission Webhook implementation + +All other ingress traffic to the catalogd pod is blocked. + +- Egress Rules +Catalogd needs to communicate with: + +* The Kubernetes API server +* Image registries specified in ClusterCatalog objects + +Currently, all egress traffic from catalogd is allowed, to support communication with arbitrary image registries that aren't known at install time. + +### Operator-Controller NetworkPolicy + +- Ingress Rules +Operator-controller exposes one service, and its NetworkPolicy allows ingress traffic to: + +* 8443: Metrics server for Prometheus metrics + +All other ingress traffic to the operator-controller pod is blocked. + +- Egress Rules +Operator-controller needs to communicate with: + +* The Kubernetes API server +* Catalogd's HTTPS server (on port 8443) +* Image registries specified in bundle metadata + +Currently, all egress traffic from operator-controller is allowed to support communication with arbitrary image registries that aren't known at install time. + +## Security Considerations + +The current implementation focuses on securing ingress traffic while allowing all egress traffic. This approach: + +* Prevents unauthorized incoming connections +* Allows communication with arbitrary image registries +* Establishes a foundation for future refinements to egress rules + +While allowing all egress does present some security risks, this implementation provides significant security improvements over having no network policies at all. + +## Troubleshooting Network Issues + +If you encounter network connectivity issues after deploying OLMv1, consider the following: + +* Verify NetworkPolicy support: Ensure your cluster has a CNI plugin that supports NetworkPolicy +* Check pod labels: Confirm that catalogd and operator-controller pods have the correct labels for NetworkPolicy selection +* Inspect logs: Check component logs for connection errors +* Test connectivity: Run test pods that attempt to communicate with OLMv1 components + +For more comprehensive information on NetworkPolicy, see: + +- How NetworkPolicy is implemented with [network plugins](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) via the Container Network Interface (CNI) +- Installing [Network Policy Providers](https://kubernetes.io/docs/tasks/administer-cluster/network-policy-provider/) documentation. + +## Future Enhancements + +The operator-framework team plan to revisit improvements to network policies in the future, such as: + +* More restrictive egress rules based on configured catalog image references +* Further securing metrics and webhook server access +* Dynamic network policy updates based on configured bundle image references + +These initial NetworkPolicy implementations represent OLMv1's commitment to being secure by default while maintaining necessary functionality.