From 1d754b43de0f0f48b806c3f67573af547b0ed1ab Mon Sep 17 00:00:00 2001
From: lwm <lwm@users.noreply.github.com>
Date: Fri, 14 Sep 2018 21:10:32 +0200
Subject: [PATCH] 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`.
---
 lib/ansible/modules/cloud/linode/linode.py | 25 +++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/lib/ansible/modules/cloud/linode/linode.py b/lib/ansible/modules/cloud/linode/linode.py
index 187064410aa..4ab7c4ef7a0 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
 '''