Use UUID for clouds by Raghav1428 · Pull Request #26233 · jenkinsci/jenkins

Raghav1428 · 2026-01-31T11:11:42Z

Cloud configuration URLs break when clouds are deleted or reordered. If you have three clouds and delete the first one, the URLs for the remaining two shift, causing 404 errors. This is especially problematic when multiple clouds share the same name since there's no way to distinguish them by URL alone.
The fix assigns each cloud a persistent unique ID (UUID) and routes URLs through that ID instead of the cloud name or index. This way, deleting or reordering clouds doesn't affect the URLs of other clouds.
Testing done
Wrote 14 unit tests in CloudUniqueIdTest covering:

UUID generation and uniqueness across 200 clouds
Thread safety of UUID generation (50 concurrent threads)
Duplicate name clouds can be individually accessed by their unique IDs
Deleting a cloud doesn't affect the IDs of remaining clouds
Copied clouds automatically get a new UUID via the overridden add() in CloudList
Input validation on getCloudById (null, empty, blank, missing)
Backward compatibility with cloudByIndex

Also manually tested on localhost:

Created three clouds with the same name
Verified each got a unique URL (cloud/cloudById/{uuid}/)
Deleted the first cloud — the other two remained accessible
Copied a cloud via the UI — the copy got a different UUID
Edited and saved a cloud — URL stayed the same

Screenshots (UI changes only)

N/A

Proposed changelog entries

Stabilize cloud configuration URLs by using persistent unique IDs instead of name or index-based routing

Proposed changelog category

/label bug

Proposed upgrade guidelines

N/A

Submitter checklist

The issue, if it exists, is well-described.
The changelog entries and upgrade guidelines are appropriate for the audience affected by the change (users or developers, depending on the change) and are in the imperative mood (see examples). Fill in the Proposed upgrade guidelines section only if there are breaking changes or changes that may require extra steps from users during upgrade.
There is automated testing or an explanation as to why this change has no tests.
New public classes, fields, and methods are annotated with @Restricted or have @since TODO Javadocs, as appropriate.
New deprecations are annotated with @Deprecated(since = "TODO") or @Deprecated(forRemoval = true, since = "TODO"), if applicable.
UI changes do not introduce regressions when enforcing the current default rules of Content Security Policy Plugin. In particular, new or substantially changed JavaScript is not defined inline and does not call eval to ease future introduction of Content Security Policy (CSP) directives (see documentation).
For dependency updates, there are links to external changelogs and, if possible, full differentials.
For new APIs and extension points, there is a link to at least one consumer.

Desired reviewers

@timja

Before the changes are marked as ready-for-merge:

Maintainer checklist

There are at least two (2) approvals for the pull request and no outstanding requests for change.
Conversations in the pull request are over, or it is explicit that a reviewer is not blocking the change.
Changelog entries in the pull request title and/or Proposed changelog entries are accurate, human-readable, and in the imperative mood.
Proper changelog labels are set so that the changelog can be generated automatically.
If the change needs additional upgrade steps from users, the upgrade-guide-needed label is set and there is a Proposed upgrade guidelines section in the pull request title (see example).
If it would make sense to backport the change to LTS, be a Bug or Improvement, and either the issue or pull request must be labeled as lts-candidate to be considered.

- Add unique ID field to Cloud class for stable identification - Implement cloud/byId URL routing to prevent URL breakage - Add CloudByIdDispatcher in CloudSet and Jenkins.CloudList - Preserve cloud identity across reconfigurations - Add comprehensive tests for unique ID behavior

….add

… URLs instead of name-based encoded URLs

timja · 2026-01-31T21:49:13Z

core/src/main/java/jenkins/agents/CloudSet.java

