kvmvm provision fix

Fix/rc 5.2.2

See merge request rudecs/decort-ansible!5

README.md

@@ -1,2 +1,12 @@
 # decort-ansible
-Ansible modules for Digital Energy Orchestration Technology (DECORT) platform v3.4.0 and above
+Ansible modules for Digital Energy Orchestration Technology (DECORT) platform v3.6.1 and above.
+
+Note that this module may produce unreliable results when used with older DECORT API versions. 
+
+Requirements:
+* Ansible 2.7 or higher
+* Python 3.7 or higher
+* PyJWT 2.0.0 Python module or higher
+* requests Python module
+* netaddr Python module
+* DECORT cloud platform version 3.8.6 or higher

examples/VINS.yaml

@@ -0,0 +1,40 @@
+---
+#
+# DECORT vins module example
+#
+
+- hosts: localhost
+  tasks:
+  - name: obtain JWT
+    decort_jwt:
+      oauth2_url: "https://sso.digitalenergy.online"
+      validity: 1200
+    register: my_jwt
+    delegate_to: localhost
+
+  - name: print out JWT
+    debug:
+      var: my_jwt.jwt
+    delegate_to: localhost
+
+  - name: Manage ViNS at resource group level
+    decort_vins:
+      authenticator: jwt
+      jwt: "{{ my_jwt.jwt }}"
+      controller_url: "https://ds1.digitalenergy.online"
+      vins_name: "vins_created_by_decort_VINS_module"
+      state: present
+      rg_id: 198
+      ext_net_id: -1
+      ipcidr: "10.20.30.0/24"
+      mgmtaddr: "10.20.30.1"
+      custom_config: false
+      config_save: false 
+      verify_ssl: false
+
+    register: managed_vins
+
+  - name: print VINS facter
+    debug:
+      msg: "{{managed_vins.facts.password}}"
+    when: managed_vins.facts.password is defined

examples/affinity.yaml

@@ -0,0 +1,36 @@
+---
+#
+# DECORT kvmvm module example
+#
+- hosts: ansible_master
+  tasks:
+  - name: create a VM named cloud-init_example
+    decort_kvmvm:
+      name: affinity_example
+      annotation: "VM managed by decort_kvmvm module"
+      authenticator: oauth2
+      app_id: ""                                          # Application id from SSO Digital Energy
+      app_secret: ""                                      # API key from SSO Digital Energy
+      controller_url: ""                                  #"https://mr4.digitalenergy.online"
+      rg_id:                                              # Resource group id
+      cpu: 2
+      ram: 2048
+      boot_disk: 10
+      image_name: "DECS Ubuntu 18.04 v1.2.3"              # Name of OS image
+      networks:
+        - type: VINS
+          id:                                             # VINS id
+      tags: "Ansible cloud init example"
+      aff_lable: "Affinity lable"
+      tag:
+        - key: bd
+          value: main
+      aff_rule:
+        - key: app
+          value: main
+          topology: compute
+          policy: REQUIRED
+          mode: EQ
+      state: present
+    delegate_to: localhost
+    register: simple_vm

examples/annotations.yaml

@@ -0,0 +1,40 @@
+---
+#
+# DECORT k8s module labels, taints, annotations example
+#
+
+- hosts: localhost
+  tasks:
+  - name: obtain JWT
+    decort_jwt:
+      oauth2_url: "https://sso.digitalenergy.online"
+      validity: 1200
+    register: my_jwt
+    delegate_to: localhost
+
+  - name: print out JWT
+    debug:
+      var: my_jwt.jwt
+    delegate_to: localhost
+
+  - name: Create k8s cluster
+    decort_k8s:
+      authenticator: jwt
+      jwt: "{{ my_jwt.jwt }}"
+      controller_url: "https://mr4.digitalenergy.online"
+      name: "example_kubernetes"
+      rg_id: 199
+      k8ci_id: 4
+      state: present
+      workers:
+      - name: workgroup1
+        labels:
+        - disktype1=ssd1
+        - disktype2=ssd2
+        taints:
+        - key1=value1:NoSchedule 
+        - key2=value2:NoSchedule
+        annotations:
+        - node.deckhouse.io/group1=g1
+        - node.deckhouse.io/group2=g2
+    register: kube

examples/anti_affinity.yaml

@@ -0,0 +1,36 @@
+---
+#
+# DECORT kvmvm module example
+#
+- hosts: ansible_master
+  tasks:
+  - name: create a VM named cloud-init_example
+    decort_kvmvm:
+      name: anti-affinity_example
+      annotation: "VM managed by decort_kvmvm module"
+      authenticator: oauth2
+      app_id: ""                                          # Application id from SSO Digital Energy
+      app_secret: ""                                      # API key from SSO Digital Energy
+      controller_url: ""                                  #"https://mr4.digitalenergy.online"
+      rg_id:                                              # Resource group id
+      cpu: 2
+      ram: 2048
+      boot_disk: 10
+      image_name: "DECS Ubuntu 18.04 v1.2.3"              #Name of OS image
+      networks:
+        - type: VINS
+          id:                                             #VINS id
+      tags: "Ansible cloud init example"
+      aff_lable: "Anti affinity lable"
+      tag:
+        - key: bd
+          value: main
+      aaff_rule:
+        - key: app
+          value: main
+          topology: compute
+          policy: REQUIRED
+          mode: ANY
+      state: present
+    delegate_to: localhost
+    register: simple_vm

examples/basicservices.yaml

@@ -0,0 +1,31 @@
+---
+#
+# DECORT bservice module example
+#
+
+- hosts: localhost
+  tasks:
+  - name: obtain JWT
+    decort_jwt:
+      oauth2_url: "https://sso.digitalenergy.online"
+      validity: 1200
+    register: my_jwt
+    delegate_to: localhost
+
+  - name: print out JWT
+    debug:
+      var: my_jwt.jwt
+    delegate_to: localhost
+
+  - name: Manage bservice at RG
+    decort_bservice:
+      account_id: 98
+      verify_ssl: false
+      authenticator: jwt
+      jwt: "{{ my_jwt.jwt }}"
+      controller_url: "https://ds1.digitalenergy.online"
+      rg_id: 1629
+      state: present
+      name: databases
+      started: True
+    register: db_bservice

examples/cloud-init.yaml

@@ -0,0 +1,38 @@
+#
+# DECORT kvmvm module example
+#
+- hosts: ansible_master
+  tasks:
+  - name: create a VM named cloud-init_example
+    decort_kvmvm:
+      annotation: "VM managed by decort_kvmvm module"
+      authenticator: oauth2
+      app_id: ""                                          # Application id from SSO Digital Energy
+      app_secret: ""                                      # API key from SSO Digital Energy
+      controller_url: ""                                  #"https://mr4.digitalenergy.online"
+      name: cloud-init_example
+      cpu: 2
+      ram: 2048
+      boot_disk: 10
+      image_name: "DECS Ubuntu 18.04 v1.2.3"              #Name of OS image
+      networks:
+        - type: VINS
+          id:                                             #VINS id
+      tags: "Ansible cloud init example"
+      state: present
+      rg_id:                                              #Resource group id
+      ci_user_data:
+        - packages:
+            - apache2
+        - write_files:
+            - content: |
+                <div>
+                Hello World!
+                </div>
+              owner: user:user
+              path: /var/www/html/index.html
+        - hostname: test-apache
+        - ssh_keys:
+            - rsa_public: ssh-rsa AAAAOasDmLxnD=  user@pc
+    delegate_to: localhost
+    register: simple_vm

examples/cloud_init.yaml

@@ -0,0 +1,38 @@
+#
+# DECORT kvmvm module example
+#
+- hosts: ansible_master
+  tasks:
+  - name: create a VM named cloud-init_example
+    decort_kvmvm:
+      annotation: "VM managed by decort_kvmvm module"
+      authenticator: oauth2
+      app_id: ""                                          # Application id from SSO Digital Energy
+      app_secret: ""                                      # API key from SSO Digital Energy
+      controller_url: ""                                  #"https://mr4.digitalenergy.online"
+      name: cloud-init_example
+      cpu: 2
+      ram: 2048
+      boot_disk: 10
+      image_name: "DECS Ubuntu 18.04 v1.2.3"              #Name of OS image
+      networks:
+        - type: VINS
+          id:                                             #VINS id
+      tags: "Ansible cloud init example"
+      state: present
+      rg_id:                                              #Resource group id
+      ci_user_data:
+        - packages:
+            - apache2
+        - write_files:
+            - content: |
+                <div>
+                Hello World!
+                </div>
+              owner: user:user
+              path: /var/www/html/index.html
+        - hostname: test-apache
+        - ssh_keys:
+            - rsa_public: ssh-rsa AAAAOasDmLxnD=  user@pc
+    delegate_to: localhost
+    register: simple_vm

examples/decort_disk/disk_create.yaml

@@ -0,0 +1,22 @@
+---
+- hosts: localhost
+  tasks:
+  - name: manage data disk 01
+    decort_disk:
+       authenticator: oauth2
+       app_id: #Application id from SSO DigitalEnergy
+       app_secret: #Application secret from SSO DigitalEnergy
+       controller_url: "https://cloud.digitalenergy.online"
+       account_name: "account_name"
+       name: "example_disk"
+       sep_id: 1
+       pool: 0
+       gid: 0
+       size: 2
+       type: "D"
+       description: "Disk created by decort_disk module"
+       iops: 2000
+       state: present
+       verify_ssl: false
+
+    delegate_to: localhost

examples/decort_disk/disk_delete.yaml

@@ -0,0 +1,18 @@
+---
+- hosts: localhost
+  tasks:
+  - name: manage data disk 01
+    decort_disk:
+       authenticator: oauth2
+       app_id: #Application id from SSO DigitalEnergy
+       app_secret: #Application secret from SSO DigitalEnergy
+       controller_url: "https://cloud.digitalenergy.online"
+       account_name: "account_name"
+       name: "example_disk"
+       permanently: False
+       force_detach: True
+       reason: "Just to test module decort_disk"
+       state: absent
+       verify_ssl: false
+
+    delegate_to: localhost

examples/decort_disk/disk_limitIO.yaml

@@ -0,0 +1,28 @@
+---
+- hosts: localhost
+  tasks:
+  - name: manage data disk 01
+    decort_disk:
+       authenticator: oauth2
+       app_id: #Application id from SSO DigitalEnergy
+       app_secret: #Application secret from SSO DigitalEnergy
+       controller_url: "https://cloud.digitalenergy.online"
+       account_name: "account_name"
+       id: 111
+       limitIO:
+         read_bytes_sec: 100
+         read_bytes_sec_max: 100
+         read_iops_sec:  100
+         read_iops_sec_max: 100
+         size_iops_sec: 100
+         write_bytes_sec: 100
+         write_bytes_sec_max: 100
+         write_iops_sec: 100
+         write_iops_sec_max: 100
+         total_bytes_sec: 0
+         total_iops_sec: 0
+         total_bytes_sec_max: 0
+         total_iops_sec_max: 0
+       verify_ssl: false
+
+    delegate_to: localhost

examples/decort_disk/disk_rename.yaml

@@ -0,0 +1,15 @@
+---
+- hosts: localhost
+  tasks:
+  - name: manage data disk 01
+    decort_disk:
+       authenticator: oauth2
+       app_id: #Application id from SSO DigitalEnergy
+       app_secret: #Application secret from SSO DigitalEnergy
+       controller_url: "https://cloud.digitalenergy.online"
+       account_name: "account_name"
+       id: 111
+       name: "example_disk2"
+       verify_ssl: false
+
+    delegate_to: localhost

examples/decort_disk/disk_restore.yaml

@@ -0,0 +1,15 @@
+---
+- hosts: localhost
+  tasks:
+  - name: manage data disk 01
+    decort_disk:
+       authenticator: oauth2
+       app_id: #Application id from SSO DigitalEnergy
+       app_secret: #Application secret from SSO DigitalEnergy
+       controller_url: "https://cloud.digitalenergy.online"
+       account_name: "account_name"
+       id: 111
+       state: present
+       verify_ssl: false
+
+    delegate_to: localhost

examples/decort_osimage/create-osimage.yaml

@@ -0,0 +1,27 @@
+---
+#
+# DECORT osimage module example
+#
+- hosts: localhost
+  tasks:
+  - name: create 
+    decort_osimage:
+      authenticator: oauth2
+      verify_ssl: False
+      controller_url: "https://ds1.digitalenergy.online"
+      state: present
+      image_name: "alpine_linux3.14.0"
+      account_Id: 12345
+      url: "https://dl-cdn.alpinelinux.org/alpine/v3.14/releases/x86_64/alpine-virt-3.14.0-x86_64.iso"
+      boottype: "uefi"
+      imagetype: "linux"
+      hotresize: False
+      image_username: "test"
+      image_password: "p@ssword"
+      usernameDL: "testDL"
+      passwordDL: "p@sswordDL"
+      architecture: "X86_64"
+      drivers: "KVM_X86"
+
+    delegate_to: localhost
+    register: simple_vm

examples/decort_osimage/create-virtual-osimage.yaml

@@ -0,0 +1,15 @@
+---
+#
+# DECORT osimage module example
+#
+- hosts: localhost
+  tasks:
+  - name: create_virtual_osimage 
+    decort_osimage:
+      authenticator: oauth2
+      controller_url: "https://ds1.digitalenergy.online"
+      image_name: "alpine_linux_3.14.0"
+      virt_name: "alpine_last"
+    delegate_to: localhost
+    register: osimage
+

examples/decort_osimage/get-osimage.yaml

@@ -0,0 +1,14 @@
+---
+#
+# DECORT osimage module example
+#
+- hosts: localhost
+  tasks:
+  - name: get_osimage 
+    decort_osimage:
+      authenticator: oauth2
+      controller_url: "https://ds1.digitalenergy.online"
+      image_name: "alpine_linux_3.14.0"
+      account_Id: 79349
+    delegate_to: localhost
+    register: simple_vm

examples/decort_osimage/rename-osimage.yaml

@@ -0,0 +1,15 @@
+---
+#
+# DECORT osimage module example
+#
+- hosts: localhost
+  tasks:
+  - name: rename_osimage 
+    decort_osimage:
+      authenticator: oauth2
+      controller_url: "https://ds1.digitalenergy.online"
+      image_name: "alpine_linux_3.14.0v2.0"
+      image_id: 54321
+    delegate_to: localhost
+    register: osimage
+

examples/decort_rg/changeLimits_rg.yaml

@@ -0,0 +1,20 @@
+- hosts: localhost
+  tasks:
+  - name: create
+    decort_rg:
+       authenticator: oauth2
+       controller_url: "https://cloud.digitalenergy.online"
+       rg_name: "rg_created_by_module"
+       # or
+       #rg_id: 999
+       account_id: 99
+       quotas:
+         cpu: 8
+         ram: 4096
+         disk: 20
+         ext_ips: 10
+         net_transfer: 200
+       state: present
+       verify_ssl: false
+    register: my_rg
+    delegate_to: localhost

examples/decort_rg/changeResTypes_rg.yaml

@@ -0,0 +1,21 @@
+- hosts: localhost
+  tasks:
+  - name: create
+    decort_rg:
+       authenticator: oauth2
+       controller_url: "https://cloud.digitalenergy.online"
+       rg_name: "rg_created_by_module"
+       # or
+       #rg_id: 999
+       account_id: 99
+       resType:
+         - vins
+         - compute
+         - k8s
+         - openshift
+         - lb
+         - flipgroup
+       state: present
+       verify_ssl: false
+    register: my_rg
+    delegate_to: localhost

examples/decort_rg/create_rg.yaml

@@ -0,0 +1,30 @@
+- hosts: localhost
+  tasks:
+  - name: create
+    decort_rg:
+       authenticator: oauth2
+       controller_url: "https://cloud.digitalenergy.online"
+       rg_name: "rg_created_by_module"
+       account_id: 99
+       owner: "user_1"  #Leave blank to set current user as owner. 
+       quotas:
+         cpu: 8
+         ram: 4096
+         disk: 20
+         ext_ips: 10
+         net_transfer: 200
+       access:
+         action: "grant"
+         user: "user_2"
+         right: "RCX"
+       def_netType: "PRIVATE"
+       ipcidr: ""                      "192.168.1.1"
+       extNetId: 0
+       extNetIp: ""                    "10.100.1.10"
+       resType: 
+       - vins 
+       - compute
+       state: present
+       verify_ssl: false
+    register: my_rg
+    delegate_to: localhost

examples/decort_rg/delete_rg.yaml

@@ -0,0 +1,15 @@
+- hosts: localhost
+  tasks:
+  - name: create
+    decort_rg:
+       authenticator: oauth2
+       controller_url: "https://cloud.digitalenergy.online"
+       rg_name: "test_rg"
+       # or
+       #rg_id: 999
+       account_id: 99
+       state: present
+       permanently: True
+       verify_ssl: false
+    register: my_rg
+    delegate_to: localhost

examples/decort_rg/disable_rg.yaml

@@ -0,0 +1,12 @@
+- hosts: localhost
+  tasks:
+  - name: create
+    decort_rg:
+       authenticator: oauth2
+       controller_url: "https://cloud.digitalenergy.online"
+       rg_id: 999         # rg can be restored only by rg id
+       account_id: 99
+       state: present
+       verify_ssl: false
+    register: my_rg
+    delegate_to: localhost

examples/decort_rg/enable_rg.yaml

@@ -0,0 +1,14 @@
+- hosts: localhost
+  tasks:
+  - name: create
+    decort_rg:
+       authenticator: oauth2
+       controller_url: "https://cloud.digitalenergy.online"
+       rg_name: "rg_created_by_module"
+       # or
+       #rg_id: 999
+       account_id: 99
+       state: enabled
+       verify_ssl: false
+    register: my_rg
+    delegate_to: localhost

examples/decort_rg/grantAccess_rg.yaml

@@ -0,0 +1,18 @@
+- hosts: localhost
+  tasks:
+  - name: create
+    decort_rg:
+       authenticator: oauth2
+       controller_url: "https://cloud.digitalenergy.online"
+       rg_name: "rg_created_by_module"
+       # or
+       #rg_id: 999
+       account_id: 99
+       access:
+         action: "grant"
+         user: "new_user"
+         right: "R"
+       state: present
+       verify_ssl: false
+    register: my_rg
+    delegate_to: localhost

examples/decort_rg/rename_rg.yaml

@@ -0,0 +1,15 @@
+- hosts: localhost
+  tasks:
+  - name: create
+    decort_rg:
+       authenticator: oauth2
+       controller_url: "https://cloud.digitalenergy.online"
+       rg_name: "old_rg_name"
+       # or
+       #rg_id: 1737
+       account_id: 99
+       rename: "new_rg_name"
+       state: present
+       verify_ssl: false
+    register: my_rg
+    delegate_to: localhost

examples/decort_rg/revokeAccess_rg.yaml

@@ -0,0 +1,17 @@
+- hosts: localhost
+  tasks:
+  - name: create
+    decort_rg:
+       authenticator: oauth2
+       controller_url: "https://cloud.digitalenergy.online"
+       rg_name: "rg_created_by_module"
+       # or
+       #rg_id: 999
+       account_id: 99
+       access:
+         action: "revoke"
+         user: "old_user"
+       state: present
+       verify_ssl: false
+    register: my_rg
+    delegate_to: localhost

examples/decort_rg/setDefNet_rg.yaml

@@ -0,0 +1,16 @@
+- hosts: localhost
+  tasks:
+  - name: create
+    decort_rg:
+       authenticator: oauth2
+       controller_url: "https://cloud.digitalenergy.online"
+       rg_name: "rg_created_by_module"
+       # or
+       #rg_id: 999
+       account_id: 99
+       def_netType: "PRIVATE"
+       def_netId: 199
+       state: present
+       verify_ssl: false
+    register: my_rg
+    delegate_to: localhost

examples/hashivault/hashivault_create_engine.yaml

@@ -0,0 +1,14 @@
+---
+#
+# This playbook create engine "test".
+#
+- hosts: localhost
+  tasks:
+    - hashivault_secret_engine:
+        url: "https://vault.domain.local"
+        authtype: ldap
+        username: "user"
+        password: "p@ssword"
+        state: present
+        name: test
+        backend: generic

examples/hashivault/hashivault_create_secret.yaml

@@ -0,0 +1,17 @@
+---
+#
+# This playbook create secret "secret" with data foo:foe. If secret "secret" exists - add data foo:foe.
+#
+- hosts: localhost
+  tasks:
+    - hashivault_secret:
+        url: "https://vault.domain.local"
+        authtype: ldap
+        username: "user"
+        password: "p@ssword"
+        mount_point: "kv"
+        state: present
+        permanent: true
+        secret: secret
+        data:
+            foo: foe

examples/hashivault/hashivault_example.yaml

@@ -0,0 +1,35 @@
+---
+
+- hosts: localhost
+  tasks:
+  - hashivault_read:
+      url: "https://vault.domain.local"
+      authtype: ldap
+      username: "user"
+      password: "p@ssword"
+      mount_point: kv
+      secret: secrets/myaccount
+      key: app_secret
+      version: 2
+    register: key
+
+  - name: create a VM using app_secret from hashicorp vault
+    decort_kvmvm:
+      annotation: "VM managed by decort_kvmvm module"
+      authenticator: oauth2
+      app_id: ""                                          # Application id from SSO Digital Energy
+      app_secret: "{{ key }}"                             # API key from SSO Digital Energy
+      controller_url: "https://cloud.digitalenergy.online" 
+      name: hashivault_read_example
+      cpu: 2
+      ram: 2048
+      boot_disk: 10
+      image_name: "DECS Ubuntu 18.04 v1.2.3"              #Name of OS image
+      networks:
+        - type: VINS
+          id: 99                                          #VINS id
+      tags: "Ansible hashivault_read example"
+      state: present
+      rg_id: 99                                           #Resource group id
+    delegate_to: localhost
+    register: simple_vm

examples/hashivault/hashivault_plugin_example.yaml

@@ -0,0 +1,31 @@
+- hosts: localhost
+  tasks:
+   - name: Read a kv2 secret with kv mount point
+     vars:
+       ansible_hashi_vault_auth_method: ldap
+       ansible_hashi_vault_username: username
+       ansible_hashi_vault_password: pwd
+       ansible_hashi_vault_engine_mount_point: kv
+     ansible.builtin.set_fact:
+       response: "{{ lookup('community.hashi_vault.vault_kv2_get', 'secret', url='https://vault.domain.local') }}"
+
+  - name: create a VM using app_secret from hashicorp vault 
+    decort_kvmvm:
+      annotation: "VM managed by decort_kvmvm module"
+      authenticator: oauth2
+      app_id: ""                                          # Application id from SSO Digital Energy
+      app_secret: "{{ response.data.password }}"          # API key from SSO Digital Energy
+      controller_url: "https://cloud.digitalenergy.online" 
+      name: hashivault_read_example
+      cpu: 2
+      ram: 2048
+      boot_disk: 10
+      image_name: "DECS Ubuntu 18.04 v1.2.3"              #Name of OS image
+      networks:
+        - type: VINS
+          id: 99                                          #VINS id
+      tags: "Ansible hashivault_read example"
+      state: present
+      rg_id: 99                                           #Resource group id
+    delegate_to: localhost
+    register: simple_vm

examples/hashivault/hashivault_plugin_login.yaml

@@ -0,0 +1,16 @@
+- hosts: localhost
+  tasks:
+   - name: Get auth token from vault
+     set_fact:
+       login_data: "{{ lookup('community.hashi_vault.vault_login', url='https://vault.domain.local', auth_method='ldap', username='username', password='pwd') }}"
+
+   - name: Perform multiple kv2 reads with a single Vault login, showing the secrets
+     vars:
+       ansible_hashi_vault_auth_method: token
+       ansible_hashi_vault_token: '{{ login_data | community.hashi_vault.vault_login_token }}'
+       ansible_hashi_vault_engine_mount_point: kv
+       paths:
+         - secret
+         - secret2
+     ansible.builtin.debug:
+       msg: "{{ lookup('community.hashi_vault.vault_kv2_get', *paths, auth_method='token', url='https://vault.domain.local') }}"

examples/hashivault/hashivault_plugin_read_secret.yaml

@@ -0,0 +1,18 @@
+- hosts: localhost
+  tasks:
+   - name: Read a kv2 secret with the default mount point
+     vars:
+       ansible_hashi_vault_auth_method: ldap
+       ansible_hashi_vault_username: username
+       ansible_hashi_vault_password: pwd
+       ansible_hashi_vault_engine_mount_point: kv
+     ansible.builtin.set_fact:
+       response: "{{ lookup('community.hashi_vault.vault_kv2_get', 'secret', url='https://vault.domain.local') }}"
+
+   - name: Display the results
+     ansible.builtin.debug:
+       msg:
+         - "Secret: {{ response.secret }}"
+         - "Data: {{ response.data }} (contains secret data & metadata in kv2)"
+         - "Metadata: {{ response.metadata }}"
+         - "Full response: {{ response.raw }}"

examples/hashivault/hashivault_read_secret.yaml

@@ -0,0 +1,13 @@
+---
+- hosts: localhost
+  tasks:
+    - hashivault_read:
+        url: "https://vault.domain.local"
+        authtype: ldap
+        username: "uset"
+        password: "p@ssword"
+        mount_point: kv
+        secret: secret
+        key: foo
+        version: 2
+      register: key

examples/kubernetes.yaml

@@ -0,0 +1,39 @@
+---
+#
+# DECORT k8s module example
+#
+- hosts: ansible_master
+  tasks:
+  - name: obtain JWT
+    decort_jwt:
+      oauth2_url: "https://sso.digitalenergy.online"
+      validity: 1200
+      verify_ssl: false
+    register: token
+    delegate_to: localhost
+
+  - name: create a VM named cluster-test
+    decort_k8s:
+      state: present
+      started: True
+      getConfig: True
+      authenticator: jwt
+      jwt: "{{ token.jwt }}"
+      controller_url: "https://ds1.digitalenergy.online"
+      name: "cluster-test"
+      rg_id:  125
+      k8ci_id: 18
+      workers:
+        - name: wg1
+          ram: 1024
+          cpu: 10
+          disk: 10
+          num: 1
+        - name: wg2
+          ram: 1024
+          cpu: 10
+          disk: 10
+          num: 2
+      verify_ssl: false
+    delegate_to: localhost
+    register: kube

examples/vins_connect.yaml

@@ -0,0 +1,42 @@
+---
+#
+# DECORT vins module example
+#
+
+- hosts: localhost
+  tasks:
+  - name: obtain JWT
+    decort_jwt:
+      oauth2_url: "https://sso.digitalenergy.online"
+      validity: 1200
+    register: my_jwt
+    delegate_to: localhost
+
+  - name: print out JWT
+    debug:
+      var: my_jwt.jwt
+    delegate_to: localhost
+
+  - name: Manage ViNS at resource group level
+    decort_vins:
+      authenticator: jwt
+      jwt: "{{ my_jwt.jwt }}"
+      controller_url: "https://cloud.digitalenergy.online"
+      vins_name: "vins_connected_by_decort_vins_module"
+      state: present
+      rg_id: 98
+      connect_to:
+       - type: VINS
+         id: 864
+         ipaddr: 192.168.5.66
+         netmask: 24
+       - type: VINS
+         id: 196
+         ipaddr: 192.168.9.133
+         netmask: 24
+    register: managed_vins
+
+  - name: print VINS facter
+    debug:
+      msg: "{{managed_vins.facts.password}}"
+    when: managed_vins.facts.password is defined

library/decort_bservice.py

