From 7f7ab96d6d2369d177e59385e5b5570d75f40d44 Mon Sep 17 00:00:00 2001 From: Daman Arora Date: Wed, 15 Apr 2026 18:23:00 +1000 Subject: [PATCH 1/2] Add documentation for Template replication on secondary storage --- source/adminguide/templates.rst | 83 +++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/source/adminguide/templates.rst b/source/adminguide/templates.rst index 2373fea198..8156f8637c 100644 --- a/source/adminguide/templates.rst +++ b/source/adminguide/templates.rst @@ -136,6 +136,89 @@ in a private Zone, it is available only to Users in the domain assigned to that Zone. If a public Template is created in a public Zone, it is available to all Users in all domains. +Template Replication on Secondary Storage +----------------------------------------- + +A Zone may have more than one secondary storage (image store). When a +Template is registered, CloudStack decides how many of those image +stores should hold a copy of the Template. Historically, this decision +was tied to the Template's ``public`` flag: + +- **Public Templates** were copied to **every** image store in the + Zone, so that the Template was readily available wherever a host + pulled from. + +- **Private Templates** were copied to **exactly one** image store in + the Zone. + +This coupling mixed two unrelated concerns — *who can see a Template* +(access control) and *how many copies are kept on secondary storage* +(placement and durability). In environments where secondary storage +already provides redundancy (for example Ceph, replicated NFS, or +object storage), copying public Templates to every image store wastes +capacity, lengthens sync times, and adds unnecessary network and I/O +load. Conversely, operators who want a second copy of a private +Template for availability had no way to ask for one. + +To give operators explicit control, CloudStack exposes two +configuration settings that cap the number of secondary storage pools +a Template is copied to: + +- ``public.template.secstorage.copy`` — the maximum number of + secondary storage pools to which a public Template is copied. The + default is ``0``, which means "copy to every image store in the + Zone" and preserves the historical behavior. + +- ``private.template.secstorage.copy`` — the maximum number of + secondary storage pools to which a private Template is copied. The + default is ``1``, which preserves the historical behavior. + +Replication stops once the configured replica count is reached. Image +store selection reuses the existing CloudStack placement logic, so +copies are spread across image stores in the Zone. + +Changing these settings does **not** change who can see or use a +Template. The ``public`` flag continues to govern visibility exactly +as described in the previous section; these settings only govern how +many physical copies are kept. + +Example scenarios +~~~~~~~~~~~~~~~~~ + +- **Large Zone with 5 secondary storages.** Setting + ``public.template.secstorage.copy = 2`` copies public Templates to + only 2 of the 5 image stores, freeing capacity on the others. + +- **Ceph-backed secondary storage.** Setting + ``public.template.secstorage.copy = 1`` avoids redundant replication + because the storage layer already provides durability. + +- **HA for private Templates.** Setting + ``private.template.secstorage.copy = 2`` keeps two copies of every + private Template so that the Template is still available if one + image store is down. + +- **Default (backward compatible).** With + ``public.template.secstorage.copy = 0`` and + ``private.template.secstorage.copy = 1``, CloudStack behaves exactly + as in earlier releases. + +Scope of application +~~~~~~~~~~~~~~~~~~~~ + +The configured replica counts are applied when: + +- A new Template is registered in a Zone. + +- A new secondary storage is added to a Zone and CloudStack + synchronises existing Templates onto it. + +The settings do not alter Templates that have already been replicated +beyond the configured count; they only affect future placement +decisions. When replication is capped by these settings, the +Management Server log records why an image store was skipped, which +is useful when auditing placement. + .. _creating-a-template-from-an-existing-virtual-machine: Creating a Template from an Existing Instance --------------------------------------------- From 2c41042b15c77da779dbb594b8c0c27c43cc012f Mon Sep 17 00:00:00 2001 From: Daman Arora Date: Mon, 27 Apr 2026 09:45:18 -0400 Subject: [PATCH 2/2] Update template replication settings in documentation for clarity and consistency --- source/adminguide/templates.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/source/adminguide/templates.rst b/source/adminguide/templates.rst index 8156f8637c..cbdfe21a13 100644 --- a/source/adminguide/templates.rst +++ b/source/adminguide/templates.rst @@ -140,9 +140,10 @@ Template Replication on Secondary Storage ----------------------------------------- A Zone may have more than one secondary storage (image store). When a -Template is registered, CloudStack decides how many of those image -stores should hold a copy of the Template. Historically, this decision -was tied to the Template's ``public`` flag: +Template is registered or a new Secondary Storage is added to the +zone, CloudStack decides how many of those image stores should hold a +copy of the Template. Historically, this decision was tied to the +Template's ``public`` flag: - **Public Templates** were copied to **every** image store in the Zone, so that the Template was readily available wherever a host @@ -164,12 +165,12 @@ To give operators explicit control, CloudStack exposes two configuration settings that cap the number of secondary storage pools a Template is copied to: -- ``public.template.secstorage.copy`` — the maximum number of +- ``secstorage.public.template.copy.max`` — the maximum number of secondary storage pools to which a public Template is copied. The default is ``0``, which means "copy to every image store in the Zone" and preserves the historical behavior. -- ``private.template.secstorage.copy`` — the maximum number of +- ``secstorage.private.template.copy.max`` — the maximum number of secondary storage pools to which a private Template is copied. The default is ``1``, which preserves the historical behavior. @@ -186,21 +187,21 @@ Example scenarios ~~~~~~~~~~~~~~~~~ - **Large Zone with 5 secondary storages.** Setting - ``public.template.secstorage.copy = 2`` copies public Templates to + ``secstorage.public.template.copy.max = 2`` copies public Templates to only 2 of the 5 image stores, freeing capacity on the others. - **Ceph-backed secondary storage.** Setting - ``public.template.secstorage.copy = 1`` avoids redundant replication + ``secstorage.public.template.copy.max = 1`` avoids redundant replication because the storage layer already provides durability. - **HA for private Templates.** Setting - ``private.template.secstorage.copy = 2`` keeps two copies of every + ``secstorage.private.template.copy.max = 2`` keeps two copies of every private Template so that the Template is still available if one image store is down. - **Default (backward compatible).** With - ``public.template.secstorage.copy = 0`` and - ``private.template.secstorage.copy = 1``, CloudStack behaves exactly + ``secstorage.public.template.copy.max = 0`` and + ``secstorage.private.template.copy.max = 1``, CloudStack behaves exactly as in earlier releases. Scope of application