Debian Codegraph @

ansible_collections/netapp/ontap/plugins/modules/na_ontap_nvme_namespace.py

raw
1 #!/usr/bin/python
2
3 # (c) 2018-2026, NetApp, Inc
4 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
5 from __future__ import absolute_import, division, print_function
6 __metaclass__ = type
7
8 DOCUMENTATION = '''
9 author: NetApp Ansible Team (@carchi8py) <[email protected]>
10 description:
11 - Create/Delete NVME namespace
12 extends_documentation_fragment:
13 - netapp.ontap.netapp.na_ontap
14 module: na_ontap_nvme_namespace
15 options:
16 state:
17 choices: ['present', 'absent']
18 description:
19 - Whether the specified namespace should exist or not.
20 default: present
21 type: str
22 vserver:
23 description:
24 - Name of the vserver to use.
25 required: true
26 type: str
27 ostype:
28 description:
29 - Specifies the ostype for initiators
30 choices: ['windows', 'linux', 'vmware', 'xen', 'hyper_v']
31 type: str
32 size:
33 description:
34 - Size in bytes.
35 Range is [0..2^63-1].
36 type: int
37 size_unit:
38 description:
39 - The unit used to interpret the size parameter.
40 choices: ['bytes', 'b', 'kb', 'mb', 'gb', 'tb', 'pb', 'eb', 'zb', 'yb']
41 type: str
42 default: 'b'
43 path:
44 description:
45 - Namespace path.
46 - The name of the NVMe namespace.
47 - NVMe namespace names are paths of the form "/vol/<volume>[/<qtree>]/<namespace>" where the qtree name is optional.
48 - For ASA r2 systems, The path should match the format <name>[@<snapshot-name>].
49 required: true
50 type: str
51 block_size:
52 description:
53 - Size in bytes of a logical block. Possible values are 512 (Data ONTAP 9.6 and later), 4096. The default value is 4096.
54 choices: [512, 4096]
55 type: int
56 version_added: '20.5.0'
57 provisioning_options:
58 description:
59 - Options that are applied to the operation.
60 - This option is available only for ASA r2 systems.
61 type: dict
62 version_added: '23.0.0'
63 suboptions:
64 count:
65 description:
66 - The number of LUNs to provision with these properties.
67 - Only POST requests based on space.size are supported.
68 - When provided, the name is considered a prefix, and a suffix of the form _<N> is generated
69 where N is the next available numeric index, starting with 1.
70 type: int
71 short_description: "NetApp ONTAP Manage NVME Namespace"
72 version_added: 2.8.0
73 notes:
74 - Compatible with ASA r2 system when using REST for ONTAP releases 9.16.0x onwards.
75 '''
76
77 EXAMPLES = """
78 - name: Create NVME Namespace
79 netapp.ontap.na_ontap_nvme_namespace:
80 state: present
81 ostype: linux
82 path: /vol/ansible/test
83 size: 5
84 size_unit: mb
85 vserver: "{{ vserver }}"
86 hostname: "{{ netapp_hostname }}"
87 username: "{{ netapp_username }}"
88 password: "{{ netapp_password }}"
89
90 - name: Create NVME Namespace ASA r2 system
91 netapp.ontap.na_ontap_nvme_namespace:
92 state: present
93 ostype: linux
94 path: /vol/ansible/test
95 size: 5
96 size_unit: mb
97 provisioning_options:
98 count: 2
99 vserver: "{{ vserver }}"
100 hostname: "{{ netapp_hostname }}"
101 username: "{{ netapp_username }}"
102 password: "{{ netapp_password }}"
103
104 - name: Modify NVME Namespace
105 netapp.ontap.na_ontap_nvme_namespace:
106 state: present
107 ostype: linux
108 path: /vol/ansible/test
109 size: 10
110 size_unit: mb
111 vserver: "{{ vserver }}"
112 hostname: "{{ netapp_hostname }}"
113 username: "{{ netapp_username }}"
114 password: "{{ netapp_password }}"
115
116 - name: Delete NVME Namespace
117 netapp.ontap.na_ontap_nvme_namespace:
118 state: absent
119 ostype: linux
120 path: /vol/ansible/test
121 size: 10
122 size_unit: mb
123 vserver: "{{ vserver }}"
124 hostname: "{{ netapp_hostname }}"
125 username: "{{ netapp_username }}"
126 password: "{{ netapp_password }}"
127 """
128
129 RETURN = """
130 """
131
132 import traceback
133 from ansible.module_utils.basic import AnsibleModule
134 from ansible.module_utils._text import to_native
135 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
136 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
137 from ansible_collections.netapp.ontap.plugins.module_utils.netapp import OntapRestAPI
138 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic, rest_ontap_personality
139
140
141 class NetAppONTAPNVMENamespace:
142 """
143 Class with NVME namespace methods
144 """
145
146 def __init__(self):
147
148 self.namespace_uuid = None
149 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
150 self.argument_spec.update(dict(
151 state=dict(required=False, type='str', choices=['present', 'absent'], default='present'),
152 vserver=dict(required=True, type='str'),
153 ostype=dict(required=False, type='str', choices=['windows', 'linux', 'vmware', 'xen', 'hyper_v']),
154 path=dict(required=True, type='str'),
155 size=dict(required=False, type='int'),
156 size_unit=dict(default='b', choices=['bytes', 'b', 'kb', 'mb', 'gb', 'tb', 'pb', 'eb', 'zb', 'yb'], type='str'),
157 block_size=dict(required=False, choices=[512, 4096], type='int'),
158 provisioning_options=dict(required=False, type='dict', options=dict(
159 count=dict(type='int'),
160 ))
161 ))
162
163 self.module = AnsibleModule(
164 argument_spec=self.argument_spec,
165 required_if=[('state', 'present', ['ostype', 'size'])],
166 supports_check_mode=True
167 )
168
169 self.na_helper = NetAppModule()
170 self.parameters = self.na_helper.set_parameters(self.module.params)
171 self.rest_api = OntapRestAPI(self.module)
172 partially_supported_rest_properties = [['provisioning_options', (9, 16, 0)]]
173 self.use_rest = self.rest_api.is_rest_supported_properties(self.parameters, [], partially_supported_rest_properties)
174 if self.parameters.get('size'):
175 self.parameters['size'] = self.parameters['size'] * \
176 netapp_utils.POW2_BYTE_MAP[self.parameters['size_unit']]
177 self.asa_r2_system = False
178 if self.use_rest:
179 if self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 16, 0):
180 self.asa_r2_system = rest_ontap_personality.is_asa_r2_system(self.rest_api, self.module)
181 if self.asa_r2_system:
182 if 'path' in self.parameters:
183 self.module.warn('For ASA r2 systems, The path should match the format <name>[@<snapshot-name>].'
184 'The name must begin with a letter or \"_\" and contain only \"_\" and alphanumeric character')
185 # If the path is passed as vol/vol1/ns it will be converted to ns for asa r2 systems.
186 self.parameters['path'] = self.parameters.get('path').split("/")[-1]
187 if not self.asa_r2_system and 'provisioning_options' in self.parameters:
188 self.module.fail_json(msg='ONTAP does not support provisioning_options')
189 if self.use_rest and 'size' in self.parameters:
190 if 'block_size' not in self.parameters and self.parameters.get('os_type') != 'vmware':
191 self.default_block_size = 4096
192 else:
193 self.default_block_size = 512
194 self.parameters['size'] = ((self.parameters['size'] + self.default_block_size - 1) // self.default_block_size) * self.default_block_size
195 if not self.use_rest:
196 if not netapp_utils.has_netapp_lib():
197 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
198 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=self.parameters['vserver'])
199
200 def get_namespace(self):
201 """
202 Get current namespace details
203 :return: dict if namespace exists, None otherwise
204 """
205 if self.use_rest:
206 return self.get_namespace_rest()
207 namespace_get = netapp_utils.zapi.NaElement('nvme-namespace-get-iter')
208 query = {
209 'query': {
210 'nvme-namespace-info': {
211 'path': self.parameters['path'],
212 'vserver': self.parameters['vserver']
213 }
214 }
215 }
216 namespace_get.translate_struct(query)
217 try:
218 result = self.server.invoke_successfully(namespace_get, enable_tunneling=False)
219 except netapp_utils.zapi.NaApiError as error:
220 self.module.fail_json(msg='Error fetching namespace info: %s' % to_native(error),
221 exception=traceback.format_exc())
222 if result.get_child_by_name('num-records') and int(result.get_child_content('num-records')) >= 1:
223 return result
224 return None
225
226 def create_namespace(self):
227 """
228 Create a NVME Namespace
229 """
230 if self.use_rest:
231 return self.create_namespace_rest()
232 options = {'path': self.parameters['path'],
233 'ostype': self.parameters['ostype'],
234 'size': self.parameters['size']
235 }
236 if self.parameters.get('block_size'):
237 options['block-size'] = self.parameters['block_size']
238 namespace_create = netapp_utils.zapi.NaElement('nvme-namespace-create')
239 namespace_create.translate_struct(options)
240 try:
241 self.server.invoke_successfully(namespace_create, enable_tunneling=True)
242 except netapp_utils.zapi.NaApiError as error:
243 self.module.fail_json(msg='Error creating namespace for path %s: %s'
244 % (self.parameters.get('path'), to_native(error)),
245 exception=traceback.format_exc())
246
247 def delete_namespace(self):
248 """
249 Delete a NVME Namespace
250 """
251 if self.use_rest:
252 return self.delete_namespace_rest()
253 options = {'path': self.parameters['path']
254 }
255 namespace_delete = netapp_utils.zapi.NaElement.create_node_with_children('nvme-namespace-delete', **options)
256 try:
257 self.server.invoke_successfully(namespace_delete, enable_tunneling=True)
258 except netapp_utils.zapi.NaApiError as error:
259 self.module.fail_json(msg='Error deleting namespace for path %s: %s'
260 % (self.parameters.get('path'), to_native(error)),
261 exception=traceback.format_exc())
262
263 def get_namespace_rest(self):
264 api = 'storage/namespaces'
265 params = {
266 'svm.name': self.parameters['vserver'],
267 'fields': 'space.size,uuid'
268 }
269 response, error = rest_generic.get_0_or_more_records(self.rest_api, api, params)
270 if error:
271 self.module.fail_json(msg='Error fetching namespace info for vserver: %s' % self.parameters['vserver'])
272
273 existing_namespaces = {}
274
275 if response:
276 for record in response:
277 existing_namespaces[record['name']] = {
278 'uuid': record['uuid'],
279 'size': record['space']['size']
280 }
281
282 requested_name = self.parameters['path']
283 if requested_name in existing_namespaces:
284 self.namespace_uuid = existing_namespaces[requested_name]['uuid']
285 return {'size' : existing_namespaces[requested_name]['size']} # Returns exact match
286
287 base_name = requested_name.rsplit('-', 1)[0] # extract base name if n exists
288 matching_names = {
289 name: data for name, data in existing_namespaces.items() if name.startswith(base_name + "_")
290 }
291 if matching_names:
292 first_match = next(iter(matching_names.values()))
293 return {'size': first_match['size']}
294 self.namespace_uuid = None
295 return None
296
297 def create_namespace_rest(self):
298 api = 'storage/namespaces'
299 body = {'svm.name': self.parameters['vserver'],
300 'os_type': self.parameters['ostype'],
301 'name': self.parameters['path'],
302 'space.size': self.parameters['size']}
303 if self.parameters.get('block_size') is not None:
304 body['space.block_size'] = self.parameters['block_size']
305 if self.parameters.get('provisioning_options') is not None:
306 body['provisioning_options'] = self.parameters['provisioning_options']
307 dummy, error = rest_generic.post_async(self.rest_api, api, body)
308 if error:
309 self.module.fail_json(msg='Error creating namespace for vserver %s: %s' % (self.parameters['vserver'], to_native(error)),
310 exception=traceback.format_exc())
311
312 def delete_namespace_rest(self):
313 api = 'storage/namespaces'
314 dummy, error = rest_generic.delete_async(self.rest_api, api, self.namespace_uuid)
315 if error:
316 self.module.fail_json(msg='Error deleting namespace for vserver %s: %s' % (self.parameters['vserver'], to_native(error)),
317 exception=traceback.format_exc())
318
319 def modify_namespace_rest(self):
320 api = 'storage/namespaces'
321 body = {'space.size': self.parameters['size']}
322 dummy, error = rest_generic.patch_async(self.rest_api, api, self.namespace_uuid, body)
323 if error:
324 self.module.fail_json(msg='Error modifying namespace for vserver %s: %s' % (self.parameters['vserver'], to_native(error)),
325 exception=traceback.format_exc())
326
327 def apply(self):
328 """
329 Apply action to NVME Namespace
330 """
331 current = self.get_namespace()
332 cd_action = self.na_helper.get_cd_action(current, self.parameters)
333 modify = self.na_helper.get_modified_attributes(current, self.parameters) if cd_action is None and self.namespace_uuid is not None else None
334
335 if self.na_helper.changed and not self.module.check_mode:
336 if cd_action == 'create':
337 self.create_namespace()
338 elif cd_action == 'delete':
339 self.delete_namespace()
340 elif modify:
341 self.modify_namespace_rest()
342 result = netapp_utils.generate_result(self.na_helper.changed, cd_action)
343 self.module.exit_json(**result)
344
345
346 def main():
347 """Execute action"""
348 community_obj = NetAppONTAPNVMENamespace()
349 community_obj.apply()
350
351
352 if __name__ == '__main__':
353 main()