diff options
Diffstat (limited to 'ansible_collections/azure/azcollection/plugins/doc_fragments')
3 files changed, 269 insertions, 0 deletions
diff --git a/ansible_collections/azure/azcollection/plugins/doc_fragments/azure.py b/ansible_collections/azure/azcollection/plugins/doc_fragments/azure.py new file mode 100644 index 000000000..bc382e401 --- /dev/null +++ b/ansible_collections/azure/azcollection/plugins/doc_fragments/azure.py @@ -0,0 +1,143 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2016 Matt Davis, <mdavis@ansible.com> +# Copyright: (c) 2016 Chris Houseknecht, <house@redhat.com> +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +class ModuleDocFragment(object): + + # Azure doc fragment + DOCUMENTATION = r''' + +options: + ad_user: + description: + - Active Directory username. Use when authenticating with an Active Directory user rather than service + principal. + type: str + password: + description: + - Active Directory user password. Use when authenticating with an Active Directory user rather than service + principal. + type: str + profile: + description: + - Security profile found in ~/.azure/credentials file. + type: str + subscription_id: + description: + - Your Azure subscription Id. + type: str + client_id: + description: + - Azure client ID. Use when authenticating with a Service Principal. + type: str + secret: + description: + - Azure client secret. Use when authenticating with a Service Principal. + type: str + tenant: + description: + - Azure tenant ID. Use when authenticating with a Service Principal. + type: str + cloud_environment: + description: + - For cloud environments other than the US public cloud, the environment name (as defined by Azure Python SDK, eg, C(AzureChinaCloud), + C(AzureUSGovernment)), or a metadata discovery endpoint URL (required for Azure Stack). Can also be set via credential file profile or + the C(AZURE_CLOUD_ENVIRONMENT) environment variable. + type: str + default: AzureCloud + version_added: '0.0.1' + adfs_authority_url: + description: + - Azure AD authority url. Use when authenticating with Username/password, and has your own ADFS authority. + type: str + version_added: '0.0.1' + cert_validation_mode: + description: + - Controls the certificate validation behavior for Azure endpoints. By default, all modules will validate the server certificate, but + when an HTTPS proxy is in use, or against Azure Stack, it may be necessary to disable this behavior by passing C(ignore). Can also be + set via credential file profile or the C(AZURE_CERT_VALIDATION) environment variable. + type: str + choices: [ ignore, validate ] + version_added: '0.0.1' + auth_source: + description: + - Controls the source of the credentials to use for authentication. + - Can also be set via the C(ANSIBLE_AZURE_AUTH_SOURCE) environment variable. + - When set to C(auto) (the default) the precedence is module parameters -> C(env) -> C(credential_file) -> C(cli). + - When set to C(env), the credentials will be read from the environment variables + - When set to C(credential_file), it will read the profile from C(~/.azure/credentials). + - When set to C(cli), the credentials will be sources from the Azure CLI profile. C(subscription_id) or the environment variable + C(AZURE_SUBSCRIPTION_ID) can be used to identify the subscription ID if more than one is present otherwise the default + az cli subscription is used. + - When set to C(msi), the host machine must be an azure resource with an enabled MSI extension. C(subscription_id) or the + environment variable C(AZURE_SUBSCRIPTION_ID) can be used to identify the subscription ID if the resource is granted + access to more than one subscription, otherwise the first subscription is chosen. + - The C(msi) was added in Ansible 2.6. + type: str + default: auto + choices: + - auto + - cli + - credential_file + - env + - msi + version_added: '0.0.1' + api_profile: + description: + - Selects an API profile to use when communicating with Azure services. Default value of C(latest) is appropriate for public clouds; + future values will allow use with Azure Stack. + type: str + default: latest + version_added: '0.0.1' + log_path: + description: + - Parent argument. + type: str + log_mode: + description: + - Parent argument. + type: str + x509_certificate_path: + description: + - Path to the X509 certificate used to create the service principal in PEM format. + - The certificate must be appended to the private key. + - Use when authenticating with a Service Principal. + type: path + version_added: '1.14.0' + thumbprint: + description: + - The thumbprint of the private key specified in I(x509_certificate_path). + - Use when authenticating with a Service Principal. + - Required if I(x509_certificate_path) is defined. + type: str + version_added: '1.14.0' +requirements: + - python >= 2.7 + - The host that executes this module must have the azure.azcollection collection installed via galaxy + - All python packages listed in collection's requirements-azure.txt must be installed via pip on the host that executes modules from azure.azcollection + - Full installation instructions may be found https://galaxy.ansible.com/azure/azcollection + +notes: + - For authentication with Azure you can pass parameters, set environment variables, use a profile stored + in ~/.azure/credentials, or log in before you run your tasks or playbook with C(az login). + - Authentication is also possible using a service principal or Active Directory user. + - To authenticate via service principal, pass subscription_id, client_id, secret and tenant or set environment + variables AZURE_SUBSCRIPTION_ID, AZURE_CLIENT_ID, AZURE_SECRET and AZURE_TENANT. + - To authenticate via Active Directory user, pass ad_user and password, or set AZURE_AD_USER and + AZURE_PASSWORD in the environment. + - "Alternatively, credentials can be stored in ~/.azure/credentials. This is an ini file containing + a [default] section and the following keys: subscription_id, client_id, secret and tenant or + subscription_id, ad_user and password. It is also possible to add additional profiles. Specify the profile + by passing profile or setting AZURE_PROFILE in the environment." + +seealso: + - name: Sign in with Azure CLI + link: https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli?view=azure-cli-latest + description: How to authenticate using the C(az login) command. + ''' diff --git a/ansible_collections/azure/azcollection/plugins/doc_fragments/azure_rm.py b/ansible_collections/azure/azcollection/plugins/doc_fragments/azure_rm.py new file mode 100644 index 000000000..8d860d863 --- /dev/null +++ b/ansible_collections/azure/azcollection/plugins/doc_fragments/azure_rm.py @@ -0,0 +1,95 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2016 Matt Davis, <mdavis@ansible.com> +# Copyright: (c) 2016 Chris Houseknecht, <house@redhat.com> +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +class ModuleDocFragment(object): + + # Azure doc fragment + DOCUMENTATION = r''' +options: + plugin: + description: marks this as an instance of the 'azure_rm' plugin + required: true + choices: ['azure_rm', 'azure.azcollection.azure_rm'] + include_vm_resource_groups: + description: A list of resource group names to search for virtual machines. '\*' will include all resource + groups in the subscription. Can also be set comma separated resource group names via the + C(ANSIBLE_AZURE_VM_RESOURCE_GROUPS) environment variable. + default: ['*'] + include_vmss_resource_groups: + description: A list of resource group names to search for virtual machine scale sets (VMSSs). '\*' will + include all resource groups in the subscription. + default: [] + fail_on_template_errors: + description: When false, template failures during group and filter processing are silently ignored (eg, + if a filter or group expression refers to an undefined host variable) + choices: [True, False] + default: True + keyed_groups: + description: Creates groups based on the value of a host variable. Requires a list of dictionaries, + defining C(key) (the source dictionary-typed variable), C(prefix) (the prefix to use for the new group + name), and optionally C(separator) (which defaults to C(_)) + conditional_groups: + description: A mapping of group names to Jinja2 expressions. When the mapped expression is true, the host + is added to the named group. + hostvar_expressions: + description: A mapping of hostvar names to Jinja2 expressions. The value for each host is the result of the + Jinja2 expression (which may refer to any of the host's existing variables at the time this inventory + plugin runs). + exclude_host_filters: + description: Excludes hosts from the inventory with a list of Jinja2 conditional expressions. Each + expression in the list is evaluated for each host; when the expression is true, the host is excluded + from the inventory. + default: [] + batch_fetch: + description: To improve performance, results are fetched using an unsupported batch API. Disabling + C(batch_fetch) uses a much slower serial fetch, resulting in many more round-trips. Generally only + useful for troubleshooting. + default: true + default_host_filters: + description: A default set of filters that is applied in addition to the conditions in + C(exclude_host_filters) to exclude powered-off and not-fully-provisioned hosts. Set this to a different + value or empty list if you need to include hosts in these states. + default: ['powerstate != "running"', 'provisioning_state != "succeeded"'] + use_contrib_script_compatible_sanitization: + description: + - By default this plugin is using a general group name sanitization to create safe and usable group names for use in Ansible. + This option allows you to override that, in efforts to allow migration from the old inventory script and + matches the sanitization of groups when the script's ``replace_dash_in_groups`` option is set to ``False``. + To replicate behavior of ``replace_dash_in_groups = True`` with constructed groups, + you will need to replace hyphens with underscores via the regex_replace filter for those entries. + - For this to work you should also turn off the TRANSFORM_INVALID_GROUP_CHARS setting, + otherwise the core engine will just use the standard sanitization on top. + - This is not the default as such names break certain functionality as not all characters are valid Python identifiers + which group names end up being used as. + type: bool + default: False + version_added: '0.0.1' + plain_host_names: + description: + - By default this plugin will use globally unique host names. + This option allows you to override that, and use the name that matches the old inventory script naming. + - This is not the default, as these names are not truly unique, and can conflict with other hosts. + The default behavior will add extra hashing to the end of the hostname to prevent such conflicts. + type: bool + default: False + version_added: '0.0.1' + hostnames: + description: + - A list of Jinja2 expressions in order of precedence to compose inventory_hostname. + - Ignores expression if result is an empty string or None value. + - By default, inventory_hostname is generated to be globally unique based on the VM host name. + See C(plain_host_names) for more details on the default. + - An expression of 'default' will force using the default hostname generator if no previous hostname expression + resulted in a valid hostname. + - Use ``default_inventory_hostname`` to access the default hostname generator's value in any of the Jinja2 expressions. + type: list + elements: str + default: [default] +''' diff --git a/ansible_collections/azure/azcollection/plugins/doc_fragments/azure_tags.py b/ansible_collections/azure/azcollection/plugins/doc_fragments/azure_tags.py new file mode 100644 index 000000000..8edb80eed --- /dev/null +++ b/ansible_collections/azure/azcollection/plugins/doc_fragments/azure_tags.py @@ -0,0 +1,31 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2016, Matt Davis, <mdavis@ansible.com> +# Copyright: (c) 2016, Chris Houseknecht, <house@redhat.com> +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +class ModuleDocFragment(object): + + # Azure doc fragment + DOCUMENTATION = r''' +options: + tags: + description: + - Dictionary of string:string pairs to assign as metadata to the object. + - Metadata tags on the object will be updated with any provided values. + - To remove tags set append_tags option to false. + - Currently, Azure DNS zones and Traffic Manager services also don't allow the use of spaces in the tag. + - Azure Front Door doesn't support the use of # in the tag name. + - Azure Automation and Azure CDN only support 15 tags on resources. + type: dict + append_tags: + description: + - Use to control if tags field is canonical or just appends to existing tags. + - When canonical, any tags not found in the tags parameter will be removed from the object's metadata. + type: bool + default: yes + ''' |