@@ -0,0 +1,289 @@
+#!/usr/bin/python
+#
+# Digital Enegry Cloud Orchestration Technology (DECORT) modules for Ansible
+# Copyright: (c) 2018-2021 Digital Energy Cloud Solutions LLC
+#
+# Apache License 2.0 (see http://www.apache.org/licenses/LICENSE-2.0.txt)
+#
+
+#
+# Author: Alexey Dankov (alexey Dankov@digitalenergy.online)
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.basic import env_fallback
+from ansible.module_utils.decort_utils import *
+
+class decort_bservice(DecortController):
+    def __init__(self,arg_amodule):
+        super(decort_bservice, self).__init__(arg_amodule)
+
+        validated_acc_id = 0
+        validated_rg_id = 0
+        validated_rg_facts = None
+        self.bservice_info = None
+        if arg_amodule.params['name'] == "" and arg_amodule.params['id'] == 0:
+            self.result['failed'] = True
+            self.result['changed'] = False
+            self.result['msg'] = "Cannot manage Basic Services when its ID is 0 and name is empty."
+            self.fail_json(**self.result)
+        if not arg_amodule.params['id']:
+            if not arg_amodule.params['rg_id']: # RG ID is not set -> locate RG by name -> need account ID
+                validated_acc_id, _ = self.account_find(arg_amodule.params['account_name'],
+                                                        arg_amodule.params['account_id'])
+                if not validated_acc_id:
+                    self.result['failed'] = True
+                    self.result['changed'] = False
+                    self.result['msg'] = ("Current user does not have access to the account ID {} / "
+                                          "name '{}' or non-existent account specified.").format(arg_amodule.params['account_id'],
+                                                                                                 arg_amodule.params['account_name'])
+                    self.fail_json(**self.result)
+                    # fail the module -> exit
+            # now validate RG
+            validated_rg_id, validated_rg_facts = self.rg_find(validated_acc_id,
+                                                               arg_amodule.params['rg_id'],)
+            if not validated_rg_id:
+                self.result['failed'] = True
+                self.result['changed'] = False
+                self.result['msg'] = "Cannot find RG ID {} / name '{}'.".format(arg_amodule.params['rg_id'],
+                                                                                arg_amodule.params['rg_name'])
+                self.fail_json(**self.result)
+        
+        arg_amodule.params['rg_id'] = validated_rg_id
+        arg_amodule.params['rg_name'] = validated_rg_facts['name']
+        self.acc_id = validated_rg_facts['accountId']
+        
+        self.bservice_id,self.bservice_info = self.bservice_find(
+            self.acc_id,
+            validated_rg_id,
+            arg_amodule.params['name'],
+            arg_amodule.params['id']
+        )
+
+        if self.bservice_id == 0:
+            self.bservice_should_exist = False
+        else:
+            self.bservice_should_exist = True
+
+    def nop(self):
+        """No operation (NOP) handler for B-service.
+        This function is intended to be called from the main switch construct of the module
+        when current state -> desired state change logic does not require any changes to
+        the actual Compute state.
+        """
+        self.result['failed'] = False
+        self.result['changed'] = False
+        if self.k8s_id:
+            self.result['msg'] = ("No state change required for B-service ID {} because of its "
+                                   "current status '{}'.").format(self.bservice_id, self.bservice_info['status'])
+        else:
+            self.result['msg'] = ("No state change to '{}' can be done for "
+                                  "non-existent B-service instance.").format(self.amodule.params['state'])
+        return                         
+
+    def error(self):
+        self.result['failed'] = True
+        self.result['changed'] = False
+        if self.bservice_id:
+            self.result['msg'] = ("Invalid target state '{}' requested for B-service ID {} in the "
+                                   "current status '{}'.").format(self.bservice_id,
+                                                                  self.amodule.params['state'],
+                                                                  self.bservice_info['status'])
+        else:
+            self.result['msg'] = ("Invalid target state '{}' requested for non-existent B-service name '{}' "
+                                   "in RG ID {} / name '{}'").format(self.amodule.params['state'],
+                                                                    self.amodule.params['name'],
+                                                                    self.amodule.params['rg_id'],
+                                                                    self.amodule.params['rg_name'])
+        return
+
+    def create(self):
+        self.bservice_id = self.bservice_id = self.bservice_provision(
+            self.amodule.params['name'],
+            self.amodule.params['rg_id'],
+            self.amodule.params['sshuser'],
+            self.amodule.params['sshkey']
+        )
+        if self.bservice_id:
+            _, self.bservice_info = self.bservice_get_by_id(self.bservice_id)
+        self.bservice_state(self.bservice_info,'enabled',self.amodule.params['started'])
+        return
+
+    def action(self,d_state,started=False):
+        self.bservice_state(self.bservice_info,d_state,started)
+        return
+
+    def restore(self):
+
+        self.result['failed'] = True
+        self.result['msg'] = "Restore B-Service ID {} manualy.".format(self.bservice_id)
+        pass
+
+    def destroy(self):
+        self.bservice_delete(self.bservice_id)
+        self.bservice_info['status'] = 'DELETED'
+        self.bservice_should_exist = False
+        return
+
+    def package_facts(self,check_mode=False):
+        
+        ret_dict = dict(
+            name="",
+            state="CHECK_MODE",
+            account_id=0,
+            rg_id=0,
+            config=None,
+        )
+
+        if check_mode:
+            # in check mode return immediately with the default values
+            return ret_dict
+
+        ret_dict['id'] = self.bservice_info['id']
+        ret_dict['name'] = self.bservice_info['name']
+        ret_dict['techStatus'] = self.bservice_info['techStatus']
+        ret_dict['state'] = self.bservice_info['status']
+        ret_dict['rg_id'] = self.bservice_info['rgId']
+        ret_dict['account_id'] = self.acc_id
+        ret_dict['groupsName'] = self.bservice_info['groupsName']
+        ret_dict['groupsIds'] = self.bservice_info['groups']
+        return ret_dict
+    @staticmethod
+    def build_parameters():
+        return dict(
+            account_id=dict(type='int', required=False),
+            account_name=dict(type='str', required=False, default=''),
+            annotation=dict(type='str', required=False, default=''),
+            app_id=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_APP_ID'])),
+            app_secret=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_APP_SECRET']),
+                            no_log=True),
+            authenticator=dict(type='str',
+                            required=True,
+                            choices=['legacy', 'oauth2', 'jwt']),
+            controller_url=dict(type='str', required=True),
+            jwt=dict(type='str',
+                    required=False,
+                    fallback=(env_fallback, ['DECORT_JWT']),
+                    no_log=True),
+            oauth2_url=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_OAUTH2_URL'])),
+            password=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_PASSWORD']),
+                        no_log=True),
+            state=dict(type='str',
+                    default='present',
+                    choices=['absent', 'disabled', 'enabled', 'present','check']),
+            started=dict(type='bool', required=False, default=True),
+            user=dict(type='str',
+                    required=False,
+                    fallback=(env_fallback, ['DECORT_USER'])),
+            name=dict(type='str', required=True),
+            sshuser=dict(type='str', required=False,default=None),
+            sshkey=dict(type='str', required=False,default=None),
+            id=dict(type='int', required=False, default=0),
+            rg_id=dict(type='int', default=0),
+            rg_name=dict(type='str',default=""),
+            description=dict(type='str', default="Created by decort ansible module"),
+            verify_ssl=dict(type='bool', required=False, default=True),
+            workflow_callback=dict(type='str', required=False),
+            workflow_context=dict(type='str', required=False),)
+def main():
+    module_parameters = decort_bservice.build_parameters()
+
+    amodule = AnsibleModule(argument_spec=module_parameters,
+                            supports_check_mode=True,
+                            mutually_exclusive=[
+                                ['oauth2', 'password'],
+                                ['password', 'jwt'],
+                                ['jwt', 'oauth2'],
+                            ],
+                            required_together=[
+                                ['app_id', 'app_secret'],
+                                ['user', 'password'],
+                            ],
+                            required_one_of=[
+                                ['id', 'name'],
+                                ['rg_id','rg_name']
+                            ],
+                            )
+
+    subj = decort_bservice(amodule)
+    
+    if amodule.params['state'] == 'check':
+        subj.result['changed'] = False
+        if subj.bservice_id:
+            subj.result['failed'] = False
+            subj.result['facts'] = subj.package_facts(amodule.check_mode)
+            amodule.exit_json(**subj.result)
+            # we exit the module at this point
+        else:
+            subj.result['failed'] = True
+            subj.result['msg'] = ("Cannot locate B-service name '{}'. Other arguments are: B-service ID {}, "
+                                  "RG name '{}', RG ID {}, Account '{}'.").format(amodule.params['name'],
+                                                                                amodule.params['id'],
+                                                                                amodule.params['rg_name'],
+                                                                                amodule.params['rg_id'],
+                                                                                amodule.params['account_name'])
+            amodule.fail_json(**subj.result)
+            pass
+    
+    
+    #MAIN MANAGE PART
+
+    if subj.bservice_id:
+        if subj.bservice_info['status'] in ("DELETING","DESTROYNG","RECONFIGURING","DESTROYING",
+                                         "ENABLING","DISABLING","RESTORING","MODELED"):
+            subj.error()
+        elif subj.bservice_info['status'] == "DELETED":
+            if amodule.params['state'] in ('disabled', 'enabled', 'present'):
+                subj.restore(subj.bservice_id)
+                subj.action(amodule.params['state'],amodule.params['started'])
+            if amodule.params['state'] == 'absent':
+                subj.nop()
+        elif subj.bservice_info['techStatus'] in ("STARTED","STOPPED"):
+            if amodule.params['state'] == 'disabled':
+                subj.action(amodule.params['state'],amodule.params['started'])
+            elif amodule.params['state'] == 'absent':
+                subj.destroy()
+            else:
+                subj.action(amodule.params['state'],amodule.params['started'])
+        elif subj.bservice_info['status'] == "DISABLED":
+            if amodule.params['state'] == 'absent':
+                subj.destroy()
+            elif amodule.params['state'] in ('present','enabled'):
+                subj.action(amodule.params['state'],amodule.params['started'])
+            else:
+                subj.nop()
+        elif subj.bservice_info['status'] == "DESTROED":
+            if amodule.params['state'] in ('present','enabled'):
+                subj.create()
+                subj.action(amodule.params['state'],amodule.params['started'])
+            if amodule.params['state'] == 'absent':    
+                subj.nop()
+    else:
+        if amodule.params['state'] == 'absent':
+            subj.nop()
+        if amodule.params['state'] in ('present','started'):
+            subj.create()
+        elif amodule.params['state'] in ('stopped', 'disabled','enabled'):
+            subj.error()
+    
+    if subj.result['failed']:
+        amodule.fail_json(**subj.result)
+    else:
+        if subj.bservice_should_exist:
+            subj.result['facts'] = subj.package_facts(amodule.check_mode)
+            amodule.exit_json(**subj.result)
+        else:
+            amodule.exit_json(**subj.result)
+if __name__ == "__main__":
+    main()

library/decort_disk.py

@@ -0,0 +1,542 @@
+#!/usr/bin/python
+#
+# Digital Enegry Cloud Orchestration Technology (DECORT) modules for Ansible
+# Copyright: (c) 2018-2021 Digital Energy Cloud Solutions LLC
+#
+# Apache License 2.0 (see http://www.apache.org/licenses/LICENSE-2.0.txt)
+#
+
+#
+# Author: Sergey Shubin (sergey.shubin@digitalenergy.online)
+#
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+DOCUMENTATION = '''
+---
+module: decort_disk
+short_description: Manage Disks (virtualized storage resources) in DECORT cloud
+description: >
+     This module can be used to create new disk in DECORT cloud platform, obtain or 
+     modify its characteristics, and delete it.
+version_added: "2.2"
+author:
+     - Sergey Shubin <sergey.shubin@digitalenergy.online>
+requirements:
+     - python >= 2.6
+     - PyJWT Python module
+     - requests Python module
+     - netaddr Python module
+     - decort_utils utility library (module)
+     - DECORT cloud platform version 3.6.1 or higher
+notes:
+     - Environment variables can be used to pass selected parameters to the module, see details below.
+     - Specified Oauth2 provider must be trusted by the DECORT cloud controller on which JWT will be used.
+     - 'Similarly, JWT supplied in I(authenticator=jwt) mode should be received from Oauth2 provider trusted by
+       the DECORT cloud controller on which this JWT will be used.'
+options:
+    account_id:
+        description:
+        - ID of the account, which owns this disk. This is the alternative to I(account_name) option.
+        - If both I(account_id) and I(account_name) specified, then I(account_name) is ignored.
+        default: 0
+        required: no
+    account_name:
+        description:
+        - 'Name of the account, which will own this disk.'
+        - 'This parameter is ignored if I(account_id) is specified.'
+        default: empty string
+        required: no
+    annotation:
+        description:
+        - Optional text description of this disk.
+        default: empty string
+        required: no
+    app_id:
+        description:
+        - 'Application ID for authenticating to the DECORT controller when I(authenticator=oauth2).'
+        - 'Required if I(authenticator=oauth2).'
+        - 'If not found in the playbook or command line arguments, the value will be taken from DECORT_APP_ID
+           environment variable.'
+        required: no
+    app_secret:
+        description:
+        - 'Application API secret used for authenticating to the DECORT controller when I(authenticator=oauth2).'
+        - This parameter is required when I(authenticator=oauth2) and ignored in other modes.
+        - 'If not found in the playbook or command line arguments, the value will be taken from DECORT_APP_SECRET
+           environment variable.'
+        required: no
+    authenticator:
+        description:
+        - Authentication mechanism to be used when accessing DECORT controller and authorizing API call.
+        default: jwt
+        choices: [ jwt, oauth2, legacy ]
+        required: yes
+    controller_url:
+        description:
+        - URL of the DECORT controller that will be contacted to manage the RG according to the specification.
+        - 'This parameter is always required regardless of the specified I(authenticator) type.'
+        required: yes
+    id:
+        description:
+        - `ID of the disk to manage. If I(id) is specified it is assumed, that this disk already
+          exists. In other words, you cannot create new disk by specifying its ID, use I(name)
+          when creating new disk.`
+        - `If non-zero I(id) is specified, then I(name), I(account_id) and I(account_name) 
+          are ignored.`
+        default: 0
+        required: no
+    name:
+        description:
+        - `Name of the disk to manage. To manage disk by name you also need to specify either
+          I(account_id) or I(account_name).`
+        - If non-zero I(id) is specified, I(name) is ignored.
+        - `Note that the platform does not enforce uniqueness of disk names, so if more than one
+          disk with this name exists under the specified account, module will return the first
+          occurence.`
+        default: empty string
+        required: no
+    force_detach:
+        description:
+        - `By default it is not allowed to delete or destroy disk that is currently attached to a compute
+          instance (e.g. virtual machine or bare metal server). Set this argument to true to change this
+          behavior.`
+        - This argument is meaningful for I(state=absent) operations only and ignored otherwise.
+        default: false
+        required: no
+    jwt:
+        description:
+        - 'JWT (access token) for authenticating to the DECORT controller when I(authenticator=jwt).'
+        - 'This parameter is required if I(authenticator=jwt) and ignored for other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_JWT environment variable.
+        required: no
+    oauth2_url:
+        description:
+        - 'URL of the oauth2 authentication provider to use when I(authenticator=oauth2).'
+        - 'This parameter is required when when I(authenticator=oauth2).'
+        - 'If not specified in the playbook, the value will be taken from DECORT_OAUTH2_URL environment variable.'
+    password:
+        description:
+        - 'Password for authenticating to the DECORT controller when I(authenticator=legacy).'
+        - 'This parameter is required if I(authenticator=legacy) and ignored in other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_PASSWORD environment variable.
+        required: no
+    place_with:
+        description:
+        - `This argument can be used to simplify data disks creation along with a new compute, by placing
+          disks in the same storage, where corresponding OS image is deployed.`
+        - `Specify ID of an OS image, and the newly created disk will be provisioned from the same
+          storage, where this OS image is located. You may optionally specify I(pool) to control
+          actual disk placement within that storage, or leave I(pool=default) to let platform manage
+          it automatically.`
+        - This parameter is used when creating new disks and ignored for all other operations.
+        - This is an alternative to specifying I(sep_id).
+        default: 0
+        required: no
+    pool:
+        description:
+        - Name of the pool where to place new disk. Once disk is created, its pool cannot be changed.
+        - This parameter is used when creating new disk and igonred for all other operations.
+        default: empty string
+        required: no
+    sep_id:
+        description:
+        - `ID of the Storage Endpoint Provider (SEP) where to place new disk. Once disk is created, 
+          its SEP cannot be changed.`
+        - `You may think of SEP as an identifier of a storage system connected to DECORT platform. There
+          may be several different storage systems and, consequently, several SEPs available to choose from.`
+        - This parameter is used when creating new disk and igonred for all other operations.
+        - See also I(place_with) for an alternative way to specify disk placement.
+        default: 0
+        required: no
+    size:
+        description:
+        - Size of the disk in GB. This parameter is mandatory when creating new disk.
+        - `If specified for an existing disk, and it is greater than current disk size, platform will try to resize
+          the disk on the fly. Downsizing disk is not allowed.`
+        required: no
+    limitIO:
+        description:
+        - Disk input / output limit, used to limit the speed of interaction with the disk.
+        required: no
+    type:
+        description:
+        - Type of the disk. 
+        - `Disks can be of the following types: "D"-Data, "B"-Boot, "T"-Tmp.`
+        default: "D"
+        required: no
+    state:
+        description:
+        - Specify the desired state of the disk at the exit of the module.
+        - 'If desired I(state=present):'
+        - ' - Disk does not exist or is in [DESTROYED, PURGED] states, create new disk according to the specifications.'
+        - ' - Disk is in DELETED state, restore it and change size if necessary.'
+        - ' - Disk is in one of [CREATED, ASSIGNED] states, do nothing.'
+        - ' - Disk in any other state, abort with an error.'
+        - 'If desired I(state=absent):'
+        - ' - Disk is in one of [CREATED, ASSIGNED, DELETED] states, destroy it.'
+        - ' - Disk not found or in [DESTROYED, PURGED] states, do nothing.' 
+        - ' - Disk in any other state, abort with an error.'
+        default: present
+        choices: [ absent, present ]
+    user:
+        description:
+        - 'Name of the legacy user for authenticating to the DECORT controller when I(authenticator=legacy).'
+        - 'This parameter is required when I(authenticator=legacy) and ignored for other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_USER environment variable.
+        required: no
+    verify_ssl:
+        description:
+        - 'Controls SSL verification mode when making API calls to DECORT controller. Set it to False if you
+         want to disable SSL certificate verification. Intended use case is when you run module in a trusted
+         environment that uses self-signed certificates. Note that disabling SSL verification in any other
+         scenario can lead to security issues, so please know what you are doing.'
+        default: True
+        required: no
+    workflow_callback:
+        description:
+        - 'Callback URL that represents an application, which invokes this module (e.g. up-level orchestrator or
+          end-user portal) and may except out-of-band updates on progress / exit status of the module run.'
+        - API call at this URL will be used to relay such information to the application.
+        - 'API call payload will include module-specific details about this module run and I(workflow_context).'
+        required: no
+    workflow_context:
+        description:
+        - 'Context data that will be included into the payload of the API call directed at I(workflow_callback) URL.'
+        - 'This context data is expected to uniquely identify the task carried out by this module invocation so
+           that up-level orchestrator could match returned information to the its internal entities.'
+        required: no
+'''
+
+EXAMPLES = '''
+- name: create new Disk named "MyDataDisk01" of size 50 GB, on SEP ID 1, in default pool, under the account "MyAccount".
+    decort_vins:
+      authenticator: oauth2
+      app_id: "{{ MY_APP_ID }}"
+      app_secret: "{{ MY_APP_SECRET }}"
+      controller_url: "https://cloud.digitalenergy.online"
+      name: "MyDataDisk01"
+      sep_id: 1
+      size: 50
+      account_name: "MyAccount"
+      state: present
+    delegate_to: localhost
+    register: my_disk
+'''
+
+RETURN = '''
+facts:
+    description: facts about the disk
+    returned: always
+    type: dict
+    sample:
+      facts:
+        id: 50
+        name: data01
+        size: 10
+        sep_id: 1
+        pool: datastore
+        state: ASSIGNED
+        account_id: 7
+        attached_to: 18
+        gid: 1001
+'''
+
+
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.basic import env_fallback
+
+from ansible.module_utils.decort_utils import *
+
+class decort_disk(DecortController):
+    def __init__(self,arg_amodule):
+        super(decort_disk, self).__init__(arg_amodule)
+
+        validated_acc_id = 0
+        validated_acc_info = None
+        validated_disk_id = 0
+        self.disk_id = 0
+        self.account_id = 0
+        validated_disk_facts = None
+        # limitIO check for exclusive parameters
+        
+        if arg_amodule.params['limitIO']:
+            self.disk_check_iotune_arg(arg_amodule.params['limitIO'])
+
+
+        if arg_amodule.params['id'] or arg_amodule.params['name']:
+            if arg_amodule.params['account_id'] or arg_amodule.params['account_name'] :
+                validated_acc_id,validated_acc_info  = self.account_find(arg_amodule.params['account_name'],arg_amodule.params['account_id'])
+            if not validated_acc_id:
+                    self.result['failed'] = True
+                    self.result['changed'] = False
+                    self.result['msg'] = ("Current user does not have access to the account ID {} / "
+                                          "name '{}' or non-existent account specified.").format(arg_amodule.params['account_id'],
+                                                                                                 arg_amodule.params['account_name'])
+                    self.fail_json(**self.result)
+            else:
+                self.acc_id = validated_acc_id
+                self.acc_info = validated_acc_info
+            validated_disk_id,validated_disk_facts = self.disk_find(
+                            disk_id=arg_amodule.params['id'],
+                            name=arg_amodule.params['name'] if "name" in arg_amodule.params else "",
+                            account_id=self.acc_id,
+                            check_state=False,
+                )
+        else:
+            self.result['failed'] = True
+            self.result['msg'] = ("Cannot manage Disk when its ID is 0 and name is empty")
+            self.fail_json(**self.result)
+
+        if arg_amodule.params['place_with']:
+            image_id, image_facts = self.image_find(arg_amodule.params['place_with'], "", 0)
+            arg_amodule.params['sep_id'] = image_facts['sepId']
+
+        self.disk_id = validated_disk_id
+        self.disk_info = validated_disk_facts
+
+    def create(self):
+        
+        self.disk_id = self.disk_create(accountId=self.acc_id,
+                                        name = self.amodule.params['name'],
+                                        description=self.amodule.params['annotation'],
+                                        size=self.amodule.params['size'],
+                                        type=self.amodule.params['type'],
+                                        iops=self.amodule.params['iops'],
+                                        sep_id=self.amodule.params['sep_id'],
+                                        pool=self.amodule.params['pool'],
+        )
+        #IO tune
+        if self.amodule.params['limitIO']:
+            self.disk_limitIO(self.amodule.params['limitIO'],self.disk_id)
+        #set share status
+        if self.amodule.params['shareable'] and self.amodule.params['type'] == "D":
+            self.dick_share(self.disk_id,self.amodule.params['shareable'])
+        return
+
+    def action(self,restore=False):
+        
+        #restore never be done
+        if restore:
+            self.disk_restore(self.disk_id)
+        #rename if id present
+        if self.amodule.params['name'] != self.disk_info['name']:
+            self.disk_rename(diskId=self.disk_id,
+                            name=self.amodule.params['name'])
+        self.disk_info['name'] = self.amodule.params['name']
+        #resize
+        if self.amodule.params['size'] != self.disk_info['sizeMax']:
+            self.disk_resize(self.disk_info,self.amodule.params['size'])
+        #IO TUNE
+        if self.amodule.params['limitIO']:
+            clean_io = [param for param in self.amodule.params['limitIO'] \
+                        if self.amodule.params['limitIO'][param]  == None]
+            for key in clean_io: del self.amodule.params['limitIO'][key]
+            if self.amodule.params['limitIO'] != self.disk_info['iotune']:
+                self.disk_limitIO(self.disk_id,self.amodule.params['limitIO'])
+        #share check/update
+        #raise Exception(self.amodule.params['shareable'])
+        if  self.amodule.params['shareable'] != self.disk_info['shareable'] and \
+            self.amodule.params['type'] == "D":
+            self.disk_share(self.disk_id,self.amodule.params['shareable'])
+        return
+    
+    def delete(self):
+        self.disk_id = self.disk_delete(disk_id=self.disk_id,
+                                        detach=self.amodule.params['force_detach'],
+                                        permanently=self.amodule.params['permanently'],
+                                        reason=self.amodule.params['reason'])
+        self.disk_info['status'] = "DELETED"
+        return
+    
+    def rename(self):
+        
+        
+        self.disk_rename(diskId = self.disk_id,
+                        name = self.amodule.params['name'])
+        self.disk_info['name'] = self.amodule.params['name']
+        return
+
+    def nop(self):
+
+        self.result['failed'] = False
+        self.result['changed'] = False
+        if self.disk_id:
+            self.result['msg'] = ("No state change required for Disk ID {} because of its "
+                                   "current status '{}'.").format(self.disk_id, self.disk_info['status'])
+        else:
+            self.result['msg'] = ("No state change to '{}' can be done for "
+                                  "non-existent Disk.").format(self.amodule.params['state'])
+        return 
+
+    def package_facts(self, check_mode=False):
+        ret_dict = dict(id=0,
+                        name="none",
+                        state="CHECK_MODE",
+                        size=0,
+                        account_id=0,
+                        sep_id=0,
+                        pool="none",
+                        attached_to=0,
+                        gid=0
+                        )
+
+        if check_mode or self.disk_info is None:
+            return ret_dict
+
+        # remove io param with zero value
+        clean_io = [param for param in self.disk_info['iotune'] if self.disk_info['iotune'][param]  == 0]
+        for key in clean_io: del self.disk_info['iotune'][key]
+        
+        ret_dict['id'] = self.disk_info['id']
+        ret_dict['name'] = self.disk_info['name']
+        ret_dict['size'] = self.disk_info['sizeMax']
+        ret_dict['state'] = self.disk_info['status']
+        ret_dict['account_id'] = self.disk_info['accountId']
+        ret_dict['sep_id'] = self.disk_info['sepId']
+        ret_dict['pool'] = self.disk_info['pool']
+        ret_dict['attached_to'] = self.disk_info['vmid']
+        ret_dict['gid'] = self.disk_info['gid']
+        ret_dict['iotune'] = self.disk_info['iotune']
+
+        return ret_dict
+    @staticmethod
+    def build_parameters():
+        """Build and return a dictionary of parameters expected by decort_disk module in a form accepted
+        by AnsibleModule utility class."""
+
+        return dict(
+            account_id=dict(type='int', required=False, default=0),
+            account_name=dict(type='str', required=False, default=''),
+            annotation=dict(type='str', required=False, default='Disk by decort_disk'),
+            app_id=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_APP_ID'])),
+            app_secret=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_APP_SECRET']),
+                            no_log=True),
+            authenticator=dict(type='str',
+                               required=True,
+                               choices=['legacy', 'oauth2', 'jwt']),
+            controller_url=dict(type='str', required=True),
+            id=dict(type='int', required=False, default=0),
+            name=dict(type='str', required=False),
+            force_detach=dict(type='bool', required=False, default=False),
+            jwt=dict(type='str',
+                     required=False,
+                     fallback=(env_fallback, ['DECORT_JWT']),
+                     no_log=True),
+            oauth2_url=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_OAUTH2_URL'])),
+            password=dict(type='str',
+                          required=False,
+                          fallback=(env_fallback, ['DECORT_PASSWORD']),
+                          no_log=True),
+            place_with=dict(type='int', default=0),
+            pool=dict(type='str', default=''),
+            sep_id=dict(type='int', default=0),
+            size=dict(type='int', default=0),
+            type=dict(type='str', 
+                      required=False, 
+                      default="D",
+                      choices=['B', 'D', 'T']),
+            iops=dict(type='int',required=False,default=2000),
+            limitIO=dict(type='dict',
+                options=dict(
+                    total_bytes_sec=dict(required=False,type='int'),
+                    read_bytes_sec=dict(required=False,type='int'),
+                    write_bytes_sec=dict(required=False,type='int'),
+                    total_iops_sec=dict(required=False,type='int'),
+                    read_iops_sec=dict(required=False,type='int'),
+                    write_iops_sec=dict(required=False,type='int'),
+                    total_bytes_sec_max=dict(required=False,type='int'),
+                    read_bytes_sec_max=dict(required=False,type='int'),
+                    write_bytes_sec_max=dict(required=False,type='int'),
+                    total_iops_sec_max=dict(required=False,type='int'),
+                    read_iops_sec_max=dict(required=False,type='int'),
+                    write_iops_sec_max=dict(required=False,type='int'),
+                    size_iops_sec=dict(required=False,type='int'),)),
+            permanently=dict(type='bool', required=False, default=False),
+            shareable=dict(type='bool', required=False, default=False),
+            reason=dict(type='str', required=False,default='Managed by Ansible decort_disk'),
+            state=dict(type='str',
+                       default='present',
+                       choices=['absent', 'present']),
+            user=dict(type='str',
+                      required=False,
+                      fallback=(env_fallback, ['DECORT_USER'])),
+            verify_ssl=dict(type='bool', required=False, default=True),
+            workflow_callback=dict(type='str', required=False),
+            workflow_context=dict(type='str', required=False),
+        )
+
+def main():
+    module_parameters = decort_disk.build_parameters()
+
+    amodule = AnsibleModule(argument_spec=module_parameters,
+                            supports_check_mode=True,
+                            mutually_exclusive=[
+                                ['oauth2', 'password'],
+                                ['password', 'jwt'],
+                                ['jwt', 'oauth2'],
+                            ],
+                            required_together=[
+                                ['app_id', 'app_secret'],
+                                ['user', 'password'],
+                            ],
+                            )
+
+    decon = decort_disk(amodule)
+    #
+    #Full range of Disk status is as follows:
+    #
+    # "ASSIGNED","MODELED", "CREATING","CREATED","DELETED", "DESTROYED","PURGED",
+    #
+    if decon.disk_id:
+        #disk exist
+        if decon.disk_info['status'] in ["MODELED", "CREATING"]:
+            decon.result['failed'] = True
+            decon.result['changed'] = False
+            decon.result['msg'] = ("No change can be done for existing Disk ID {} because of its current "
+                                   "status '{}'").format(decon.disk_id, decon.disk_info['status'])
+         # "ASSIGNED","CREATED","DELETED","PURGED", "DESTROYED"
+        elif decon.disk_info['status'] in ["ASSIGNED","CREATED"]:
+            if  amodule.params['state'] == 'absent':
+                decon.delete()
+            elif amodule.params['state'] == 'present':
+                decon.action()
+        elif decon.disk_info['status'] in ["PURGED", "DESTROYED"]:
+            #re-provision disk
+            if amodule.params['state'] in ('present'):
+                decon.create()
+            else:
+                decon.nop()
+        elif decon.disk_info['status'] == "DELETED":
+            if amodule.params['state'] in ('present'):
+                decon.action(restore=True)
+            else:
+                decon.nop()
+    else:
+        # preexisting Disk was not found
+        if amodule.params['state'] == 'absent':
+            decon.nop()
+        else:
+            decon.create()         
+    
+    if decon.result['failed']:
+        amodule.fail_json(**decon.result)
+    else:
+        if decon.result['changed'] and amodule.params['state'] in ('present'):
+            _, decon.disk_info = decon.disk_find(decon.disk_id)
+        decon.result['facts'] = decon.package_facts(amodule.check_mode)
+        amodule.exit_json(**decon.result)
+
+if __name__ == "__main__":
+    main()
+
+#SHARE

