Skip to content

CNV#50738: Doc: Update downstream doc Delete Protection for VMs #90981

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
Apr 23, 2025
Merged

CNV#50738: Doc: Update downstream doc Delete Protection for VMs #90981

Show file tree
Hide file tree
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
2 changes: 2 additions & 0 deletions _topic_maps/_topic_map.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4667,6 +4667,8 @@ Topics:
File: virt-edit-boot-order
- Name: Deleting virtual machines
File: virt-delete-vms
- Name: Enabling or disabling virtual machine delete protection
File: virt-enabling-disabling-vm-delete-protection
- Name: Exporting virtual machines
File: virt-exporting-vms
- Name: Managing virtual machine instances
Expand Down
22 changes: 16 additions & 6 deletions modules/virt-delete-vm-web.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,32 @@
// Module included in the following assemblies:
//
// * virt/virtual_machines/virt-delete-vms.adoc
// * virt/managing-vms/virt-delete-vms.adoc

:_mod-docs-content-type: PROCEDURE
[id="virt-delete-vm-web_{context}"]

= Deleting a virtual machine using the web console

Deleting a virtual machine permanently removes it from the cluster.
Deleting a virtual machine (VM) permanently removes it from the cluster.

If the VM is delete protected, the *Delete* action is disabled in the VM's *Actions* menu.

.Prequisite

* To delete the VM, you must first disable the VM's delete protection setting, if enabled.

.Procedure

. In the {product-title} console, click *Virtualization* -> *VirtualMachines* from the side menu.
. From the {product-title} web console, choose your view:

* For a virtualization-focused view, select *Administrator* → *Virtualization* → *VirtualMachines*.

* For a general view, navigate to *Virtualization* → *VirtualMachines*.

. Click the Options menu {kebab} beside a virtual machine and select *Delete*.
. Click the *Actions* menu {kebab} beside a VM and select *Delete*.
+
Alternatively, click the virtual machine name to open the *VirtualMachine details* page and click *Actions* -> *Delete*.
Alternatively, click the VM's name to open the *VirtualMachine details* page and click *Actions* -> *Delete*.

. Optional: Select *With grace period* or clear *Delete disks*.

. Click *Delete* to permanently delete the virtual machine.
. Click *Delete* to permanently delete the VM.
9 changes: 5 additions & 4 deletions modules/virt-deleting-vms.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
// Module included in the following assemblies:
//
// * virt/virtual_machines/virt-delete-vms.adoc
// * virt/managing-vms/virt-delete-vms.adoc

:_mod-docs-content-type: PROCEDURE
[id="virt-deleting-vms_{context}"]

= Deleting a virtual machine by using the CLI

You can delete a virtual machine by using the `oc` command-line interface (CLI). The `oc` client enables you to perform actions on multiple virtual machines.
You can delete a virtual machine (VM) by using the `oc` command-line interface (CLI). The `oc` client enables you to perform actions on multiple VMs.

.Prerequisites

* Identify the name of the virtual machine that you want to delete.
* To delete the VM, you must first disable the VM's delete protection setting, if enabled.

.Procedure

* Delete the virtual machine by running the following command:
* Delete the VM by running the following command:
+
[source,terminal]
----
Expand All @@ -28,3 +28,4 @@ This command only deletes a VM in the current project. Specify the
`-n <project_name>` option if the VM you want to delete is in
a different project or namespace.
====

32 changes: 32 additions & 0 deletions modules/virt-enabling-disabling-vm-delete-protection-cli.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
// Module included in the following assemblies:
//
// * virt/managing-vms/virt-enabling-disabling-vm-delete-protection.adoc

:_mod-docs-content-type: PROCEDURE
[id="virt-enabling-disabling-vm-delete-protection-cli_{context}"]
Copy link
Contributor

Choose a reason for hiding this comment

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

IMHO these should be two separate one-command procedures, not a single one. Probably want to modularize these some time later prior to DITA migration.

Copy link
Author

Choose a reason for hiding this comment

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

I can do that in another PR; thanks.

= Enabling or disabling VM delete protection by using the command line

Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change

delete extra line

