Document foreman_resource_quota plugin #3460

maximiliankolb · 2024-11-20T15:48:05Z

What changes are you introducing?

basic usage docs for https://github.com/ATIX-AG/foreman_resource_quota/

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

new plugin -> new docs 🎉

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

installation via foreman-installer is not yet implemented
Hammer CLI is still missing to my knowledge

Checklists

I am okay with my commits getting squashed when you merge this PR.
I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.13/Katello 4.15 (Satellite 6.17)
Foreman 3.12/Katello 4.14 (Satellite 6.16)
Foreman 3.11/Katello 4.13 (orcharhino 6.11 on EL8 only)
Foreman 3.10/Katello 4.12
Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
Foreman 3.8/Katello 4.10
Foreman 3.7/Katello 4.9 (Satellite 6.14)
Foreman 3.6/Katello 4.8
Foreman 3.5/Katello 4.7 (Satellite 6.13; orcharhino 6.6/6.7)
We do not accept PRs for Foreman older than 3.5.

github-actions · 2024-11-20T15:50:32Z

The PR preview for e0c5c49 is available at theforeman-foreman-documentation-preview-pr-3460.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

guides/common/modules/proc_installing-the-resource-quota-plugin.adoc

maximiliankolb · 2024-11-20T15:49:46Z

guides/common/modules/con_limiting-resources.adoc

+* VMware
+* libvirt
+
+Configuration options::


Should I move this towards a "Configuring resource quotas plugin" module?

That depends.
Are these configuration options determined as arguments to the foreman-installer? Or are they global settings?

They are global settings that are not exposed via foreman-installer.

I'd make make them into a separate module with a heading like "Resource Quota Settings", add navigation information where the user can find these settings and put the list of these settings there. Perhaps the first module under Managing resource quotas? Or even a higher-level heading after Installing the plugin.

I've moved it to a "ref_" file at the end of the assembly. Is that too far away? Assuming we have sensible default values, users should not need to configure the plugin before typical usage.

I would prefer after the installation step. The further text is talking about the settings which have not been introduced before and it feels a bit confusing to me. You can also mention the default values of the settings, if that is something which is commonly done in docs.

maximiliankolb · 2024-11-20T15:50:59Z

guides/doc-Administering_Project/master.adoc

@@ -60,6 +60,8 @@ include::common/assembly_logging-and-reporting-problems.adoc[leveloffset=+1]

 include::common/assembly_monitoring-resources.adoc[leveloffset=+1]

+include::common/assembly_limiting-resources.adoc[leveloffset=+1]


The plugin is pretty cool, all downstream products should deliver it :) If that's not yet the case, please let me now and I can limit the visibility here. 🙃

guides/common/modules/proc_installing-the-resource-quota-plugin.adoc

guides/common/modules/con_managing-resource-quotas.adoc

guides/common/modules/proc_creating-a-resource-quota.adoc

bastian-src

Besides the per-user assignment and when it is optional: LGTM!

Thanks @maximiliankolb, looking great! Technical approval.

guides/common/modules/con_assigning-resource-quotas-to-users.adoc

maximiliankolb

Rebased to "master" and applied both suggestions to guides/common/modules/con_assigning-resource-quotas-to-users.adoc. Please re-review.

guides/common/modules/con_assigning-resource-quotas-to-users.adoc

Lennonka

My initial suggestions.

I'm unsure if talking about CPU cores, memory and disk space as "resources" is a good term here because it might get confused with "compute resources". We should try to come up with another term.
How about something like "compute capacity" or "compute allocation" or "compute units"? Or something else...

Lennonka · 2024-11-25T16:42:31Z

guides/common/modules/con_limiting-resources.adoc

+[id="limiting-resources"]
+= Limiting resources
+
+You can use the Resource Quota plugin to limit users' access to resources.


Suggested change

You can use the Resource Quota plugin to limit users' access to resources.

You can use the Resource Quota plugin to limit users' access to compute resources.

I'm missing the following information:

What resources exactly? Is it limited to compute resources?

In what use cases does the admin want to limit resource usage for users?

How will it affect usage of compute profiles?

"Resources" refers to the list of resources defined by the plugin: CPU, memory, and disk. It does not affect compute profiles which are merely a blueprint for the "size" of new hosts.

A typical use case is to limit resource consumption for a user/a group of users, for example, when multiple departments rely on "one" infrastructure managed by one Foreman+Katello instance. ACK @bastian-src ?

Exactly! Thanks @maximiliankolb and @Lennonka.
In short, the plugin enables administrators to limit the amount of resources users/usergroups can consume when provisioning hosts.

I see how the term "resource" is a little difficult since it is already used by compute resources. However, a resource quota relates to host resources as CPU cores, memory, and disk space - they are not directly related to a certain compute resource, but to users/usergroups and hosts.

