Linode: clarify how to create/delete linode machines with `linode_id`. (#45659)

* Attempt to explain `linode_id` a bit better.

Don't include in any example that creates a Linode.

Based on comments in

> https://github.com/ansible/ansible/issues/45403#issuecomment-419752856

* Add simple creation example. Show how to pass `linode_id`.

1 files changed, 20 insertions, 5 deletions

diff --git a/lib/ansible/modules/cloud/linode/linode.py b/lib/ansible/modules/cloud/linode/linode.py
index 187064410a..4ab7c4ef7a 100644
--- a/lib/ansible/modules/cloud/linode/linode.py
+++ b/lib/ansible/modules/cloud/linode/linode.py
@@ -37,7 +37,10 @@ options:
     version_added: "2.3"
   linode_id:
     description:
-     - Unique ID of a linode server
+     - Unique ID of a linode server. This value is read-only in the sense that
+       if you specify it on creation of a Linode it will not be used. The
+       Linode API generates these IDs and we can those generated value here to
+       reference a Linode more specifically. This is useful for idempotence.
     aliases: [ lid ]
   additional_disks:
     description:
@@ -153,6 +156,16 @@ notes:
 '''
 
 EXAMPLES = '''
+
+- name: Create a new Linode
+  linode:
+    name: linode-test1
+    plan: 1
+    datacenter: 7
+    distribution: 129
+    state: present
+  register: linode_creation
+
 - name: Create a server with a private IP Address
   linode:
      module: linode
@@ -169,6 +182,7 @@ EXAMPLES = '''
      wait_timeout: 600
      state: present
   delegate_to: localhost
+  register: linode_creation
 
 - name: Fully configure new server
   linode:
@@ -203,12 +217,12 @@ EXAMPLES = '''
       - {Label: 'newdisk', Size: 2000}
      watchdog: True
   delegate_to: localhost
+  register: linode_creation
 
 - name: Ensure a running server (create if missing)
   linode:
      api_key: 'longStringFromLinodeApi'
      name: linode-test1
-     linode_id: 12345678
      plan: 1
      datacenter: 2
      distribution: 99
@@ -219,12 +233,13 @@ EXAMPLES = '''
      wait_timeout: 600
      state: present
   delegate_to: localhost
+  register: linode_creation
 
 - name: Delete a server
   linode:
      api_key: 'longStringFromLinodeApi'
      name: linode-test1
-     linode_id: 12345678
+     linode_id: "{{ linode_creation.instance.id }}"
      state: absent
   delegate_to: localhost
 
@@ -232,7 +247,7 @@ EXAMPLES = '''
   linode:
      api_key: 'longStringFromLinodeApi'
      name: linode-test1
-     linode_id: 12345678
+     linode_id: "{{ linode_creation.instance.id }}"
      state: stopped
   delegate_to: localhost
 
@@ -240,7 +255,7 @@ EXAMPLES = '''
   linode:
      api_key: 'longStringFromLinodeApi'
      name: linode-test1
-     linode_id: 12345678
+     linode_id: "{{ linode_creation.instance.id }}"
      state: restarted
   delegate_to: localhost
 '''