To prevent the inadvertent deletion of a virtual machine (VM), you can enable VM delete protection by using the command line. You can also disable delete protection for a VM.

By default, delete protection is not enabled for VMs. You must set the option for each individual VM.

.Prerequisites

* You have installed the {oc-first}.
Copy link
Contributor

Choose a reason for hiding this comment

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

You also need to know the VMs you want to protect or allow to be deleted, right?

Copy link
Author

Choose a reason for hiding this comment

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

Andrea had me remove that prereq in her peer review.


.Procedure

* Enable delete protection for a VM by running the following command:
+
[source,terminal]
----
$ oc patch vm <vm_name> --type merge -p '{"metadata":{"labels":{"kubevirt.io/vm-delete-protection":"True"}}}' -n <namespace>
----

* Disable delete protection for a VM by running the following command:
+
[source,terminal]
----
$ oc patch vm <vm_name> --type json -p '[{"op": "remove", "path": "/metadata/labels/kubevirt.io~1vm-delete-protection"}]' -n <namespace>
----

34 changes: 34 additions & 0 deletions modules/virt-enabling-disabling-vm-delete-protection-web.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
// Module included in the following assemblies:
//
// * virt/managing-vms/virt-enabling-disabling-vm-delete-protection.adoc

:_mod-docs-content-type: PROCEDURE
[id="virt-enabling-disabling-vm-delete-protection-web_{context}"]

= Enabling or disabling virtual machine delete protection by using the web console
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
= Enabling or disabling virtual machine delete protection by using the web console
= Enabling or disabling VM delete protection by using the web console


To prevent the inadvertent deletion of a virtual machine (VM), you can enable VM delete protection by using the {product-title} web console. You can also disable delete protection for a VM.

By default, delete protection is not enabled for VMs. You must set the option for each individual VM.

.Procedure

. From the {product-title} web console, choose your view:

* For a virtualization-focused view, select *Administrator* → *Virtualization* → *VirtualMachines*.

* For a general view, navigate to *Virtualization* → *VirtualMachines*.

. From the *VirtualMachines* list, select the VM whose delete protection you want to enable or disable.

. Click the *Configuration* tab.

. In the *VirtualMachines details*, choose to enable or disable the protection as follows:

* To enable the protection:
.. Set the *Deletion protection* switch to *On*.
.. Click *Enable* to confirm the protection.

* To disable the protection:
.. Set the *Deletion protection* switch to *Off*.
.. Click *Disable* to disable the protection.
78 changes: 78 additions & 0 deletions modules/virt-removing-vm-delete-protection.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
// Module included in the following assemblies:
//
// * virt/managing-vms/virt-enabling-disabling-vm-delete-protection.adoc

:_mod-docs-content-type: PROCEDURE
[id="virt-removing-vm-delete-protection_{context}"]

Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change

= Removing the VM delete protection option

When you enable delete protection on a virtual machine (VM), you ensure that the VM cannot be inadvertently deleted. You can also disable the protection for a VM.

As a cluster administrator, you can choose not to make the VM delete protection option available. VMs with delete protection already enabled retain that setting; for any new VMs that are created, enabling the option is not allowed.
Copy link
Contributor

Choose a reason for hiding this comment

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

"choose not to make" sounds a little wordy. Maybe something like this?

Also a suggestion for the second sentence.

Suggested change
As a cluster administrator, you can choose not to make the VM delete protection option available. VMs with delete protection already enabled retain that setting; for any new VMs that are created, enabling the option is not allowed.
As a cluster administrator, you can remove the VM delete protection option completely. VMs with delete protection already enabled retain that setting; any new VMs that are created do not have delete protection as an option.

Copy link
Contributor

Choose a reason for hiding this comment

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

@aspauldi Looks like this comment was missed.


You can remove the delete protection option by establishing a validation admission policy for the cluster and then creating the necessary binding to use the policy in the cluster.

.Prerequisites

* You must have cluster administrator privileges.

.Procedure

. Create the validation admission policy, as shown in the following example:
+
.Example validation admission policy file
[source,yaml]
----
Copy link
Collaborator

Choose a reason for hiding this comment

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

