feat: add new created state for idempotent server creation (#606)

##### SUMMARY

Add a new state for server creation without immediate start, to allow
idempotent network customization before starting

##### ISSUE TYPE
- Feature Pull Request

##### COMPONENT NAME
server

---------

Co-authored-by: jo <ljonas@riseup.net>

changelogs/fragments/server-add-created-state.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - server - Add `created` state that creates a server but do not start it.

examples/server-with-private-ip-only.yml

@@ -32,7 +32,7 @@
         image: debian-12
         enable_ipv4: false
         enable_ipv6: false
-        state: stopped # A server without networking cannot be started!
+        state: created # A server without networking cannot be started!
       loop: "{{ servers }}"
 
     - name: Attach private IP to servers

plugins/modules/server.py

@@ -150,7 +150,7 @@ options:
         description:
             - State of the server.
         default: present
-        choices: [ absent, present, restarted, started, stopped, rebuild ]
+        choices: [ absent, present, created, restarted, started, stopped, rebuild ]
         type: str
 extends_documentation_fragment:
 - hetzner.hcloud.hcloud
@@ -462,7 +462,7 @@ class AnsibleHCloudServer(AnsibleHCloud):
         elif self.module.params.get("location") is None and self.module.params.get("datacenter") is not None:
             params["datacenter"] = self._client_get_by_name_or_id("datacenters", self.module.params.get("datacenter"))
 
-        if self.module.params.get("state") == "stopped":
+        if self.module.params.get("state") == "stopped" or self.module.params.get("state") == "created":
             params["start_after_create"] = False
 
         if not self.module.check_mode:
@@ -944,7 +944,7 @@ class AnsibleHCloudServer(AnsibleHCloud):
                 rebuild_protection={"type": "bool"},
                 placement_group={"type": "str"},
                 state={
-                    "choices": ["absent", "present", "restarted", "started", "stopped", "rebuild"],
+                    "choices": ["absent", "present", "created", "restarted", "started", "stopped", "rebuild"],
                     "default": "present",
                 },
                 **super().base_module_arguments(),
@@ -965,6 +965,9 @@ def main():
         hcloud.delete_server()
     elif state == "present":
         hcloud.present_server()
+        hcloud.start_server()
+    elif state == "created":
+        hcloud.present_server()
     elif state == "started":
         hcloud.present_server()
         hcloud.start_server()

tests/integration/targets/firewall/tasks/prepare.yml

@@ -5,5 +5,5 @@
     server_type: "{{ hcloud_server_type_name }}"
     image: "{{ hcloud_image_name }}"
     location: "{{ hcloud_location_name }}"
-    state: stopped
+    state: created
   register: test_server

tests/integration/targets/firewall_info/tasks/prepare.yml

@@ -7,7 +7,7 @@
     location: "{{ hcloud_location_name }}"
     labels:
       firewall: "{{ hcloud_firewall_name }}"
-    state: stopped
+    state: created
   register: test_server
 
 - name: Create test_firewall

tests/integration/targets/firewall_resource/tasks/prepare.yml

@@ -7,7 +7,7 @@
     location: "{{ hcloud_location_name }}"
     labels:
       key: value
-    state: stopped
+    state: created
   register: test_server
 
 - name: Create test_firewall

tests/integration/targets/floating_ip/tasks/test.yml

@@ -22,7 +22,7 @@
     server_type: "{{ hcloud_server_type_name }}"
     image: "{{ hcloud_image_name }}"
     location: "{{ hcloud_location_name }}"
-    state: stopped
+    state: created
   register: main_server
 - name: verify setup server
   assert:
@@ -35,7 +35,7 @@
     server_type: "{{ hcloud_server_type_name }}"
     image: "{{ hcloud_image_name }}"
     location: "{{ hcloud_location_name }}"
-    state: stopped
+    state: created
   register: main_server2
 - name: verify setup another server
   assert:

tests/integration/targets/image_info/tasks/prepare.yml

@@ -5,7 +5,7 @@
     server_type: "{{ hcloud_server_type_name }}"
     image: "{{ hcloud_image_name }}"
     location: "{{ hcloud_location_name }}"
-    state: stopped
+    state: created
   register: test_server
 
 - name: Create test_snapshot

tests/integration/targets/load_balancer_info/tasks/prepare.yml

@@ -5,7 +5,7 @@
     server_type: "{{ hcloud_server_type_name }}"
     image: "{{ hcloud_image_name }}"
     location: "{{ hcloud_location_name }}"
-    state: stopped
+    state: created
   register: test_server
 
 - name: Create test_load_balancer

tests/integration/targets/load_balancer_target/tasks/prepare.yml

@@ -5,7 +5,7 @@
     server_type: "{{ hcloud_server_type_name }}"
     image: "{{ hcloud_image_name }}"
     location: "{{ hcloud_location_name }}"
-    state: stopped
+    state: created
   register: test_server
 
 - name: Create test_load_balancer

tests/integration/targets/primary_ip/tasks/prepare.yml

@@ -5,7 +5,7 @@
     server_type: "{{ hcloud_server_type_name }}"
     image: "{{ hcloud_image_name }}"
     location: "{{ hcloud_location_name }}"
-    state: stopped
+    state: created
     enable_ipv4: false
     enable_ipv6: false
   register: test_server

tests/integration/targets/server/tasks/test_primary_ips.yml

@@ -32,7 +32,7 @@
     ipv6: "{{primaryIPv6.hcloud_primary_ip.id}}"
     ssh_keys:
       - "{{ hcloud_ssh_key_name }}"
-    state: stopped
+    state: created
   register: result
 - name: verify test create server with primary ips
   assert:
@@ -50,7 +50,7 @@
     enable_ipv6: false
     ssh_keys:
       - "{{ hcloud_ssh_key_name }}"
-    state: stopped
+    state: created
   register: result
 - name: verify test create server with primary ips
   assert:

tests/integration/targets/server/tasks/test_private_network_only.yml

@@ -72,7 +72,7 @@
       - "{{ primaryNetwork.hcloud_network.name }}"
     ssh_keys:
       - "{{ hcloud_ssh_key_name }}"
-    state: stopped
+    state: created
   register: result
 - name: verify test create server with primary network
   assert:
@@ -92,7 +92,7 @@
       - "{{ secondaryNetwork.hcloud_network.id }}"
     ssh_keys:
       - "{{ hcloud_ssh_key_name }}"
-    state: stopped
+    state: created
   register: result
 - name: verify test update server by adding secondary network
   assert:
@@ -112,7 +112,47 @@
       - "{{ secondaryNetwork.hcloud_network.id }}"
     ssh_keys:
       - "{{ hcloud_ssh_key_name }}"
-    state: stopped
+    state: created
+  register: result
+- name: verify test update server idem
+  assert:
+    that:
+      - result is not changed
+
+- name: test server can now be started
+  hetzner.hcloud.server:
+    name: "{{ hcloud_server_name }}"
+    server_type: "{{ hcloud_server_type_name }}"
+    datacenter: "{{ hcloud_datacenter_name }}"
+    image: "{{ hcloud_image_name }}"
+    enable_ipv4: false
+    enable_ipv6: false
+    private_networks:
+      - "{{ primaryNetwork.hcloud_network.name }}"
+      - "{{ secondaryNetwork.hcloud_network.id }}"
+    ssh_keys:
+      - "{{ hcloud_ssh_key_name }}"
+    state: started
+  register: result
+- name: verify test server can now be started
+  assert:
+    that:
+      - result is changed
+
+- name: test update server idem
+  hetzner.hcloud.server:
+    name: "{{ hcloud_server_name }}"
+    server_type: "{{ hcloud_server_type_name }}"
+    datacenter: "{{ hcloud_datacenter_name }}"
+    image: "{{ hcloud_image_name }}"
+    enable_ipv4: false
+    enable_ipv6: false
+    private_networks:
+      - "{{ primaryNetwork.hcloud_network.name }}"
+      - "{{ secondaryNetwork.hcloud_network.id }}"
+    ssh_keys:
+      - "{{ hcloud_ssh_key_name }}"
+    state: created
   register: result
 - name: verify test update server idem
   assert:

tests/integration/targets/server_info/tasks/prepare.yml

@@ -5,18 +5,18 @@
     server_type: "{{ hcloud_server_type_name }}"
     image: "{{ hcloud_image_name }}"
     location: "{{ hcloud_location_name }}"
-    state: stopped
+    state: created
     labels:
       key: value
   register: test_server
 
-- name: Create test_server2 (stopped + without ip)
+- name: Create test_server2 (without ip)
   hetzner.hcloud.server:
     name: "{{ hcloud_server_name }}2"
     server_type: "{{ hcloud_server_type_name }}"
     image: "{{ hcloud_image_name }}"
     location: "{{ hcloud_location_name }}"
-    state: stopped
+    state: created
     labels:
       key: value
     enable_ipv4: false

tests/integration/targets/server_network/tasks/prepare.yml

@@ -21,5 +21,5 @@
     server_type: "{{ hcloud_server_type_name }}"
     image: "{{ hcloud_image_name }}"
     location: "{{ hcloud_location_name }}"
-    state: stopped
+    state: created
   register: test_server

tests/integration/targets/volume/tasks/test.yml

@@ -6,7 +6,7 @@
     name: "{{hcloud_server_name}}"
     server_type: "{{ hcloud_server_type_name }}"
     image: "{{ hcloud_image_name }}"
-    state: stopped
+    state: created
     location: "{{ hcloud_location_name }}"
   register: vol_server
 - name: verify setup server