library/decort_group.py

@@ -0,0 +1,285 @@
+#!/usr/bin/python
+#
+# Digital Enegry Cloud Orchestration Technology (DECORT) modules for Ansible
+# Copyright: (c) 2018-2021 Digital Energy Cloud Solutions LLC
+#
+# Apache License 2.0 (see http://www.apache.org/licenses/LICENSE-2.0.txt)
+#
+
+#
+# Author: Alexey Dankov (alexey.dankov@digitalenergy.online)
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.basic import env_fallback
+from ansible.module_utils.decort_utils import *
+
+class decort_group(DecortController):
+    def __init__(self,arg_amodule):
+        super(decort_group, self).__init__(arg_amodule)
+        self.group_should_exist = False
+        validated_bservice_id = None
+        #find and validate B-Service
+
+        validated_bservice_id, bservice_info = self.bservice_get_by_id(arg_amodule.params['bservice_id'])
+        if not validated_bservice_id:
+            self.result['failed'] = True
+            self.result['changed'] = False
+            self.result['msg'] = ("Cannot find B-service ID {}.").format(arg_amodule.params['bservice_id'])
+            self.fail_json(**self.result)
+        #find group
+        self.bservice_id = validated_bservice_id
+        self.bservice_info = bservice_info
+        self.group_id,self.group_info = self.group_find(
+            bs_id=validated_bservice_id,
+            bs_info=bservice_info,
+            group_id=arg_amodule.params['id'],
+            group_name=arg_amodule.params['name'],
+            )
+
+        if self.group_id:
+            self.group_should_exist = True
+        
+        return
+    def nop(self):
+        """No operation (NOP) handler for B-service.
+        This function is intended to be called from the main switch construct of the module
+        when current state -> desired state change logic does not require any changes to
+        the actual Compute state.
+        """
+        self.result['failed'] = False
+        self.result['changed'] = False
+        if self.group_id:
+            self.result['msg'] = ("No state change required for B-service ID {} because of its "
+                                   "current status '{}'.").format(self.group_id, self.group_info['status'])
+        else:
+            self.result['msg'] = ("No state change to '{}' can be done for "
+                                  "non-existent B-service instance.").format(self.amodule.params['state'])
+        return                         
+
+    def error(self):
+        self.result['failed'] = True
+        self.result['changed'] = False
+        if self.group_id:
+            self.result['msg'] = ("Invalid target state '{}' requested for Group ID {} in the "
+                                   "current status '{}'.").format(self.group_id,
+                                                                  self.amodule.params['state'],
+                                                                  self.group_info['status'])
+        else:
+            self.result['msg'] = ("Invalid target state '{}' requested for non-existent Group name '{}' "
+                                   "in B-service {}").format(self.amodule.params['state'],
+                                                                    self.amodule.params['name'],
+                                                                    self.amodule.params['bservice_id'],
+                                )
+        return
+
+    def create(self):
+
+        if self.amodule.params['driver'] not in ["KVM_X86","KVM_PPC"]:
+            self.result['failed'] = True
+            self.result['msg'] = ("Unsupported driver '{}' is specified for "
+                                  "Group.").format(self.amodule.params['driver'])
+            self.amodule.fail_json(**self.result)
+
+        self.group_id=self.group_provision(
+           self.bservice_id,
+           self.amodule.params['name'],
+           self.amodule.params['count'],
+           self.amodule.params['cpu'],
+           self.amodule.params['ram'],
+           self.amodule.params['boot_disk'],
+           self.amodule.params['image_id'],
+           self.amodule.params['driver'],
+           self.amodule.params['role'],
+           self.amodule.params['networks'],
+           self.amodule.params['timeoutStart'], 
+        )
+        
+        if self.amodule.params['state'] in ('started','present'):
+            self.group_state(self.bservice_id,self.group_id,self.amodule.params['state'])
+        return
+
+    def action(self):
+        #change desired state
+        if (
+            self.group_info['techStatus'] == 'STARTED' and self.amodule.params['state'] == 'stopped') or (
+            self.group_info['techStatus'] == 'STOPPED' and self.amodule.params['state'] in ('started','present')
+            ):
+            self.group_state(self.bservice_id,self.group_id,self.amodule.params['state'])
+        self.group_resize_count(self.bservice_id,self.group_info,self.amodule.params['count'])
+        self.group_update_hw(
+            self.bservice_id,
+            self.group_info,
+            self.amodule.params['cpu'],
+            self.amodule.params['boot_disk'],
+            self.amodule.params['name'],
+            self.amodule.params['role'],
+            self.amodule.params['ram'],
+        )
+        self.group_update_net(
+            self.bservice_id,
+            self.group_info,
+            self.amodule.params['networks']
+        )
+        return
+
+    def destroy(self):
+
+        self.group_delete(
+            self.bservice_id,
+            self.group_id
+        )
+
+        return
+
+    def package_facts(self,check_mode=False):
+        
+        ret_dict = dict(
+            name="",
+            state="CHECK_MODE",
+            account_id=0,
+            rg_id=0,
+            config=None,
+        )
+
+        if check_mode:
+            # in check mode return immediately with the default values
+            return ret_dict
+        if self.result['changed'] == True:
+            self.group_id,self.group_info = self.group_find(
+                self.bservice_id,
+                self.bservice_info,
+                self.group_id
+            )
+
+        ret_dict['account_id'] = self.group_info['accountId']
+        ret_dict['rg_id'] = self.group_info['rgId']
+        ret_dict['id'] = self.group_info['id']
+        ret_dict['name'] = self.group_info['name']
+        ret_dict['techStatus'] = self.group_info['techStatus']
+        ret_dict['state'] = self.group_info['status']
+        ret_dict['Computes'] = self.group_info['computes']
+        return ret_dict
+    @staticmethod
+    def build_parameters():
+        return dict(
+            account_id=dict(type='int', required=False),
+            account_name=dict(type='str', required=False, default=''),
+            annotation=dict(type='str', required=False, default=''),
+            app_id=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_APP_ID'])),
+            app_secret=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_APP_SECRET']),
+                            no_log=True),
+            authenticator=dict(type='str',
+                            required=True,
+                            choices=['legacy', 'oauth2', 'jwt']),
+            controller_url=dict(type='str', required=True),
+            jwt=dict(type='str',
+                    required=False,
+                    fallback=(env_fallback, ['DECORT_JWT']),
+                    no_log=True),
+            oauth2_url=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_OAUTH2_URL'])),
+            password=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_PASSWORD']),
+                        no_log=True),
+            state=dict(type='str',
+                    default='present',
+                    choices=['absent', 'started', 'stopped', 'present','check']),
+            user=dict(type='str',
+                    required=False,
+                    fallback=(env_fallback, ['DECORT_USER'])),
+            name=dict(type='str', required=True),
+            id=dict(type='int', required=False, default=0),
+            image_id=dict(type='int', required=False),
+            image_name=dict(type='str', required=False),
+            driver=dict(type='str', required=False,default="KVM_X86"),
+            boot_disk=dict(type='int', required=False),
+            bservice_id=dict(type='int', required=True),
+            count=dict(type='int', required=True),
+            timeoutStart=dict(type='int', required=False),
+            role=dict(type='str', required=False),
+            cpu=dict(type='int', required=False),
+            ram=dict(type='int', required=False),
+            networks=dict(type='list', default=[], required=False),
+            description=dict(type='str', default="Created by decort ansible module"),
+            verify_ssl=dict(type='bool', required=False, default=True),
+            workflow_callback=dict(type='str', required=False),
+            workflow_context=dict(type='str', required=False),)
+def main():
+    module_parameters = decort_group.build_parameters()
+
+    amodule = AnsibleModule(argument_spec=module_parameters,
+                            supports_check_mode=True,
+                            mutually_exclusive=[
+                                ['oauth2', 'password'],
+                                ['password', 'jwt'],
+                                ['jwt', 'oauth2'],
+                            ],
+                            required_together=[
+                                ['app_id', 'app_secret'],
+                                ['user', 'password'],
+                            ],
+                            required_one_of=[
+                                ['id', 'name'],
+                            ],
+                            )
+
+    subj = decort_group(amodule)
+    
+    if amodule.params['state'] == 'check':
+        subj.result['changed'] = False
+        if subj.group_id:
+            # cluster is found - package facts and report success to Ansible
+            subj.result['failed'] = False
+            subj.result['facts'] = subj.package_facts(amodule.check_mode)
+            amodule.exit_json(**subj.result)
+            # we exit the module at this point
+        else:
+            subj.result['failed'] = True
+            subj.result['msg'] = ("Cannot locate Group name '{}'. "
+                                  "B-service ID {}").format(amodule.params['name'],
+                                                     amodule.params['bservice_id'],)
+            amodule.fail_json(**subj.result)       
+
+    if subj.group_id:
+        if subj.group_info['status'] in ("DELETING","DESTROYNG","CREATING","DESTROYING",
+                                         "ENABLING","DISABLING","RESTORING","MODELED",
+                                         "DISABLED","DESTROYED"):
+            subj.error()
+        elif subj.group_info['status'] in ("DELETED","DESTROYED"):
+            if amodule.params['state'] == 'absent':
+                subj.nop()
+            if amodule.params['state'] in ('present','started','stopped'):
+                subj.create()
+        elif subj.group_info['techStatus'] in ("STARTED","STOPPED"):
+            if amodule.params['state'] == 'absent':
+                subj.destroy()
+            else:
+                subj.action()
+
+    else:
+        if amodule.params['state'] == 'absent':
+            subj.nop()
+        if amodule.params['state'] in ('present','started','stopped'):
+            subj.create()
+    
+    if subj.result['failed']:
+        amodule.fail_json(**subj.result)
+    else:
+        if subj.group_should_exist:
+            subj.result['facts'] = subj.package_facts(amodule.check_mode)
+            amodule.exit_json(**subj.result)
+        else:
+            amodule.exit_json(**subj.result)
+
+if __name__ == "__main__":
+    main()

library/decort_jwt.py

@@ -0,0 +1,157 @@
+#!/usr/bin/python
+#
+# Digital Enegry Cloud Orchestration Technology (DECORT) modules for Ansible
+# Copyright: (c) 2018-2021 Digital Energy Cloud Solutions LLC
+#
+# Apache License 2.0 (see http://www.apache.org/licenses/LICENSE-2.0.txt)
+#
+
+#
+# Author: Sergey Shubin (sergey.shubin@digitalenergy.online)
+#
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+DOCUMENTATION = '''
+---
+module: decort_jwt
+short_description: Obtain access token to be used for authentication to DECORT cloud controller
+description:
+     - Obtain JWT (JSON Web Token) from the specified Oauth2 provider. This JWT can be used in subsequent DECS modules'
+       invocations to authenticate them to the DECS cloud controller.
+version_added: "2.4"
+author: "Sergey Shubin (sergey.shubin@digitalenergy.online)"
+notes:
+     - Environment variables can be used to pass parameters to the module (see options below for details).
+     - Specified Oauth2 provider must be trusted by the DECORT cloud controller on which JWT will be used.
+     - 'If you register module output as I(my_jwt), the JWT value is accessed as I(my_jwt.jwt)'
+requirements:
+     - python >= 2.6
+     - PyJWT module
+     - requests module
+     - decort_utils utility library (module)
+     - DECORT cloud platform version 3.6.1 or higher
+options:
+    app_id:
+        description:
+        - 'Application ID for authenticating to the Oauth2 provider specified in I(oauth2_url).'
+        - 'If not found in the playbook or command line arguments, the value will be taken from DECORT_APP_ID
+           environment variable.'
+        required: no
+    app_secret:
+        description:
+        - 'Application API secret used for authenticating to the Oauth2 provider specified in I(oauth2_url).'
+        - 'If not found in the playbook or command line arguments, the value will be taken from DECORT_APP_SECRET
+           environment variable.'
+        required: no
+    oauth2_url:
+        description:
+        - 'URL of the oauth2 authentication provider to obtain JWT from.'
+        - If not specified in the playbook, the value will be taken from DECORT_OAUTH2_URL environment variable.
+    validity:
+        description:
+        - Validity of the JWT in seconds. Default value is 3600 (one hour).
+        required: no
+    verify_ssl:
+        description:
+        - 'Controls SSL verification mode when making API calls to DECS controller. Set it to False if you
+         want to disable SSL certificate verification.'
+        - `Intended use case is when you run module in a trusted environment that uses self-signed certificates. 
+         Note that disabling SSL verification in any other scenario can lead to security issues, so please use 
+         with caution.'
+        default: True
+        required: no
+'''
+
+EXAMPLES = '''
+- name: Obtain JWT and store it as my_jwt for authenticating subsequent task to DECORT cloud controller
+  decort_jwt:
+    app_id: "{{ my_app_id }}"
+    app_secret: "{{ my_app_secret }}"
+    oauth2_url: https://sso.decs.online
+    delegate_to: localhost
+    register: my_jwt
+'''
+
+RETURN = '''
+jwt:
+    description: JSON Web Token that can be used to access DECS cloud controller
+    returned: always
+    type: string
+    sample: None
+'''
+
+import requests
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.basic import env_fallback
+
+def decort_jwt_parameters():
+    """Build and return a dictionary of parameters expected by decort_jwt module in a form accepted
+    by AnsibleModule utility class"""
+
+    return dict(
+        app_id=dict(type='str',
+                    required=True,
+                    fallback=(env_fallback, ['DECORT_APP_ID'])),
+        app_secret=dict(type='str',
+                        required=True,
+                        fallback=(env_fallback, ['DECORT_APP_SECRET']),
+                        no_log=True),
+        oauth2_url=dict(type='str',
+                        required=True,
+                        fallback=(env_fallback, ['DECORT_OAUTH2_URL'])),
+        validity=dict(type='int',
+                      required=False,
+                      default=3600),
+        verify_ssl=dict(type='bool', required=False, default=True),
+        workflow_callback=dict(type='str', required=False),
+        workflow_context=dict(type='str', required=False),
+    )
+
+def main():
+    module_parameters = decort_jwt_parameters()
+
+    amodule = AnsibleModule(argument_spec=module_parameters,
+                            supports_check_mode=True,)
+
+    result = {'failed': False, 'changed': False}
+
+    token_get_url = amodule.params['oauth2_url'] + "/v1/oauth/access_token"
+    req_data = dict(grant_type="client_credentials",
+                    client_id=amodule.params['app_id'],
+                    client_secret=amodule.params['app_secret'],
+                    response_type="id_token",
+                    validity=amodule.params['validity'],)
+    # TODO: Need standard code snippet to handle server timeouts gracefully
+    # Consider a few retries before giving up or use requests.Session & requests.HTTPAdapter
+    # see https://stackoverflow.com/questions/15431044/can-i-set-max-retries-for-requests-request
+
+    # catch requests.exceptions.ConnectionError to handle incorrect oauth2_url case
+    try:
+        token_get_resp = requests.post(token_get_url, data=req_data, verify=amodule.params['verify_ssl'])
+    except requests.exceptions.ConnectionError as errco:
+        result.update(failed=True)
+        result['msg'] = "Failed to connect to {}: {}".format(token_get_url, errco)
+        amodule.fail_json(**result)
+    except requests.exceptions.Timeout as errti:
+        result.update(failed=True)
+        result['msg'] = "Timeout when trying to connect to {}: {}".format(token_get_url, errti)
+        amodule.fail_json(**result)
+
+    # alternative -- if resp == requests.codes.ok
+    if token_get_resp.status_code != 200:
+        result.update(failed=True)
+        result['msg'] = "Failed to obtain JWT access token from oauth2_url {} for app_id {}: {} {}".format(
+            token_get_url, amodule.params['app_id'],
+            token_get_resp.status_code, token_get_resp.reason)
+        amodule.fail_json(**result)
+
+    # Common return values: https://docs.ansible.com/ansible/2.3/common_return_values.html
+    result['jwt'] = token_get_resp.content.decode('utf8')
+    amodule.exit_json(**result)
+
+if __name__ == '__main__':
+    main()

library/decort_k8s.py

@@ -0,0 +1,395 @@
+#!/usr/bin/python
+#
+# Digital Enegry Cloud Orchestration Technology (DECORT) modules for Ansible
+# Copyright: (c) 2018-2023 Digital Energy Cloud Solutions LLC
+#
+# Apache License 2.0 (see http://www.apache.org/licenses/LICENSE-2.0.txt)
+#
+
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+DOCUMENTATION = '''
+---
+---
+'''
+
+EXAMPLES = '''
+- name: Create k8s cluster
+  decort_k8s:
+    verify_ssl: false
+    authenticator: jwt
+    jwt: "{{ run_jwt.jwt }}"
+    controller_url: "{{CONTROLLER_URL}}"
+    name: SOME_NAME
+    rg_id: {{RG_ID}}
+    k8ci_id: 10
+    master_count: 3
+    master_cpu: 2
+    master_ram: 2048
+    master_disk: 10
+    state: present
+    permanent: True
+    started: True
+    getConfig: True
+    network_plugin: flannel
+    workers:
+      - name: wg1
+        ram: 1024
+        cpu: 2
+        disk: 10
+        num: 1
+        labels:
+        - disktype1=ssd1
+        - disktype2=ssd2
+        - disktype3=ssd3
+        taints:
+        - key1=value1:NoSchedule 
+        - key2=value2:NoSchedule
+        - key3=value3:NoSchedule
+        annotations:
+        - node.deckhouse.io/group1=g1
+        - node.deckhouse.io/group2=g2
+        - node.deckhouse.io/group3=g3
+      - name: wg2
+        ram: 1024
+        cpu: 2
+        disk: 10
+        num: 1
+        labels:
+        - apptype=main
+        annotations:
+        - node.mainapp.domen.local/group1=g1
+  register: some_cluster
+'''
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.basic import env_fallback
+from ansible.module_utils.decort_utils import *
+
+class decort_k8s(DecortController):
+    def __init__(self,arg_amodule):
+        super(decort_k8s, self).__init__(arg_amodule)
+ 
+        validated_acc_id = 0
+        validated_rg_id = 0
+        validated_rg_facts = None
+        validated_k8ci_id = 0
+        self.k8s_should_exist = False
+        if not arg_amodule.params['workers']:
+            self.result['failed'] = True
+            self.result['changed'] = False
+            self.result['msg'] = "At least one worker group must be present"
+            self.fail_json(**self.result)
+
+        if arg_amodule.params['name'] == "" and arg_amodule.params['id'] == 0:
+            self.result['failed'] = True
+            self.result['changed'] = False
+            self.result['msg'] = "Cannot manage k8s cluster when its ID is 0 and name is empty."
+            self.fail_json(**self.result)
+
+
+        if not arg_amodule.params['id']:
+            if not arg_amodule.params['rg_id']: # RG ID is not set -> locate RG by name -> need account ID
+                validated_acc_id, _ = self.account_find(arg_amodule.params['account_name'],
+                                                        arg_amodule.params['account_id'])
+                if not validated_acc_id:
+                    self.result['failed'] = True
+                    self.result['changed'] = False
+                    self.result['msg'] = ("Current user does not have access to the account ID {} / "
+                                          "name '{}' or non-existent account specified.").format(arg_amodule.params['account_id'],
+                                                                                                 arg_amodule.params['account_name'])
+                    self.fail_json(**self.result)
+                    # fail the module -> exit
+            # now validate RG
+            validated_rg_id, validated_rg_facts = self.rg_find(validated_acc_id,
+                                                               arg_amodule.params['rg_id'],)
+            if not validated_rg_id:
+                self.result['failed'] = True
+                self.result['changed'] = False
+                self.result['msg'] = "Cannot find RG ID {} / name '{}'.".format(arg_amodule.params['rg_id'],
+                                                                                arg_amodule.params['rg_name'])
+                self.fail_json(**self.result)
+                # fail the module - exit
+            
+
+            #validate k8ci ID
+
+            validated_k8ci_id = self.k8s_k8ci_find(arg_amodule.params['k8ci_id'])  
+            if not validated_k8ci_id:
+                self.result['failed'] = True
+                self.result['changed'] = False
+                self.result['msg'] = "Cannot find K8CI ID {}.".format(arg_amodule.params['k8ci_id'])
+                self.fail_json(**self.result)
+
+            self.rg_id = validated_rg_id
+            arg_amodule.params['rg_id'] = validated_rg_id
+            arg_amodule.params['rg_name'] = validated_rg_facts['name']
+            self.acc_id = validated_rg_facts['accountId']
+            arg_amodule.params['k8ci_id'] = validated_k8ci_id
+
+            self.k8s_id,self.k8s_info = self.k8s_find(k8s_id=arg_amodule.params['id'],
+                                                      k8s_name=arg_amodule.params['name'],
+                                                      rg_id=validated_rg_id,
+                                                      check_state=False)
+            if self.k8s_id:
+                self.k8s_should_exist = True
+                self.acc_id = self.k8s_info['accountId']
+            # check workers and groups for add or remove?
+        
+        return
+
+    def package_facts(self,check_mode=False):
+        
+        ret_dict = dict(
+            name="",
+            state="CHECK_MODE",
+            account_id=0,
+            rg_id=0,
+            config=None,
+        )
+
+        if check_mode:
+            # in check mode return immediately with the default values
+            return ret_dict
+
+        #if self.k8s_facts is None:
+        #    #if void facts provided - change state value to ABSENT and return
+        #    ret_dict['state'] = "ABSENT"
+        #    return ret_dict
+
+        ret_dict['id'] = self.k8s_info['id']
+        ret_dict['name'] = self.k8s_info['name']
+        ret_dict['techStatus'] = self.k8s_info['techStatus']
+        ret_dict['state'] = self.k8s_info['status']
+        ret_dict['rg_id'] = self.rg_id
+        ret_dict['vins_id'] = self.k8s_vins_id
+        ret_dict['account_id'] = self.acc_id
+        if self.amodule.params['getConfig'] and self.k8s_info['techStatus'] == "STARTED":
+            ret_dict['config'] = self.k8s_getConfig()
+        
+        return ret_dict
+    
+    def nop(self):
+        """No operation (NOP) handler for k8s cluster management by decort_k8s module.
+        This function is intended to be called from the main switch construct of the module
+        when current state -> desired state change logic does not require any changes to
+        the actual k8s cluster state.
+        """
+        self.result['failed'] = False
+        self.result['changed'] = False
+        if self.k8s_id:
+            self.result['msg'] = ("No state change required for K8s  ID {} because of its "
+                                   "current status '{}'.").format(self.k8s_id, self.k8s_info['status'])
+        else:
+            self.result['msg'] = ("No state change to '{}' can be done for "
+                                  "non-existent K8s instance.").format(self.amodule.params['state'])
+        return                         
+
+    def error(self):
+        self.result['failed'] = True
+        self.result['changed'] = False
+        if self.k8s_id:
+            self.result['msg'] = ("Invalid target state '{}' requested for K8s cluster ID {} in the "
+                                   "current status '{}'.").format(self.k8s_id,
+                                                                  self.amodule.params['state'],
+                                                                  self.k8s_info['status'])
+        else:
+            self.result['msg'] = ("Invalid target state '{}' requested for non-existent K8s Cluster name '{}' "
+                                   "in RG ID {} / name '{}'").format(self.amodule.params['state'],
+                                                                    self.amodule.params['name'],
+                                                                    self.amodule.params['rg_id'],
+                                                                    self.amodule.params['rg_name'])
+        return
+
+    def create(self):
+        self.k8s_provision(self.amodule.params['name'],
+                                    self.amodule.params['k8ci_id'],
+                                    self.amodule.params['rg_id'],
+                                    self.amodule.params['network_plugin'],
+                                    self.amodule.params['master_count'],
+                                    self.amodule.params['master_cpu'],
+                                    self.amodule.params['master_ram'],
+                                    self.amodule.params['master_disk'],
+                                    self.amodule.params['workers'][0],
+                                    self.amodule.params['extnet_id'],
+                                    self.amodule.params['with_lb'],
+                                    self.amodule.params['description'],)
+        
+        self.k8s_id,self.k8s_info = self.k8s_find(k8s_id=self.amodule.params['id'],
+                                                      k8s_name=self.amodule.params['name'],
+                                                      rg_id=self.rg_id,
+                                                      check_state=False)
+        
+        if self.k8s_id:
+                self.k8s_should_exist = True
+        if self.k8s_id and len(self.amodule.params['workers'])>1 :
+            self.k8s_workers_modify(self.k8s_info,self.amodule.params['workers'])
+        return
+    
+    def destroy(self):
+        self.k8s_delete(self.k8s_id,self.amodule.params['permanent'])
+        self.k8s_info['status'] = 'DELETED'
+        self.k8s_should_exist = False
+        return    
+    
+    def action(self,disared_state,started=True):
+        
+        self.k8s_state(self.k8s_info, disared_state,started)
+        self.k8s_id,self.k8s_info = self.k8s_find(k8s_id=self.amodule.params['id'],
+                                                      k8s_name=self.amodule.params['name'],
+                                                      rg_id=self.rg_id,
+                                                      check_state=False)
+        if started == True and self.k8s_info['techStatus'] == "STOPPED":
+            self.k8s_state(self.k8s_info, disared_state,started)
+            self.k8s_info['techStatus'] == "STARTED"
+        self.k8s_workers_modify(self.k8s_info,self.amodule.params['workers'])
+
+        return
+    @staticmethod
+    def build_parameters():
+        return dict(
+            account_id=dict(type='int', required=False),
+            account_name=dict(type='str', required=False, default=''),
+            annotation=dict(type='str', required=False, default=''),
+            app_id=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_APP_ID'])),
+            app_secret=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_APP_SECRET']),
+                            no_log=True),
+            authenticator=dict(type='str',
+                            required=True,
+                            choices=['legacy', 'oauth2', 'jwt']),
+            controller_url=dict(type='str', required=True),
+            # datacenter=dict(type='str', required=False, default=''),
+            jwt=dict(type='str',
+                    required=False,
+                    fallback=(env_fallback, ['DECORT_JWT']),
+                    no_log=True),
+            oauth2_url=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_OAUTH2_URL'])),
+            password=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_PASSWORD']),
+                        no_log=True),
+            quotas=dict(type='dict', required=False),
+            state=dict(type='str',
+                    default='present',
+                    choices=['absent', 'disabled', 'enabled', 'present','check']),
+            permanent=dict(type='bool', default=False),
+            started=dict(type='bool', default=True),
+            user=dict(type='str',
+                    required=False,
+                    fallback=(env_fallback, ['DECORT_USER'])),
+            name=dict(type='str', required=True),
+            id=dict(type='int', required=False, default=0),
+            getConfig=dict(type='bool',required=False, default=False),
+            rg_id=dict(type='int', default=0),
+            rg_name=dict(type='str',default=""),
+            k8ci_id=dict(type='int', required=True),
+            network_plugin=dict(type='str',required=False,default="flannel"),
+            wg_name=dict(type='str', required=False),
+            master_count=dict(type='int', default=1),
+            master_cpu=dict(type='int', default=2),
+            master_ram=dict(type='int', default=2048),
+            master_disk=dict(type='int', default=10),
+            worker_count=dict(type='int', default=1),
+            worker_cpu=dict(type='int', default=1),
+            worker_ram_mb=dict(type='int', default=1024),
+            worker_disk_gb=dict(type='int', default=10),
+            workers=dict(type='list',required=True),
+            extnet_id=dict(type='int',  default=0),
+            description=dict(type='str', default="Created by decort ansible module"),
+            with_lb=dict(type='bool', default=True),
+            verify_ssl=dict(type='bool', required=False, default=True),
+            workflow_callback=dict(type='str', required=False),
+            workflow_context=dict(type='str', required=False),)
+
+def main():
+    module_parameters = decort_k8s.build_parameters()
+
+    amodule = AnsibleModule(argument_spec=module_parameters,
+                            supports_check_mode=True,
+                            mutually_exclusive=[
+                                ['oauth2', 'password'],
+                                ['password', 'jwt'],
+                                ['jwt', 'oauth2'],
+                            ],
+                            required_together=[
+                                ['app_id', 'app_secret'],
+                                ['user', 'password'],
+                            ],
+                            required_one_of=[
+                                ['id', 'name'],
+                                ['rg_id','rg_name']
+                            ],
+                            )
+
+    subj = decort_k8s(amodule)
+
+    if amodule.params['state'] == 'check':
+        subj.result['changed'] = False
+        if subj.k8s_id:
+            # cluster is found - package facts and report success to Ansible
+            subj.result['failed'] = False
+            subj.result['facts'] = subj.package_facts(amodule.check_mode)
+            amodule.exit_json(**subj.result)
+            # we exit the module at this point
+        else:
+            subj.result['failed'] = True
+            subj.result['msg'] = ("Cannot locate K8s cluster name '{}'. "
+                                  "RG ID {}").format(amodule.params['name'],
+                                                     amodule.params['rg_id'],)
+            amodule.fail_json(**subj.result)                          
+
+    if subj.k8s_id:
+        if subj.k8s_info['status'] in ("DELETING","DESTROYNG","CREATING","DESTROYING",
+                                         "ENABLING","DISABLING","RESTORING","MODELED"):
+            subj.error()
+        elif subj.k8s_info['status'] == "DELETED":
+            if amodule.params['state'] in ('disabled', 'enabled', 'present'):
+                subj.k8s_restore(subj.k8s_id)
+                subj.action(amodule.params['state'])
+            if amodule.params['state'] == 'absent':
+                subj.nop()
+        elif subj.k8s_info['techStatus'] in ("STARTED","STOPPED"):
+            if amodule.params['state'] == 'disabled':
+                subj.action(amodule.params['state'])
+            elif amodule.params['state'] == 'absent':
+                subj.destroy()
+            else:
+                subj.action(amodule.params['state'],amodule.params['started'])
+        elif subj.k8s_info['status'] == "DISABLED":
+            if amodule.params['state'] == 'absent':
+                subj.destroy()
+            elif amodule.params['state'] in ('present','enabled'):
+                subj.action(amodule.params['state'],amodule.params['started'])
+            else:
+                subj.nop()
+        elif subj.k8s_info['status'] == "DESTROED":
+            if amodule.params['state'] in ('present','enabled'):
+                subj.create()
+            if amodule.params['state'] == 'absent':    
+                subj.nop()
+    else:
+        if amodule.params['state'] == 'absent':
+            subj.nop()
+        if amodule.params['state'] in ('present','started'):
+            subj.create() 
+        elif amodule.params['state'] in ('stopped', 'disabled','enabled'):
+            subj.error()
+            
+    if subj.result['failed']:
+        amodule.fail_json(**subj.result)
+    else:
+        if subj.k8s_should_exist:
+            subj.result['facts'] = subj.package_facts(amodule.check_mode)
+            amodule.exit_json(**subj.result)
+        else:
+            amodule.exit_json(**subj.result)
+
+if __name__ == "__main__":
+    main()