🤖 [error] AsciiDoc.ValidCodeBlocks: Unterminated listing block found in file.

Copy link
Contributor

Choose a reason for hiding this comment

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

When I lint this YAML file, I get the following error:

Missing closing "quote at line 17, column 170
Implicit keys need to be on a single line at line 18, column 5

Looks like it could use a check-over.

Copy link
Author

Choose a reason for hiding this comment

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

Checking again with Javier. The YAML file had an issue earlier, and Javier provide a new file. Not sure what the issue is now.

Copy link

Choose a reason for hiding this comment

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

Let's try like this now:

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
  name: "disable-vm-delete-protection"
spec:
  failurePolicy: Fail
  matchConstraints:
    resourceRules:
    - apiGroups:   ["kubevirt.io"]
      apiVersions: ["*"]
      operations:  ["UPDATE", "CREATE"]
      resources:   ["virtualmachines"]
  variables:
    - expression: string('kubevirt.io/vm-delete-protection')
      name: vmDeleteProtectionLabel
  validations:
  - expression: >- 
      !has(object.metadata.labels) || 
      !object.metadata.labels.exists(label, label == variables.vmDeleteProtectionLabel) || 
      has(oldObject.metadata.labels) &&
      oldObject.metadata.labels.exists(label, label == variables.vmDeleteProtectionLabel)
    message: "Virtual Machine delete protection feature is disabled"

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
name: "disable-vm-delete-protection"
spec:
failurePolicy: Fail
matchConstraints:
resourceRules:
- apiGroups: ["kubevirt.io"]
apiVersions: ["*"]
operations: ["UPDATE", "CREATE"]
resources: ["virtualmachines"]
variables:
- expression: string('kubevirt.io/vm-delete-protection')
name: vmDeleteProtectionLabel
validations:
- expression: >-
!has(object.metadata.labels) ||
!object.metadata.labels.exists(label, label == variables.vmDeleteProtectionLabel) ||
has(oldObject.metadata.labels) &&
oldObject.metadata.labels.exists(label, label == variables.vmDeleteProtectionLabel)
message: "Virtual Machine delete protection feature is disabled"
----

. Apply the validation admission policy to the cluster:
+
[source,terminal]
----
$ oc apply -f disable-vm-delete-protection.yaml
----

. Create the validation admission policy binding, as shown in the following example:
+
.Example validation admission policy binding file
[source,yaml]
----
apiVersion: admissionregistration.k8s.io/v1
Copy link
Collaborator

Choose a reason for hiding this comment

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

🤖 [error] RedHat.TermsErrors: Use 'Kubernetes' rather than 'k8s'. For more information, see RedHat.TermsErrors.

Copy link
Author

Choose a reason for hiding this comment

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

CNV docs use k8s all over the place, so no change made here.

Copy link
Contributor

Choose a reason for hiding this comment

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

Hmm, @aireilly is that a new bug in CI? I've never seen this pop up as an error in the apiVersion field before.

Copy link
Contributor

Choose a reason for hiding this comment

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

Fixed this in https://github.com/redhat-documentation/vale-at-red-hat/pull/933/files

kind: ValidatingAdmissionPolicyBinding
metadata:
name: "disable-vm-delete-protection-binding"
spec:
policyName: "disable-vm-delete-protection"
validationActions: [Deny]
matchResources:
----

Copy link
Contributor

Choose a reason for hiding this comment

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

This procedure only creates the YAML files - it doesn't actually apply them to the cluster. I'd recommend adding two more steps for applying them.

Here's an example of another procedure that does this: https://docs.redhat.com/en/documentation/openshift_container_platform/4.18/html-single/security_and_compliance/index#installing-nbde-tang-server-operator-using-cli_installing-nbde-tang-server-operator

Copy link
Author

@aspauldi aspauldi Apr 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

@jcanocan and @geetikakay, the documentation peer reviewer Andrea Hoffer recommended adding two steps to this procedure. Can you please take a look and see if what I have added is correct? Thanks! The procedure is documented here: https://90981--ocpdocs-pr.netlify.app/openshift-enterprise/latest/virt/managing_vms/virt-enabling-disabling-vm-delete-protection#virt-removing-vm-delete-protection_virt-enabling-disabling-vm-delete-protection