+
+    /**
+     * Stapler dispatcher that routes cloud requests by unique ID.
+     * Handles URL patterns like /cloud/cloudById/{uuid}/


can't we either do:

/cloud/id/{uuid}

or just:
/cloud/{uuid} and we can route it by checking if the name is a UUID / it matches a cloud that we have a uuid for?

Ok i will change it to cloud/{uuud}

-Update getDynamic methods in CloudSet to consistently use getById() instead of mixing name-based and UUID-based lookups

mawinter69

Maybe we should include the uuid in the configure.jelly as a hidden field.
In the doConfigsubmit method we check if the uuids of this and the new cloud are identical. If not we throw an error. Don't know if that works though. Would require a DataBoundSetter setUniqueId

Might avoid all the logic we have in the doConfigSubmit at the beginning

I think we need a test for following scenario:

Jenkins starts with a cloud that has no uuid
the cloud should now have an id
restart Jenkins
the uuid you get in step 2 shouldn't change.

The problem right now might be that after the call to readResolve during startup there is no save of the Jenkins configuration happening which could lead to a loss of the uuid.

There is work in one of my plugins jenkinsci/agent-maintenance-plugin#320 that would greatly benefit from that uuid

mawinter69 · 2026-02-01T20:59:53Z

test/src/test/java/hudson/slaves/CloudUniqueIdTest.java

+    }
+
+    @Test
+    void testReadResolveMigrationAssignsId() throws Exception {


This is not testing the readResolve method. You test here that adding a cloud without id to Jenkins assigns a new id.

In this method i am setting the uniqueId field to null and then adding it so the readResolve is called, i have created a new method namely testUuidPersistsAcrossRestartAfterMigration() that triggers the readResolve and also verifies the UUID persists across restart

Where is the readResolve called here?

mawinter69 · 2026-02-01T21:14:25Z

core/src/main/java/hudson/slaves/Cloud.java

+    private volatile String uniqueId;
+
    /**
     * Uniquely identifies this {@link Cloud} instance among other instances in {@link jenkins.model.Jenkins#clouds}.


That comment is not true. Should be adjusted accordingly.

Actually in my previous commits i had transient, i have removed it now

I meant the comment in line 123 for the name which states that it uniquely identifies the cloud, which is wrong.

mawinter69 · 2026-02-01T21:24:52Z

core/src/main/java/hudson/slaves/Cloud.java

+        // Use identity comparison to find the correct cloud to replace
+        // This avoids issues where equals() (often based on name) matches multiple
+        // clouds
+        List<Cloud> newClouds = new ArrayList<>(j.clouds);


Is that threadsafe? Assume one user changes a cloud and another user deletes a cloud at the same time. Unlikely but possible. One of the changes might then be lost when you replace the complete cloud list below

I will synchronize the method

I think it should be avoided to replace the complete list. See my general comment to include the uuid as a hidden field in the configure.jelly.
With this the reconfigured cloud should have a uuid already set. We can then just check if it is identical to the uuid of this if not loop over all clouds and find the one with the same id, if identical we can just use j.clouds.replace(this, reconfigured)

mawinter69 · 2026-02-01T21:27:14Z

core/src/main/java/hudson/slaves/Cloud.java

+            }
+        }
+
+        Cloud reconfigured = cloud.reconfigure(req, req.getSubmittedForm());


Should we just use this.reconfigure here?

Yes, correct i will rectify that

Note that this was wrong before already

mawinter69 · 2026-02-01T21:31:38Z

core/src/main/java/jenkins/agents/CloudSet.java

-            throw new Failure(String.format("No cloud type ‘%s’ is known", cloudDescriptorName));
+            throw new Failure(String.format("No cloud type '%s' is known", cloudDescriptorName));
        }
        Cloud cloud = cloudDescriptor.newInstance(req, req.getSubmittedForm());


Already here the new uuid should be set I think

Yes, mostly it would be set but but the condition was there so i didnt remove that shall i omit it?

I mean that here you should call cloud.provisionNewId() before adding it to

- Assign a UUID to each Cloud on creation and via readResolve migration - Persist UUID across Jenkins restarts by saving config after assignment - Synchronize cloud list updates in doConfigSubmit to avoid race conditions - Use this.reconfigure instead of re-fetching the cloud instance - Set UUID eagerly in CloudSet.newInstance to avoid conditional checks - Add tests for UUID migration and persistence across restarts - add hidden field for UUID and validate it

…id-for-clouds

mawinter69 · 2026-02-03T16:37:22Z

test/src/test/java/hudson/slaves/CloudUniqueIdTest.java

+    }
+
+    @Test
+    void testReadResolveMigrationAssignsId() throws Exception {


Where is the readResolve called here?

mawinter69 · 2026-02-03T16:38:13Z

test/src/test/java/hudson/slaves/CloudUniqueIdTest.java

+        // Simulate pre-uniqueId serialized form
+        Field field = Cloud.class.getDeclaredField("uniqueId");
+        field.setAccessible(true);
+        field.set(cloud, null);


That is not necessary I think. The uniqueId field is not set by the constructor so it should still be null.

the method testReadResolveMigrationAssignsId() doesn't actually uses the readResolve because it doesn't simulate deserialization, and right the constructor doesn't set the uniqueTd so it is redundant and can be removed

I am removing the method testReadResolveMigrationAssignsId as the new method testUuidPersistsAcrossRestartAfterMigration handles readResolve calling and verifies the uuid persists across restart

mawinter69 · 2026-02-03T16:59:10Z

core/src/main/java/hudson/slaves/Cloud.java

+    private volatile String uniqueId;
+
    /**
     * Uniquely identifies this {@link Cloud} instance among other instances in {@link jenkins.model.Jenkins#clouds}.


I meant the comment in line 123 for the name which states that it uniquely identifies the cloud, which is wrong.

mawinter69 · 2026-02-03T17:06:07Z

core/src/main/java/hudson/slaves/Cloud.java

        if (!proposedName.equals(this.name)
                && j.getCloud(proposedName) != null) {
-            throw new Descriptor.FormException(jenkins.agents.Messages.CloudSet_CloudAlreadyExists(proposedName), "name");
+            throw new Descriptor.FormException(


Please restore the formatting to have the throw on one line. There is no real change here.

Surei will change that

mawinter69 · 2026-02-03T17:07:15Z

core/src/main/java/hudson/slaves/Cloud.java

+        // Use identity comparison to find the correct cloud to replace
+        // This avoids issues where equals() (often based on name) matches multiple
+        // clouds
+        List<Cloud> newClouds = new ArrayList<>(j.clouds);


I think it should be avoided to replace the complete list. See my general comment to include the uuid as a hidden field in the configure.jelly.
With this the reconfigured cloud should have a uuid already set. We can then just check if it is identical to the uuid of this if not loop over all clouds and find the one with the same id, if identical we can just use j.clouds.replace(this, reconfigured)

mawinter69 · 2026-02-03T17:13:46Z

core/src/main/java/hudson/slaves/Cloud.java

+            }
+        }
+
+        Cloud reconfigured = cloud.reconfigure(req, req.getSubmittedForm());


Note that this was wrong before already

mawinter69 · 2026-02-03T17:17:54Z

core/src/main/java/jenkins/agents/CloudSet.java

+     * @return dispatcher object for ID-based cloud lookup
+     */
+    @SuppressWarnings("unused") // stapler
+    public CloudByIdDispatcher getCloudById() {


Is that still needed? we don't have the cloudById in the url anymore.
THe UI works fine without this and the CloudByIdDispatcher class

mawinter69 · 2026-02-03T17:26:37Z

core/src/main/java/jenkins/agents/CloudSet.java

-            throw new Failure(String.format("No cloud type ‘%s’ is known", cloudDescriptorName));
+            throw new Failure(String.format("No cloud type '%s' is known", cloudDescriptorName));
        }
        Cloud cloud = cloudDescriptor.newInstance(req, req.getSubmittedForm());