library/decort_kvmvm.py

@@ -0,0 +1,913 @@
+#!/usr/bin/python
+#
+# Digital Enegry Cloud Orchestration Technology (DECORT) modules for Ansible
+# Copyright: (c) 2018-2023 Digital Energy Cloud Solutions LLC
+#
+# Apache License 2.0 (see http://www.apache.org/licenses/LICENSE-2.0.txt)
+#
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+DOCUMENTATION = '''
+---
+module: decort_kvmvm
+short_description: Manage KVM virtual machine in DECORT cloud
+description: >
+     This module can be used to create a KVM based virtual machine in Digital Energy cloud platform from a 
+     specified OS image, modify virtual machine's CPU and RAM allocation, change its power state, configure
+     network port forwarding rules, restart guest OS and delete a virtual machine thus releasing
+     corresponding cloud resources.
+version_added: "2.2"
+
+requirements:
+     - python >= 3.8
+     - PyJWT Python module
+     - requests Python module
+     - netaddr Python module
+     - decort_utils utility library (module)
+     - DECORT cloud platform version 3.8.6 or higher
+notes:
+     - Environment variables can be used to pass selected parameters to the module, see details below.
+     - Specified Oauth2 provider must be trusted by the DECORT cloud controller on which JWT will be used.
+     - 'Similarly, JWT supplied in I(authenticator=jwt) mode should be received from Oauth2 provider trusted by
+       the DECORT cloud controller on which this JWT will be used.'
+options:
+    account_id:
+        description:
+        - 'ID of the account in which this VM will be created (for new VMs) or is located (for already
+          existing VMs). This is the alternative to I(account_name) option.'
+        - If both I(account_id) and I(account_name) specified, then I(account_name) is ignored.
+        - If any one of I(vm_id) or I(rg_id) specified, I(account_id) is ignored.
+        required: no
+    account_name:
+        description:
+        - 'Name of the account in which this VM will be created (for new VMs) or is located (for already
+           existing VMs).'
+        - This parameter is ignored if I(account_id) is specified.
+        - If any one of I(vm_id) or I(rg_id) specified, I(account_name) is ignored.
+        required: no
+    annotation:
+        description:
+        - Optional text description of this VM.
+        default: empty string
+        required: no
+    app_id:
+        description:
+        - 'Application ID for authenticating to the DECORT controller when I(authenticator=oauth2).'
+        - 'Required if I(authenticator=oauth2).'
+        - 'If not found in the playbook or command line arguments, the value will be taken from DECORT_APP_ID
+           environment variable.'
+        required: no
+    app_secret:
+        description:
+        - 'Application API secret used for authenticating to the DECORT controller when I(authenticator=oauth2).'
+        - This parameter is required when I(authenticator=oauth2) and ignored in other modes.
+        - 'If not found in the playbook or command line arguments, the value will be taken from DECORT_APP_SECRET
+           environment variable.'
+        required: no
+    arch:
+        description:
+        - Architecture of the KVM VM. DECORT supports KVM hosts based on Intel x86 and IBM PowerPC hardware.
+        - This parameter is used when new KVM VM is created and ignored for all other operations.
+        - Module may fail if your DECORT installation does not have physical nodes of specified architecture.
+        default: X86_64
+        choices: [ X86_64, PPC64_LE ]
+        required: yes
+    authenticator:
+        description:
+        - Authentication mechanism to be used when accessing DECORT controller and authorizing API call.
+        default: jwt
+        choices: [ jwt, oauth2, legacy ]
+        required: yes
+    boot_disk:
+        description:
+        - 'Boot disk size in GB. If this parameter is not specified for a new VM, the size of the boot disk 
+          will be set to the size of the OS image, which this VM is based on.'
+        - Boot disk is always created in the same storage and pool, as the OS image, which this VM is based on.
+        - Boot disk cannot be detached from VM.
+        required: no
+    controller_url:
+        description:
+        - URL of the DECORT controller that will be contacted to manage the VM according to the specification.
+        - 'This parameter is always required regardless of the specified I(authenticator) type.'
+        required: yes
+    cpu:
+        description:
+        - Number of virtual CPUs to allocate for the VM.
+        - This parameter is required for creating new VM and optional for other operations.
+        - 'If you set this parameter for an existing VM, then the module will check if VM resize is necessary and do
+          it accordingly. Note that resize operation on a running VM may generate errors as not all OS images support
+          hot resize feature.'
+        required: no
+    data_disks:
+        description:
+        - Optional list of integer IDs of the pre-existing disks that will be attached to this VM.
+        - These are additional disks (aka data disks) besides boot disk, which is created and attached automatically.
+        required: no
+    id:
+        description:
+        - ID of the KVM VM to manage.
+        - 'Either I(id) or a combination of VM name I(name) and RG related parameters (either I(rg_id) or a pair of
+           I(account_name) and I(rg_name) is required to manage an existing VM.'
+        - 'This parameter is not required (and ignored) when creating new VM as VM ID is assigned by cloud platform
+           automatically and cannot be changed afterwards. If existing VM is identified by I(id), then I(account_id),
+           I(account_name), I(rg_name) or I(rg_id) parameters will be ignored.'
+        required: no
+    image_id:
+        description:
+        - ID of the OS image to use for VM provisioning.
+        - 'This parameter is valid at VM creation time only and is ignored for operations on existing VMs.'
+        - 'You need to know image ID, e.g. by extracting it with decort_osimage module and storing
+           in a variable prior to calling decort_kvmvm.'
+        - 'If both I(image_id) and I(image_name) are specified, I(image_name) will be ignored.'
+        required: no
+    image_name:
+        description:
+        - Name of the OS image to use for a new VM provisioning.
+        - 'This parameter is valid at VM creation time only and is ignored for operations on existing VMs.'
+        - 'The specified image name will be looked up in the target DECORT controller and error will be generated if
+          no matching image is found.'
+        - 'If both I(image_id) and I(image_name) are specified, I(image_name) will be ignored.'
+        required: no
+    jwt:
+        description:
+        - 'JWT (access token) for authenticating to the DECORT controller when I(authenticator=jwt).'
+        - 'This parameter is required if I(authenticator=jwt) and ignored for other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_JWT environment variable.
+        required: no
+    name:
+        description:
+        - Name of the VM.
+        - 'To manage VM by I(name) you also need to specify either I(rg_id) or a pair of I(rg_name) and I(account_name).'
+        - 'If both I(name) and I(id) are specified, I(name) will be ignored and I(id) used to locate the VM.'
+        required: no
+    networks:
+        description:
+        - List of dictionaries that specifies network connections for this VM.
+        - Structure of each element is as follows:
+        - ' - (string) type - type of the network connection. Supported types are VINS and EXTNET.'
+        - ' - (int)    id - ID of the target network segment. It is ViNS ID for I(net_type=VINS) and
+              external network segment ID for I(net_type=EXTNET)'
+        - ' - (string) ip_addr - optional IP address to request for this connection. If not specified, the 
+              platform will assign valid IP address automatically.'
+        - 'If you call decort_kvmvm module for an existing VM, the module will try to reconfigure existing network
+          connections according to the new specification.'
+        - If this parameter is not specified, the VM will have no connections to the network(s).
+        required: no
+    oauth2_url:
+        description:
+        - 'URL of the oauth2 authentication provider to use when I(authenticator=oauth2).'
+        - 'This parameter is required when when I(authenticator=oauth2).'
+        - If not specified in the playbook, the value will be taken from DECORT_OAUTH2_URL environment variable.
+    password:
+        description:
+        - 'Password for authenticating to the DECORT controller when I(authenticator=legacy).'
+        - 'This parameter is required if I(authenticator=legacy) and ignored in other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_PASSWORD environment variable.
+        required: no
+    ram:
+        description:
+        - Size of RAM in MB to allocate to the VM.
+        - This parameter is required for creating new VM and optional for other operations.
+        - 'If you set this parameter for an existing VM, then the module will check if VM resize is necessary and do
+          it accordingly. Note that resize operation on a running VM may generate errors as not all OS images support
+          hot resize feature.'
+        required: no
+    ssh_key:
+        description:
+        - 'SSH public key to be deployed on to the new VM for I(ssh_key_user). If I(ssh_key_user) is not specified,
+          the key will not be deployed, and a warning is generated.'
+        - This parameter is valid at VM creation time only and ignored for any operation on existing VMs.
+        required: no
+    ssh_key_user:
+        description:
+        - User for which I(ssh_key) should be deployed.
+        - If I(ssh_key) is not specified, this parameter is ignored and a warning is generated.
+        - This parameter is valid at VM creation time only and ignored for any operation on existing VMs.
+        required: no
+    user_data:
+        description:
+        - Cloud-init User-Data, exept ssh module
+    state:
+        description:
+        - Specify the desired state of the virtual machine at the exit of the module.
+        - 'Regardless of I(state), if VM exists and is in one of [MIGRATING, DESTROYING, ERROR] states, do nothing.'
+        - 'If desired I(state=check):'
+        - ' - Just check if VM exists in any state and return its current specifications.'
+        - ' - If VM does not exist, fail the task.'
+        - 'If desired I(state=present):'
+        - ' - VM does not exist, create the VM according to the specifications and start it.'
+        - ' - VM in one of [RUNNING, PAUSED, HALTED] states, attempt resize if necessary, change network if necessary.'
+        - ' - VM in DELETED state, restore and start it.'
+        - ' - VM in DESTROYED state, recreate the VM according to the specifications and start it.'
+        - 'If desired I(state=poweredon):'
+        - ' - VM does not exist, create it according to the specifications.'
+        - ' - VM in RUNNING state, attempt resize if necessary, change network if necessary.'
+        - ' - VM in one of [PAUSED, HALTED] states, attempt resize if necessary, change network if necessary, next
+              start the VM.'
+        - ' - VM in DELETED state, restore it.'
+        - ' - VM in DESTROYED state, create it according to the specifications.'
+        - 'If desired I(state=absent):'
+        - ' - VM in one of [RUNNING, PAUSED, HALTED] states, destroy it.'
+        - ' - VM in one of [DELETED, DESTROYED] states, do nothing.'
+        - 'If desired I(state=paused):'
+        - ' - VM in RUNNING state, pause the VM, resize if necessary, change network if necessary.'
+        - ' - VM in one of [PAUSED, HALTED] states, resize if necessary, change network if necessary.'
+        - ' - VM in one of [DELETED, DESTROYED] states, abort with an error.'
+        - 'If desired I(state=poweredoff) or I(state=halted):'
+        - ' - VM does not exist, create the VM according to the specifications and leave it in HALTED state.'
+        - ' - VM in RUNNING state, stop the VM, resize if necessary, change network if necessary.'
+        - ' - VM in one of [PAUSED, HALTED] states, resize if necessary, change network if necessary.'
+        - ' - VM in DELETED state, abort with an error.'
+        - ' - VM in DESTROYED state, recreate the VM according to the specifications and leave it in HALTED state.'
+        default: present
+        choices: [ present, absent, poweredon, poweredoff, halted, paused, check ]
+    tags:
+        description:
+        - Dict of custom tags to be assigned to the VM.
+        - These tags are arbitrary text that can be used for grouping or indexing the VMs by other applications.
+        required: no
+    user:
+        description:
+        - 'Name of the legacy user for authenticating to the DECORT controller when I(authenticator=legacy).'
+        - 'This parameter is required when I(authenticator=legacy) and ignored for other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_USER environment variable.
+        required: no
+    rg_id:
+        description:
+        - ID of the Resource Group where a new VM will be deployed or an existing VM can be found.
+        - 'This parameter may be required when managing VM by its I(name). If you specify I(rg_id), then
+          I(account_name), I(account_id) and I(rg_name) will be ignored.'
+        required: no
+    rg_name:
+        description:
+        - Name of the RG where the VM will be deployed (for new VMs) or can be found (for existing VMs).
+        - This parameter is required when managing VM by its I(name).
+        - If both I(rg_id) and I(rg_name) are specified, I(rg_name) will be ignored.
+        - If I(rg_name) is specified, then either I(account_name) or I(account_id) must also be set.
+        required: no
+    verify_ssl:
+        description:
+        - 'Controls SSL verification mode when making API calls to DECORT controller. Set it to False if you
+         want to disable SSL certificate verification. Intended use case is when you run module in a trusted
+         environment that uses self-signed certificates. Note that disabling SSL verification in any other
+         scenario can lead to security issues, so please know what you are doing.'
+        default: True
+        required: no
+    workflow_callback:
+        description:
+        - 'Callback URL that represents an application, which invokes this module (e.g. up-level orchestrator or
+          end-user portal) and may except out-of-band updates on progress / exit status of the module run.'
+        - API call at this URL will be used to relay such information to the application.
+        - 'API call payload will include module-specific details about this module run and I(workflow_context).'
+        required: no
+    workflow_context:
+        description:
+        - 'Context data that will be included into the payload of the API call directed at I(workflow_callback) URL.'
+        - 'This context data is expected to uniquely identify the task carried out by this module invocation so
+           that up-level orchestrator could match returned information to the its internal entities.'
+        required: no
+'''
+
+EXAMPLES = '''
+- name: create a VM named "SimpleVM" in the DECORT cloud along with VDC named "ANewVDC" if it does not exist yet.
+    decort_kvmvm:
+      annotation: "VM managed by decort_kvmvm module"
+      authenticator: oauth2
+      app_id: "{{ MY_APP_ID }}"
+      app_secret: "{{ MY_APP_SECRET }}"
+      controller_url: "https://ds1.digitalenergy.online"
+      name: SimpleVM
+      cpu: 2
+      ram: 4096
+      boot_disk: 10
+      image_name: "Ubuntu 16.04 v1.1"
+      data_disks:
+        - {{DISK_ID}}
+      state: present
+      tags: 
+        PROJECT:Ansible 
+        STATUS:Test
+      account_name: "Development"
+      rg_name: "ANewVDC"
+    delegate_to: localhost
+    register: simple_vm
+- name: resize the above VM to CPU 4 and remove port forward rule for port number 80.
+    decort_kvmvm:
+      authenticator: jwt
+      jwt: "{{ MY_JWT }}"
+      controller_url: "https://ds1.digitalenergy.online"
+      name: SimpleVM
+      cpu: 4
+      ram: 4096
+      port_forwards:
+        - ext_port: 21022
+          int_port: 22
+          proto: tcp
+      state: present
+      account_name: "Development"
+      rg_name: "ANewVDC"
+    delegate_to: localhost
+    register: simple_vm
+- name: stop existing VM identified by the VM ID and down size it to CPU:RAM 1:2048 along the way.
+    decort_kvmvm:
+      authenticator: jwt
+      jwt: "{{ MY_JWT }}"
+      controller_url: "https://ds1.digitalenergy.online"
+      id: "{{ TARGET_VM_ID }}"
+      cpu: 1
+      ram: 2048
+      state: poweredoff
+    delegate_to: localhost
+    register: simple_vm
+'''
+
+RETURN = '''
+facts:
+    description: facts about the virtual machine that may be useful in the playbook
+    returned: always
+    type: dict
+    sample:
+      facts:
+        id: 9454
+        name: TestVM
+        state: RUNNING
+        username: testuser
+        password: Yab!tWbyPF
+        int_ip: 192.168.103.253
+        rg_name: SandboxVDC
+        rg_id: 2883
+        vdc_ext_ip: 185.193.143.151
+        ext_ip: 185.193.143.106
+        ext_netmask: 24
+        ext_gateway: 185.193.143.1
+        ext_mac: 52:54:00:00:1a:24
+'''
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.basic import env_fallback
+from ansible.module_utils.decort_utils import *
+
+class decort_kvmvm(DecortController):
+    def __init__(self, arg_amodule):
+        # call superclass constructor first
+        super(decort_kvmvm, self).__init__(arg_amodule)
+
+        self.comp_should_exist = False
+        # This following flag is used to avoid extra (and unnecessary) get of compute details prior to 
+        # packaging facts before the module completes. As ""
+        self.skip_final_get = False
+        self.comp_id = 0
+        self.comp_info = None
+        self.acc_id = 0
+        self.rg_id = 0
+
+        validated_acc_id =0
+        validated_rg_id = 0
+        validated_rg_facts = None
+
+        # Analyze Compute name & ID, RG name & ID and build arguments to compute_find accordingly.
+        if arg_amodule.params['name'] == "" and arg_amodule.params['id'] == 0:
+            self.result['failed'] = True
+            self.result['changed'] = False
+            self.result['msg'] = "Cannot manage Compute when its ID is 0 and name is empty."
+            self.fail_json(**self.result)
+            # fail the module - exit
+
+        if not arg_amodule.params['id']: # manage Compute by name -> need RG identity
+            if not arg_amodule.params['rg_id']: # RG ID is not set -> locate RG by name -> need account ID
+                validated_acc_id, _ = self.account_find(arg_amodule.params['account_name'],
+                                                        arg_amodule.params['account_id'])
+                if not validated_acc_id:
+                    self.result['failed'] = True
+                    self.result['changed'] = False
+                    self.result['msg'] = ("Current user does not have access to the account ID {} / "
+                                          "name '{}' or non-existent account specified.").format(arg_amodule.params['account_id'],
+                                                                                                 arg_amodule.params['account_name'])
+                    self.fail_json(**self.result)
+                    # fail the module -> exit
+            # now validate RG
+            validated_rg_id, validated_rg_facts = self.rg_find(validated_acc_id,
+                                                               arg_amodule.params['rg_id'],
+                                                               arg_amodule.params['rg_name'])
+            if not validated_rg_id:
+                self.result['failed'] = True
+                self.result['changed'] = False
+                self.result['msg'] = "Cannot find RG ID {} / name '{}'.".format(arg_amodule.params['rg_id'],
+                                                                                arg_amodule.params['rg_name'])
+                self.fail_json(**self.result)
+                # fail the module - exit
+
+            self.rg_id = validated_rg_id
+            arg_amodule.params['rg_id'] = validated_rg_id
+            arg_amodule.params['rg_name'] = validated_rg_facts['name']
+            self.acc_id = validated_rg_facts['accountId']
+
+        # at this point we are ready to locate Compute, and if anything fails now, then it must be
+        # because this Compute does not exist or something goes wrong in the upstream API
+        # We call compute_find with check_state=False as we also consider the case when a Compute
+        # specified by account / RG / compute name never existed and will be created for the first time.
+        self.comp_id, self.comp_info, self.rg_id = self.compute_find(comp_id=arg_amodule.params['id'],
+                                                                     comp_name=arg_amodule.params['name'],
+                                                                     rg_id=validated_rg_id,
+                                                                     check_state=False)
+
+        if self.comp_id:
+            if self.comp_info['status'] != 'DESTROYED' and self.comp_info['arch'] not in ["X86_64", "PPC64_LE"]:
+                # If we found a Compute in a non-DESTROYED state and it is not of type valid arch, abort the module
+                self.result['failed'] = True
+                self.result['msg'] = ("Compute ID {} architecture '{}' is not supported by "
+                                      "decort_kvmvm module.").format(self.comp_id, 
+                                                                     self.amodule.params['arch'])
+                self.amodule.fail_json(**self.result)
+                # fail the module - exit
+            self.comp_should_exist = True
+            self.acc_id = self.comp_info['accountId']
+
+        return
+
+    def nop(self):
+        """No operation (NOP) handler for Compute management by decort_kvmvm module.
+        This function is intended to be called from the main switch construct of the module
+        when current state -> desired state change logic does not require any changes to
+        the actual Compute state.
+        """
+        self.result['failed'] = False
+        self.result['changed'] = False
+        if self.comp_id:
+            self.result['msg'] = ("No state change required for Compute ID {} because of its "
+                                   "current status '{}'.").format(self.comp_id, self.comp_info['status'])
+        else:
+            self.result['msg'] = ("No state change to '{}' can be done for "
+                                  "non-existent Compute instance.").format(self.amodule.params['state'])
+        return
+
+    def error(self):
+        """Error handler for Compute instance management by decort_kvmvm module.
+        This function is intended to be called when an invalid state change is requested.
+        Invalid means that the current is invalid for any operations on the Compute or the 
+        transition from current to desired state is not technically possible.
+        """
+        self.result['failed'] = True
+        self.result['changed'] = False
+        if self.comp_id:
+            self.result['msg'] = ("Invalid target state '{}' requested for Compute ID {} in the "
+                                   "current status '{}'.").format(self.comp_id,
+                                                                  self.amodule.params['state'],
+                                                                  self.comp_info['status'])
+        else:
+            self.result['msg'] = ("Invalid target state '{}' requested for non-existent Compute name '{}' "
+                                   "in RG ID {} / name '{}'").format(self.amodule.params['state'],
+                                                                    self.amodule.params['name'],
+                                                                    self.amodule.params['rg_id'],
+                                                                    self.amodule.params['rg_name'])
+        return
+
+    def create(self):
+        """New Compute instance creation handler for decort_kvmvm module.
+        This function checks for the presence of required parameters and deploys a new KVM VM
+        Compute instance with the specified characteristics into the target Resource Group.
+        The target RG must exist.
+        """
+        # the following parameters must be present: cpu, ram, image_id or image_name
+        # each of the following calls will abort if argument is missing
+        self.check_amodule_argument('cpu')
+        self.check_amodule_argument('ram')
+
+        if self.amodule.params['arch'] not in ["X86_64", "PPC64_LE"]:
+            self.result['failed'] = True
+            self.result['msg'] = ("Unsupported architecture '{}' is specified for "
+                                  "KVM VM create.").format(self.amodule.params['arch'])
+            self.amodule.fail_json(**self.result)
+            # fail the module - exit
+
+        validated_bdisk_size = 0
+
+        image_facts = None
+        # either image_name or image_id must be present
+        if self.check_amodule_argument('image_id', abort=False) and self.amodule.params['image_id'] > 0 :
+            # find image by image ID and account ID
+            # image_find(self, image_id, image_name, account_id, rg_id=0, sepid=0, pool=""):
+            _, image_facts = self.image_find(image_id=self.amodule.params['image_id'],
+                                             image_name="",
+                                             account_id=self.acc_id)
+        elif self.check_amodule_argument('image_name', abort=False) and self.amodule.params['image_name'] != "":
+            # find image by image name and account ID
+            _, image_facts = self.image_find(image_id=0,
+                                             image_name=self.amodule.params['image_name'],
+                                             account_id=self.acc_id)
+        else:
+            # neither image_name nor image_id are set - abort the script
+            self.result['failed'] = True
+            self.result['msg'] = "Missing both 'image_name' and 'image_id'. You need to specify one to create a Compute."
+            self.amodule.fail_json(**self.result)
+            # fail the module - exit
+
+        if ((not self.check_amodule_argument('boot_disk', False)) or 
+            self.amodule.params['boot_disk'] <= image_facts['size']):
+            # adjust disk size to the minimum allowed by OS image, which will be used to spin off this Compute
+            validated_bdisk_size = image_facts['size']
+        else:
+            validated_bdisk_size =self.amodule.params['boot_disk']
+
+        # NOTE: due to a libvirt "feature", that impacts management of a VM created without any network interfaces,
+        # we create KVM VM in HALTED state.
+        # Consequently, if desired state is different from 'halted' or 'porewedoff", we should explicitly start it
+        # in the upstream code.
+        # See corresponding NOTE below for another place where this "feature" is redressed for.
+        #
+        # Once this "feature" is fixed, make sure VM is created according to the actual desired state
+        #
+        start_compute = False # change this once a workaround for the aforementioned libvirt "feature" is implemented 
+        if self.amodule.params['state'] in ('halted', 'poweredoff'):
+            start_compute = False
+        
+        if self.amodule.params['ssh_key'] and self.amodule.params['ssh_key_user'] and not self.amodule.params['ci_user_data']:
+            cloud_init_params = {'users': [
+                {"name": self.amodule.params['ssh_key_user'],
+                    "ssh-authorized-keys": [self.amodule.params['ssh_key']],
+                    "shell": '/bin/bash'}
+                ]}
+        elif self.amodule.params['ci_user_data']:
+            cloud_init_params = {}
+            for ci_param in self.amodule.params['ci_user_data']:
+                cloud_init_params.update(ci_param)
+        else:
+            cloud_init_params = None
+        # if we get through here, all parameters required to create new Compute instance should be at hand
+
+        # NOTE: KVM VM is created in HALTED state and must be explicitly started
+        self.comp_id = self.kvmvm_provision(rg_id=self.rg_id, 
+                                    comp_name=self.amodule.params['name'], arch=self.amodule.params['arch'],
+                                    cpu=self.amodule.params['cpu'], ram=self.amodule.params['ram'],
+                                    boot_disk=validated_bdisk_size,
+                                    image_id=image_facts['id'],
+                                    annotation=self.amodule.params['annotation'],
+                                    userdata=cloud_init_params,
+                                    sep_id=self.amodule.params['sep_id' ] if "sep_id" in self.amodule.params else None,
+                                    pool_name=self.amodule.params['pool'] if "pool" in self.amodule.params else None,
+                                    start_on_create=start_compute) 
+        self.comp_should_exist = True
+        
+        # Originally we would have had to re-read comp_info after VM was provisioned
+        # _, self.comp_info, _ = self.compute_find(self.comp_id)
+
+        # However, to avoid extra call to compute/get API we need to construct comp_info so that
+        # the below calls to compute_networks and compute_data_disks work properly.
+        # 
+        # Here we are imitating comp_info structure as if it has been returned by a real call 
+        # to API compute/get 
+        self.comp_info = {
+            'id':  self.comp_id,
+            'accountId': self.acc_id,
+            'status': "ENABLED",
+            'techStatus': "STOPPED",
+            'interfaces': [], # new compute instance is created network-less
+            'disks': [], # new compute instance is created without any data disks attached
+            'tags': {},
+            'affinityLabel': "",
+            'affinityRules': [],
+            'antiAffinityRules': [],
+        }
+
+        # 
+        # Compute was created
+        #
+        # Setup network connections
+        self.compute_networks(self.comp_info, self.amodule.params['networks']) 
+        # Next manage data disks
+        self.compute_data_disks(self.comp_info, self.amodule.params['data_disks'])
+
+        self.compute_affinity(self.comp_info,
+                              self.amodule.params['tag'],
+                              self.amodule.params['aff_rule'],
+                              self.amodule.params['aaff_rule'],
+                              label=self.amodule.params['affinity_label'],)
+        # NOTE: see NOTE above regarding libvirt "feature" and new VMs created in HALTED state
+        if self.amodule.params['state'] not in ('halted', 'poweredoff'):
+            self.compute_powerstate(self.comp_info, 'started')
+        
+        # read in Compute facts once more after all initial setup is complete
+        _, self.comp_info, _ = self.compute_find(comp_id=self.comp_id)
+
+        self.skip_final_get = True
+
+        return
+
+    def destroy(self):
+        """Compute destroy handler for VM management by decort_kvmvm module.
+        Note that this handler deletes the VM permanently together with all assigned disk resources.
+        """
+        self.compute_delete(comp_id=self.comp_id, permanently=True)
+        self.comp_info['status'] = 'DESTROYED'
+        self.comp_should_exist = False
+        return
+
+    def restore(self):
+        """Compute restore handler for Compute instance management by decort_kvmvm module.
+        Note that restoring Compute is only possible if it is in DELETED state. If called on a 
+        Compute instance in any other state, the method will throw an error and abort the execution
+        of the module.
+        """
+        self.compute_restore(comp_id=self.comp_id)
+        # TODO - do we need updated comp_info to manage port forwards and size after VM is restored?
+        _, self.comp_info, _ = self.compute_find(comp_id=self.comp_id)
+        self.modify()
+        self.comp_should_exist = True
+        return
+
+    def modify(self, arg_wait_cycles=0):
+        """Compute modify handler for KVM VM management by decort_kvmvm module.
+        This method is a convenience wrapper that calls individual Compute modification functions from
+        DECORT utility library (module).
+
+        Note that it does not modify power state of KVM VM.
+        """
+        self.compute_networks(self.comp_info, self.amodule.params['networks'])
+        self.compute_bootdisk_size(self.comp_info, self.amodule.params['boot_disk'])
+        self.compute_data_disks(self.comp_info, self.amodule.params['data_disks'])
+        self.compute_resize(self.comp_info,
+                            self.amodule.params['cpu'], self.amodule.params['ram'],
+                            wait_for_state_change=arg_wait_cycles)
+        
+        self.compute_affinity(self.comp_info,
+                              self.amodule.params['tag'],
+                              self.amodule.params['aff_rule'],
+                              self.amodule.params['aaff_rule'],
+                              label=self.amodule.params['affinity_label'])
+
+        return
+
+    def package_facts(self, check_mode=False):
+        """Package a dictionary of KVM VM facts according to the decort_kvmvm module specification. 
+        This dictionary will be returned to the upstream Ansible engine at the completion of decort_kvmvm 
+        module run.
+
+        @param check_mode: boolean that tells if this Ansible module is run in check mode
+
+        @return: dictionary of KVM VM facts, containing suffucient information to manage the KVM VM in
+        subsequent Ansible tasks.
+        """
+
+        ret_dict = dict(id=0,
+                    name="",
+                    arch="",
+                    cpu="",
+                    ram="",
+                    disk_size=0,
+                    data_disks=[],  # IDs of attached data disks; this list can be emty
+                    state="CHECK_MODE",
+                    tech_status="",
+                    account_id=0,
+                    rg_id=0,
+                    username="",
+                    password="",
+                    public_ips=[],  # direct IPs; this list can be empty
+                    private_ips=[], # IPs on ViNSes; usually, at least one IP is listed
+                    nat_ip="",      # IP of the external ViNS interface; can be empty.
+                    tags={},
+                    )
+
+        if check_mode or self.comp_info is None:
+            # if in check mode (or void facts provided) return immediately with the default values
+            return ret_dict
+
+        # if not self.comp_should_exist:
+        #    ret_dict['state'] = "ABSENT"
+        #    return ret_dict
+
+        ret_dict['id'] = self.comp_info['id']
+        ret_dict['name'] = self.comp_info['name']
+        ret_dict['arch'] = self.comp_info['arch']
+        ret_dict['state'] = self.comp_info['status']
+        ret_dict['tech_status'] = self.comp_info['techStatus']
+        ret_dict['account_id'] = self.comp_info['accountId']
+        ret_dict['rg_id'] = self.comp_info['rgId']
+        if self.comp_info['tags']:
+            ret_dict['tags'] = self.comp_info['tags']
+        # if the VM is an imported VM, then the 'accounts' list may be empty,
+        # so check for this case before trying to access login and passowrd values
+        if len(self.comp_info['osUsers']):
+            ret_dict['username'] = self.comp_info['osUsers'][0]['login']
+            ret_dict['password'] = self.comp_info['osUsers'][0]['password']
+
+        if self.comp_info['interfaces']:
+            # We need a list of all ViNSes in the account, which owns this Compute
+            # to find a ViNS, which may have active external connection. Then
+            # we will save external IP address of that connection in ret_dict['nat_ip']
+
+            for iface in self.comp_info['interfaces']:
+                if iface['connType'] == "VXLAN": # This is ViNS connection
+                    ret_dict['private_ips'].append(iface['ipAddress'])
+                    # if iface['connId']
+                    # Now we need to check if this ViNS has GW function and external connection.
+                    # If it does - save public IP address of GW VNF in ret_dict['nat_ip']
+                elif iface['connType'] == "VLAN": # This is direct external network connection
+                    ret_dict['public_ips'].append(iface['ipAddress'])
+            
+        ret_dict['cpu'] = self.comp_info['cpus']
+        ret_dict['ram'] = self.comp_info['ram']
+
+        ret_dict['image_id'] = self.comp_info['imageId']
+
+        for ddisk in self.comp_info['disks']:
+            if ddisk['type'] == 'B':
+                # if it is a boot disk - store its size
+                ret_dict['disk_size'] = ddisk['sizeMax']
+            elif ddisk['type'] == 'D':
+                # if it is a data disk - append its ID to the list of data disks IDs
+                ret_dict['data_disks'].append(ddisk['id'])
+
+        return ret_dict
+
+    @staticmethod
+    def build_parameters():
+        """Build and return a dictionary of parameters expected by decort_kvmvm module in a form
+        accepted by AnsibleModule utility class.
+        This dictionary is then used y AnsibleModule class instance to parse and validate parameters
+        passed to the module from the playbook.
+        """
+
+        return dict(
+            account_id=dict(type='int', required=False, default=0),
+            account_name=dict(type='str', required=False, default=''),
+            annotation=dict(type='str',
+                            default='',
+                            required=False),
+            app_id=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_APP_ID'])),
+            app_secret=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_APP_SECRET']),
+                            no_log=True),
+            arch=dict(type='str', choices=['X86_64', 'PPC64_LE'], default='X86_64'),
+            authenticator=dict(type='str',
+                               required=True,
+                               choices=['legacy', 'oauth2', 'jwt']),
+            boot_disk=dict(type='int', required=False),
+            sep_id=dict(type='int', required=False),
+            pool=dict(type='str', required=False),
+            controller_url=dict(type='str', required=True),
+            # count=dict(type='int', required=False, default=1),
+            cpu=dict(type='int', required=False),
+            # datacenter=dict(type='str', required=False, default=''),
+            data_disks=dict(type='list', default=[], required=False), # list of integer disk IDs
+            id=dict(type='int', required=False, default=0),
+            image_id=dict(type='int', required=False),
+            image_name=dict(type='str', required=False),
+            jwt=dict(type='str',
+                     required=False,
+                     fallback=(env_fallback, ['DECORT_JWT']),
+                     no_log=True),
+            name=dict(type='str'),
+            networks=dict(type='list', default=[], required=False), # list of dictionaries
+            oauth2_url=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_OAUTH2_URL'])),
+            password=dict(type='str',
+                          required=False,
+                          fallback=(env_fallback, ['DECORT_PASSWORD']),
+                          no_log=True),
+            ram=dict(type='int', required=False),
+            rg_id=dict(type='int', default=0),
+            rg_name=dict(type='str', default=""),
+            ssh_key=dict(type='str', required=False),
+            ssh_key_user=dict(type='str', required=False),
+            tag=dict(type='dict', required=False),
+            affinity_label=dict(type='str', required=False),
+            aff_rule=dict(type='list', required=False),
+            aaff_rule=dict(type='list', required=False),
+            ci_user_data=dict(type='list',elements='dict', required=False),
+            state=dict(type='str',
+                       default='present',
+                       choices=['absent', 'paused', 'poweredoff', 'halted', 'poweredon', 'present', 'check']),
+            tags=dict(type='str', required=False),
+            user=dict(type='str',
+                      required=False,
+                      fallback=(env_fallback, ['DECORT_USER'])),
+            verify_ssl=dict(type='bool', required=False, default=True),
+            # wait_for_ip_address=dict(type='bool', required=False, default=False),
+            workflow_callback=dict(type='str', required=False),
+            workflow_context=dict(type='str', required=False),
+        )
+
+# Workflow digest:
+# 1) authenticate to DECORT controller & validate authentication by issuing API call - done when creating DECSController
+# 2) check if the VM with the specified id or rg_name:name exists
+# 3) if VM does not exist, check if there is enough resources to deploy it in the target account / vdc
+# 4) if VM exists: check desired state, desired configuration -> initiate action accordingly
+# 5) VM does not exist: check desired state -> initiate action accordingly
+#       - create VM: check if target VDC exists, create VDC as necessary, create VM
+#       - delete VM: delete VM
+#       - change power state: change as required
+#       - change guest OS state: change as required
+# 6) report result to Ansible
+
+def main():
+    module_parameters = decort_kvmvm.build_parameters()
+
+    amodule = AnsibleModule(argument_spec=module_parameters,
+                            supports_check_mode=True,
+                            mutually_exclusive=[
+                                ['oauth2', 'password'],
+                                ['password', 'jwt'],
+                                ['jwt', 'oauth2'],
+                            ],
+                            required_together=[
+                                ['app_id', 'app_secret'],
+                                ['user', 'password'],
+                            ],
+                            required_one_of=[
+                                ['id', 'name'],
+                            ],
+                            )
+
+    # Initialize DECORT KVM VM instance object
+    # This object does not necessarily represent an existing KVM VM
+    subj = decort_kvmvm(amodule)
+
+    # handle state=check before any other logic
+    if amodule.params['state'] == 'check':
+        subj.result['changed'] = False
+        if subj.comp_id:
+            # Compute is found - package facts and report success to Ansible
+            subj.result['failed'] = False
+            # _, subj.comp_info, _ = subj.compute_find(comp_id=subj.comp_id)
+            # _, rg_facts = subj.rg_find(arg_account_id=0, arg_rg_id=subj.rg_id)
+            subj.result['facts'] = subj.package_facts(amodule.check_mode)
+            amodule.exit_json(**subj.result)
+            # we exit the module at this point
+        else:
+            subj.result['failed'] = True
+            subj.result['msg'] = ("Cannot locate Compute name '{}'. Other arguments are: Compute ID {}, "
+                                  "RG name '{}', RG ID {}, Account '{}'.").format(amodule.params['name'],
+                                                                                amodule.params['id'],
+                                                                                amodule.params['rg_name'],
+                                                                                amodule.params['rg_id'],
+                                                                                amodule.params['account_name'])
+            amodule.fail_json(**subj.result)
+            pass
+
+    if subj.comp_id:
+        if subj.comp_info['status'] in ("DISABLED", "MIGRATING", "DELETING", "DESTROYING", "ERROR", "REDEPLOYING"):
+            # cannot do anything on the existing Compute in the listed states
+            subj.error() # was subj.nop()
+        elif subj.comp_info['status'] in ("ENABLED", "DISABLED"):
+            if amodule.params['state'] == 'absent':
+                subj.destroy()
+            elif amodule.params['state'] in ('present', 'paused', 'poweredon', 'poweredoff', 'halted'):
+                subj.compute_powerstate(subj.comp_info, amodule.params['state'])
+                subj.modify(arg_wait_cycles=7)
+        elif subj.comp_info['status'] == "DELETED":
+            if amodule.params['state'] in ('present', 'poweredon'):
+                # TODO - check if restore API returns VM ID (similarly to VM create API)
+                subj.compute_restore(comp_id=subj.comp_id)
+                # TODO - do we need updated comp_info to manage port forwards and size after VM is restored?
+                _, subj.comp_info, _ = subj.compute_find(comp_id=subj.comp_id)
+                subj.modify()
+            elif amodule.params['state'] == 'absent':
+                # subj.nop()
+                # subj.comp_should_exist = False
+                subj.destroy()
+            elif amodule.params['state'] in ('paused', 'poweredoff', 'halted'):
+                subj.error()
+        elif subj.comp_info['status'] == "DESTROYED":
+            if amodule.params['state'] in ('present', 'poweredon', 'poweredoff', 'halted'):
+                subj.create() # this call will also handle data disk & network connection
+            elif amodule.params['state'] == 'absent':
+                subj.nop()
+                subj.comp_should_exist = False
+            elif amodule.params['state'] == 'paused':
+                subj.error()
+    else:
+        # Preexisting Compute of specified identity was not found.
+        # If requested state is 'absent' - nothing to do
+        if amodule.params['state'] == 'absent':
+            subj.nop()
+        elif amodule.params['state'] in ('present', 'poweredon', 'poweredoff', 'halted'):
+            subj.create() # this call will also handle data disk & network connection
+        elif amodule.params['state'] == 'paused':
+            subj.error()
+
+    if subj.result['failed']:
+        amodule.fail_json(**subj.result)
+    else:
+        # prepare Compute facts to be returned as part of decon.result and then call exit_json(...)
+        rg_facts = None
+        if subj.comp_should_exist:
+            if subj.result['changed'] and not subj.skip_final_get:
+                # There were changes to the Compute - refresh Compute facts.
+                _, subj.comp_info, _ = subj.compute_find(comp_id=subj.comp_id)
+            #
+            # We no longer need to re-read RG facts, as all network info is now available inside
+            # compute structure
+            # _, rg_facts = subj.rg_find(arg_account_id=0, arg_rg_id=subj.rg_id)
+        subj.result['facts'] = subj.package_facts(amodule.check_mode)
+        amodule.exit_json(**subj.result)
+
+
+if __name__ == "__main__":
+    main()