Copy link

@geetikakay geetikakay Apr 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

@aspauldi Sure, I will review again. But I have a quick question:
When enabling vm-delete-protection, we patch the VM with a label like this:

-- enable labels
$ oc patch vm <vm_name> --type merge -p '{"metadata":{"labels":{"kubevirt.io/vm-delete-protection":"True"}}}' -n

To disable it, there can be two approaches:

  1. Set the label value to "False"

$ oc patch vm <vm_name> --type merge -p '{"metadata":{"labels":{"kubevirt.io/vm-delete-protection":"False"}}}' -n

  1. Remove the label entirely
    $ oc patch vm <vm_name> --type json -p '[{"op": "remove", "path": "/metadata/labels/kubevirt.io~1vm-delete-protection"}]' -n

Should we treat disabling (setting to "False") and removing the label as two different cases? Technically, both result in the same outcomethe protection is no longer enforced. But from a documentation or behavior clarity perspective, does it make sense to distinguish between them?

cc @jcanocan

Copy link
Author

Choose a reason for hiding this comment

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

Hi @geetikakay, I think that we can keep the procedure just to one method to make it easier for the users. Thanks!

Copy link

Choose a reason for hiding this comment

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

@bergerhoffer's suggestion sounds fine to me! Great idea.
@geetikakay's suggestion makes sense. However, I have chosen the approach of removing the label to keep the final yaml manifest as sort as possible. I tend to agree with @aspauldi. Thanks for the suggestion, nevertheless.

Copy link
Contributor

Choose a reason for hiding this comment

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

Looks like this was done, as I see an oc apply here. Is this resolved?

Copy link
Author

Choose a reason for hiding this comment

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

Yes, the steps were added.

. Apply the validation admission policy binding to the cluster:
+
[source,terminal]
----
$ oc apply -f disable-vm-delete-protection-binding.yaml
----
2 changes: 1 addition & 1 deletion virt/managing_vms/virt-delete-vms.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ include::_attributes/common-attributes.adoc[]

toc::[]

You can delete a virtual machine from the web console or by using the `oc` command-line interface.
You can delete a virtual machine by using the web console or the `oc` command line interface.

include::modules/virt-delete-vm-web.adoc[leveloffset=+1]
include::modules/virt-deleting-vms.adoc[leveloffset=+1]
23 changes: 23 additions & 0 deletions virt/managing_vms/virt-enabling-disabling-vm-delete-protection.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
:_mod-docs-content-type: ASSEMBLY
[id="virt-enabling-disabling-vm-delete-protection"]
= Enabling or disabling virtual machine delete protection
include::_attributes/common-attributes.adoc[]
:context: virt-enabling-disabling-vm-delete-protection

toc::[]

You can prevent the inadvertent deletion of a virtual machine (VM) by enabling delete protection for the VM. You can also disable delete protection for the VM.

You enable or disable delete protection from either the command line or the VM's *VirtualMachine details* page in the {product-title} web console. The option is disabled by default.

You can also choose to remove availability of the delete protection option for any VMs in a cluster you administer. In this case, VMs with the feature already enabled retain the protection, while the option is unavailable for any newly created VMs.

include::modules/virt-enabling-disabling-vm-delete-protection-web.adoc[leveloffset=+1]
include::modules/virt-enabling-disabling-vm-delete-protection-cli.adoc[leveloffset=+1]
include::modules/virt-removing-vm-delete-protection.adoc[leveloffset=+1]

[role="_additional-resources"]
[id="additional-resources_{context}"]
== Additional resources
* xref:../../virt/managing_vms/virt-enabling-disabling-vm-delete-protection.adoc#virt-enabling-disabling-vm-delete-protection-web_virt-enabling-disabling-vm-delete-protection[Enabling or disabling virtual machine delete protection by using the web console]
* xref:../../virt/managing_vms/virt-enabling-disabling-vm-delete-protection.adoc#virt-enabling-disabling-vm-delete-protection-cli_virt-enabling-disabling-vm-delete-protection[Enabling or disabling virtual machine delete protection by using the CLI]