Skip to content

📖 Add NetworkPolicy doc #1973

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 21, 2025
Merged

📖 Add NetworkPolicy doc #1973

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions docs/draft/api-reference/network-policies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
# NetworkPolicy in OLMv1
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@michaelryanpeter I think it would be nice to get your help with.


## 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.

* The catalogd NetworkPolicy is implemented [here](https://github.com/operator-framework/operator-controller/blob/main/config/base/catalogd/manager/network_policy.yaml).
* The operator-controller is implemented [here](https://github.com/operator-framework/operator-controller/blob/main/config/base/operator-controller/manager/network_policy.yaml).

This document explains the details of `NetworkPolicy` implementation for the core components.


## Implementation Overview

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think about linking the code from the repo?
So, those looking can easily check the NPs by clicking on them.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know how I feel about that tbh. If we just link the yaml file, that's self documenting 😄.

This doc is to expand on that yaml file, in words.

I feel like users who're adept enough at reading yaml files will find that file and know how to read it anyway, and this is for those users who will need help understanding that yaml file.

Which is why I didn't include the link to the yaml file in the first place.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know how I feel about that tbh. If we just link the yaml file, that's self documenting 😄.
Yes, can we link the YAMLs?

For me, for example, it would be much easier to check the NP directly rather than reading the documentation.
As a new contributor and user, I might not even know where they live in the repo.

So the suggestion here is simply to add a direct link to the YAML files.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added links to the NetworkPolicy yaml files from the repo in the overview section 👍🏽


## 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. If your Kubernetes cluster is using a Container Network Interface (CNI) plugin that doesn't support NetworkPolicy, then the NetworkPolicy resources you create will be completely ignored and have no effect whatsoever on traffic flow.
* Check pod labels: Confirm that catalogd and operator-controller pods have the correct labels for NetworkPolicy selection:

```bash
# Verify catalogd pod labels
kubectl get pods -n olmv1-system --selector=control-plane=catalogd-controller-manager

# Verify operator-controller pod labels
kubectl get pods -n olmv1-system --selector=control-plane=operator-controller-controller-manager

# Compare with actual pod names
kubectl get pods -n olmv1-system | grep -E 'catalogd|operator-controller'
```
* Inspect logs: Check component logs for connection errors

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.