library/decort_lb.py

@@ -0,0 +1,328 @@
+#!/usr/bin/python
+#
+# Digital Enegry Cloud Orchestration Technology (DECORT) modules for Ansible
+# Copyright: (c) 2018-2023 Digital Energy Cloud Solutions LLC
+#
+# Apache License 2.0 (see http://www.apache.org/licenses/LICENSE-2.0.txt)
+#
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+DOCUMENTATION = '''
+    TODO
+'''
+
+EXAMPLES = '''
+    TODO
+'''
+
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.basic import env_fallback
+
+from ansible.module_utils.decort_utils import *
+
+class decort_lb(DecortController):
+    def __init__(self,arg_amodule) -> None:
+        super(decort_lb,self).__init__(arg_amodule)    
+
+        self.lb_id = 0
+        self.lb_facts = None
+        self.vins_id = 0
+        self.vins_facts = None
+        self.rg_id = 0
+        self.rg_facts = None
+        self.acc_id = 0
+        self.acc_facts = None
+        self.default_server_check = "enabled"
+        self.default_alg = "roundrobin"
+        self.default_settings = {
+                "downinter": 10000,
+                "fall": 2,
+                "inter": 5000,
+                "maxconn": 250,
+                "maxqueue": 256,
+                "rise": 2,
+                "slowstart": 60000,
+                "weight": 100,
+        }        
+        if arg_amodule.params['lb_id']:
+            self.lb_id, self.lb_facts = self.lb_find(arg_amodule.params['lb_id'])
+            if not self.lb_id:
+                self.result['failed'] = True
+                self.result['msg'] = "Specified LB ID {} not found."\
+                .format(arg_amodule.params['lb _id'])
+                self.fail_json(**self.result)
+            self.acc_id = self.lb_facts['accountId']
+            self.rg_id = self.lb_facts['rgId']
+            self.vins_id = self.lb_facts['vinsId']
+            return
+                
+        if arg_amodule.params['rg_id']:
+            self.rg_id, self.rg_facts = self.rg_find(0,arg_amodule.params['rg_id'], arg_rg_name="")
+            if not self.rg_id:
+                self.result['failed'] = True
+                self.result['msg'] = "Specified RG ID {} not found.".format(arg_amodule.params['vins_id'])
+                self.fail_json(**self.result)
+
+        if arg_amodule.params['vins_id']:
+            self.vins_id, self.vins_facts = self.vins_find(arg_amodule.params['vins_id'])
+            if not self.vins_id:
+                self.result['failed'] = True
+                self.result['msg'] = "Specified ViNS ID {} not found.".format(arg_amodule.params['vins_id'])
+                self.fail_json(**self.result)
+
+        elif arg_amodule.params['account_id'] or arg_amodule.params['account_name'] != "":
+            
+            if arg_amodule.params['rg_name']:
+                self.result['failed'] = True
+                self.result['msg'] = ("RG name must be specified with account present")
+                self.fail_json(**self.result)
+            self.acc_id, self.acc_facts = self.account_find(arg_amodule.params['account_name'], 
+                                                            arg_amodule.params['account_id'])
+            if not self.acc_id:
+                self.result['failed'] = True
+                self.result['msg'] = ("Current user does not have access to the requested account "
+                                    "or non-existent account specified.")
+                self.fail_json(**self.result)
+            self.rg_id, self.rg_facts = self.rg_find(self._acc_id,0, arg_rg_name=arg_amodule.params['rg_name'])
+        
+        if self.rg_id and self.vins_id:
+            self.lb_id, self.lb_facts = self.lb_find(0,arg_amodule.params['lb_name'],self.rg_id)
+        return
+    
+    def create(self):
+        self.lb_id = self.lb_provision(self.amodule.params['lb_name'],
+                                    self.rg_id,self.vins_id,
+                                    self.amodule.params['ext_net_id'],
+                                    self.amodule.params['annotation'])
+        if self.amodule.params['backends'] or self.amodule.params['frontends']:
+            self.lb_id, self.lb_facts = self.lb_find(0,self.amodule.params['lb_name'],self.rg_id)
+            self.lb_update(
+                self.lb_facts['backends'],
+                self.lb_facts['frontends'],
+                self.amodule.params['backends'],
+                self.amodule.params['servers'],
+                self.amodule.params['frontends']
+            )        
+        return
+    
+    def action(self,d_state='',restore=False):
+        if restore == True:
+            self.lb_restore(arg_vins_id=self.lb_id)
+            self.lb_state(self.vins_facts, 'enabled')
+            self.lb_facts['status'] = "ENABLED"
+            self.lb_facts['techStatus'] = "STARTED"    
+        
+        self.lb_update(
+            self.lb_facts['backends'],
+            self.lb_facts['frontends'],
+            self.amodule.params['backends'],
+            self.amodule.params['servers'],
+            self.amodule.params['frontends']
+        )
+
+        if d_state != '':
+            self.lb_state(self.lb_facts, d_state)
+        return
+
+    def delete(self):
+        self.lb_delete(self.lb_id, self.amodule.params['permanently'])
+        self.lb_facts['status'] = 'DESTROYED'
+        return
+    def nop(self):
+        """No operation (NOP) handler for LB management by decort_lb module.
+        This function is intended to be called from the main switch construct of the module
+        when current state -> desired state change logic does not require any changes to
+        the actual LB state.
+        """
+        self.result['failed'] = False
+        self.result['changed'] = False
+        if self.lb_id:
+            self.result['msg'] = ("No state change required for LB  ID {} because of its "
+                                   "current status '{}'.").format(self.lb_id, self.vins_facts['status'])
+        else:
+            self.result['msg'] = ("No state change to '{}' can be done for "
+                                  "non-existent LB instance.").format(self.amodule.params['state'])
+        return
+    def error(self):
+        self.result['failed'] = True
+        self.result['changed'] = False
+        if self.vins_id:
+            self.result['failed'] = True
+            self.result['changed'] = False
+            self.result['msg'] = ("Invalid target state '{}' requested for LB ID {} in the "
+                                    "current status '{}'").format(self.lb_id,
+                                                                    self.amodule.params['state'],
+                                                                    self.lb_facts['status'])
+        else:
+            self.result['failed'] = True
+            self.result['changed'] = False
+            self.result['msg'] = ("Invalid target state '{}' requested for non-existent "
+                                   "LB name '{}'").format(self.amodule.params['state'],
+                                                            self.amodule.params['lb_name'])   
+        return
+    def package_facts(self, arg_check_mode=False):
+        """Package a dictionary of LB facts according to the decort_lb module specification. 
+        This dictionary will be returned to the upstream Ansible engine at the completion of 
+        the module run.
+
+        @param arg_check_mode: boolean that tells if this Ansible module is run in check mode
+        """
+
+        ret_dict = dict(id=0,
+                        name="none",
+                        state="CHECK_MODE",
+                        )
+
+        if arg_check_mode:
+            # in check mode return immediately with the default values
+            return ret_dict
+
+        if self.vins_facts is None:
+            # if void facts provided - change state value to ABSENT and return
+            ret_dict['state'] = "ABSENT"
+            return ret_dict
+
+        ret_dict['id'] = self.lb_facts['id']
+        ret_dict['name'] = self.lb_facts['name']
+        ret_dict['state'] = self.lb_facts['status']
+        #ret_dict['account_id'] = self.lb_facts['accountId']
+        ret_dict['rg_id'] = self.lb_facts['rgId']
+        ret_dict['gid'] = self.lb_facts['gid']
+        if self.amodule.params['state']!="absent":
+            ret_dict['backends'] = self.lb_facts['backends']
+            ret_dict['frontends'] = self.lb_facts['frontends']
+        return ret_dict
+    @staticmethod
+    def build_parameters():
+        """Build and return a dictionary of parameters expected by decort_vins module in a form accepted
+        by AnsibleModule utility class."""
+
+        return dict(
+            account_id=dict(type='int', required=False),
+            account_name=dict(type='str', required=False, default=''),
+            annotation=dict(type='str', required=False, default='Managed by Ansible module decort_lb'),
+            app_id=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_APP_ID'])),
+            app_secret=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_APP_SECRET']),
+                            no_log=True),
+            authenticator=dict(type='str',
+                            required=True,
+                            choices=['legacy', 'oauth2', 'jwt']),
+            controller_url=dict(type='str', required=True),
+            # datacenter=dict(type='str', required=False, default=''),
+            ext_net_id=dict(type='int', required=False, default=-1),
+            ext_ip_addr=dict(type='str', required=False, default=''),
+            jwt=dict(type='str',
+                    required=False,
+                    fallback=(env_fallback, ['DECORT_JWT']),
+                    no_log=True),
+            oauth2_url=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_OAUTH2_URL'])),
+            password=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_PASSWORD']),
+                        no_log=True),
+            state=dict(type='str',
+                    default='present',
+                    choices=['absent', 'disabled', 'enabled', 'present','restart']),
+            user=dict(type='str',
+                    required=False,
+                    fallback=(env_fallback, ['DECORT_USER'])),
+            rg_id=dict(type='int', required=False, default=0),
+            rg_name=dict(type='str', required=False, default=''),
+            vins_name=dict(type='str', required=False, default=''),
+            vins_id=dict(type='int', required=False, default=0),
+            verify_ssl=dict(type='bool', required=False, default=True),
+            lb_id=dict(type='int', required=False, default=0),
+            lb_name=dict(type='str', required=True),
+            backends=dict(type='list',required=False,default=[]),
+            frontends=dict(type='list',required=False,default=[]),
+            servers=dict(type='list',required=False,default=[]),
+            permanently=dict(type='bool', required=False, default=False),
+            workflow_callback=dict(type='str', required=False),
+            workflow_context=dict(type='str', required=False),
+        )
+
+def main():
+    module_parameters = decort_lb.build_parameters()
+
+    amodule = AnsibleModule(argument_spec=module_parameters,
+                            supports_check_mode=True,
+                            mutually_exclusive=[
+                                ['oauth2', 'password'],
+                                ['password', 'jwt'],
+                                ['jwt', 'oauth2'],
+                            ],
+                            required_together=[
+                                ['app_id', 'app_secret'],
+                                ['user', 'password']
+                            ],
+                            required_one_of=[
+                                ['rg_id','rg_name'],
+                                ['lb_id','lb_name'],
+                                ['vins_id','vins_name']
+                            ]
+                            )
+    decon = decort_lb(amodule)
+    if decon.lb_id:
+        if decon.lb_facts['status'] in ["MODELED", "DISABLING", "ENABLING", "DELETING","DESTROYING","RESTORING"]:
+            decon.result['failed'] = True
+            decon.result['changed'] = False
+            decon.result['msg'] = ("No change can be done for existing LB ID {} because of its current "
+                                "status '{}'").format(decon.lb_id, decon.lb_facts['status'])
+        elif decon.lb_facts['status'] == "DISABLED":
+                if amodule.params['state'] == 'absent':
+                    decon.delete()
+                elif amodule.params['state'] in ('present', 'disabled'):
+                    decon.action()
+                elif amodule.params['state'] == 'enabled':
+                    decon.action('enabled')
+        elif decon.lb_facts['status'] in ["CREATED", "ENABLED"]:
+                if amodule.params['state'] == 'absent':
+                    decon.delete()
+                elif amodule.params['state'] in ('present', 'enabled'):
+                    decon.action()
+                elif amodule.params['state'] == 'disabled':
+                    decon.action('disabled')
+                elif amodule.params['state'] in ('stopped', 'started','restart'):
+                    decon.action(amodule.params['state'])
+        elif decon.lb_facts['status'] == "DELETED":
+            if amodule.params['state'] in ['present', 'enabled']:
+                decon.action(restore=True)
+            elif amodule.params['state'] == 'absent':
+                decon.delete()
+            elif amodule.params['state'] == 'disabled':
+                decon.error()
+        elif decon.lb_facts['status'] == "DESTROYED":
+            if amodule.params['state'] in ('present', 'enabled'):
+                decon.create()
+            elif amodule.params['state'] == 'absent':
+                decon.nop()
+            elif amodule.params['state'] == 'disabled':
+                decon.error()
+    else:
+        if amodule.params['state'] == 'absent':
+            decon.nop()
+        elif amodule.params['state'] in ('present', 'enabled'):
+            decon.create()
+        elif amodule.params['state'] == 'disabled':
+            decon.error()
+
+    if decon.result['failed']:
+        amodule.fail_json(**decon.result)
+    else:
+        if decon.result['changed'] and amodule.params['state'] != 'absent':
+            _, decon.lb_facts = decon.lb_find(decon.lb_id)
+        if decon.lb_id:
+            decon.result['facts'] = decon.package_facts(amodule.check_mode)
+        amodule.exit_json(**decon.result)
+if __name__ == "__main__":
+    main()

