1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
community.general/plugins/modules/gitlab_project_variable.py
Felix Fontein b531ecdc9b
Unflatmap community.general (#5461)
* Move files.

* Update imports and references.

* Move wrongly placed files.

* Reverse redirects, deprecate long → short name redirects.

* Simplify contribution guidelines for new modules.

* Rewrite BOTMETA.

* Add changelog fragment.

* Fix ignore.txt files.
2022-11-02 20:42:29 +00:00

482 lines
16 KiB
Python

#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright (c) 2019, Markus Bergholz (markuman@gmail.com)
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
module: gitlab_project_variable
short_description: Creates/updates/deletes GitLab Projects Variables
description:
- When a project variable does not exist, it will be created.
- When a project variable does exist, its value will be updated when the values are different.
- Variables which are untouched in the playbook, but are not untouched in the GitLab project,
they stay untouched (I(purge) is C(false)) or will be deleted (I(purge) is C(true)).
author:
- "Markus Bergholz (@markuman)"
requirements:
- python >= 2.7
- python-gitlab python module
extends_documentation_fragment:
- community.general.auth_basic
- community.general.gitlab
options:
state:
description:
- Create or delete project variable.
- Possible values are present and absent.
default: present
type: str
choices: ["present", "absent"]
project:
description:
- The path and name of the project.
required: true
type: str
purge:
description:
- When set to true, all variables which are not untouched in the task will be deleted.
default: false
type: bool
vars:
description:
- When the list element is a simple key-value pair, masked and protected will be set to false.
- When the list element is a dict with the keys I(value), I(masked) and I(protected), the user can
have full control about whether a value should be masked, protected or both.
- Support for protected values requires GitLab >= 9.3.
- Support for masked values requires GitLab >= 11.10.
- Support for environment_scope requires GitLab Premium >= 13.11.
- Support for variable_type requires GitLab >= 11.11.
- A I(value) must be a string or a number.
- Field I(variable_type) must be a string with either C(env_var), which is the default, or C(file).
- Field I(environment_scope) must be a string defined by scope environment.
- When a value is masked, it must be in Base64 and have a length of at least 8 characters.
See GitLab documentation on acceptable values for a masked variable (https://docs.gitlab.com/ce/ci/variables/#masked-variables).
default: {}
type: dict
variables:
version_added: 4.4.0
description:
- A list of dictionaries that represents CI/CD variables.
- This module works internal with this structure, even if the older I(vars) parameter is used.
default: []
type: list
elements: dict
suboptions:
name:
description:
- The name of the variable.
type: str
required: true
value:
description:
- The variable value.
- Required when I(state=present).
type: str
masked:
description:
- Wether variable value is masked or not.
- Support for masked values requires GitLab >= 11.10.
type: bool
default: false
protected:
description:
- Wether variable value is protected or not.
- Support for protected values requires GitLab >= 9.3.
type: bool
default: false
variable_type:
description:
- Wether a variable is an environment variable (C(env_var)) or a file (C(file)).
- Support for I(variable_type) requires GitLab >= 11.11.
type: str
choices: ["env_var", "file"]
default: env_var
environment_scope:
description:
- The scope for the variable.
- Support for I(environment_scope) requires GitLab Premium >= 13.11.
type: str
default: '*'
'''
EXAMPLES = '''
- name: Set or update some CI/CD variables
community.general.gitlab_project_variable:
api_url: https://gitlab.com
api_token: secret_access_token
project: markuman/dotfiles
purge: false
variables:
- name: ACCESS_KEY_ID
value: abc123
- name: SECRET_ACCESS_KEY
value: dassgrfaeui8989
masked: true
protected: true
environment_scope: production
- name: Set or update some CI/CD variables
community.general.gitlab_project_variable:
api_url: https://gitlab.com
api_token: secret_access_token
project: markuman/dotfiles
purge: false
vars:
ACCESS_KEY_ID: abc123
SECRET_ACCESS_KEY:
value: 3214cbad
masked: true
protected: true
variable_type: env_var
environment_scope: '*'
- name: Delete one variable
community.general.gitlab_project_variable:
api_url: https://gitlab.com
api_token: secret_access_token
project: markuman/dotfiles
state: absent
vars:
ACCESS_KEY_ID: abc123
'''
RETURN = '''
project_variable:
description: Four lists of the variablenames which were added, updated, removed or exist.
returned: always
type: dict
contains:
added:
description: A list of variables which were created.
returned: always
type: list
sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY']
untouched:
description: A list of variables which exist.
returned: always
type: list
sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY']
removed:
description: A list of variables which were deleted.
returned: always
type: list
sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY']
updated:
description: A list of variables whose values were changed.
returned: always
type: list
sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY']
'''
import traceback
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.six import string_types
from ansible.module_utils.six import integer_types
GITLAB_IMP_ERR = None
try:
import gitlab
HAS_GITLAB_PACKAGE = True
except Exception:
GITLAB_IMP_ERR = traceback.format_exc()
HAS_GITLAB_PACKAGE = False
from ansible_collections.community.general.plugins.module_utils.gitlab import (
auth_argument_spec, gitlab_authentication, ensure_gitlab_package
)
def vars_to_variables(vars, module):
# transform old vars to new variables structure
variables = list()
for item, value in vars.items():
if (isinstance(value, string_types) or
isinstance(value, (integer_types, float))):
variables.append(
{
"name": item,
"value": str(value),
"masked": False,
"protected": False,
"variable_type": "env_var",
}
)
elif isinstance(value, dict):
new_item = {
"name": item,
"value": value.get('value'),
"masked": value.get('masked'),
"protected": value.get('protected'),
"variable_type": value.get('variable_type'),
}
if value.get('environment_scope'):
new_item['environment_scope'] = value.get('environment_scope')
variables.append(new_item)
else:
module.fail_json(msg="value must be of type string, integer, float or dict")
return variables
class GitlabProjectVariables(object):
def __init__(self, module, gitlab_instance):
self.repo = gitlab_instance
self.project = self.get_project(module.params['project'])
self._module = module
def get_project(self, project_name):
return self.repo.projects.get(project_name)
def list_all_project_variables(self):
page_nb = 1
variables = []
vars_page = self.project.variables.list(page=page_nb)
while len(vars_page) > 0:
variables += vars_page
page_nb += 1
vars_page = self.project.variables.list(page=page_nb)
return variables
def create_variable(self, var_obj):
if self._module.check_mode:
return True
var = {
"key": var_obj.get('key'), "value": var_obj.get('value'),
"masked": var_obj.get('masked'), "protected": var_obj.get('protected'),
"variable_type": var_obj.get('variable_type')
}
if var_obj.get('environment_scope') is not None:
var["environment_scope"] = var_obj.get('environment_scope')
self.project.variables.create(var)
return True
def update_variable(self, var_obj):
if self._module.check_mode:
return True
self.delete_variable(var_obj)
self.create_variable(var_obj)
return True
def delete_variable(self, var_obj):
if self._module.check_mode:
return True
self.project.variables.delete(var_obj.get('key'), filter={'environment_scope': var_obj.get('environment_scope')})
return True
def compare(requested_variables, existing_variables, state):
# we need to do this, because it was determined in a previous version - more or less buggy
# basically it is not necessary and might results in more/other bugs!
# but it is required and only relevant for check mode!!
# logic represents state 'present' when not purge. all other can be derived from that
# untouched => equal in both
# updated => name and scope are equal
# added => name and scope does not exist
untouched = list()
updated = list()
added = list()
if state == 'present':
existing_key_scope_vars = list()
for item in existing_variables:
existing_key_scope_vars.append({'key': item.get('key'), 'environment_scope': item.get('environment_scope')})
for var in requested_variables:
if var in existing_variables:
untouched.append(var)
else:
compare_item = {'key': var.get('name'), 'environment_scope': var.get('environment_scope')}
if compare_item in existing_key_scope_vars:
updated.append(var)
else:
added.append(var)
return untouched, updated, added
def native_python_main(this_gitlab, purge, requested_variables, state, module):
change = False
return_value = dict(added=list(), updated=list(), removed=list(), untouched=list())
gitlab_keys = this_gitlab.list_all_project_variables()
before = [x.attributes for x in gitlab_keys]
gitlab_keys = this_gitlab.list_all_project_variables()
existing_variables = [x.attributes for x in gitlab_keys]
# preprocessing:filter out and enrich before compare
for item in existing_variables:
item.pop('project_id')
for item in requested_variables:
item['key'] = item.pop('name')
item['value'] = str(item.get('value'))
if item.get('protected') is None:
item['protected'] = False
if item.get('masked') is None:
item['masked'] = False
if item.get('environment_scope') is None:
item['environment_scope'] = '*'
if item.get('variable_type') is None:
item['variable_type'] = 'env_var'
if module.check_mode:
untouched, updated, added = compare(requested_variables, existing_variables, state)
if state == 'present':
add_or_update = [x for x in requested_variables if x not in existing_variables]
for item in add_or_update:
try:
if this_gitlab.create_variable(item):
return_value['added'].append(item)
except Exception:
if this_gitlab.update_variable(item):
return_value['updated'].append(item)
if purge:
# refetch and filter
gitlab_keys = this_gitlab.list_all_project_variables()
existing_variables = [x.attributes for x in gitlab_keys]
for item in existing_variables:
item.pop('project_id')
remove = [x for x in existing_variables if x not in requested_variables]
for item in remove:
if this_gitlab.delete_variable(item):
return_value['removed'].append(item)
elif state == 'absent':
# value does not matter on removing variables.
# key and environment scope are sufficient
for item in existing_variables:
item.pop('value')
item.pop('variable_type')
for item in requested_variables:
item.pop('value')
item.pop('variable_type')
if not purge:
remove_requested = [x for x in requested_variables if x in existing_variables]
for item in remove_requested:
if this_gitlab.delete_variable(item):
return_value['removed'].append(item)
else:
for item in existing_variables:
if this_gitlab.delete_variable(item):
return_value['removed'].append(item)
if module.check_mode:
return_value = dict(added=added, updated=updated, removed=return_value['removed'], untouched=untouched)
if return_value['added'] or return_value['removed'] or return_value['updated']:
change = True
gitlab_keys = this_gitlab.list_all_project_variables()
after = [x.attributes for x in gitlab_keys]
return change, return_value, before, after
def main():
argument_spec = basic_auth_argument_spec()
argument_spec.update(auth_argument_spec())
argument_spec.update(
project=dict(type='str', required=True),
purge=dict(type='bool', required=False, default=False),
vars=dict(type='dict', required=False, default=dict(), no_log=True),
variables=dict(type='list', elements='dict', required=False, default=list(), options=dict(
name=dict(type='str', required=True),
value=dict(type='str', no_log=True),
masked=dict(type='bool', default=False),
protected=dict(type='bool', default=False),
environment_scope=dict(type='str', default='*'),
variable_type=dict(type='str', default='env_var', choices=["env_var", "file"])
)),
state=dict(type='str', default="present", choices=["absent", "present"]),
)
module = AnsibleModule(
argument_spec=argument_spec,
mutually_exclusive=[
['api_username', 'api_token'],
['api_username', 'api_oauth_token'],
['api_username', 'api_job_token'],
['api_token', 'api_oauth_token'],
['api_token', 'api_job_token'],
['vars', 'variables'],
],
required_together=[
['api_username', 'api_password'],
],
required_one_of=[
['api_username', 'api_token', 'api_oauth_token', 'api_job_token']
],
supports_check_mode=True
)
ensure_gitlab_package(module)
if not HAS_GITLAB_PACKAGE:
module.fail_json(msg=missing_required_lib("python-gitlab"), exception=GITLAB_IMP_ERR)
purge = module.params['purge']
var_list = module.params['vars']
state = module.params['state']
if var_list:
variables = vars_to_variables(var_list, module)
else:
variables = module.params['variables']
if state == 'present':
if any(x['value'] is None for x in variables):
module.fail_json(msg='value parameter is required in state present')
gitlab_instance = gitlab_authentication(module)
this_gitlab = GitlabProjectVariables(module=module, gitlab_instance=gitlab_instance)
change, raw_return_value, before, after = native_python_main(this_gitlab, purge, variables, state, module)
# postprocessing
for item in after:
item.pop('project_id')
item['name'] = item.pop('key')
for item in before:
item.pop('project_id')
item['name'] = item.pop('key')
untouched_key_name = 'key'
if not module.check_mode:
untouched_key_name = 'name'
raw_return_value['untouched'] = [x for x in before if x in after]
added = [x.get('key') for x in raw_return_value['added']]
updated = [x.get('key') for x in raw_return_value['updated']]
removed = [x.get('key') for x in raw_return_value['removed']]
untouched = [x.get(untouched_key_name) for x in raw_return_value['untouched']]
return_value = dict(added=added, updated=updated, removed=removed, untouched=untouched)
module.exit_json(changed=change, project_variable=return_value)
if __name__ == '__main__':
main()