I mean that here you should call cloud.provisionNewId() before adding it to

mawinter69 · 2026-02-03T17:49:42Z

core/src/main/java/jenkins/agents/CloudSet.java

+    @Deprecated
    @SuppressWarnings("unused") // stapler
    @Restricted(DoNotUse.class) // stapler
    public Cloud getCloudByIndex(int index) {


I think it is safe to delete this method. I was only used in the UI of core. A search on github shows no usage of that method (was anyway annotated as DoNotUse)

mawinter69 · 2026-02-03T17:53:37Z

core/src/main/java/hudson/slaves/Cloud.java

+        // Use identity comparison to find the correct cloud to replace
+        // This avoids issues where equals() (often based on name) matches multiple
+        // clouds
+        synchronized (j.clouds) {


I think it should be avoided to replace the complete list. See my general comment to include the uuid as a hidden field in the configure.jelly.
With this the reconfigured cloud should have a uuid already set. We can then just check if it is identical to the uuid of this if not throw an error, if identical we can just use j.clouds.replace(this, reconfigured)

mawinter69 · 2026-02-03T18:02:53Z

core/src/main/java/hudson/slaves/Cloud.java

+        JSONObject submittedForm = req.getSubmittedForm();
+
+        // Validate that the submitted UUID matches this cloud's identity
+        String submittedUuid = submittedForm.optString("uniqueId", null);


No need for this. The reconfigured variable will get the uuid injected via stapler so you can just check for reconfigured.uniqueId == this.uniqueId

mawinter69 · 2026-02-03T18:09:19Z

core/src/main/java/hudson/slaves/Cloud.java

-        Cloud result = cloud.reconfigure(req, req.getSubmittedForm());
-        String proposedName = result.name;
+
+        reconfigured.setUniqueIdIfNotSet(this.getUniqueId());


Not needed. The uniqueId should be set already. If it is not something went wrong.

- Remove getCloudById() and CloudByIdDispatcher from CloudSet (redundant; getDynamic already handles UUID routing) - Remove deprecated getCloudByIndex() from CloudSet (no external usage, was DoNotUse) - Remove setUniqueIdIfNotSet() from Cloud (uniqueId now injected via @DataBoundSetter from hidden form field) - Add provisionNewId() call when copying clouds via XStream to ensure distinct identity - Simplify doConfigSubmit() to directly compare uniqueId fields - Update Javadoc for Cloud.name field to reflect it's a display name, not unique identifier - Remove obsolete tests for deleted internal methods

- add provisionNewId() to doDoCreate

…ssign

mawinter69

One thing that is not good at the moment is that we we can still create clouds with duplicate uuids. Nobody stops you from modifying the config.xml and change the uuid to something else.
And when working with configuration as code as then when the uuid is missing in the yaml, it is not created upon applying the yaml file with the cloud configurations. The uuid would only be created once you access the UI. So users that configure clouds will need to set a uuid for each cloud to ensure the uuid is stable across Jenkins restarts.

Ideally clouds are no longer persisted as part of the Jenkins global config.xml but in a separate folder and then use the name as folder name. But that would require some mechanism to deduplicate names where I don't know if that can be done so easily without breaking any cloud implementation. It would also require that cloud names are good names.
E.g. with google compute you can create a cloud that is named gce-<google:!*> which would not be a valid file system name

That would require some research on each cloud implementation if the name is used for anything else. Afaik there is at least one cloud that set a hard coded value for the name.

mawinter69 · 2026-02-04T16:30:31Z

core/src/main/java/jenkins/model/Jenkins.java

+    @SuppressWarnings("unused") // stapler
+    @Restricted(DoNotUse.class) // stapler
+    public Cloud getCloudById(String id) {
+        if (id == null || id.trim().isEmpty()) {


The body of the method can be simplified to return clouds.getById(id)

mawinter69 · 2026-02-04T18:22:53Z

core/src/main/java/hudson/slaves/Cloud.java

+     * This handles migration of existing configurations that don't have IDs.
+     */
+    @SuppressWarnings("unused")
+    private Object readResolve() {


Unfortunately this doesn't work. I tried this with a google cloud and the method is not called on Jenkins startup. You need to add

clouds.stream().forEach(c -> c.getUniqueId());

to the readResolve method in the Jenkins class.

This also ensures that the new ids are persisted

Okay i will implement that

mawinter69 · 2026-02-04T18:42:45Z

core/src/main/java/jenkins/model/Jenkins.java

+
+        @Override
+        public boolean add(Cloud c) {
+            if (getById(c.getUniqueId()) != null) {


This is never true as getUniqueId will create a uuid if not set.

I will check for that

mawinter69 · 2026-02-04T21:46:01Z

core/src/main/java/jenkins/agents/CloudSet.java

            // Not great, but cloud name is final
            xml = xml.replace("<name>" + src.name + "</name>", "<name>" + name + "</name>");
+            // Remove uniqueId so the copy gets a new identity via provisionNewId()
+            xml = xml.replaceAll("<uniqueId>[^<]*</uniqueId>", "");


This is dangerous. While extremely unlikely, but if a plugin would define itself a field with name uniqueId you would remove that as well.

timja · 2026-02-04T22:57:50Z

And when working with configuration as code as then when the uuid is missing in the yaml,

You could put it in the databoundconstructor so its mandatory to be specified by jcasc users.
Edit: You would have to create a new constructor in core and then update plugins to call it

- Add duplicate UUID detection in Jenkins.readResolve() to handle manually edited config.xml files with duplicate UUIDs - Ensure all clouds get UUIDs on startup, fixing JCasc configs that don't specify UUIDs - Simplify getCloudById() to delegate to clouds.getById() - Remove dangerous regex in CloudSet.doCreate() that could affect plugin fields; CloudList.add() handles duplicate prevention - Update CloudUniqueIdTest to use clouds.replace() for realistic form submission simulation

…ouds element

github-actions · 2026-02-07T00:05:28Z

Please take a moment and address the merge conflicts of your pull request. Thanks!

Raghav1428 added 2 commits January 31, 2026 01:27

fix: remove transient from uniqueId and provision new ID on CloudList…

66c1f56

….add

comment-ops-bot bot added the bug For changelog: Minor bug. Will be listed after features label Jan 31, 2026

Raghav1428 added 3 commits January 31, 2026 16:42

Merge branch 'master' into use-uuid-for-clouds

7addb81

fix: broken @link in CloudSet

7054e1f

fix: Update CloudTest.cloudNameIsEncodedInGetUrl to verify UUID-based…

9554917

… URLs instead of name-based encoded URLs

timja reviewed Jan 31, 2026

View reviewed changes

Raghav1428 added 3 commits February 1, 2026 16:38

simplify cloud URLs by removing byId

5283a32

Make all cloud routing methods use UUID-based lookup

6873377

-Update getDynamic methods in CloudSet to consistently use getById() instead of mixing name-based and UUID-based lookups

Merge branch 'master' into use-uuid-for-clouds

02c38c4

mawinter69 mentioned this pull request Feb 1, 2026

Fix Cloud#getUrl when 2 clouds with same name exist #26177

Open

14 tasks

mawinter69 suggested changes Feb 1, 2026

View reviewed changes

This was referenced Feb 1, 2026

Fix 404 after deleting an indexed cloud #26181

Open

[JENKINS-76317]: Add support to define maintenance windows for Clouds jenkinsci/agent-maintenance-plugin#320

Open

Raghav1428 added 2 commits February 3, 2026 22:37

Merge remote-tracking branch 'origin/use-uuid-for-clouds' into use-uu…

51d55ce

…id-for-clouds

Raghav1428 requested review from mawinter69 and timja February 3, 2026 17:08

mawinter69 suggested changes Feb 3, 2026

View reviewed changes

mawinter69 reviewed Feb 3, 2026

View reviewed changes

Raghav1428 requested a review from mawinter69 February 4, 2026 13:57

Raghav1428 added 3 commits February 4, 2026 19:44

refactor(cloud): Cloud unique ID implementation

b43bcdb

- add provisionNewId() to doDoCreate

update the provisionNewId method to check for the uniqueId and then a…

4405333

…ssign

revert the provisionNewId and override the replace method

9034ab5

mawinter69 suggested changes Feb 4, 2026

View reviewed changes

mawinter69 reviewed Feb 4, 2026

View reviewed changes

Raghav1428 requested a review from mawinter69 February 5, 2026 12:52

Raghav1428 added 2 commits February 6, 2026 00:20

Fix NPE in readResolve when deserializing old config files without cl…

d1f21ba

…ouds element

update the comment for provisionNewId

e8cd89c

github-actions bot added the unresolved-merge-conflict There is a merge conflict with the target branch. label Feb 7, 2026

Merge branch 'master' into use-uuid-for-clouds

7a64b00

github-actions bot removed the unresolved-merge-conflict There is a merge conflict with the target branch. label Feb 7, 2026

Uh oh!

Conversation

Raghav1428 commented Jan 31, 2026

Screenshots (UI changes only)

Proposed changelog entries

Proposed changelog category

Proposed upgrade guidelines

Submitter checklist

Desired reviewers

Maintainer checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mawinter69 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mawinter69 Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mawinter69 Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

mawinter69 left a comment •

edited

Loading

mawinter69 Feb 1, 2026 •

edited

Loading

mawinter69 Feb 3, 2026 •

edited

Loading

mawinter69 left a comment •

edited

Loading

timja commented Feb 4, 2026 •

edited

Loading