library/decort_osimage.py

@@ -0,0 +1,573 @@
+#!/usr/bin/python
+#
+# Digital Enegry Cloud Orchestration Technology (DECORT) modules for Ansible
+# Copyright: (c) 2018-2021 Digital Energy Cloud Solutions LLC
+#
+# Apache License 2.0 (see http://www.apache.org/licenses/LICENSE-2.0.txt)
+#
+
+#
+# Author: Sergey Shubin (sergey.shubin@digitalenergy.online)
+#
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+DOCUMENTATION = '''
+---
+module: decort_osimage
+short_description: Locate OS image in DCORT cloud by its name and return image ID
+description: >
+     This module can be used to obtain image ID of an OS image in DECORT cloud to use with subsequent calls to
+     decort_vm module for batch VM provisioning. It will speed up VM creation and save a bunch of extra calls to
+     DECORT cloud controller on each VM creation act.
+
+version_added: "2.2"
+author:
+     - Sergey Shubin <sergey.shubin@digitalenergy.online>
+requirements:
+     - python >= 2.6
+     - PyJWT Python module
+     - requests Python module
+     - netaddr Python module
+     - decort_utils utility library (module)
+     - DECORT cloud platform version 3.6.1 or higher.
+notes:
+     - Environment variables can be used to pass selected parameters to the module, see details below.
+     - Specified Oauth2 provider must be trusted by the DECORT cloud controller on which JWT will be used.
+     - 'Similarly, JWT supplied in I(authenticator=jwt) mode should be received from Oauth2 provider trusted by
+       the DECORT cloud controller on which this JWT will be used.'
+options:
+    app_id:
+        description:
+        - 'Application ID for authenticating to the DECORT controller when I(authenticator=oauth2).'
+        - 'Required if I(authenticator=oauth2).'
+        - 'If not found in the playbook or command line arguments, the value will be taken from DECORT_APP_ID
+           environment variable.'
+        required: no
+    app_secret:
+        description:
+        - 'Application API secret used for authenticating to the DECORT controller when I(authenticator=oauth2).'
+        - This parameter is required when I(authenticator=oauth2) and ignored in other modes.
+        - 'If not found in the playbook or command line arguments, the value will be taken from DECORT_APP_SECRET
+           environment variable.'
+        required: no
+    authenticator:
+        description:
+        - Authentication mechanism to be used when accessing DECORT controller and authorizing API call.
+        default: jwt
+        choices: [ jwt, oauth2, legacy ]
+        required: yes
+    controller_url:
+        description:
+        - URL of the DECORT controller that will be contacted to obtain OS image details.
+        - 'This parameter is always required regardless of the specified I(authenticator) type.'
+        required: yes
+    image_name:
+        description:
+        - Name of the OS image to use. Module will return the ID of this image.
+        - 'The specified image name will be looked up in the target DECORT controller and error will be generated
+        - if no matching image is found.'
+        required: yes
+    jwt:
+        description:
+        - 'JWT (access token) for authenticating to the DECORT controller when I(authenticator=jwt).'
+        - 'This parameter is required if I(authenticator=jwt) and ignored for other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_JWT environment variable.
+        required: no
+    oauth2_url:
+        description:
+        - 'URL of the oauth2 authentication provider to use when I(authenticator=oauth2).'
+        - 'This parameter is required when when I(authenticator=oauth2).'
+        - If not specified in the playbook, the value will be taken from DECORT_OAUTH2_URL environment variable.
+    password:
+        description:
+        - 'Password for authenticating to the DECORT controller when I(authenticator=legacy).'
+        - 'This parameter is required if I(authenticator=legacy) and ignored in other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_PASSWORD environment variable.
+        required: no
+    pool:
+        description:
+        - 'Name of the storage pool, where the image should be found.'
+        - 'Omit this option if no matching by pool name is required. The first matching image will be returned."
+        required: no
+    sep_id:
+        description:
+        - 'ID of the SEP (Storage End-point Provider), where the image should be found.'
+        - 'Omit this option if no matching by SEP ID is required. The first matching image will be returned."
+        required: no
+    account_name:
+        description:
+        - 'Name of the account for which the specified OS image will be looked up.'
+        - 'This parameter is required for listing OS images.'
+        required: yes
+    user:
+        description:
+        - 'Name of the legacy user for authenticating to the DECORT controller when I(authenticator=legacy).'
+        - 'This parameter is required when I(authenticator=legacy) and ignored for other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_USER environment variable.
+        required: no
+    verify_ssl:
+        description:
+        - 'Controls SSL verification mode when making API calls to DECORT controller. Set it to False if you
+         want to disable SSL certificate verification. Intended use case is when you run module in a trusted
+         environment that uses self-signed certificates. Note that disabling SSL verification in any other
+         scenario can lead to security issues, so please know what you are doing.'
+        default: True
+        required: no
+    workflow_callback:
+        description:
+        - 'Callback URL that represents an application, which invokes this module (e.g. up-level orchestrator or
+          end-user portal) and may except out-of-band updates on progress / exit status of the module run.'
+        - API call at this URL will be used to relay such information to the application.
+        - 'API call payload will include module-specific details about this module run and I(workflow_context).'
+        required: no
+    workflow_context:
+        description:
+        - 'Context data that will be included into the payload of the API call directed at I(workflow_callback) URL.'
+        - 'This context data is expected to uniquely identify the task carried out by this module invocation so
+           that up-level orchestrator could match returned information to the its internal entities.'
+        required: no
+    account_name:
+        description:
+        - 'Account name. Used to get a unique integer account ID.'
+        required: no
+    virt_id:
+        description:
+        - 'A unique integer identifier for the virtual image.'
+        - 'Can be used to obtain information about a virtual image, as well as to create a virtual image and 
+        - bind another operating system image to it.'
+        required: no
+    virt_name:
+        description:
+        - 'Name of the virtual image. Used to get the `virt_id`, and later information about the virtual image, 
+        - as well as to create a virtual image and bind another operating system image to it.'
+        required: no
+    state:
+        description:
+        - 'The state of the images. If set to present, operating system images will be created to which 
+        - the account specified in `account_Id` or `account_name` is bound. If set to absent, they will be removed.
+        required: no
+    drivers:
+        description:
+        - 'A list of compute types (eg virtual servers) that are appropriate for the operating system image. 
+        - Note: `KVM_X86`. Used when creating an operating system image.'
+        required: no
+    architecture:
+        description:
+        - 'Binary architecture of the image. Note. `X86_64` or `PPC64_LE`. Used when creating 
+        -an operating system image.'
+        required: no
+    imagetype:
+        description:
+        - 'Image type. `linux`, `windows` or `other`. The default is `linux`. Used when creating
+        - an operating system image.'
+        required: no
+    boottype:
+        description:
+        - 'Image upload type. `bios` or `uefi`. The default is `uefi`. Used when creating an operating 
+        -system image.'
+        required: no
+    url:
+        description:
+        - 'Uniform resource locator (URL) pointing to the iso image of the operating system. Used when 
+        -creating an operating system image.'
+        required: no
+    sepId:
+        description:
+        - 'The unique integer ID of the storage provider endpoint. Specified in pair with `poolName`. 
+        - Used when creating an operating system image.'
+        required: no
+    poolName:
+        description:
+        - 'The pool in which the image will be created. Specified in pair with `sepId`. Used when creating
+        - an operating system image.'
+        required: no
+    hotresize:
+        description:
+        - 'Whether the image supports "hot" resizing. The default is `false`. Used when creating an operating
+        - system image.'
+        required: no
+    image_username:
+        description:
+        - 'An optional username for the image. Used when creating an operating system image.'
+        required: no
+    image_password:
+        description:
+        - 'An optional password for the image. Used when creating an operating system image. Used when creating
+        - an operating system image.'
+        required: no
+    usernameDL:
+        description:
+        - 'The username for loading the binary media. Used in conjunction with `passwordDL`. Used when creating
+        - an operating system image'
+        required: no
+    passwordDL:
+        description:
+        - 'The password for loading the binary media. Used in conjunction with `usernameDL`. Used when creating
+        - an operating system image.'
+        required: no
+    permanently:
+        description:
+        - 'Whether to permanently delete the image. Used when deleting an image. The default is false.'
+        required: no
+
+'''
+
+EXAMPLES = '''
+  - name: create_osimage 
+    decort_osimage:
+      authenticator: oauth2
+      verify_ssl: False
+      controller_url: "https://ds1.digitalenergy.online"
+      state: present
+      image_name: "alpine_linux3.14.0"
+      account_Id: 12345
+      url: "https://dl-cdn.alpinelinux.org/alpine/v3.14/releases/x86_64/alpine-virt-3.14.0-x86_64.iso"
+      boottype: "uefi"
+      imagetype: "linux"
+      hotresize: False
+      image_username: "test"
+      image_password: "p@ssw0rd"
+      usernameDL: "testDL"
+      passwordDL: "p@ssw0rdDL"
+      architecture: "X86_64"
+      drivers: "KVM_X86"
+    delegate_to: localhost
+    register: osimage
+
+  - name: get_osimage 
+    decort_osimage:
+      authenticator: oauth2
+      controller_url: "https://ds1.digitalenergy.online"
+      image_name: "alpine_linux_3.14.0"
+      account_Id: 12345
+    delegate_to: localhost
+    register: osimage
+
+  - name: create_virtual_osimage 
+    decort_osimage:
+      authenticator: oauth2
+      controller_url: "https://ds1.digitalenergy.online"
+      image_name: "alpine_linux_3.14.0"
+      virt_name: "alpine_last"
+    delegate_to: localhost
+    register: osimage
+
+  - name: rename_osimage 
+    decort_osimage:
+      authenticator: oauth2
+      controller_url: "https://ds1.digitalenergy.online"
+      image_name: "alpine_linux_3.14.0v2.0"
+      image_id: 54321
+    delegate_to: localhost
+    register: osimage
+
+
+
+'''
+
+RETURN = '''
+facts:
+    description: facts about the specified OS image
+    returned: always
+    type: dict
+    sample:
+      facts:
+        id: 100
+        linkto: 80
+        name: "Ubuntu 16.04 v1.0"
+        size: 3
+        sep_id: 1
+        pool: "vmstore"
+        type: Linux
+        arch: x86_64
+        state: CREATED
+'''
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.basic import env_fallback
+
+from ansible.module_utils.decort_utils import *
+
+class decort_osimage(DecortController):
+    def __init__(self,amodule):
+        super(decort_osimage, self).__init__(amodule)
+
+        self.validated_image_id = 0
+        self.validated_virt_image_id = 0
+        self.validated_image_name = amodule.params['image_name']
+        self.validated_virt_image_name = None
+        self.validated_virt_image_id = amodule.params['virt_id']
+        if amodule.params['account_name']:
+            self.validated_account_id, _ = self.account_find(amodule.params['account_name'])
+        else:
+            self.validated_account_id = amodule.params['account_Id']
+        
+        if self.validated_account_id == 0:
+            # we failed either to find or access the specified account - fail the module
+            self.result['failed'] = True
+            self.result['changed'] = False
+            self.result['msg'] = ("Cannot find account '{}'").format(amodule.params['account_name'])
+            amodule.fail_json(**self.result)
+
+
+        if amodule.params['image_id'] != 0 and amodule.params['image_name']:
+            self.validated_image_id = amodule.params['image_id']
+            if amodule.params['image_name']:
+                decort_osimage.decort_image_rename(self,amodule)
+                self.result['msg'] = ("Image renamed successfully")
+
+
+
+    def decort_image_find(self, amodule):
+        # function that finds the OS image
+        image_id, image_facts = self.image_find(image_id=amodule.params['image_id'], image_name=self.validated_image_name,
+                                                account_id=self.validated_account_id, rg_id=0,
+                                                sepid=amodule.params['sep_id'],
+                                                pool=amodule.params['pool'])
+        return image_id, image_facts
+
+    def decort_virt_image_find(self, amodule):
+        # function that finds a virtual image
+        image_id, image_facts = self.virt_image_find(image_id=amodule.params['virt_id'],
+                                                    account_id=self.validated_account_id, rg_id=0,
+                                                    sepid=amodule.params['sep_id'],
+                                                    virt_name=amodule.params['virt_name'],
+                                                    pool=amodule.params['pool'])
+        return image_id, image_facts
+
+
+
+    def decort_image_create(self,amodule):
+        # function that creates OS image
+        image_facts = self.image_create(img_name=self.validated_image_name, 
+                        url=amodule.params['url'], 
+                        gid=amodule.params['gid'], 
+                        boottype=amodule.params['boottype'],
+                        imagetype=amodule.params['imagetype'],
+                        hotresize=amodule.params['hotresize'],
+                        username=amodule.params['image_username'],
+                        password=amodule.params['image_password'],
+                        account_Id=amodule.params['account_Id'],
+                        usernameDL=amodule.params['usernameDL'],
+                        passwordDL=amodule.params['passwordDL'],
+                        sepId=amodule.params['sepId'],
+                        poolName=amodule.params['poolName'],
+                        architecture=amodule.params['architecture'],
+                        drivers=amodule.params['drivers'])
+        self.result['changed'] = True
+        return image_facts
+
+    def decort_virt_image_link(self,amodule):
+        # function that links an OS image to a virtual one
+        self.virt_image_link(imageId=self.validated_virt_image_id, targetId=self.validated_image_id)
+        image_id, image_facts = decort_osimage.decort_virt_image_find(self, amodule)
+        self.result['facts'] = decort_osimage.decort_osimage_package_facts(image_facts, amodule.check_mode)
+        self.result['msg'] = ("Image '{}' linked to virtual image '{}'").format(self.validated_image_id,
+                                                                                decort_osimage.decort_osimage_package_facts(image_facts)['id'],)
+        return image_id, image_facts
+    
+    def decort_image_delete(self,amodule):
+        # function that removes an image
+        self.image_delete(imageId=amodule.image_id_delete, permanently=amodule.params['permanently'])
+        self.result['changed'] = True
+        self.result['msg'] = ("Image '{}' deleted").format(amodule.image_id_delete)
+
+    def decort_virt_image_create(self,amodule):
+        # function that creates a virtual image
+        image_facts = self.virt_image_create(name=amodule.params['virt_name'], targetId=self.validated_image_id)
+        image_id, image_facts = decort_osimage.decort_virt_image_find(self, amodule)
+        self.result['facts'] = decort_osimage.decort_osimage_package_facts(image_facts, amodule.check_mode)
+        return image_id, image_facts
+    
+    def decort_image_rename(self,amodule):
+        # image renaming function
+        image_facts = self.image_rename(imageId=self.validated_image_id, name=amodule.params['image_name'])
+        self.result['msg'] = ("Image renamed successfully")
+        image_id, image_facts = decort_osimage.decort_image_find(self, amodule)
+        return image_id, image_facts
+
+
+    def decort_osimage_package_facts(arg_osimage_facts, arg_check_mode=False):
+        """Package a dictionary of OS image according to the decort_osimage module specification. This
+        dictionary will be returned to the upstream Ansible engine at the completion of the module run.
+
+        @param arg_osimage_facts: dictionary with OS image facts as returned by API call to .../images/list
+        @param arg_check_mode: boolean that tells if this Ansible module is run in check mode.
+
+        @return: dictionary with OS image specs populated from arg_osimage_facts.
+        """
+
+        ret_dict = dict(id=0,
+                        name="none",
+                        size=0,
+                        type="none",
+                        state="CHECK_MODE",                        )
+
+        if arg_check_mode:
+            # in check mode return immediately with the default values
+            return ret_dict
+
+        if arg_osimage_facts is None:
+            # if void facts provided - change state value to ABSENT and return
+            ret_dict['state'] = "ABSENT"
+            return ret_dict
+    
+        ret_dict['id'] = arg_osimage_facts['id']
+        ret_dict['name'] = arg_osimage_facts['name']
+        ret_dict['size'] = arg_osimage_facts['size']
+        ret_dict['type'] = arg_osimage_facts['type']
+        # ret_dict['arch'] = arg_osimage_facts['architecture']
+        ret_dict['sep_id'] = arg_osimage_facts['sepId']
+        ret_dict['pool'] = arg_osimage_facts['pool']
+        ret_dict['state'] = arg_osimage_facts['status']
+        ret_dict['linkto'] = arg_osimage_facts['linkTo']
+        ret_dict['accountId'] = arg_osimage_facts['accountId']
+        return ret_dict
+
+
+    def decort_osimage_parameters():
+        """Build and return a dictionary of parameters expected by decort_osimage module in a form accepted
+        by AnsibleModule utility class."""
+
+        return dict(
+            app_id=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_APP_ID'])),
+            app_secret=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_APP_SECRET']),
+                            no_log=True),
+            authenticator=dict(type='str',
+                               required=True,
+                               choices=['legacy', 'oauth2', 'jwt']),
+            controller_url=dict(type='str', required=True),
+            jwt=dict(type='str',
+                     required=False,
+                     fallback=(env_fallback, ['DECORT_JWT']),
+                     no_log=True),
+            oauth2_url=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_OAUTH2_URL'])),
+            password=dict(type='str',
+                          required=False,
+                          fallback=(env_fallback, ['DECORT_PASSWORD']),
+                          no_log=True),
+            pool=dict(type='str', required=False, default=""),
+            sep_id=dict(type='int', required=False, default=0),
+            account_name=dict(type='str', required=False),
+            account_Id=dict(type='int', required=False),
+            user=dict(type='str',
+                      required=False,
+                      fallback=(env_fallback, ['DECORT_USER'])),
+            verify_ssl=dict(type='bool', required=False, default=True),
+            workflow_callback=dict(type='str', required=False),
+            workflow_context=dict(type='str', required=False),
+            image_name=dict(type='str', required=False),
+            image_id=dict(type='int', required=False,default=0),
+            virt_id=dict(type='int', required=False, default=0),
+            virt_name=dict(type='str', required=False),
+            state=dict(type='str',
+                   default='present',
+                   choices=['absent', 'present']),
+            drivers=dict(type='str', required=False, default="KVM_X86"),
+            architecture=dict(type='str', required=False, default="X86_64"),
+            imagetype=dict(type='str', required=False, default="linux"),
+            boottype=dict(type='str', required=False, default="uefi"),
+            url=dict(type='str', required=False),
+            gid=dict(type='int', required=False, default=0),
+            sepId=dict(type='int', required=False, default=0),
+            poolName=dict(type='str', required=False),
+            hotresize=dict(type='bool', required=False, default=False),
+            image_username=dict(type='str', required=False),
+            image_password=dict(type='str', required=False),
+            usernameDL=dict(type='str', required=False),
+            passwordDL=dict(type='str', required=False),
+            permanently=dict(type='bool', required=False, default=False),
+        )
+        
+
+def main():
+    module_parameters = decort_osimage.decort_osimage_parameters()
+
+    amodule = AnsibleModule(argument_spec=module_parameters,
+                            supports_check_mode=True,
+                            mutually_exclusive=[
+                                ['oauth2', 'password'],
+                                ['password', 'jwt'],
+                                ['jwt', 'oauth2'],
+                            ],
+                            required_together=[
+                                ['app_id', 'app_secret'],
+                                ['user', 'password'],
+                            ],
+                            )
+
+    decon = decort_osimage(amodule)
+
+    if amodule.params['image_name'] or amodule.params['image_id']:
+        image_id, image_facts = decort_osimage.decort_image_find(decon, amodule)
+        decon.validated_image_id = decort_osimage.decort_osimage_package_facts(image_facts)['id']
+        if decort_osimage.decort_osimage_package_facts(image_facts)['id'] > 0:
+            decon.result['facts'] = decort_osimage.decort_osimage_package_facts(image_facts, amodule.check_mode)
+
+    if amodule.params['state'] == "present" and decon.validated_image_id == 0 and amodule.params['image_name'] and amodule.params['url']:
+        decort_osimage.decort_image_create(decon,amodule)
+        decon.result['changed'] = True
+        image_id, image_facts = decort_osimage.decort_image_find(decon, amodule)
+        decon.result['msg'] = ("OS image '{}' created").format(decort_osimage.decort_osimage_package_facts(image_facts)['id'])
+        decon.result['facts'] = decort_osimage.decort_osimage_package_facts(image_facts, amodule.check_mode)
+        decon.validated_image_id = decort_osimage.decort_osimage_package_facts(image_facts)['id']
+
+    
+    elif amodule.params['state'] == "absent":
+        if amodule.params['image_name'] or amodule.params['image_id'] and\
+             decort_osimage.decort_osimage_package_facts(image_facts)['accountId'] == amodule.params['account_Id']:
+            amodule.image_id_delete = decon.validated_image_id
+            decort_osimage.decort_image_delete(decon,amodule)
+    
+
+
+    if amodule.params['virt_name'] or amodule.params['virt_id']:
+
+        image_id, image_facts = decort_osimage.decort_virt_image_find(decon, amodule)
+        if decort_osimage.decort_osimage_package_facts(image_facts)['id'] > 0:
+            decon.result['facts'] = decort_osimage.decort_osimage_package_facts(image_facts, amodule.check_mode)
+        decon.validated_virt_image_id = decort_osimage.decort_osimage_package_facts(image_facts)['id']
+        decon.validated_virt_image_name = decort_osimage.decort_osimage_package_facts(image_facts)['name']
+
+
+        if decort_osimage.decort_osimage_package_facts(image_facts)['id'] == 0 and amodule.params['state'] == "present" and decon.validated_image_id > 0:
+            image_id, image_facts = decort_osimage.decort_virt_image_create(decon,amodule)
+            decon.result['msg'] = ("Virtual image '{}' created").format(decort_osimage.decort_osimage_package_facts(image_facts)['id'])
+            decon.result['changed'] = True
+        elif decort_osimage.decort_osimage_package_facts(image_facts)['id'] == 0 and amodule.params['state'] == "present" and decon.validated_image_id == 0:
+            decon.result['msg'] = ("Cannot find OS image")
+            amodule.fail_json(**decon.result)
+
+
+        if decon.validated_image_id:
+            if decort_osimage.decort_osimage_package_facts(image_facts)['linkto'] != decon.validated_image_id:
+                decort_osimage.decort_virt_image_link(decon,amodule)
+                decon.result['changed'] = True
+                amodule.exit_json(**decon.result)
+        
+
+        if decon.validated_virt_image_id > 0 and amodule.params['state'] == "absent":
+            decon.result['msg'] = ("Osimage module cannot delete virtual images.")
+            decon.result['failed'] = True
+            amodule.exit_json(**decon.result)
+
+
+    if decon.result['failed'] == True:
+        # we failed to find the specified image - fail the module
+        decon.result['changed'] = False
+        amodule.fail_json(**decon.result)
+
+    amodule.exit_json(**decon.result)
+
+    
+if __name__ == "__main__":
+    main()

library/decort_pfw.py

