Add Kubermatic Virtualization firewall rules how-to - #2282
Conversation
Signed-off-by: Mihir Agrawal <mihir@kubermatic.com>
kubermatic-bot
added
the
dco-signoff: yes
kubermatic-bot
added
the
size/L
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
| The YAML editor behaves differently. It submits the exact version you opened, so if the | ||
| rule changed underneath you the save is refused with *"This rule changed since you opened | ||
| it — reload and reapply your edit"* instead of overwriting. The form carries no such | ||
| check, which is why concurrent edits are lost there but rejected here. |
There was a problem hiding this comment.
This is the other way round. The form PUTs the object it fetched when Edit was clicked, resourceVersion included (routes/firewalls.tsx:176-195), and the update mutation maps a 409 to exactly the message quoted here (hooks/mutations/use-service-mutations.ts:366-368). The YAML dialog has its own conflict text with a "Load latest version" button (components/yaml/resource-yaml-dialog.tsx:81-84). Suggest rewriting so both editors are described as rejecting a stale save, with the quoted string attributed to the form.
| Editing a rule replaces the whole policy. Changes made outside the dashboard to the same | ||
| rule, such as extra ports or additional sources, are lost when you save the form. If a rule is | ||
| too complex for the form to represent, the dashboard says so and opens the YAML editor | ||
| instead of showing you a simplified version it would then destroy. |
There was a problem hiding this comment.
The form does not silently drop anything. parse-network-policy.ts loads every port row (the 8-row cap only hides the Add button) and refuses a rule with more than one peer, which is what sends it to the YAML editor; labels and annotations are merged from the live object in handleEdit. Suggest dropping the "extra ports or additional sources ... are lost" sentence and keeping the rest of the paragraph, which is accurate.
| * *"Applies to 1 virtual machine."* means the rule will be enforced. The number is a real | ||
| count, so a pool rule reports how many machines it selects, for example *"Applies to 4 | ||
| virtual machines."* |
There was a problem hiding this comment.
The match line only renders when the target type is Virtual Machine, and the count is targetableVms.includes(target) ? 1 : 0 (components/forms/firewall-form.tsx:210-215). Pool targets get no match feedback at all, so "Applies to 4 virtual machines" cannot appear. Suggest removing the pool example and saying the line appears for VM targets only.
|
|
||
| Turning the firewall on creates a policy named `<vm-name>-vm-default-deny`. The `vm` part | ||
| is in the name because a VM and a VM pool can share a name in one namespace, and each type | ||
| needs its own system policy. For a pool the name is `<pool-name>-pool-default-deny`. |
There was a problem hiding this comment.
buildBaselinePolicy has a single caller, hard-coded to 'VirtualMachine' (components/vm-detail/vm-firewall-section.tsx:54), and there is no firewall section under pool-detail. The -pool-default-deny name exists in the naming scheme but nothing in the dashboard creates it. Suggest saying the switch is VM-only today and pools are closed only by their inbound rules.
| A firewall rule selects VMs by a label that this dashboard applies when it creates a VM. | ||
| Nothing back-fills that label, so a VM created another way, whether by `kubectl`, a YAML | ||
| manifest, or an import, cannot be targeted by a rule. The API server accepts such a rule and it then |
There was a problem hiding this comment.
Naming the label would give the reader a remedy. The selector is fw.kubevirt-manager.io/vm-name=<vm-name> on spec.template.metadata.labels (lib/constants.ts:20, hooks/use-vm-names.ts:41-42), so an imported VM can be made targetable by adding it. Suggest naming the label and where it goes.
| By default, rules are created in a relaxed enforcement mode that keeps **ICMP (ping) | ||
| and DHCP working** on a firewalled VM, no matter what the rules say. This is almost | ||
| always what you want: |
There was a problem hiding this comment.
The relaxed mode is the Kube-OVN annotation ovn.kubernetes.io/network_policy_enforcement: lax on the policy, and strict is simply its absence (components/forms/build-network-policy.ts:17-18,115). Since the troubleshooting section sends people to the policy YAML, they have no way to recognise the mode without this. Suggest naming the annotation once and noting the ping/DHCP allowance is a Kube-OVN behaviour.
|
|
||
| | Field | What it does | | ||
| | --- | --- | | ||
| | **Name** | Identifies the rule. Lowercase letters, numbers and hyphens. Cannot be changed later. | |
There was a problem hiding this comment.
Names ending in -default-deny or -allow-dns are rejected on create (components/forms/firewall-form-schema.ts:109-117). Since this page introduces both suffixes it is worth saying they are reserved.
| +++ | ||
| title = "Tutorials & How-tos" | ||
| date = 2026-08-26T10:00:00+00:00 | ||
| weight = 6 |
There was a problem hiding this comment.
Three sibling sections already use weight = 6 (access-control-guide, configuration-guide, references), so where this lands in the sidebar is tie-broken rather than chosen. Suggest picking a free weight.
| Step-by-step guides for day-to-day work with Kubermatic Virtualization. Each page walks | ||
| through a complete task from the dashboard, rather than describing a single setting in | ||
| isolation. For the full list of settings, see the | ||
| [Configuration Reference]({{< ref "../configuration-reference" >}}). |
There was a problem hiding this comment.
The KKP tutorials-howtos/_index.en.md this mirrors ends with a ## Pages heading and {{% children depth=5 %}}, so the section landing page lists its how-tos. Without it this page shows only the intro prose. Suggest adding the same listing.
3 participants
What this PR documents:
Adds a "Firewall Rules" how-to for Kubermatic Virtualization, covering the dashboard
workflow for firewall rules: creating, editing and deleting rules from the Firewalls
page, the per-VM firewall switch on the Networking tab, port ranges, and the relaxed
enforcement mode that keeps ICMP (ping) and DHCP working on a firewalled VM. Also
documents the
<vm>-default-denybaseline policy and the<vm>-allow-dnscompanionpolicy that accompanies a target's first outbound rule.
This also introduces a
tutorials-howtossection for Kubermatic Virtualization,mirroring the existing KKP layout, and files the new page under it.
Which change does this document:
Documents the dashboard feature added in
kubermatic/kubermatic-virtualization#439 ("Add firewall rule create, edit and per-VM posture"),
How does this affect users:
Firewall rules were previously visible in the dashboard but read-only. Users can now
manage them from the UI. Rules are additive and allow-only, so blocking is expressed by
turning the firewall on and then permitting what you need; and the default relaxed
enforcement mode keeps ping and DHCP alive because Kubernetes NetworkPolicy cannot
express ICMP at all.