EDIT:

Other terms like "compute capacity" or "compute allocation" or "compute units" might not fit so well too, since the Resource Quota plugin can also be used for bare metal hosts which are independent of any compute resource AFAIK. Internally, I've also been using the term "host resources" - what about that?

"Host resources" might work. Let's go with that.

@maximiliankolb Do you think you could extend the introduction by summarizing what was written in this thread?

Yes, I have summarized it and rephrased it to "limiting host resources".

Lennonka · 2024-11-25T16:44:04Z

guides/common/modules/con_limiting-resources.adoc

+* VMware
+* libvirt
+
+Configuration options::


That depends.
Are these configuration options determined as arguments to the foreman-installer? Or are they global settings?

guides/common/modules/con_limiting-resources.adoc

Lennonka · 2024-11-25T16:59:13Z

@maximiliankolb ~~Can you also please link the PR where it's developed to the description of this PR?~~ Nevermind, you linked the ATIX plugin repo.

I'm wondering, should it be included in the Foreman organization in order to be counted as a Foreman plugin that could eventually be used in other downstreams? Not sure what the policy is here. :)

maximiliankolb

Applied all suggestions by Lena and Avital.

maximiliankolb · 2024-11-26T14:39:51Z

guides/common/modules/con_limiting-resources.adoc

+[id="limiting-resources"]
+= Limiting resources
+
+You can use the Resource Quota plugin to limit users' access to resources.


"Resources" refers to the list of resources defined by the plugin: CPU, memory, and disk. It does not affect compute profiles which are merely a blueprint for the "size" of new hosts.

guides/common/modules/con_limiting-resources.adoc

maximiliankolb · 2024-11-26T14:54:14Z

guides/common/modules/con_limiting-resources.adoc

+* VMware
+* libvirt
+
+Configuration options::


They are global settings that are not exposed via foreman-installer.

guides/common/modules/proc_installing-the-resource-quota-plugin.adoc

guides/common/modules/proc_creating-a-resource-quota.adoc

Lennonka · 2024-11-26T22:33:56Z

guides/common/modules/con_limiting-resources.adoc

+[id="limiting-resources"]
+= Limiting resources
+
+You can use the Resource Quota plugin to limit users' access to resources.


"Host resources" might work. Let's go with that.

@maximiliankolb Do you think you could extend the introduction by summarizing what was written in this thread?

Lennonka · 2024-11-26T22:35:43Z

guides/common/modules/con_limiting-resources.adoc

+* VMware
+* libvirt
+
+Configuration options::


I'd make make them into a separate module with a heading like "Resource Quota Settings", add navigation information where the user can find these settings and put the list of these settings there. Perhaps the first module under Managing resource quotas? Or even a higher-level heading after Installing the plugin.

maximiliankolb

Rebased to "master" and applied Lena's and Bastian's feedback. Ready for re-review.

maximiliankolb · 2024-11-27T08:14:36Z

guides/common/modules/con_limiting-resources.adoc

+* VMware
+* libvirt
+
+Configuration options::


I've moved it to a "ref_" file at the end of the assembly. Is that too far away? Assuming we have sensible default values, users should not need to configure the plugin before typical usage.

maximiliankolb · 2024-11-27T10:04:23Z

guides/common/modules/con_limiting-resources.adoc

+[id="limiting-resources"]
+= Limiting resources
+
+You can use the Resource Quota plugin to limit users' access to resources.


Yes, I have summarized it and rephrased it to "limiting host resources".

nadjaheitmann · 2024-11-27T12:24:01Z

guides/common/modules/con_limiting-host-resources.adoc

+Supported resource types::
+* CPU cores {endash} limit the number of CPU cores
+* Memory {endash} limit the amount of memory
+* Disk space {endash} limit the amount of disk space


I know I'm late to the party :) But this part seems kind of repetitive to me.

Suggested change

Supported resource types::

* CPU cores {endash} limit the number of CPU cores

* Memory {endash} limit the amount of memory

* Disk space {endash} limit the amount of disk space

It is supported to limit the following resource types::

* CPU cores

* Memory

* Disk space

pr-processor bot added the Not yet reviewed label Nov 20, 2024

maximiliankolb commented Nov 20, 2024

View reviewed changes

pr-processor bot removed the Not yet reviewed label Nov 20, 2024

maximiliankolb commented Nov 21, 2024

View reviewed changes

guides/common/modules/proc_creating-a-resource-quota.adoc Outdated Show resolved Hide resolved

bastian-src reviewed Nov 22, 2024

View reviewed changes

guides/common/modules/con_assigning-resource-quotas-to-users.adoc Outdated Show resolved Hide resolved