@@ -0,0 +1,332 @@
+#!/usr/bin/python
+#
+# Digital Enegry Cloud Orchestration Technology (DECORT) modules for Ansible
+# Copyright: (c) 2018-2021 Digital Energy Cloud Solutions LLC
+#
+# Apache License 2.0 (see http://www.apache.org/licenses/LICENSE-2.0.txt)
+#
+
+#
+# Author: Sergey Shubin (sergey.shubin@digitalenergy.online)
+#
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+DOCUMENTATION = '''
+---
+module: decort_pfw
+short_description: Manage network Port Forward rules for Compute instances in DECORT cloud
+description: >
+     This module can be used to create new port forwarding rules in DECORT cloud platform, 
+     modify and delete them.
+version_added: "2.2"
+author:
+     - Sergey Shubin <sergey.shubin@digitalenergy.online>
+requirements:
+     - python >= 2.6
+     - PyJWT Python module
+     - requests Python module
+     - netaddr Python module
+     - decort_utils utility library (module)
+     - DECORT cloud platform version 3.6.1 or higher
+notes:
+     - Environment variables can be used to pass selected parameters to the module, see details below.
+     - Specified Oauth2 provider must be trusted by the DECORT cloud controller on which JWT will be used.
+     - 'Similarly, JWT supplied in I(authenticator=jwt) mode should be received from Oauth2 provider trusted by
+       the DECORT cloud controller on which this JWT will be used.'
+options:
+    account_id:
+        description:
+        - ID of the account, which owns this disk. This is the alternative to I(account_name) option.
+        - If both I(account_id) and I(account_name) specified, then I(account_name) is ignored.
+        default: 0
+        required: no
+    account_name:
+        description:
+        - 'Name of the account, which will own this disk.'
+        - 'This parameter is ignored if I(account_id) is specified.'
+        default: empty string
+        required: no
+    app_id:
+        description:
+        - 'Application ID for authenticating to the DECORT controller when I(authenticator=oauth2).'
+        - 'Required if I(authenticator=oauth2).'
+        - 'If not found in the playbook or command line arguments, the value will be taken from DECORT_APP_ID
+           environment variable.'
+        required: no
+    app_secret:
+        description:
+        - 'Application API secret used for authenticating to the DECORT controller when I(authenticator=oauth2).'
+        - This parameter is required when I(authenticator=oauth2) and ignored in other modes.
+        - 'If not found in the playbook or command line arguments, the value will be taken from DECORT_APP_SECRET
+           environment variable.'
+        required: no
+    authenticator:
+        description:
+        - Authentication mechanism to be used when accessing DECORT controller and authorizing API call.
+        default: jwt
+        choices: [ jwt, oauth2, legacy ]
+        required: yes
+    controller_url:
+        description:
+        - URL of the DECORT controller that will be contacted to manage the RG according to the specification.
+        - 'This parameter is always required regardless of the specified I(authenticator) type.'
+        required: yes
+    compute_id:
+        description:
+        - ID of the Compute instance to manage network port forwarding rules for.
+        required: yes
+    jwt:
+        description:
+        - 'JWT (access token) for authenticating to the DECORT controller when I(authenticator=jwt).'
+        - 'This parameter is required if I(authenticator=jwt) and ignored for other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_JWT environment variable.
+        required: no
+    oauth2_url:
+        description:
+        - 'URL of the oauth2 authentication provider to use when I(authenticator=oauth2).'
+        - 'This parameter is required when when I(authenticator=oauth2).'
+        - 'If not specified in the playbook, the value will be taken from DECORT_OAUTH2_URL environment variable.'
+    password:
+        description:
+        - 'Password for authenticating to the DECORT controller when I(authenticator=legacy).'
+        - 'This parameter is required if I(authenticator=legacy) and ignored in other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_PASSWORD environment variable.
+        required: no
+    rules:
+        description:
+        - 'Set of rules to configure for the Compute instance identidied by I(compute_id) in the virtual
+          network segment identidied by I(vins_id).'
+        - The set is specified as a list of dictionaries with the following structure:
+        - '  - (int) public_port_start - starting port number on the ViNS external interface.'
+        - '  - (int) public_port_end - optional end port number of the ViNS external interface. If not specified
+               or set equal to I(public_port_start), a one-to-one rule is created. Otherwise a ranged rule will
+               be created, which maps specified external port range to local ports starting from I(local_port).'
+        - '  - (int) local_port - port number on the local interface of the Compute. For ranged rule it is
+               interpreted as a base port to translate public port range to internal port range.'
+        - '  - (string) proto - protocol, specify either I(tcp) or I(udp).'
+        - 'Note that rules are meaningful only if I(state=present). If I(state=absent) is specified, rules set
+           will be ignored, and all rules for the specified Compute will be deleted.'
+    state:
+        description:
+        - 'Specify the desired state of the port forwarding rules set for the Compute instance identified by
+          I(compute_id).'
+        - 'If I(state=present), the rules will be applied according to the I(rules) parameter.'
+        - 'If I(state=absent), all rules for the specified Compute instance will be deleted regardless of
+           I(rules) parameter.'
+        default: present
+        choices: [ absent, present ]
+    verify_ssl:
+        description:
+        - 'Controls SSL verification mode when making API calls to DECORT controller. Set it to False if you
+         want to disable SSL certificate verification. Intended use case is when you run module in a trusted
+         environment that uses self-signed certificates. Note that disabling SSL verification in any other
+         scenario can lead to security issues, so please know what you are doing.'
+        default: True
+        required: no
+    vins_id:
+        description:
+        - ID of the virtual network segment (ViNS), where port forwarding rules will be set up.
+        - This ViNS must have connection to external network.
+        - Compute instance specified by I(compute_id) must be connected to this ViNS.
+    workflow_callback:
+        description:
+        - 'Callback URL that represents an application, which invokes this module (e.g. up-level orchestrator or
+          end-user portal) and may except out-of-band updates on progress / exit status of the module run.'
+        - API call at this URL will be used to relay such information to the application.
+        - 'API call payload will include module-specific details about this module run and I(workflow_context).'
+        required: no
+    workflow_context:
+        description:
+        - 'Context data that will be included into the payload of the API call directed at I(workflow_callback) URL.'
+        - 'This context data is expected to uniquely identify the task carried out by this module invocation so
+           that up-level orchestrator could match returned information to the its internal entities.'
+        required: no
+'''
+
+EXAMPLES = '''
+- name: configure one-toone rule for SSH protocol on Compute ID 100 connected to ViNS ID 5.
+    decort_pfw:
+      authenticator: oauth2
+      app_id: "{{ MY_APP_ID }}"
+      app_secret: "{{ MY_APP_SECRET }}"
+      controller_url: "https://cloud.digitalenergy.online"
+      compute_id: 100
+      vins_id: 5
+      rules:
+        - public_port_start: 10022
+          local_port: 22
+          proto: tcp
+      state: present
+    delegate_to: localhost
+    register: my_pfw
+'''
+
+RETURN = '''
+facts:
+    description: facts about created PFW rules
+    returned: always
+    type: dict
+    sample:
+      facts:
+        compute_id: 100
+        vins_id: 5
+        rules:
+          - 
+'''
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.basic import env_fallback
+
+from ansible.module_utils.decort_utils import *
+
+
+def decort_pfw_package_facts(comp_facts, vins_facts, pfw_facts, check_mode=False):
+    """Package a dictionary of PFW rules facts according to the decort_pfw module specification. 
+    This dictionary will be returned to the upstream Ansible engine at the completion of 
+    the module run.
+
+    @param (dict) pfw_facts: dictionary with PFW facts as returned by API call to .../???/get
+    @param (bool) check_mode: boolean that tells if this Ansible module is run in check mode
+    """
+
+    ret_dict = dict(state="CHECK_MODE",
+                    compute_id=0,
+                    public_ip="",
+                    rules=[],
+                    vins_id=0,
+                    )
+
+    if check_mode:
+        # in check mode return immediately with the default values
+        return ret_dict
+
+    if pfw_facts is None:
+        # if void facts provided - change state value to ABSENT and return
+        ret_dict['state'] = "ABSENT"
+        return ret_dict
+
+    ret_dict['compute_id'] = comp_facts['id']
+    ret_dict['vins_id'] = vins_facts['id']
+    ret_dict['public_ip'] = vins_facts['vnfs']['GW']['config']['ext_net_ip']
+    
+    if len(pfw_facts) != 0:
+        ret_dict['state'] = 'PRESENT'
+        ret_dict['rules'] = pfw_facts
+    else:
+        ret_dict['state'] = 'ABSENT'
+
+    return ret_dict
+
+def decort_pfw_parameters():
+    """Build and return a dictionary of parameters expected by decort_pfw module in a form accepted
+    by AnsibleModule utility class."""
+
+    return dict(
+        app_id=dict(type='str',
+                    required=False,
+                    fallback=(env_fallback, ['DECORT_APP_ID'])),
+        app_secret=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_APP_SECRET']),
+                        no_log=True),
+        authenticator=dict(type='str',
+                           required=True,
+                           choices=['legacy', 'oauth2', 'jwt']),
+        compute_id=dict(type='int', required=True),
+        controller_url=dict(type='str', required=True),
+        jwt=dict(type='str',
+                 required=False,
+                 fallback=(env_fallback, ['DECORT_JWT']),
+                 no_log=True),
+        oauth2_url=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_OAUTH2_URL'])),
+        password=dict(type='str',
+                      required=False,
+                      fallback=(env_fallback, ['DECORT_PASSWORD']),
+                      no_log=True),
+        rules=dict(type='list', required=False, default=[]),
+        state=dict(type='str',
+                   default='present',
+                   choices=['absent', 'present']),
+        user=dict(type='str',
+                  required=False,
+                  fallback=(env_fallback, ['DECORT_USER'])),
+        verify_ssl=dict(type='bool', required=False, default=True),
+        vins_id=dict(type='int', required=True),
+        workflow_callback=dict(type='str', required=False),
+        workflow_context=dict(type='str', required=False),
+    )
+
+def main():
+    module_parameters = decort_pfw_parameters()
+
+    amodule = AnsibleModule(argument_spec=module_parameters,
+                            supports_check_mode=True,
+                            mutually_exclusive=[
+                                ['oauth2', 'password'],
+                                ['password', 'jwt'],
+                                ['jwt', 'oauth2'],
+                            ],
+                            required_together=[
+                                ['app_id', 'app_secret'],
+                                ['user', 'password'],
+                            ],
+                            )
+
+    decon = DecortController(amodule)
+
+    pfw_facts = None # will hold PFW facts as returned by pfw_configure
+
+    #
+    # Validate module arguments:
+    # 1) specified Compute instance exists in correct state
+    # 2) specified ViNS exists
+    # 3) ViNS has GW function
+    # 4) Compute is connected to this ViNS
+    #
+
+    validated_comp_id, comp_facts, rg_id = decon.compute_find(amodule.params['compute_id'])
+    if not validated_comp_id:
+        decon.result['failed'] = True
+        decon.result['msg'] = "Cannot find specified Compute ID {}.".format(amodule.params['compute_id'])
+        amodule.fail_json(**decon.result)
+
+    validated_vins_id, vins_facts = decon.vins_find(amodule.params['vins_id'])
+    if not validated_vins_id:
+        decon.result['failed'] = True
+        decon.result['msg'] = "Cannot find specified ViNS ID {}.".format(amodule.params['vins_id'])
+        amodule.fail_json(**decon.result)
+
+    gw_vnf_facts = vins_facts['vnfs'].get('GW')
+    if not gw_vnf_facts or gw_vnf_facts['status'] == "DESTROYED":
+        decon.result['failed'] = True
+        decon.result['msg'] = "ViNS ID {} does not have a configured external connection.".format(validated_vins_id)
+        amodule.fail_json(**decon.result)
+
+    #
+    # Initial validation of module arguments is complete
+    # 
+
+    if amodule.params['state'] == 'absent':
+        # ignore amodule.params['rules'] and remove all rules associated with this Compute
+        pfw_facts = decon.pfw_configure(comp_facts, vins_facts, None) 
+    else:
+        # manage PFW rules accodring to the module arguments
+        pfw_facts = decon.pfw_configure(comp_facts, vins_facts, amodule.params['rules'])
+    
+    #
+    # complete module run
+    #
+    if decon.result['failed']:
+        amodule.fail_json(**decon.result)
+    else:
+        # prepare PFW facts to be returned as part of decon.result and then call exit_json(...)
+        decon.result['facts'] = decort_pfw_package_facts(comp_facts, vins_facts, pfw_facts, amodule.check_mode)
+        amodule.exit_json(**decon.result)
+
+if __name__ == "__main__":
+    main()

library/decort_rg.py

@@ -0,0 +1,523 @@
+#!/usr/bin/python
+#
+# Digital Enegry Cloud Orchestration Technology (DECORT) modules for Ansible
+# Copyright: (c) 2018-2021 Digital Energy Cloud Solutions LLC
+#
+# Apache License 2.0 (see http://www.apache.org/licenses/LICENSE-2.0.txt)
+#
+
+#
+# Author: Sergey Shubin (sergey.shubin@digitalenergy.online)
+#
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+DOCUMENTATION = '''
+---
+module: decort_rg
+short_description: Manage resource groups (RGs) in DECORT cloud
+description: >
+     This module can be used to create a new resource group in DECORT cloud platform, modify its
+     characteristics, and delete it.
+version_added: "2.2"
+author:
+     - Sergey Shubin <sergey.shubin@digitalenergy.online>
+requirements:
+     - python >= 2.6
+     - PyJWT Python module
+     - requests Python module
+     - netaddr Python module
+     - decort_utils utility library (module)
+     - DECORT cloud platform version 3.6.1 or higher
+notes:
+     - Environment variables can be used to pass selected parameters to the module, see details below.
+     - Specified Oauth2 provider must be trusted by the DECORT cloud controller on which JWT will be used.
+     - 'Similarly, JWT supplied in I(authenticator=jwt) mode should be received from Oauth2 provider trusted by
+       the DECORT cloud controller on which this JWT will be used.'
+     - New RGs provisioned with this module will be deployed to the first location under specified DECORT 
+       controller (if there is more than one location).
+options:
+    account_id:
+        description:
+        - ID of the account under which this RG will be created. This is the alternative to I(account_name)
+          option. If both I(account_id) and I(account_name) specified, the latter is ignored.
+    account_name:
+        description:
+        - 'Name of the account under which this RG will be created (for new RGs) or is located.'
+        - 'This parameter is ignored if I(account_id) is specified.'
+        required: no
+    annotation:
+        description:
+        - Optional text description of this resource group.
+        default: empty string
+        required: no
+    app_id:
+        description:
+        - 'Application ID for authenticating to the DECORT controller when I(authenticator=oauth2).'
+        - 'Required if I(authenticator=oauth2).'
+        - 'If not found in the playbook or command line arguments, the value will be taken from DECORT_APP_ID
+           environment variable.'
+        required: no
+    app_secret:
+        description:
+        - 'Application API secret used for authenticating to the DECORT controller when I(authenticator=oauth2).'
+        - This parameter is required when I(authenticator=oauth2) and ignored in other modes.
+        - 'If not found in the playbook or command line arguments, the value will be taken from DECORT_APP_SECRET
+           environment variable.'
+        required: no
+    authenticator:
+        description:
+        - Authentication mechanism to be used when accessing DECORT controller and authorizing API call.
+        default: jwt
+        choices: [ jwt, oauth2, legacy ]
+        required: yes
+    controller_url:
+        description:
+        - URL of the DECORT controller that will be contacted to manage the RG according to the specification.
+        - 'This parameter is always required regardless of the specified I(authenticator) type.'
+        required: yes
+    jwt:
+        description:
+        - 'JWT (access token) for authenticating to the DECORT controller when I(authenticator=jwt).'
+        - 'This parameter is required if I(authenticator=jwt) and ignored for other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_JWT environment variable.
+        required: no
+    oauth2_url:
+        description:
+        - 'URL of the oauth2 authentication provider to use when I(authenticator=oauth2).'
+        - 'This parameter is required when when I(authenticator=oauth2).'
+        - If not specified in the playbook, the value will be taken from DECORT_OAUTH2_URL environment variable.
+    password:
+        description:
+        - 'Password for authenticating to the DECORT controller when I(authenticator=legacy).'
+        - 'This parameter is required if I(authenticator=legacy) and ignored in other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_PASSWORD environment variable.
+        required: no
+    quotas:
+        description:
+        - Dictionary that defines resource quotas to be set on a newly created RG.
+        - 'This parameter is optional and only used when creating new RG. It is ignored for any operations on an
+          existing RG.'
+        - 'The following keys are valid to set the resource quotas:'
+        - ' - I(cpu) (integer) - limit on the total number of CPUs that can be consumed by all compute instances 
+          in this RG.'
+        - ' - I(ram) (integer) - limit on the total amount of RAM in GB that can be consumed by compute instances
+          in this RG.'
+        - ' - I(disk) (integer) - limit on the total volume of disk space in GB that can be consumed by all
+          compute instances in this RG.'
+        - ' - I(ext_ips) (integer) - maximum number of external IP addresses that can be allocated to the compute
+          instances and virtual network segments (ViNS) in this RG.'
+        - 'Each of the above keys is optional. For example, you may specify I(cpu) and I(ram) while omitting the
+        other two keys. Then the quotas will be set on RAM and CPU leaving disk volume and the number of external
+        IP addresses unlimited.'
+        required: no
+    rg_name:
+        description:
+        - Name of the RG to manage.
+        required: yes
+    state:
+        description:
+        - Specify the desired state of the resource group at the exit of the module.
+        - 'Regardless of I(state), if RG exists and is in one of [DEPLOYING, DESTROYING, MIGRATING, ] states,
+          do nothing.'
+        - 'If desired I(state=present):'
+        - ' - RG does not exist or is in DESTROYED state, create new RG according to the specifications.'
+        - ' - RG is in one of [CREATED, DISABLED] states, change quotas if necessary.'
+        - ' - RG is in DELETED state, restore it and change quotas if necessary. RG will be left in DISABLED state.'
+        - ' - RG in any other state, abort with an error.'
+        - 'If desired I(state=enabled):'
+        - ' - RG does not exist or is in DESTROYED state, create new RG according to the specifications.'
+        - ' - RG is in CREATED state, change quotas if necessary.'
+        - ' - RG is in DELETED state, restore it, change quotas if necessary and enable.'
+        - ' - RG is in any other state, abort with an error.'
+        - 'If desired I(state=absent):'
+        - ' - RG is in one of [CREATED, DISABLED, DELETED] states, destroy it.'
+        - ' - RG in DESTROYED state, do nothing.' 
+        - ' - RG in any other state, abort with an error.'
+        - 'If desired I(state=disabled):'
+        - ' - RG does not exist or is in one of [ENABLING, DISABLING, DELETING, DELETED, DESTROYING, DESTROYED] 
+              states, abort with an error.'
+        - ' - RG is DISABLED state, change quotas if necessary.'
+        - ' - RG is in CREATED state, change quotas if necessary and disable the RG.'
+        default: present
+        choices: [ absent, disabled, enabled, present ]
+    user:
+        description:
+        - 'Name of the legacy user for authenticating to the DECORT controller when I(authenticator=legacy).'
+        - 'This parameter is required when I(authenticator=legacy) and ignored for other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_USER environment variable.
+        required: no
+    verify_ssl:
+        description:
+        - 'Controls SSL verification mode when making API calls to DECORT controller. Set it to False if you
+         want to disable SSL certificate verification. Intended use case is when you run module in a trusted
+         environment that uses self-signed certificates. Note that disabling SSL verification in any other
+         scenario can lead to security issues, so please know what you are doing.'
+        default: True
+        required: no
+    workflow_callback:
+        description:
+        - 'Callback URL that represents an application, which invokes this module (e.g. up-level orchestrator or
+          end-user portal) and may except out-of-band updates on progress / exit status of the module run.'
+        - API call at this URL will be used to relay such information to the application.
+        - 'API call payload will include module-specific details about this module run and I(workflow_context).'
+        required: no
+    workflow_context:
+        description:
+        - 'Context data that will be included into the payload of the API call directed at I(workflow_callback) URL.'
+        - 'This context data is expected to uniquely identify the task carried out by this module invocation so
+           that up-level orchestrator could match returned information to the its internal entities.'
+        required: no
+'''
+
+EXAMPLES = '''
+- name: create a new RG named "MyFirstRG" if it does not exist yet, set quotas on CPU and the number of exteranl IPs.
+    decort_rg:
+      authenticator: oauth2
+      app_id: "{{ MY_APP_ID }}"
+      app_secret: "{{ MY_APP_SECRET }}"
+      controller_url: "https://cloud.digitalenergy.online"
+      rg_name: "MyFirstRG"
+      account_name: "MyMainAccount"
+      quotas:
+        cpu: 16
+        ext_ips: 4
+      annotation: "My first RG created with Ansible module"
+      state: present
+    delegate_to: localhost
+    register: my_rg
+'''
+
+RETURN = '''
+facts:
+    description: facts about the resource group
+    returned: always
+    type: dict
+    sample:
+      facts:
+        id: 100
+        name: MyFirstRG
+        state: CREATED
+        account_id: 10
+        gid: 1001
+'''
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.basic import env_fallback
+
+from ansible.module_utils.decort_utils import *
+
+class decort_rg(DecortController):
+    def __init__(self,amodule):
+        super(decort_rg, self).__init__(amodule)
+
+        self.validated_acc_id = 0
+        self.validated_rg_id = 0
+        self.validated_rg_facts = None
+
+        if self.amodule.params['account_id']:
+            self.validated_acc_id, _ = self.account_find("", amodule.params['account_id'])
+        elif amodule.params['account_name']:
+            self.validated_acc_id, _ = self.account_find(amodule.params['account_name'])
+        if not self.validated_acc_id:
+            # we failed to locate account by either name or ID - abort with an error
+            self.result['failed'] = True
+            self.result['msg'] = ("Current user does not have access to the requested account "
+                                    "or non-existent account specified.")
+            self.fail_json(**self.result)
+
+        if amodule.params['rg_id'] > 0:
+            self.validated_rg_id = amodule.params['rg_id']
+
+        # Check if the RG with the specified parameters already exists
+        self.validated_rg_id, self.rg_facts = self.rg_find(self.validated_acc_id,
+                                                            arg_rg_id = self.validated_rg_id, 
+                                                            arg_rg_name=amodule.params['rg_name'],
+                                                            arg_check_state=False)
+
+        if amodule.params['state'] != "absent":
+            self.rg_should_exist = True
+        else:
+            self.rg_should_exist = False
+
+    def access(self):
+        should_change_access = False
+        acc_granted = False
+        for rg_item in self.rg_facts['acl']:
+            if rg_item['userGroupId'] == self.amodule.params['access']['user']:
+                acc_granted = True
+                if self.amodule.params['access']['action'] == 'grant':
+                    if rg_item['right'] != self.amodule.params['access']['right']:
+                        should_change_access = True
+                if self.amodule.params['access']['action'] == 'revoke':
+                    should_change_access = True
+        if acc_granted == False and self.amodule.params['access']['action'] == 'grant':
+            should_change_access = True
+
+        if should_change_access == True:
+            self.rg_access(self.validated_rg_id, self.amodule.params['access'])
+            self.rg_facts['access'] = self.amodule.params['access']
+        self.rg_should_exist = True
+        return
+
+    def error(self):
+        self.result['failed'] = True
+        self.result['changed'] = False
+        if self.validated_rg_id > 0:
+            self.result['msg'] = ("Invalid target state '{}' requested for rg ID {} in the "
+                                   "current status '{}'.").format(self.validated_rg_id,
+                                                                  self.amodule.params['state'],
+                                                                  self.rg_facts['status'])
+        else:
+            self.result['msg'] = ("Invalid target state '{}' requested for non-existent rg name '{}' "
+                                   "in account ID {} ").format(self.amodule.params['state'],
+                                                               self.amodule.params['rg_name'],
+                                                               self.validated_acc_id)
+        return
+    
+    def update(self):
+        resources = self.rg_facts['Resources']['Reserved']
+        incorrect_quota = dict(Requested=dict(),
+                               Reserved=dict(),)
+        query_key_map = dict(cpu='cpu',
+                             ram='ram',
+                             disk='disksize',
+                             ext_ips='extips', 
+                             net_transfer='exttraffic',)
+        if self.amodule.params['quotas']:
+            for quota_item in self.amodule.params['quotas']:
+                if self.amodule.params['quotas'][quota_item] < resources[query_key_map[quota_item]]:
+                    incorrect_quota['Requested'][quota_item]=self.amodule.params['quotas'][quota_item]
+                    incorrect_quota['Reserved'][quota_item]=resources[query_key_map[quota_item]]
+
+        if incorrect_quota['Requested']:
+            self.result['msg'] = ("Cannot limit less than already reserved'{}'").format(incorrect_quota)
+            self.result['failed'] = True
+        
+        if self.result['failed'] != True:
+            self.rg_update(self.rg_facts, self.amodule.params['quotas'], 
+                           self.amodule.params['resType'], self.amodule.params['rename'])
+            self.rg_should_exist = True
+        return
+    
+    def setDefNet(self):
+        if self.amodule.params['def_netId'] != self.rg_facts['def_net_id']:
+            self.rg_setDefNet(self.validated_rg_id,
+                              self.amodule.params['def_netType'],
+                              self.amodule.params['def_netId'])
+        self.rg_should_exist = True
+        return
+
+    def create(self):
+        self.validated_rg_id = self.rg_provision(self.validated_acc_id,
+                                        self.amodule.params['rg_name'], 
+                                        self.amodule.params['owner'],
+                                        self.amodule.params['annotation'],
+                                        self.amodule.params['resType'],
+                                        self.amodule.params['def_netType'],
+                                        self.amodule.params['ipcidr'],
+                                        self.amodule.params['extNetId'],
+                                        self.amodule.params['extNetIp'],
+                                        self.amodule.params['quotas'],
+                                        "", # this is location code. TODO: add module argument
+                                        )
+
+        self.validated_rg_id, self.rg_facts = self.rg_find(self.validated_acc_id,
+                                        self.validated_rg_id, 
+                                        arg_rg_name="",
+                                        arg_check_state=False)
+        self.rg_should_exist = True 
+        return
+    
+    def enable(self):
+        self.rg_enable(self.validated_rg_id, 
+                       self.amodule.params['state'])
+        if self.amodule.params['state'] == "enabled":
+            self.rg_facts['status'] = 'CREATED'
+        else:
+            self.rg_facts['status'] = 'DISABLED'
+        self.rg_should_exist = True
+        return
+    
+    def restore(self):
+        self.rg_restore(self.validated_rg_id)
+        self.rg_facts['status'] = 'DISABLED'
+        self.rg_should_exist = True
+        return
+        
+    def destroy(self):
+
+        self.rg_delete(self.validated_rg_id, self.amodule.params['permanently'])
+        if self.amodule.params['permanently'] == True:
+            self.rg_facts['status'] = 'DESTROYED'
+        else:
+            self.rg_facts['status'] = 'DELETED'
+        self.rg_should_exist = False
+        return
+
+    def package_facts(self, check_mode=False):
+        """Package a dictionary of RG facts according to the decort_rg module specification. This dictionary will
+        be returned to the upstream Ansible engine at the completion of the module run.
+
+        @param arg_rg_facts: dictionary with RG facts as returned by API call to .../rg/get
+        @param arg_check_mode: boolean that tells if this Ansible module is run in check mode
+        """
+
+        ret_dict = dict(id=0,
+                        name="none",
+                        state="CHECK_MODE",
+                        )
+
+        if check_mode:
+            # in check mode return immediately with the default values
+            return ret_dict
+
+        #if arg_rg_facts is None:
+        #    # if void facts provided - change state value to ABSENT and return
+        #    ret_dict['state'] = "ABSENT"
+        #    return ret_dict
+
+        ret_dict['id'] = self.rg_facts['id']
+        ret_dict['name'] = self.rg_facts['name']
+        ret_dict['state'] = self.rg_facts['status']
+        ret_dict['account_id'] = self.rg_facts['accountId']
+        ret_dict['gid'] = self.rg_facts['gid']
+        ret_dict['quota'] = self.rg_facts['resourceLimits']
+        ret_dict['resTypes'] = self.rg_facts['resourceTypes']
+        ret_dict['defNetId'] = self.rg_facts['def_net_id']
+        ret_dict['defNetType'] = self.rg_facts['def_net_type']
+        ret_dict['ViNS'] = self.rg_facts['vins']
+        ret_dict['computes'] = self.rg_facts['vms']
+
+        return ret_dict
+
+    def parameters():
+        """Build and return a dictionary of parameters expected by decort_rg module in a form accepted
+        by AnsibleModule utility class."""
+
+        return dict(
+            account_id=dict(type='int', required=False),
+            account_name=dict(type='str', required=False, default=''),
+            access=dict(type='dict'),
+            annotation=dict(type='str', required=False, default=''),
+            app_id=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_APP_ID'])),
+            app_secret=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_APP_SECRET']),
+                            no_log=True),
+            authenticator=dict(type='str',
+                               required=True,
+                               choices=['legacy', 'oauth2', 'jwt']),
+            controller_url=dict(type='str', required=True),
+            # datacenter=dict(type='str', required=False, default=''),
+            def_netType=dict(type='str', choices=['PRIVATE','PUBLIC', 'NONE'], default='PRIVATE'),
+            def_netId=dict(type='int', default=0),
+            extNetId=dict(type='int', default=0),
+            extNetIp=dict(type='str', default=""),
+            owner=dict(type='str', default=""),
+            ipcidr=dict(type='str', default=""),
+            jwt=dict(type='str',
+                     required=False,
+                     fallback=(env_fallback, ['DECORT_JWT']),
+                    no_log=True),
+            oauth2_url=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_OAUTH2_URL'])),
+            rename=dict(type='str', default=""),
+            password=dict(type='str',
+                          required=False,
+                          fallback=(env_fallback, ['DECORT_PASSWORD']),
+                          no_log=True),
+            quotas=dict(type='dict', required=False),
+            resType=dict(type='list'),
+            state=dict(type='str',
+                       default='present',
+                       choices=['absent', 'disabled', 'enabled', 'present']),
+            permanently=dict(type='bool',
+                             default='False'),
+            user=dict(type='str',
+                      required=False,
+                      fallback=(env_fallback, ['DECORT_USER'])),
+            rg_name=dict(type='str', required=False,),
+            rg_id=dict(type='int', required=False, default=0),
+            verify_ssl=dict(type='bool', required=False, default=True),
+            workflow_callback=dict(type='str', required=False),
+            workflow_context=dict(type='str', required=False),
+        )
+
+    # Workflow digest:
+    # 1) authenticate to DECORT controller & validate authentication by issuing API call - done when creating DECORTController
+    # 2) check if the RG with the specified id or rg_name:name exists
+    # 3) if RG does not exist -> deploy
+    # 4) if RG exists: check desired state, desired configuration -> initiate action accordingly
+    # 5) report result to Ansible
+
+def main():
+    module_parameters = decort_rg.parameters()
+
+    amodule = AnsibleModule(argument_spec=module_parameters,
+                            supports_check_mode=True,
+                            mutually_exclusive=[
+                                ['oauth2', 'password'],
+                                ['password', 'jwt'],
+                                ['jwt', 'oauth2'],
+                            ],
+                            required_together=[
+                                ['app_id', 'app_secret'],
+                                ['user', 'password'],
+                            ],
+                            )
+
+    decon = decort_rg(amodule)
+    #amodule.check_mode=True
+    if decon.validated_rg_id > 0:
+        if decon.rg_facts['status'] in ["MODELED", "DISABLING", "ENABLING", "DELETING", "DESTROYING", "CONFIRMED"]:
+            decon.error()
+        elif decon.rg_facts['status'] in ("CREATED"):
+            if amodule.params['state'] == 'absent':
+                decon.destroy()
+            elif amodule.params['state'] == "disabled":
+                decon.enable()
+            if amodule.params['state'] in ['present', 'enabled']:
+                if amodule.params['quotas'] or amodule.params['resType'] or amodule.params['rename'] != "":
+                    decon.update()
+                if amodule.params['access']:
+                    decon.access()
+                if amodule.params['def_netId'] > 0:
+                    decon.setDefNet()
+
+        elif decon.rg_facts['status'] == "DELETED":
+            if amodule.params['state'] == 'absent' and amodule.params['permanently'] == True:
+                decon.destroy()
+            elif amodule.params['state'] == 'present':
+                decon.restore()
+        elif decon.rg_facts['status'] in ("DISABLED"):
+            if amodule.params['state'] == 'absent':
+                decon.destroy()
+            elif amodule.params['state'] == ("enabled"):
+                decon.enable()
+
+    else:
+        if amodule.params['state'] in ('present', 'enabled'):
+            decon.create() 
+            if amodule.params['access']:
+                decon.access()
+        elif amodule.params['state'] in ('disabled'):
+            decon.error()
+        
+
+    if decon.result['failed']:
+        amodule.fail_json(**decon.result)
+    else:
+        if decon.rg_should_exist:
+            decon.result['facts'] = decon.package_facts(amodule.check_mode)
+            amodule.exit_json(**decon.result)
+        else:
+            amodule.exit_json(**decon.result)
+
+if __name__ == "__main__":
+    main()

