This is an automated email from the ASF dual-hosted git repository.
shwstppr pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/main by this push:
new 13cc7e5 Add docs about storage and host tags (#365)
13cc7e5 is described below
commit 13cc7e589e4339d4dc06baa82ebb1d1ac30eea85
Author: João Jandre <[email protected]>
AuthorDate: Mon Feb 5 02:54:45 2024 -0300
Add docs about storage and host tags (#365)
Creates a new section about the flexible tags documentation for hosts and
storage.
---
source/adminguide/host_and_storage_tags.rst | 92 +++++++++++++++++++++++++++++
source/adminguide/index.rst | 7 +++
source/adminguide/management.rst | 2 +
3 files changed, 101 insertions(+)
diff --git a/source/adminguide/host_and_storage_tags.rst
b/source/adminguide/host_and_storage_tags.rst
new file mode 100644
index 0000000..1f909f8
--- /dev/null
+++ b/source/adminguide/host_and_storage_tags.rst
@@ -0,0 +1,92 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information#
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+
+Host and Storage Tags
+======================
+
+Host tags and storage tags, despite the name, are not related to resource tags
( see section :ref:`resource-tags` ); they are a feature to direct resource
allocation, such as which host the VM will be deployed on or which storage the
volume will be created on. There are several reasons for using tags (such as
directing the volume to better quality storage, according to the offering).
+
+Host tags
+---------
+Host tags are responsible for directing VMs to compatible hosts. They are
validated with the host tags informed in the compute offerings or in the system
offerings.
+
+To explain the behavior of host tags, some examples will be demonstrated with
two hosts (Host1 and Host2):
+
+#. Tag setup:
+ * Host1: h1
+ * Host2: h2
+ * Offering: h1
+ When a VM is created with the offering, the deployment will be carried out
on Host1, as it is the one that has the tag compatible with the offering.
+
+#. Tag setup:
+ * Host1: h1
+ * Host2: h2,h3
+ * Offering: h3
+ Hosts and offerings accept a list of tags, with comma (,) being their
separator. So in this example, Host2 has the h2 and h3 tags. When a VM is
created with the offering, the deployment will be carried out on Host2, as it
is the one that has the tag compatible with the offering.
+
+#. Tag setup:
+ * Host1: h1
+ * Host2: h2,h3
+ * Offering: (no tag)
+ When the offering does not have tags, it will be possible to deploy the VM
on any host.
+
+#. Tag setup:
+ * Host1: (no tag)
+ * Host2: h2
+ * Offering: h3
+ None of the hosts have compatible tags and it will not be possible to
deploy a VM with the offering. However, CloudStack ignores this behavior when a
host is manually selected.
+
+Storage tags
+------------
+Storage tags are responsible for directing volumes to compatible primary
storage. They are validated with the storage tags entered in the disk offerings
or system offerings.
+
+To explain the behavior of storage tags, some examples will be demonstrated:
+
+#. Tag setup:
+ * Storage: A
+ * Offering: A,B
+ Storage and offering accept a list of tags, with the comma (,) being their
separator. Therefore, in this example, the offering has tags A and B. In this
example, it will not be possible to allocate the volume, as all the offering
tags must exist in the storage. Although the storage has the A tag, it does not
have the B tag.
+
+#. Tag setup:
+ * Storage: A,B,C,D,X
+ * Offering: A,B,C
+ In this example, it will be possible to allocate the volume, as all the
offering tags exist in the storage.
+
+#. Tag setup:
+ * Storage: A, B, C
+ * Offering: (no tag)
+ In this example, it will be possible to allocate the volume, as the
offering does not have any tag requirements.
+
+#. Tag setup:
+ * Storage: (no tag)
+ * Offering: D,E
+ In this example, it will not be possible to allocate the volume, as the
storage does not have tags, therefore it does not meet the offering
requirements.
+
+In short, if the offering has tags, the storage will need to have all the tags
for the volume to be allocated. If the offering does not have tags, the volume
can be allocated, regardless of whether the storage has a tag or not.
+
+Flexible Tags
+--------------
+When defining tags for a resource (a host, for example), offerings with those
tags will be directed to that resource. However, offerings without tags can
also be targeted to it. So, even after adding tags to a resource with the
intention of making it exclusive to certain types of offerings, this
exclusivity can be ignored.
+
+Furthermore, the standard tag system only allows the user to enter a simple
list of tags, without the possibility of creating more complex rules, such as
checking whether the offering has certain pairs of tags.
+
+To overcome these situations, ACS allows hosts and storages to have tags that
are rules written in JavaScript, also known as flexible tags. With flexible
tags, the role of tag targeting is reversed, that is, instead of the host or
storage needing to have the offering's tag for targeting to be carried out, the
offering will need to have the tag of the resource to which it will be
directed. This inversion means that offerings without tags cannot be directed
to any resource. This way, opera [...]
+
+Configuring flexible tags on hosts is carried out through the ``updateHost``
API, entering the rule in the ``hosttags`` field. On the other hand,
configuring flexible tags in the storages is done using the
``updateStoragePool`` API, informing the rule in the ``tags`` field. For the
informed tag to be effectively interpreted as JavaScript, you must declare the
``istagarule`` parameter as true whenever you use one of the APIs presented.
+
+It is worth mentioning that the compute offering or disk offering tags are
injected in list format. Thus, when validating an offering with tags ``A, B``,
during processing, there will be the variable ``tags``, where ``tags[0]`` will
be tag A, and ``tags[1]`` will be tag B.
+
+It's also important to mention that flexible tags are not compatible with
quota's activation rules.
diff --git a/source/adminguide/index.rst b/source/adminguide/index.rst
index 44633e9..f597cdd 100644
--- a/source/adminguide/index.rst
+++ b/source/adminguide/index.rst
@@ -132,6 +132,13 @@ Working with Usage
usage
+Managing VM and Volume Allocation
+---------------------------------
+
+.. toctree::
+ :maxdepth: 4
+
+ host_and_storage_tags
Managing Networks and Traffic
-----------------------------
diff --git a/source/adminguide/management.rst b/source/adminguide/management.rst
index b13086f..3808b64 100644
--- a/source/adminguide/management.rst
+++ b/source/adminguide/management.rst
@@ -14,6 +14,8 @@
under the License.
+.. _resource-tags:
+
Using Tags to Organize Resources in the Cloud
---------------------------------------------
