Document difference between ID and virtual ID

1 files changed, 8 insertions, 2 deletions

diff --git a/config-provisioning/src/main/java/com/yahoo/config/provision/zone/ZoneApi.java b/config-provisioning/src/main/java/com/yahoo/config/provision/zone/ZoneApi.java
index c6ba6d1bae5..b50d8ce2e7c 100644
--- a/config-provisioning/src/main/java/com/yahoo/config/provision/zone/ZoneApi.java
+++ b/config-provisioning/src/main/java/com/yahoo/config/provision/zone/ZoneApi.java
@@ -13,6 +13,12 @@ public interface ZoneApi {
 
     SystemName getSystemName();
 
+    /**
+     * Returns the ID of the zone.
+     *
+     * WARNING: The ID of a controller zone is equal to the ID of a prod zone in the same region.
+     * @see #getVirtualId()
+     */
     ZoneId getId();
 
     /** Returns the SYSTEM.ENVIRONMENT.REGION string. */
@@ -21,8 +27,8 @@ public interface ZoneApi {
     }
 
     /**
-     * Returns the virtual ID of this zone. For ordinary zones this is the same as {@link ZoneApi#getId()}, for a
-     * system represented as a zone this is a fixed ID that is independent of the actual zone ID.
+     * Returns {@link #getId()} for all zones except the controller zone.  Unlike {@link #getId()},
+     * the virtual ID of a controller is distinct from all other zones.
      */
     default ZoneId getVirtualId() {
         return getId();