library/decort_vins.py

@@ -0,0 +1,644 @@
+#!/usr/bin/python
+#
+# Digital Enegry Cloud Orchestration Technology (DECORT) modules for Ansible
+# Copyright: (c) 2018-2021 Digital Energy Cloud Solutions LLC
+#
+# Apache License 2.0 (see http://www.apache.org/licenses/LICENSE-2.0.txt)
+#
+
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+DOCUMENTATION = '''
+---
+module: decort_vins
+short_description: Manage Virtual Network Segments (ViNS) in DECORT cloud
+description: >
+     This module can be used to create new ViNS in DECORT cloud platform, obtain or 
+     modify its characteristics, and delete it.
+version_added: "2.2"
+author:
+requirements:
+     - python >= 3.8
+     - PyJWT Python module
+     - requests Python module
+     - netaddr Python module
+     - decort_utils utility library (module)
+     - DECORT cloud platform version 3.8.6 or higher
+notes:
+     - Environment variables can be used to pass selected parameters to the module, see details below.
+     - Specified Oauth2 provider must be trusted by the DECORT cloud controller on which JWT will be used.
+     - 'Similarly, JWT supplied in I(authenticator=jwt) mode should be received from Oauth2 provider trusted by
+       the DECORT cloud controller on which this JWT will be used.'
+options:
+    account_id:
+        description:
+        - 'ID of the account under which this ViNS will be created (for new ViNS) or is located (for already
+          existing ViNS). This is the alternative to I(account_name) option.'
+        - If both I(account_id) and I(account_name) specified, then I(account_name) is ignored.
+        required: no
+    account_name:
+        description:
+        - 'Name of the account under which this ViNS will be created (for new RGs) or is located (for already
+           existing ViNS).'
+        - 'This parameter is ignored if I(account_id) is specified.'
+        required: no
+    annotation:
+        description:
+        - Optional text description of this virtual network segment.
+        default: empty string
+        required: no
+    app_id:
+        description:
+        - 'Application ID for authenticating to the DECORT controller when I(authenticator=oauth2).'
+        - 'Required if I(authenticator=oauth2).'
+        - 'If not found in the playbook or command line arguments, the value will be taken from DECORT_APP_ID
+           environment variable.'
+        required: no
+    app_secret:
+        description:
+        - 'Application API secret used for authenticating to the DECORT controller when I(authenticator=oauth2).'
+        - This parameter is required when I(authenticator=oauth2) and ignored in other modes.
+        - 'If not found in the playbook or command line arguments, the value will be taken from DECORT_APP_SECRET
+           environment variable.'
+        required: no
+    authenticator:
+        description:
+        - Authentication mechanism to be used when accessing DECORT controller and authorizing API call.
+        default: jwt
+        choices: [ jwt, oauth2, legacy ]
+        required: yes
+    controller_url:
+        description:
+        - URL of the DECORT controller that will be contacted to manage the RG according to the specification.
+        - 'This parameter is always required regardless of the specified I(authenticator) type.'
+        required: yes
+    ext_net_id:
+        description:
+        - 'Controls ViNS connection to an external network. This argument is optional with default value of -1,
+          which means no external connection.'
+        - Specify 0 to connect ViNS to external network and let platform select external network Id automatically.
+        - Specify positive value to request ViNS connection to the external network with corresponding ID.
+        - You may also control external IP address selection with I(ext_ip_addr) argument.
+        default: -1
+        required: no
+    ext_ip_addr:
+        description:
+        - IP address to assign to the external interface of this ViNS when connecting to the external net.
+        - If empty string is passed, the platform will assign free IP address automatically.
+        - 'Note that if invalid IP address or an address already occupied by another client is specified, 
+           the module will abort with an error.'
+        - 'This argument is used only for new connection to the specified network. You cannot select another 
+           external IP address without changing external network ID.'
+        - ViNS connection to the external network is controlled by I(ext_net_id) argument.
+        default: empty string
+        required: no
+    ipcidr:
+        description:
+        - Internal ViNS network address in a format XXX.XXX.XXX.XXX/XX (includes address and netmask).
+        - If empty string is passed, the platform will assign network address automatically.
+        - 'When selecting this address manually, note that this address must be unique amomng all ViNSes in 
+           the target account.'
+        default: empty string
+        required: no
+    jwt:
+        description:
+        - 'JWT (access token) for authenticating to the DECORT controller when I(authenticator=jwt).'
+        - 'This parameter is required if I(authenticator=jwt) and ignored for other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_JWT environment variable.
+        required: no
+    oauth2_url:
+        description:
+        - 'URL of the oauth2 authentication provider to use when I(authenticator=oauth2).'
+        - 'This parameter is required when when I(authenticator=oauth2).'
+        - 'If not specified in the playbook, the value will be taken from DECORT_OAUTH2_URL environment variable.'
+    password:
+        description:
+        - 'Password for authenticating to the DECORT controller when I(authenticator=legacy).'
+        - 'This parameter is required if I(authenticator=legacy) and ignored in other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_PASSWORD environment variable.
+        required: no
+    rg_id:
+        description:
+        - 'ID of the resource group (RG), where this ViNS will be created (for a new ViNS) or located 
+           (for already existing ViNS).'
+        - If ViNS is created at the account level, I(rg_id) should be omitted or set to 0.
+        - If both I(rg_id) and I(rg_name) are specified, then I(rg_name) is ignored.
+        default: 0
+        required: no
+    rg_name:
+        description:
+        - 'Name of the resource group (RG), where this ViNS will be created (for new ViNS) or 
+          located (for already existing ViNS).'
+        - If ViNS is created at the account level, I(rg_name) should be omitted or set to emtpy string.
+        - If both I(rg_name) and I(rg_id) are specified, then I(rg_name) is ignored. 
+        default: empty string
+        required: no
+    state:
+        description:
+        - Specify the desired state of the ViNS at the exit of the module.
+        - 'Regardless of I(state), if ViNS exists and is in one of [DEPLOYING, DESTROYING, MIGRATING] states,
+          do nothing.'
+        - 'If desired I(state=present):'
+        - ' - ViNS does not exist or is in DESTROYED state, create new ViNS according to the specifications.'
+        - ' - ViNS is in DELETED state, restore it and change quotas if necessary. Note that on successful 
+              restore ViNS will be left in DISABLED state.'
+        - ' - ViNS is in one of [CREATED, ENABLED, DISABLED] states, do nothing.'
+        - ' - ViNS in any other state, abort with an error.'
+        - 'If desired I(state=enabled):'
+        - ' - ViNS does not exist or is in DESTROYED state, create new ViNS according to the specifications.'
+        - ' - ViNS is in DELETED state, restore and enable it.'
+        - ' - ViNS is in one of [CREATED, ENABLED] states, do nothing.'
+        - ' - viNS is in any other state, abort with an error.'
+        - 'If desired I(state=absent):'
+        - ' - ViNS is in one of [CREATED, ENABLED, DISABLED, DELETED] states, destroy it.'
+        - ' - ViNS in DESTROYED state, do nothing.' 
+        - ' - ViNS in any other state, abort with an error.'
+        - 'If desired I(state=disabled):'
+        - ' - ViNS is in one of [CREATED, ENABLED] states, disable it.'
+        - ' - ViNS is DISABLED state, do nothing.'
+        - ' - ViNS does not exist or is in one of [ENABLING, DISABLING, DELETING, DELETED, DESTROYING, DESTROYED] 
+              states, abort with an error.'
+        default: present
+        choices: [ absent, disabled, enabled, present ]
+    user:
+        description:
+        - 'Name of the legacy user for authenticating to the DECORT controller when I(authenticator=legacy).'
+        - 'This parameter is required when I(authenticator=legacy) and ignored for other authentication modes.'
+        - If not specified in the playbook, the value will be taken from DECORT_USER environment variable.
+        required: no
+    verify_ssl:
+        description:
+        - 'Controls SSL verification mode when making API calls to DECORT controller. Set it to False if you
+         want to disable SSL certificate verification. Intended use case is when you run module in a trusted
+         environment that uses self-signed certificates. Note that disabling SSL verification in any other
+         scenario can lead to security issues, so please know what you are doing.'
+        default: True
+        required: no
+    vins_id:
+        description:
+        - ID of the ViNs to manage. If ViNS is identified by ID it must be present.
+        - If ViNS ID is specified, I(account_id), I(account_name), I(rg_id) and I(rg_name) are ignored.
+    vins_name:
+        description:
+        - Name of the ViNS.
+        - ViNS can exist at either account or resource group level.
+        - ViNS name is unique only within its parent (i.e. account or resource group).
+        - 'To create ViNS at account level omit both I(rg_id) and I(rg_name), or set them to 0 and empty
+           string respectively.'
+        required: yes
+    workflow_callback:
+        description:
+        - 'Callback URL that represents an application, which invokes this module (e.g. up-level orchestrator or
+          end-user portal) and may except out-of-band updates on progress / exit status of the module run.'
+        - API call at this URL will be used to relay such information to the application.
+        - 'API call payload will include module-specific details about this module run and I(workflow_context).'
+        required: no
+    workflow_context:
+        description:
+        - 'Context data that will be included into the payload of the API call directed at I(workflow_callback) URL.'
+        - 'This context data is expected to uniquely identify the task carried out by this module invocation so
+           that up-level orchestrator could match returned information to the its internal entities.'
+        required: no
+'''
+
+EXAMPLES = '''
+- name: create a new ViNS named "MyViNS" if it does not exist yet under RG "MyRG" in the account "MyAccount".
+    decort_vins:
+      authenticator: oauth2
+      app_id: "{{ MY_APP_ID }}"
+      app_secret: "{{ MY_APP_SECRET }}"
+      controller_url: "https://cloud.digitalenergy.online"
+      vins_name: "MyViNS"
+      rg_name: "MyRG"
+      account_name: "MyAccount"
+      state: present
+    delegate_to: localhost
+    register: my_vins
+'''
+
+RETURN = '''
+facts:
+    description: facts about the virtual network segment
+    returned: always
+    type: dict
+    sample:
+      facts:
+        id: 5
+        name: MyViNS
+        int_net_addr: 192.168.1.0
+        ext_net_addr: 10.50.11.118
+        state: CREATED
+        account_id: 7
+        rg_id: 19
+        gid: 1001
+'''
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.basic import env_fallback
+
+from ansible.module_utils.decort_utils import *
+
+class decort_vins(DecortController):
+    def __init__(self,arg_amodule):
+        super(decort_vins, self).__init__(arg_amodule)
+
+        self.vins_id = 0
+        self.vins_level = ""  # "ID" if specified by ID, "RG" - at resource group, "ACC" - at account level
+        vins_facts = None  # will hold ViNS facts
+        validated_rg_id = 0
+        rg_facts = None  # will hold RG facts
+        validated_acc_id = 0
+        acc_facts = None  # will hold Account facts
+
+        if arg_amodule.params['vins_id']:
+            # expect existing ViNS with the specified ID
+            # This call to vins_find will abort the module if no ViNS with such ID is present
+            self.vins_id, self.vins_facts = self.vins_find(arg_amodule.params['vins_id'],check_state=False)
+            if self.vins_id == 0:
+                self.result['failed'] = True
+                self.result['msg'] = "Specified ViNS ID {} not found.".format(arg_amodule.params['vins_id'])
+                self.fail_json(**self.result)
+            self.vins_level = "ID"
+            #raise Exception(self.vins_facts)
+            validated_acc_id = self.vins_facts['accountId']
+            validated_rg_id = self.vins_facts['rgId']
+    
+        elif arg_amodule.params['rg_id']:
+            # expect ViNS @ RG level in the RG with specified ID
+            self.vins_level = "RG"
+            # This call to rg_find will abort the module if no RG with such ID is present
+            validated_rg_id, rg_facts = self.rg_find(0,  # account ID set to 0 as we search for RG by RG ID
+                                                    arg_amodule.params['rg_id'], arg_rg_name="")
+            
+            # This call to vins_find may return vins_id=0 if no ViNS found
+            self.vins_id, self.vins_facts = self.vins_find(vins_id=0, vins_name=arg_amodule.params['vins_name'],
+                                                account_id=0,
+                                                rg_id=arg_amodule.params['rg_id'],
+                                                rg_facts=rg_facts,
+                                                check_state=False)
+            # TODO: add checks and setup ViNS presence flags accordingly
+            pass
+        elif arg_amodule.params['account_id'] or arg_amodule.params['account_name'] != "":
+            # Specified account must be present and accessible by the user, otherwise abort the module
+            validated_acc_id, acc_facts = self.account_find(arg_amodule.params['account_name'], arg_amodule.params['account_id'])
+            if not validated_acc_id:
+                self.result['failed'] = True
+                self.result['msg'] = ("Current user does not have access to the requested account "
+                                    "or non-existent account specified.")
+                self.amodule.fail_json(**self.result)
+            if arg_amodule.params['rg_name'] != "":  # at this point we know that rg_id=0
+                # expect ViNS @ RG level in the RG with specified name under specified account
+                # RG with the specified name must be present under the account, otherwise abort the module
+                validated_rg_id, rg_facts = self.rg_find(validated_acc_id, 0, arg_amodule.params['rg_name'])
+                if (not validated_rg_id or
+                        rg_facts['status'] in ["DESTROYING", "DESTROYED", "DELETING", "DELETED", "DISABLING", "ENABLING"]):
+                    self.result['failed'] = True
+                    self.result['msg'] = "RG name '{}' not found or has invalid state.".format(arg_amodule.params['rg_name'])
+                    self.amodule.fail_json(**self.result)
+                # This call to vins_find may return vins_id=0 if no ViNS with this name found under specified RG
+                self.vins_id, self.vins_facts = self.vins_find(vins_id=0, vins_name=arg_amodule.params['vins_name'],
+                                                    account_id=0,  # set to 0, as we are looking for ViNS under RG
+                                                    rg_id=validated_rg_id,
+                                                    rg_facts=rg_facts,
+                                                    check_state=False)
+                self.vins_level = "RG"
+                # TODO: add checks and setup ViNS presence flags accordingly
+            else:  # At this point we know for sure that rg_name="" and rg_id=0
+                # So we expect ViNS @ account level
+                # This call to vins_find may return vins_id=0 if no ViNS found
+                self.vins_id, self.vins_facts = self.vins_find(vins_id=0, vins_name=arg_amodule.params['vins_name'],
+                                                    account_id=validated_acc_id,
+                                                    rg_id=0,
+                                                    rg_facts=rg_facts,
+                                                    check_state=False)
+                self.vins_level = "ACC"
+                # TODO: add checks and setup ViNS presence flags accordingly
+        else:
+            # this is "invalid arguments combination" sink
+            # if we end up here, it means that module was invoked with vins_id=0 and rg_id=0
+            self.result['failed'] = True
+            self.result['msg'] = "Cannot find ViNS by name"
+            if arg_amodule.params['account_id'] == 0 and arg_amodule.params['account_name'] == '':
+                self.result['msg'] = "Cannot find ViNS by name when account name is empty and account ID is 0."
+            if arg_amodule.params['rg_name'] == "":
+                # rg_name without account specified
+                self.result['msg'] = "Cannot find ViNS by name when RG name is empty and RG ID is 0."
+            self.amodule.fail_json(**self.result)
+
+            return
+        self.rg_id = validated_rg_id
+        self.acc_id = validated_acc_id
+        return 
+    def create(self):
+        self.vins_id = self.vins_provision(self.amodule.params['vins_name'],
+                                    self.acc_id, self.rg_id,
+                                    self.amodule.params['ipcidr'],
+                                    self.amodule.params['ext_net_id'], self.amodule.params['ext_ip_addr'],
+                                    self.amodule.params['annotation'])
+        
+        if self.amodule.params['mgmtaddr'] or self.amodule.params['connect_to']:
+            _, self.vins_facts = self.vins_find(self.vins_id)                  
+        if self.amodule.params['connect_to']:
+            self.vins_update_ifaces(self.vins_facts,self.amodule.params['connect_to'],)
+        if self.amodule.params['mgmtaddr']:
+            self.vins_update_mgmt(self.vins_facts,self.amodule.params['mgmtaddr'])
+            
+        return
+    def action(self,d_state='',restore=False):
+        if restore == True:
+            self.vins_restore(arg_vins_id=self.vins_id)
+            self.vins_state(self.vins_facts, 'enabled')
+            self.vins_facts['status'] = "ENABLED"
+            self.vins_facts['VNFDev']['techStatus'] = "STARTED"    
+        
+        self.vins_update_extnet(self.vins_facts,
+                         self.amodule.params['ext_net_id'], 
+                         self.amodule.params['ext_ip_addr'],
+                        )
+        
+        if d_state == 'enabled' and self.vins_facts['status'] == "DISABLED":
+            self.vins_state(self.vins_facts, d_state)
+            self.vins_facts['status'] = "ENABLED"
+            self.vins_facts['VNFDev']['techStatus'] = "STARTED"
+            d_state = ''
+
+        if self.vins_facts['status'] == "ENABLED" and self.vins_facts['VNFDev']['techStatus'] == "STARTED":
+            self.vins_update_ifaces(self.vins_facts,
+                                    self.amodule.params['connect_to'],
+                                )
+            if self.result['changed']:
+                _, self.vins_facts = self.vins_find(self.vins_id)
+            self.vins_update_mgmt(self.vins_facts,
+                                self.amodule.params['mgmtaddr'],
+                                )
+        
+        if d_state != '':
+            self.vins_state(self.vins_facts, d_state)
+        return
+    def delete(self):
+        self.vins_delete(self.vins_id, permanently=True)
+        self.vins_facts['status'] = 'DESTROYED'
+        return
+    def nop(self):
+        """No operation (NOP) handler for ViNS management by decort_vins module.
+        This function is intended to be called from the main switch construct of the module
+        when current state -> desired state change logic does not require any changes to
+        the actual ViNS state.
+        """
+        self.result['failed'] = False
+        self.result['changed'] = False
+        if self.vins_id:
+            self.result['msg'] = ("No state change required for ViNS  ID {} because of its "
+                                   "current status '{}'.").format(self.vins_id, self.vins_facts['status'])
+        else:
+            self.result['msg'] = ("No state change to '{}' can be done for "
+                                  "non-existent ViNS instance.").format(self.amodule.params['state'])
+        return
+    def error(self):
+        self.result['failed'] = True
+        self.result['changed'] = False
+        if self.vins_id:
+            self.result['failed'] = True
+            self.result['changed'] = False
+            self.result['msg'] = ("Invalid target state '{}' requested for ViNS ID {} in the "
+                                    "current status '{}'").format(self.vins_id,
+                                                                    self.amodule.params['state'],
+                                                                    self.vins_facts['status'])
+        else:
+            self.result['failed'] = True
+            self.result['changed'] = False
+            self.result['msg'] = ("Invalid target state '{}' requested for non-existent "
+                                   "ViNS name '{}'").format(self.amodule.params['state'],
+                                                            self.amodule.params['vins_name'])   
+        return
+    def package_facts(self, arg_check_mode=False):
+        """Package a dictionary of ViNS facts according to the decort_vins module specification. 
+        This dictionary will be returned to the upstream Ansible engine at the completion of 
+        the module run.
+
+        @param arg_check_mode: boolean that tells if this Ansible module is run in check mode
+        """
+
+        ret_dict = dict(id=0,
+                        name="none",
+                        state="CHECK_MODE",
+                        )
+
+        if arg_check_mode:
+            # in check mode return immediately with the default values
+            return ret_dict
+
+        if self.vins_facts is None:
+            # if void facts provided - change state value to ABSENT and return
+            ret_dict['state'] = "ABSENT"
+            return ret_dict
+
+        ret_dict['id'] = self.vins_facts['id']
+        ret_dict['name'] = self.vins_facts['name']
+        ret_dict['state'] = self.vins_facts['status']
+        ret_dict['account_id'] = self.vins_facts['accountId']
+        ret_dict['rg_id'] = self.vins_facts['rgId']
+        ret_dict['int_net_addr'] = self.vins_facts['network']
+        ret_dict['gid'] = self.vins_facts['gid']
+        custom_interfaces = list(filter(lambda i: i['type']=="CUSTOM",self.vins_facts['VNFDev']['interfaces']))
+        if custom_interfaces:
+            ret_dict['custom_net_addr'] = []
+            for runner in custom_interfaces:
+                ret_dict['custom_net_addr'].append(runner['ipAddress'])
+        mgmt_interfaces = list(filter(lambda i: i['listenSsh'] and i['name']!="ens9",self.vins_facts['VNFDev']['interfaces']))
+        if mgmt_interfaces:
+            ret_dict['ssh_ipaddr'] = []
+            for runner in mgmt_interfaces:
+                ret_dict['ssh_ipaddr'].append(runner['ipAddress'])
+            ret_dict['ssh_password'] = self.vins_facts['VNFDev']['config']['mgmt']['password']
+            ret_dict['ssh_port'] = 9022
+        if self.vins_facts['vnfs'].get('GW'):
+            gw_config = self.vins_facts['vnfs']['GW']['config']
+            ret_dict['ext_ip_addr'] = gw_config['ext_net_ip']
+            ret_dict['ext_net_id'] = gw_config['ext_net_id']
+        else:
+            ret_dict['ext_ip_addr'] = ""
+            ret_dict['ext_net_id'] = -1
+
+        return ret_dict
+
+    @staticmethod
+    def build_parameters():
+        """Build and return a dictionary of parameters expected by decort_vins module in a form accepted
+        by AnsibleModule utility class."""
+
+        return dict(
+            account_id=dict(type='int', required=False,default=0),
+            account_name=dict(type='str', required=False, default=''),
+            annotation=dict(type='str', required=False, default=''),
+            app_id=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_APP_ID'])),
+            app_secret=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_APP_SECRET']),
+                            no_log=True),
+            authenticator=dict(type='str',
+                            required=True,
+                            choices=['legacy', 'oauth2', 'jwt']),
+            controller_url=dict(type='str', required=True),
+            # datacenter=dict(type='str', required=False, default=''),
+            ext_net_id=dict(type='int', required=False, default=-1),
+            ext_ip_addr=dict(type='str', required=False, default=''),
+            ipcidr=dict(type='str', required=False, default=''),
+            mgmtaddr=dict(type='list',required=False, default=[]),
+            custom_config=dict(type='bool',required=False, default=False),
+            config_save=dict(type='bool',required=False, default=False),
+            connect_to=dict(type='list', default=[], required=False),
+            jwt=dict(type='str',
+                    required=False,
+                    fallback=(env_fallback, ['DECORT_JWT']),
+                    no_log=True),
+            oauth2_url=dict(type='str',
+                            required=False,
+                            fallback=(env_fallback, ['DECORT_OAUTH2_URL'])),
+            password=dict(type='str',
+                        required=False,
+                        fallback=(env_fallback, ['DECORT_PASSWORD']),
+                        no_log=True),
+            state=dict(type='str',
+                    default='present',
+                    choices=['absent', 'disabled', 'enabled', 'present']),
+            user=dict(type='str',
+                    required=False,
+                    fallback=(env_fallback, ['DECORT_USER'])),
+            rg_id=dict(type='int', required=False, default=0),
+            rg_name=dict(type='str', required=False, default=''),
+            verify_ssl=dict(type='bool', required=False, default=True),
+            vins_id=dict(type='int', required=False, default=0),
+            vins_name=dict(type='str', required=False,default=""),
+            workflow_callback=dict(type='str', required=False),
+            workflow_context=dict(type='str', required=False),
+        )
+
+
+# Workflow digest:
+# 1) authenticate to DECORT controller & validate authentication by issuing API call - done when creating DECORTController
+# 2) check if the ViNS with this id or name exists under specified account / resource group
+# 3) if ViNS does not exist -> deploy
+# 4) if ViNS exists: check desired state, desired configuration -> initiate action(s) accordingly
+# 5) report result to Ansible
+
+def main():
+    module_parameters = decort_vins.build_parameters()
+
+    amodule = AnsibleModule(argument_spec=module_parameters,
+                            supports_check_mode=True,
+                            mutually_exclusive=[
+                                ['oauth2', 'password'],
+                                ['password', 'jwt'],
+                                ['jwt', 'oauth2'],
+                            ],
+                            required_together=[
+                                ['app_id', 'app_secret'],
+                                ['user', 'password'],
+                            ],
+                            required_one_of=[
+                                ['vins_id', 'vins_name'],
+                            ],
+                            )
+
+    decon = decort_vins(amodule)
+    #
+    # Initial validation of module arguments is complete
+    #
+    # At this point non-zero vins_id means that we will be managing pre-existing ViNS
+    # Otherwise we are about to create a new one as follows:
+    # - if validated_rg_id is non-zero, create ViNS @ RG level
+    # - if validated_rg_id is zero, create ViNS @ account level
+    #
+    # When managing existing ViNS we need to account for both "static" and "transient"
+    # status. Full range of ViNS statii is as follows:
+    #
+    # "MODELED", "CREATED", "ENABLED", "ENABLING", "DISABLED", "DISABLING", "DELETED", "DELETING", "DESTROYED", "DESTROYING"
+    #
+    # if cconfig_save is true, only config save without other updates
+    vins_should_exist = False
+
+    if decon.vins_id:
+        vins_should_exist = True
+        if decon.vins_facts['status'] in ["MODELED", "DISABLING", "ENABLING", "DELETING", "DESTROYING"]:
+            # error: nothing can be done to existing ViNS in the listed statii regardless of
+            # the requested state
+            decon.result['failed'] = True
+            decon.result['changed'] = False
+            decon.result['msg'] = ("No change can be done for existing ViNS ID {} because of its current "
+                                   "status '{}'").format(decon.vins_id, decon.vins_facts['status'])
+        elif decon.vins_facts['status'] == "DISABLED":
+            if amodule.params['state'] == 'absent':
+                decon.delete()
+                vins_should_exist = False
+            elif amodule.params['state'] in ('present', 'disabled'):
+                # update ViNS, leave in disabled state
+                decon.action()
+            elif amodule.params['state'] == 'enabled':
+                # update ViNS and enable
+                decon.action('enabled')
+        elif decon.vins_facts['status'] in ["CREATED", "ENABLED"]:
+            if amodule.params['state'] == 'absent':
+                decon.delete()
+                vins_should_exist = False
+            elif amodule.params['state'] in ('present', 'enabled'):
+                # update ViNS
+                decon.action()
+            elif amodule.params['state'] == 'disabled':
+                # disable and update ViNS
+                decon.action('disabled')
+        elif decon.vins_facts['status'] == "DELETED":
+            if amodule.params['state'] in ['present', 'enabled']:
+                # restore and enable
+                decon.action(restore=True)
+                vins_should_exist = True
+            elif amodule.params['state'] == 'absent':
+                # destroy permanently
+                decon.delete()
+                vins_should_exist = False
+            elif amodule.params['state'] == 'disabled':
+                decon.error()
+                vins_should_exist = False
+        elif decon.vins_facts['status'] == "DESTROYED":
+            if amodule.params['state'] in ('present', 'enabled'):
+                # need to re-provision ViNS;
+                decon.create()
+                vins_should_exist = True
+            elif amodule.params['state'] == 'absent':
+                decon.nop()
+                vins_should_exist = False
+            elif amodule.params['state'] == 'disabled':
+                decon.error()
+    else:
+        # Preexisting ViNS was not found.
+        vins_should_exist = False  # we will change it back to True if ViNS is created or restored
+        # If requested state is 'absent' - nothing to do
+        if amodule.params['state'] == 'absent':
+            decon.nop()
+        elif amodule.params['state'] in ('present', 'enabled'):
+            decon.check_amodule_argument('vins_name')
+            # as we already have account ID and RG ID we can create ViNS and get vins_id on success
+            decon.create()
+            vins_should_exist = True
+        elif amodule.params['state'] == 'disabled':
+            decon.error()
+    #
+    # conditional switch end - complete module run
+    #
+    if decon.result['failed']:
+        amodule.fail_json(**decon.result)
+    else:
+        # prepare ViNS facts to be returned as part of decon.result and then call exit_json(...)
+        if decon.result['changed']:
+            _, decon.vins_facts = decon.vins_find(decon.vins_id)
+        decon.result['facts'] = decon.package_facts(amodule.check_mode)
+        amodule.exit_json(**decon.result)
+
+
+if __name__ == "__main__":
+    main()