guides/common/modules/con_assigning-resource-quotas-to-users.adoc Outdated Show resolved Hide resolved

maximiliankolb force-pushed the foreman_resource_quota branch from 17441f2 to f0b4d45 Compare November 22, 2024 13:57

maximiliankolb commented Nov 22, 2024

View reviewed changes

guides/common/modules/con_assigning-resource-quotas-to-users.adoc Outdated Show resolved Hide resolved

guides/common/modules/con_assigning-resource-quotas-to-users.adoc Outdated Show resolved Hide resolved

maximiliankolb marked this pull request as ready for review November 22, 2024 13:58

maximiliankolb added tech review done No issues from the technical perspective Needs style review Requires a review from docs style/grammar perspective labels Nov 22, 2024

Lennonka requested changes Nov 25, 2024

View reviewed changes

pr-processor bot added the Waiting on contributor Requires an action from the author label Nov 25, 2024

maximiliankolb force-pushed the foreman_resource_quota branch from f0b4d45 to 41df150 Compare November 26, 2024 14:58

pr-processor bot added Needs re-review and removed Waiting on contributor Requires an action from the author labels Nov 26, 2024

maximiliankolb commented Nov 26, 2024

View reviewed changes

pr-processor bot removed the Needs re-review label Nov 26, 2024

Lennonka requested changes Nov 26, 2024

View reviewed changes

pr-processor bot added the Waiting on contributor Requires an action from the author label Nov 26, 2024

maximiliankolb force-pushed the foreman_resource_quota branch from 41df150 to 364ca53 Compare November 27, 2024 10:03

pr-processor bot added Needs re-review and removed Waiting on contributor Requires an action from the author labels Nov 27, 2024

maximiliankolb commented Nov 27, 2024

View reviewed changes

pr-processor bot removed the Needs re-review label Nov 27, 2024

maximiliankolb force-pushed the foreman_resource_quota branch from 364ca53 to 0af84ec Compare November 27, 2024 10:42

nadjaheitmann reviewed Nov 27, 2024

View reviewed changes

Document foreman_resource_quota plugin

e0c5c49

maximiliankolb force-pushed the foreman_resource_quota branch from 0af84ec to e0c5c49 Compare November 27, 2024 12:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document foreman_resource_quota plugin #3460

Document foreman_resource_quota plugin #3460

maximiliankolb commented Nov 20, 2024

github-actions bot commented Nov 20, 2024 •

edited

Loading

maximiliankolb Nov 20, 2024

Lennonka Nov 25, 2024

maximiliankolb Nov 26, 2024

Lennonka Nov 26, 2024

maximiliankolb Nov 27, 2024

nadjaheitmann Nov 27, 2024

maximiliankolb Nov 20, 2024

bastian-src left a comment

maximiliankolb left a comment

Lennonka left a comment •

edited

Loading

Lennonka Nov 25, 2024

maximiliankolb Nov 26, 2024

maximiliankolb Nov 26, 2024

bastian-src Nov 26, 2024 •

edited

Loading

Lennonka Nov 26, 2024

maximiliankolb Nov 27, 2024

Lennonka Nov 25, 2024

Lennonka commented Nov 25, 2024 •

edited

Loading

maximiliankolb left a comment

maximiliankolb Nov 26, 2024

maximiliankolb Nov 26, 2024

Lennonka Nov 26, 2024

Lennonka Nov 26, 2024

maximiliankolb left a comment

maximiliankolb Nov 27, 2024

maximiliankolb Nov 27, 2024

nadjaheitmann Nov 27, 2024

		@@ -60,6 +60,8 @@ include::common/assembly_logging-and-reporting-problems.adoc[leveloffset=+1]

		include::common/assembly_monitoring-resources.adoc[leveloffset=+1]

		include::common/assembly_limiting-resources.adoc[leveloffset=+1]

	You can use the Resource Quota plugin to limit users' access to resources.
	You can use the Resource Quota plugin to limit users' access to compute resources.

Document foreman_resource_quota plugin #3460

Are you sure you want to change the base?

Document foreman_resource_quota plugin #3460

Conversation

maximiliankolb commented Nov 20, 2024

What changes are you introducing?

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Checklists

github-actions bot commented Nov 20, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bastian-src left a comment

Choose a reason for hiding this comment

maximiliankolb left a comment

Choose a reason for hiding this comment

Lennonka left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bastian-src Nov 26, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Lennonka commented Nov 25, 2024 • edited Loading

maximiliankolb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

maximiliankolb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Nov 20, 2024 •

edited

Loading

Lennonka left a comment •

edited

Loading

bastian-src Nov 26, 2024 •

edited

Loading

Lennonka commented Nov 25, 2024 •

edited

Loading