xref: /dports/sysutils/py-salt/salt-3004.1/salt/modules/boto3_elasticsearch.py

"""
Connection module for Amazon Elasticsearch Service

.. versionadded:: 3001

:configuration: This module accepts explicit IAM credentials but can also
    utilize IAM roles assigned to the instance trough Instance Profiles.
    Dynamic credentials are then automatically obtained from AWS API and no
    further configuration is necessary. More Information available at:

    .. code-block:: text

        http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html

    If IAM roles are not used you need to specify them either in a pillar or
    in the minion's config file:

    .. code-block:: yaml

        es.keyid: GKTADJGHEIQSXMKKRBJ08H
        es.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

    A region may also be specified in the configuration:

    .. code-block:: yaml

        es.region: us-east-1

    If a region is not specified, the default is us-east-1.

    It's also possible to specify key, keyid and region via a profile, either
    as a passed in dict, or as a string to pull from pillars or minion config:

    .. code-block:: yaml

        myprofile:
            keyid: GKTADJGHEIQSXMKKRBJ08H
            key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
            region: us-east-1

    All methods return a dict with:
        'result' key containing a boolean indicating success or failure,
        'error' key containing the errormessage returned by boto on error,
        'response' key containing the data of the response returned by boto on success.

:codeauthor: Herbert Buurman <herbert.buurman@ogd.nl>
:depends: boto3
"""
# keep lint from choking on _get_conn and _cache_id
# pylint: disable=E0602


import logging

import salt.utils.compat
import salt.utils.json
import salt.utils.versions
from salt.exceptions import SaltInvocationError
from salt.utils.decorators import depends

try:
    # Disable unused import-errors as these are only used for dependency checking
    # pylint: disable=unused-import
    import boto3
    import botocore

    # pylint: enable=unused-import
    from botocore.exceptions import ClientError, ParamValidationError, WaiterError

    logging.getLogger("boto3").setLevel(logging.INFO)
    HAS_BOTO = True
except ImportError:
    HAS_BOTO = False

log = logging.getLogger(__name__)


def __virtual__():
    """
    Only load if boto libraries exist and if boto libraries are greater than
    a given version.
    """
    return HAS_BOTO and salt.utils.versions.check_boto_reqs(
        boto3_ver="1.2.7", check_boto=False
    )


def __init__(opts):
    _ = opts
    if HAS_BOTO:
        __utils__["boto3.assign_funcs"](__name__, "es")


def add_tags(
    domain_name=None,
    arn=None,
    tags=None,
    region=None,
    key=None,
    keyid=None,
    profile=None,
):
    """
    Attaches tags to an existing Elasticsearch domain.
    Tags are a set of case-sensitive key value pairs.
    An Elasticsearch domain may have up to 10 tags.

    :param str domain_name: The name of the Elasticsearch domain you want to add tags to.
    :param str arn: The ARN of the Elasticsearch domain you want to add tags to.
        Specifying this overrides ``domain_name``.
    :param dict tags: The dict of tags to add to the Elasticsearch domain.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    CLI Example:

    .. code-block:: bash

        salt myminion boto3_elasticsearch.add_tags domain_name=mydomain tags='{"foo": "bar", "baz": "qux"}'
    """
    if not any((arn, domain_name)):
        raise SaltInvocationError(
            "At least one of domain_name or arn must be specified."
        )
    ret = {"result": False}
    if arn is None:
        res = describe_elasticsearch_domain(
            domain_name=domain_name,
            region=region,
            key=key,
            keyid=keyid,
            profile=profile,
        )
        if "error" in res:
            ret.update(res)
        elif not res["result"]:
            ret.update(
                {
                    "error": 'The domain with name "{}" does not exist.'.format(
                        domain_name
                    )
                }
            )
        else:
            arn = res["response"].get("ARN")
    if arn:
        boto_params = {
            "ARN": arn,
            "TagList": [
                {"Key": k, "Value": value} for k, value in (tags or {}).items()
            ],
        }
        try:
            conn = _get_conn(region=region, key=key, keyid=keyid, profile=profile)
            conn.add_tags(**boto_params)
            ret["result"] = True
        except (ParamValidationError, ClientError) as exp:
            ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


@depends("botocore", version="1.12.21")
def cancel_elasticsearch_service_software_update(
    domain_name, region=None, keyid=None, key=None, profile=None
):
    """
    Cancels a scheduled service software update for an Amazon ES domain. You can
    only perform this operation before the AutomatedUpdateDate and when the UpdateStatus
    is in the PENDING_UPDATE state.

    :param str domain_name: The name of the domain that you want to stop the latest
        service software update on.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with the current service software options.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        res = conn.cancel_elasticsearch_service_software_update(DomainName=domain_name)
        ret["result"] = True
        res["response"] = res["ServiceSoftwareOptions"]
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


def create_elasticsearch_domain(
    domain_name,
    elasticsearch_version=None,
    elasticsearch_cluster_config=None,
    ebs_options=None,
    access_policies=None,
    snapshot_options=None,
    vpc_options=None,
    cognito_options=None,
    encryption_at_rest_options=None,
    node_to_node_encryption_options=None,
    advanced_options=None,
    log_publishing_options=None,
    blocking=False,
    region=None,
    key=None,
    keyid=None,
    profile=None,
):
    """
    Given a valid config, create a domain.

    :param str domain_name: The name of the Elasticsearch domain that you are creating.
        Domain names are unique across the domains owned by an account within an
        AWS region. Domain names must start with a letter or number and can contain
        the following characters: a-z (lowercase), 0-9, and - (hyphen).
    :param str elasticsearch_version: String of format X.Y to specify version for
        the Elasticsearch domain eg. "1.5" or "2.3".
    :param dict elasticsearch_cluster_config: Dictionary specifying the configuration
        options for an Elasticsearch domain. Keys (case sensitive) in here are:

        - InstanceType (str): The instance type for an Elasticsearch cluster.
        - InstanceCount (int): The instance type for an Elasticsearch cluster.
        - DedicatedMasterEnabled (bool): Indicate whether a dedicated master
          node is enabled.
        - ZoneAwarenessEnabled (bool): Indicate whether zone awareness is enabled.
          If this is not enabled, the Elasticsearch domain will only be in one
          availability zone.
        - ZoneAwarenessConfig (dict): Specifies the zone awareness configuration
          for a domain when zone awareness is enabled.
          Keys (case sensitive) in here are:

          - AvailabilityZoneCount (int): An integer value to indicate the
            number of availability zones for a domain when zone awareness is
            enabled. This should be equal to number of subnets if VPC endpoints
            is enabled. Allowed values: 2, 3

        - DedicatedMasterType (str): The instance type for a dedicated master node.
        - DedicatedMasterCount (int): Total number of dedicated master nodes,
          active and on standby, for the cluster.
    :param dict ebs_options: Dict specifying the options to enable or disable and
        specifying the type and size of EBS storage volumes.
        Keys (case sensitive) in here are:

        - EBSEnabled (bool): Specifies whether EBS-based storage is enabled.
        - VolumeType (str): Specifies the volume type for EBS-based storage.
        - VolumeSize (int): Integer to specify the size of an EBS volume.
        - Iops (int): Specifies the IOPD for a Provisioned IOPS EBS volume (SSD).
    :type access_policies: str or dict
    :param access_policies: Dict or JSON string with the IAM access policy.
    :param dict snapshot_options: Dict specifying the snapshot options.
        Keys (case sensitive) in here are:

        - AutomatedSnapshotStartHour (int): Specifies the time, in UTC format,
          when the service takes a daily automated snapshot of the specified
          Elasticsearch domain. Default value is 0 hours.
    :param dict vpc_options: Dict with the options to specify the subnets and security
        groups for the VPC endpoint.
        Keys (case sensitive) in here are:

        - SubnetIds (list): The list of subnets for the VPC endpoint.
        - SecurityGroupIds (list): The list of security groups for the VPC endpoint.
    :param dict cognito_options: Dict with options to specify the cognito user and
        identity pools for Kibana authentication.
        Keys (case sensitive) in here are:

        - Enabled (bool): Specifies the option to enable Cognito for Kibana authentication.
        - UserPoolId (str): Specifies the Cognito user pool ID for Kibana authentication.
        - IdentityPoolId (str): Specifies the Cognito identity pool ID for Kibana authentication.
        - RoleArn (str): Specifies the role ARN that provides Elasticsearch permissions
          for accessing Cognito resources.
    :param dict encryption_at_rest_options: Dict specifying the encryption at rest
        options. Keys (case sensitive) in here are:

        - Enabled (bool): Specifies the option to enable Encryption At Rest.
        - KmsKeyId (str): Specifies the KMS Key ID for Encryption At Rest options.
    :param dict node_to_node_encryption_options: Dict specifying the node to node
        encryption options. Keys (case sensitive) in here are:

        - Enabled (bool): Specify True to enable node-to-node encryption.
    :param dict advanced_options: Dict with option to allow references to indices
        in an HTTP request body. Must be False when configuring access to individual
        sub-resources. By default, the value is True.
        See http://docs.aws.amazon.com/elasticsearch-service/latest/developerguide\
        /es-createupdatedomains.html#es-createdomain-configure-advanced-options
        for more information.
    :param dict log_publishing_options: Dict with options for various type of logs.
        The keys denote the type of log file and can be one of the following:

        - INDEX_SLOW_LOGS
        - SEARCH_SLOW_LOGS
        - ES_APPLICATION_LOGS

        The value assigned to each key is a dict with the following case sensitive keys:

        - CloudWatchLogsLogGroupArn (str): The ARN of the Cloudwatch log
          group to which the log needs to be published.
        - Enabled (bool): Specifies whether given log publishing option is enabled or not.
    :param bool blocking: Whether or not to wait (block) until the Elasticsearch
        domain has been created.

    Note: Not all instance types allow enabling encryption at rest. See https://docs.aws.amazon.com\
        /elasticsearch-service/latest/developerguide/aes-supported-instance-types.html

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with the domain status configuration.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    CLI Example:

    .. code-block:: bash

        salt myminion boto3_elasticsearch.create_elasticsearch_domain mydomain \\
        elasticsearch_cluster_config='{ \\
          "InstanceType": "t2.micro.elasticsearch", \\
          "InstanceCount": 1, \\
          "DedicatedMasterEnabled": False, \\
          "ZoneAwarenessEnabled": False}' \\
        ebs_options='{ \\
          "EBSEnabled": True, \\
          "VolumeType": "gp2", \\
          "VolumeSize": 10, \\
          "Iops": 0}' \\
        access_policies='{ \\
          "Version": "2012-10-17", \\
          "Statement": [ \\
            {"Effect": "Allow", \\
             "Principal": {"AWS": "*"}, \\
             "Action": "es:*", \\
             "Resource": "arn:aws:es:us-east-1:111111111111:domain/mydomain/*", \\
             "Condition": {"IpAddress": {"aws:SourceIp": ["127.0.0.1"]}}}]}' \\
        snapshot_options='{"AutomatedSnapshotStartHour": 0}' \\
        advanced_options='{"rest.action.multi.allow_explicit_index": "true"}'
    """
    boto_kwargs = salt.utils.data.filter_falsey(
        {
            "DomainName": domain_name,
            "ElasticsearchVersion": str(elasticsearch_version or ""),
            "ElasticsearchClusterConfig": elasticsearch_cluster_config,
            "EBSOptions": ebs_options,
            "AccessPolicies": (
                salt.utils.json.dumps(access_policies)
                if isinstance(access_policies, dict)
                else access_policies
            ),
            "SnapshotOptions": snapshot_options,
            "VPCOptions": vpc_options,
            "CognitoOptions": cognito_options,
            "EncryptionAtRestOptions": encryption_at_rest_options,
            "NodeToNodeEncryptionOptions": node_to_node_encryption_options,
            "AdvancedOptions": advanced_options,
            "LogPublishingOptions": log_publishing_options,
        }
    )
    ret = {"result": False}
    try:
        conn = _get_conn(region=region, key=key, keyid=keyid, profile=profile)
        res = conn.create_elasticsearch_domain(**boto_kwargs)
        if res and "DomainStatus" in res:
            ret["result"] = True
            ret["response"] = res["DomainStatus"]
        if blocking:
            conn.get_waiter("ESDomainAvailable").wait(DomainName=domain_name)
    except (ParamValidationError, ClientError, WaiterError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


def delete_elasticsearch_domain(
    domain_name, blocking=False, region=None, key=None, keyid=None, profile=None
):
    """
    Permanently deletes the specified Elasticsearch domain and all of its data.
    Once a domain is deleted, it cannot be recovered.

    :param str domain_name: The name of the domain to delete.
    :param bool blocking: Whether or not to wait (block) until the Elasticsearch
        domain has been deleted.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    try:
        conn = _get_conn(region=region, key=key, keyid=keyid, profile=profile)
        conn.delete_elasticsearch_domain(DomainName=domain_name)
        ret["result"] = True
        if blocking:
            conn.get_waiter("ESDomainDeleted").wait(DomainName=domain_name)
    except (ParamValidationError, ClientError, WaiterError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


@depends("botocore", version="1.7.30")
def delete_elasticsearch_service_role(region=None, keyid=None, key=None, profile=None):
    """
    Deletes the service-linked role that Elasticsearch Service uses to manage and
    maintain VPC domains. Role deletion will fail if any existing VPC domains use
    the role. You must delete any such Elasticsearch domains before deleting the role.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        conn.delete_elasticsearch_service_role()
        ret["result"] = True
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


def describe_elasticsearch_domain(
    domain_name, region=None, keyid=None, key=None, profile=None
):
    """
    Given a domain name gets its status description.

    :param str domain_name: The name of the domain to get the status of.

    :rtype: dict
    :return: Dictionary ith key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with the domain status information.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    try:
        conn = _get_conn(region=region, key=key, keyid=keyid, profile=profile)
        res = conn.describe_elasticsearch_domain(DomainName=domain_name)
        if res and "DomainStatus" in res:
            ret["result"] = True
            ret["response"] = res["DomainStatus"]
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


def describe_elasticsearch_domain_config(
    domain_name, region=None, keyid=None, key=None, profile=None
):
    """
    Provides cluster configuration information about the specified Elasticsearch domain,
    such as the state, creation date, update version, and update date for cluster options.

    :param str domain_name: The name of the domain to describe.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with the current configuration information.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    try:
        conn = _get_conn(region=region, key=key, keyid=keyid, profile=profile)
        res = conn.describe_elasticsearch_domain_config(DomainName=domain_name)
        if res and "DomainConfig" in res:
            ret["result"] = True
            ret["response"] = res["DomainConfig"]
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


def describe_elasticsearch_domains(
    domain_names, region=None, keyid=None, key=None, profile=None
):
    """
    Returns domain configuration information about the specified Elasticsearch
    domains, including the domain ID, domain endpoint, and domain ARN.

    :param list domain_names: List of domain names to get information for.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with the list of domain status information.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    CLI Example:

    .. code-block:: bash

        salt myminion boto3_elasticsearch.describe_elasticsearch_domains '["domain_a", "domain_b"]'
    """
    ret = {"result": False}
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        res = conn.describe_elasticsearch_domains(DomainNames=domain_names)
        if res and "DomainStatusList" in res:
            ret["result"] = True
            ret["response"] = res["DomainStatusList"]
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


@depends("botocore", version="1.5.18")
def describe_elasticsearch_instance_type_limits(
    instance_type,
    elasticsearch_version,
    domain_name=None,
    region=None,
    keyid=None,
    key=None,
    profile=None,
):
    """
    Describe Elasticsearch Limits for a given InstanceType and ElasticsearchVersion.
    When modifying existing Domain, specify the `` DomainName `` to know what Limits
    are supported for modifying.

    :param str instance_type: The instance type for an Elasticsearch cluster for
        which Elasticsearch ``Limits`` are needed.
    :param str elasticsearch_version: Version of Elasticsearch for which ``Limits``
        are needed.
    :param str domain_name: Represents the name of the Domain that we are trying
        to modify. This should be present only if we are querying for Elasticsearch
        ``Limits`` for existing domain.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with the limits information.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    CLI Example:

    .. code-block:: bash

        salt myminion boto3_elasticsearch.describe_elasticsearch_instance_type_limits \\
          instance_type=r3.8xlarge.elasticsearch \\
          elasticsearch_version='6.2'
    """
    ret = {"result": False}
    boto_params = salt.utils.data.filter_falsey(
        {
            "DomainName": domain_name,
            "InstanceType": instance_type,
            "ElasticsearchVersion": str(elasticsearch_version),
        }
    )
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        res = conn.describe_elasticsearch_instance_type_limits(**boto_params)
        if res and "LimitsByRole" in res:
            ret["result"] = True
            ret["response"] = res["LimitsByRole"]
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


@depends("botocore", version="1.10.15")
def describe_reserved_elasticsearch_instance_offerings(
    reserved_elasticsearch_instance_offering_id=None,
    region=None,
    keyid=None,
    key=None,
    profile=None,
):
    """
    Lists available reserved Elasticsearch instance offerings.

    :param str reserved_elasticsearch_instance_offering_id: The offering identifier
        filter value. Use this parameter to show only the available offering that
        matches the specified reservation identifier.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with the list of offerings information.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        boto_params = {
            "ReservedElasticsearchInstanceOfferingId": reserved_elasticsearch_instance_offering_id
        }
        res = []
        for page in conn.get_paginator(
            "describe_reserved_elasticsearch_instance_offerings"
        ).paginate(**boto_params):
            res.extend(page["ReservedElasticsearchInstanceOfferings"])
        if res:
            ret["result"] = True
            ret["response"] = res
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


@depends("botocore", version="1.10.15")
def describe_reserved_elasticsearch_instances(
    reserved_elasticsearch_instance_id=None,
    region=None,
    keyid=None,
    key=None,
    profile=None,
):
    """
    Returns information about reserved Elasticsearch instances for this account.

    :param str reserved_elasticsearch_instance_id: The reserved instance identifier
        filter value. Use this parameter to show only the reservation that matches
        the specified reserved Elasticsearch instance ID.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with a list of information on
        reserved instances.
        Upon failure, also contains a key 'error' with the error message as value.

    :note: Version 1.9.174 of boto3 has a bug in that reserved_elasticsearch_instance_id
        is considered a required argument, even though the documentation says otherwise.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        boto_params = {
            "ReservedElasticsearchInstanceId": reserved_elasticsearch_instance_id,
        }
        res = []
        for page in conn.get_paginator(
            "describe_reserved_elasticsearch_instances"
        ).paginate(**boto_params):
            res.extend(page["ReservedElasticsearchInstances"])
        if res:
            ret["result"] = True
            ret["response"] = res
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


@depends("botocore", version="1.10.77")
def get_compatible_elasticsearch_versions(
    domain_name=None, region=None, keyid=None, key=None, profile=None
):
    """
    Returns a list of upgrade compatible Elastisearch versions. You can optionally
    pass a ``domain_name`` to get all upgrade compatible Elasticsearch versions
    for that specific domain.

    :param str domain_name: The name of an Elasticsearch domain.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with a list of compatible versions.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    boto_params = salt.utils.data.filter_falsey({"DomainName": domain_name})
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        res = conn.get_compatible_elasticsearch_versions(**boto_params)
        if res and "CompatibleElasticsearchVersions" in res:
            ret["result"] = True
            ret["response"] = res["CompatibleElasticsearchVersions"]
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


@depends("botocore", version="1.10.77")
def get_upgrade_history(domain_name, region=None, keyid=None, key=None, profile=None):
    """
    Retrieves the complete history of the last 10 upgrades that were performed on the domain.

    :param str domain_name: The name of an Elasticsearch domain. Domain names are
        unique across the domains owned by an account within an AWS region. Domain
        names start with a letter or number and can contain the following characters:
        a-z (lowercase), 0-9, and - (hyphen).

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with a list of upgrade histories.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        boto_params = {"DomainName": domain_name}
        res = []
        for page in conn.get_paginator("get_upgrade_history").paginate(**boto_params):
            res.extend(page["UpgradeHistories"])
        if res:
            ret["result"] = True
            ret["response"] = res
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


@depends("botocore", version="1.10.77")
def get_upgrade_status(domain_name, region=None, keyid=None, key=None, profile=None):
    """
    Retrieves the latest status of the last upgrade or upgrade eligibility check
    that was performed on the domain.

    :param str domain_name: The name of an Elasticsearch domain. Domain names are
        unique across the domains owned by an account within an AWS region. Domain
        names start with a letter or number and can contain the following characters:
        a-z (lowercase), 0-9, and - (hyphen).

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with upgrade status information.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    boto_params = {"DomainName": domain_name}
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        res = conn.get_upgrade_status(**boto_params)
        ret["result"] = True
        ret["response"] = res
        del res["ResponseMetadata"]
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


def list_domain_names(region=None, keyid=None, key=None, profile=None):
    """
    Returns the name of all Elasticsearch domains owned by the current user's account.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with a list of domain names.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        res = conn.list_domain_names()
        if res and "DomainNames" in res:
            ret["result"] = True
            ret["response"] = [item["DomainName"] for item in res["DomainNames"]]
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


@depends("botocore", version="1.5.18")
def list_elasticsearch_instance_types(
    elasticsearch_version,
    domain_name=None,
    region=None,
    keyid=None,
    key=None,
    profile=None,
):
    """
    List all Elasticsearch instance types that are supported for given ElasticsearchVersion.

    :param str elasticsearch_version: Version of Elasticsearch for which list of
        supported elasticsearch instance types are needed.
    :param str domain_name: DomainName represents the name of the Domain that we
        are trying to modify. This should be present only if we are querying for
        list of available Elasticsearch instance types when modifying existing domain.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with a list of Elasticsearch instance types.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        boto_params = salt.utils.data.filter_falsey(
            {
                "ElasticsearchVersion": str(elasticsearch_version),
                "DomainName": domain_name,
            }
        )
        res = []
        for page in conn.get_paginator("list_elasticsearch_instance_types").paginate(
            **boto_params
        ):
            res.extend(page["ElasticsearchInstanceTypes"])
        if res:
            ret["result"] = True
            ret["response"] = res
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


@depends("botocore", version="1.5.18")
def list_elasticsearch_versions(region=None, keyid=None, key=None, profile=None):
    """
    List all supported Elasticsearch versions.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with a list of Elasticsearch versions.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        res = []
        for page in conn.get_paginator("list_elasticsearch_versions").paginate():
            res.extend(page["ElasticsearchVersions"])
        if res:
            ret["result"] = True
            ret["response"] = res
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


def list_tags(
    domain_name=None, arn=None, region=None, key=None, keyid=None, profile=None
):
    """
    Returns all tags for the given Elasticsearch domain.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with a dict of tags.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    if not any((arn, domain_name)):
        raise SaltInvocationError(
            "At least one of domain_name or arn must be specified."
        )
    ret = {"result": False}
    if arn is None:
        res = describe_elasticsearch_domain(
            domain_name=domain_name,
            region=region,
            key=key,
            keyid=keyid,
            profile=profile,
        )
        if "error" in res:
            ret.update(res)
        elif not res["result"]:
            ret.update(
                {
                    "error": 'The domain with name "{}" does not exist.'.format(
                        domain_name
                    )
                }
            )
        else:
            arn = res["response"].get("ARN")
    if arn:
        try:
            conn = _get_conn(region=region, key=key, keyid=keyid, profile=profile)
            res = conn.list_tags(ARN=arn)
            ret["result"] = True
            ret["response"] = {
                item["Key"]: item["Value"] for item in res.get("TagList", [])
            }
        except (ParamValidationError, ClientError) as exp:
            ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


@depends("botocore", version="1.10.15")
def purchase_reserved_elasticsearch_instance_offering(
    reserved_elasticsearch_instance_offering_id,
    reservation_name,
    instance_count=None,
    region=None,
    keyid=None,
    key=None,
    profile=None,
):
    """
    Allows you to purchase reserved Elasticsearch instances.

    :param str reserved_elasticsearch_instance_offering_id: The ID of the reserved
        Elasticsearch instance offering to purchase.
    :param str reservation_name: A customer-specified identifier to track this reservation.
    :param int instance_count: The number of Elasticsearch instances to reserve.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with purchase information.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    boto_params = salt.utils.data.filter_falsey(
        {
            "ReservedElasticsearchInstanceOfferingId": reserved_elasticsearch_instance_offering_id,
            "ReservationName": reservation_name,
            "InstanceCount": instance_count,
        }
    )
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        res = conn.purchase_reserved_elasticsearch_instance_offering(**boto_params)
        if res:
            ret["result"] = True
            ret["response"] = res
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


def remove_tags(
    tag_keys,
    domain_name=None,
    arn=None,
    region=None,
    key=None,
    keyid=None,
    profile=None,
):
    """
    Removes the specified set of tags from the specified Elasticsearch domain.

    :param list tag_keys: List with tag keys you want to remove from the Elasticsearch domain.
    :param str domain_name: The name of the Elasticsearch domain you want to remove tags from.
    :param str arn: The ARN of the Elasticsearch domain you want to remove tags from.
        Specifying this overrides ``domain_name``.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    CLI Example:

    .. code-block:: bash

        salt myminion boto3_elasticsearch.remove_tags '["foo", "bar"]' domain_name=my_domain
    """
    if not any((arn, domain_name)):
        raise SaltInvocationError(
            "At least one of domain_name or arn must be specified."
        )
    ret = {"result": False}
    if arn is None:
        res = describe_elasticsearch_domain(
            domain_name=domain_name,
            region=region,
            key=key,
            keyid=keyid,
            profile=profile,
        )
        if "error" in res:
            ret.update(res)
        elif not res["result"]:
            ret.update(
                {
                    "error": 'The domain with name "{}" does not exist.'.format(
                        domain_name
                    )
                }
            )
        else:
            arn = res["response"].get("ARN")
    if arn:
        try:
            conn = _get_conn(region=region, key=key, keyid=keyid, profile=profile)
            conn.remove_tags(ARN=arn, TagKeys=tag_keys)
            ret["result"] = True
        except (ParamValidationError, ClientError) as exp:
            ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


@depends("botocore", version="1.12.21")
def start_elasticsearch_service_software_update(
    domain_name, region=None, keyid=None, key=None, profile=None
):
    """
    Schedules a service software update for an Amazon ES domain.

    :param str domain_name: The name of the domain that you want to update to the
        latest service software.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with service software information.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    boto_params = {"DomainName": domain_name}
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        res = conn.start_elasticsearch_service_software_update(**boto_params)
        if res and "ServiceSoftwareOptions" in res:
            ret["result"] = True
            ret["response"] = res["ServiceSoftwareOptions"]
    except (ParamValidationError, ClientError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


def update_elasticsearch_domain_config(
    domain_name,
    elasticsearch_cluster_config=None,
    ebs_options=None,
    vpc_options=None,
    access_policies=None,
    snapshot_options=None,
    cognito_options=None,
    advanced_options=None,
    log_publishing_options=None,
    blocking=False,
    region=None,
    key=None,
    keyid=None,
    profile=None,
):
    """
    Modifies the cluster configuration of the specified Elasticsearch domain,
    for example setting the instance type and the number of instances.

    :param str domain_name: The name of the Elasticsearch domain that you are creating.
        Domain names are unique across the domains owned by an account within an
        AWS region. Domain names must start with a letter or number and can contain
        the following characters: a-z (lowercase), 0-9, and - (hyphen).
    :param dict elasticsearch_cluster_config: Dictionary specifying the configuration
        options for an Elasticsearch domain. Keys (case sensitive) in here are:

        - InstanceType (str): The instance type for an Elasticsearch cluster.
        - InstanceCount (int): The instance type for an Elasticsearch cluster.
        - DedicatedMasterEnabled (bool): Indicate whether a dedicated master
          node is enabled.
        - ZoneAwarenessEnabled (bool): Indicate whether zone awareness is enabled.
        - ZoneAwarenessConfig (dict): Specifies the zone awareness configuration
          for a domain when zone awareness is enabled.
          Keys (case sensitive) in here are:

          - AvailabilityZoneCount (int): An integer value to indicate the
            number of availability zones for a domain when zone awareness is
            enabled. This should be equal to number of subnets if VPC endpoints
            is enabled.

        - DedicatedMasterType (str): The instance type for a dedicated master node.
        - DedicatedMasterCount (int): Total number of dedicated master nodes,
          active and on standby, for the cluster.
    :param dict ebs_options: Dict specifying the options to enable or disable and
        specifying the type and size of EBS storage volumes.
        Keys (case sensitive) in here are:

        - EBSEnabled (bool): Specifies whether EBS-based storage is enabled.
        - VolumeType (str): Specifies the volume type for EBS-based storage.
        - VolumeSize (int): Integer to specify the size of an EBS volume.
        - Iops (int): Specifies the IOPD for a Provisioned IOPS EBS volume (SSD).
    :param dict snapshot_options: Dict specifying the snapshot options.
        Keys (case sensitive) in here are:

        - AutomatedSnapshotStartHour (int): Specifies the time, in UTC format,
          when the service takes a daily automated snapshot of the specified
          Elasticsearch domain. Default value is 0 hours.
    :param dict vpc_options: Dict with the options to specify the subnets and security
        groups for the VPC endpoint.
        Keys (case sensitive) in here are:

        - SubnetIds (list): The list of subnets for the VPC endpoint.
        - SecurityGroupIds (list): The list of security groups for the VPC endpoint.
    :param dict cognito_options: Dict with options to specify the cognito user and
        identity pools for Kibana authentication.
        Keys (case sensitive) in here are:

        - Enabled (bool): Specifies the option to enable Cognito for Kibana authentication.
        - UserPoolId (str): Specifies the Cognito user pool ID for Kibana authentication.
        - IdentityPoolId (str): Specifies the Cognito identity pool ID for Kibana authentication.
        - RoleArn (str): Specifies the role ARN that provides Elasticsearch permissions
          for accessing Cognito resources.
    :param dict advanced_options: Dict with option to allow references to indices
        in an HTTP request body. Must be False when configuring access to individual
        sub-resources. By default, the value is True.
        See http://docs.aws.amazon.com/elasticsearch-service/latest/developerguide\
        /es-createupdatedomains.html#es-createdomain-configure-advanced-options
        for more information.
    :param str/dict access_policies: Dict or JSON string with the IAM access policy.
    :param dict log_publishing_options: Dict with options for various type of logs.
        The keys denote the type of log file and can be one of the following:

            INDEX_SLOW_LOGS, SEARCH_SLOW_LOGS, ES_APPLICATION_LOGS.

        The value assigned to each key is a dict with the following case sensitive keys:

        - CloudWatchLogsLogGroupArn (str): The ARN of the Cloudwatch log
          group to which the log needs to be published.
        - Enabled (bool): Specifies whether given log publishing option
          is enabled or not.
    :param bool blocking: Whether or not to wait (block) until the Elasticsearch
        domain has been updated.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with the domain configuration.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    CLI Example:

    .. code-block:: bash

        salt myminion boto3_elasticsearch.update_elasticsearch_domain_config mydomain \\
          elasticsearch_cluster_config='{\\
            "InstanceType": "t2.micro.elasticsearch", \\
            "InstanceCount": 1, \\
            "DedicatedMasterEnabled": false,
            "ZoneAwarenessEnabled": false}' \\
          ebs_options='{\\
            "EBSEnabled": true, \\
            "VolumeType": "gp2", \\
            "VolumeSize": 10, \\
            "Iops": 0}' \\
          access_policies='{"Version": "2012-10-17", "Statement": [{\\
            "Effect": "Allow", "Principal": {"AWS": "*"}, "Action": "es:*", \\
            "Resource": "arn:aws:es:us-east-1:111111111111:domain/mydomain/*", \\
            "Condition": {"IpAddress": {"aws:SourceIp": ["127.0.0.1"]}}}]}' \\
          snapshot_options='{"AutomatedSnapshotStartHour": 0}' \\
          advanced_options='{"rest.action.multi.allow_explicit_index": "true"}'
    """
    ret = {"result": False}
    boto_kwargs = salt.utils.data.filter_falsey(
        {
            "DomainName": domain_name,
            "ElasticsearchClusterConfig": elasticsearch_cluster_config,
            "EBSOptions": ebs_options,
            "SnapshotOptions": snapshot_options,
            "VPCOptions": vpc_options,
            "CognitoOptions": cognito_options,
            "AdvancedOptions": advanced_options,
            "AccessPolicies": (
                salt.utils.json.dumps(access_policies)
                if isinstance(access_policies, dict)
                else access_policies
            ),
            "LogPublishingOptions": log_publishing_options,
        }
    )
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        res = conn.update_elasticsearch_domain_config(**boto_kwargs)
        if not res or "DomainConfig" not in res:
            log.warning("Domain was not updated")
        else:
            ret["result"] = True
            ret["response"] = res["DomainConfig"]
        if blocking:
            conn.get_waiter("ESDomainAvailable").wait(DomainName=domain_name)
    except (ParamValidationError, ClientError, WaiterError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


@depends("botocore", version="1.10.77")
def upgrade_elasticsearch_domain(
    domain_name,
    target_version,
    perform_check_only=None,
    blocking=False,
    region=None,
    keyid=None,
    key=None,
    profile=None,
):
    """
    Allows you to either upgrade your domain or perform an Upgrade eligibility
    check to a compatible Elasticsearch version.

    :param str domain_name: The name of an Elasticsearch domain. Domain names are
        unique across the domains owned by an account within an AWS region. Domain
        names start with a letter or number and can contain the following characters:
        a-z (lowercase), 0-9, and - (hyphen).
    :param str target_version: The version of Elasticsearch that you intend to
        upgrade the domain to.
    :param bool perform_check_only: This flag, when set to True, indicates that
        an Upgrade Eligibility Check needs to be performed. This will not actually
        perform the Upgrade.
    :param bool blocking: Whether or not to wait (block) until the Elasticsearch
        domain has been upgraded.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with the domain configuration.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    CLI Example:

    .. code-block:: bash

        salt myminion boto3_elasticsearch.upgrade_elasticsearch_domain mydomain \\
        target_version='6.7' \\
        perform_check_only=True
    """
    ret = {"result": False}
    boto_params = salt.utils.data.filter_falsey(
        {
            "DomainName": domain_name,
            "TargetVersion": str(target_version),
            "PerformCheckOnly": perform_check_only,
        }
    )
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        res = conn.upgrade_elasticsearch_domain(**boto_params)
        if res:
            ret["result"] = True
            ret["response"] = res
        if blocking:
            conn.get_waiter("ESUpgradeFinished").wait(DomainName=domain_name)
    except (ParamValidationError, ClientError, WaiterError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


def exists(domain_name, region=None, key=None, keyid=None, profile=None):
    """
    Given a domain name, check to see if the given domain exists.

    :param str domain_name: The name of the domain to check.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    try:
        conn = _get_conn(region=region, key=key, keyid=keyid, profile=profile)
        conn.describe_elasticsearch_domain(DomainName=domain_name)
        ret["result"] = True
    except (ParamValidationError, ClientError) as exp:
        if exp.response.get("Error", {}).get("Code") != "ResourceNotFoundException":
            ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


def wait_for_upgrade(domain_name, region=None, keyid=None, key=None, profile=None):
    """
    Block until an upgrade-in-progress for domain ``name`` is finished.

    :param str name: The name of the domain to wait for.

    :rtype dict:
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    """
    ret = {"result": False}
    try:
        conn = _get_conn(region=region, keyid=keyid, key=key, profile=profile)
        conn.get_waiter("ESUpgradeFinished").wait(DomainName=domain_name)
        ret["result"] = True
    except (ParamValidationError, ClientError, WaiterError) as exp:
        ret.update({"error": __utils__["boto3.get_error"](exp)["message"]})
    return ret


@depends("botocore", version="1.10.77")
def check_upgrade_eligibility(
    domain_name, elasticsearch_version, region=None, keyid=None, key=None, profile=None
):
    """
    Helper function to determine in one call if an Elasticsearch domain can be
    upgraded to the specified Elasticsearch version.

    This assumes that the Elasticsearch domain is at rest at the moment this function
    is called. I.e. The domain is not in the process of :

    - being created.
    - being updated.
    - another upgrade running, or a check thereof.
    - being deleted.

    Behind the scenes, this does 3 things:

    - Check if ``elasticsearch_version`` is among the compatible elasticsearch versions.
    - Perform a check if the Elasticsearch domain is eligible for the upgrade.
    - Check the result of the check and return the result as a boolean.

    :param str name: The Elasticsearch domain name to check.
    :param str elasticsearch_version: The Elasticsearch version to upgrade to.

    :rtype: dict
    :return: Dictionary with key 'result' and as value a boolean denoting success or failure.
        Upon success, also contains a key 'reponse' with boolean result of the check.
        Upon failure, also contains a key 'error' with the error message as value.

    .. versionadded:: 3001

    CLI Example:

    .. code-block:: bash

        salt myminion boto3_elasticsearch.check_upgrade_eligibility mydomain '6.7'
    """
    ret = {"result": False}
    # Check if the desired version is in the list of compatible versions
    res = get_compatible_elasticsearch_versions(
        domain_name, region=region, keyid=keyid, key=key, profile=profile
    )
    if "error" in res:
        return res
    compatible_versions = res["response"][0]["TargetVersions"]
    if str(elasticsearch_version) not in compatible_versions:
        ret["result"] = True
        ret["response"] = False
        ret["error"] = 'Desired version "{}" not in compatible versions: {}.'.format(
            elasticsearch_version, compatible_versions
        )
        return ret
    # Check if the domain is eligible to upgrade to the desired version
    res = upgrade_elasticsearch_domain(
        domain_name,
        elasticsearch_version,
        perform_check_only=True,
        blocking=True,
        region=region,
        keyid=keyid,
        key=key,
        profile=profile,
    )
    if "error" in res:
        return res
    res = wait_for_upgrade(
        domain_name, region=region, keyid=keyid, key=key, profile=profile
    )
    if "error" in res:
        return res
    res = get_upgrade_status(
        domain_name, region=region, keyid=keyid, key=key, profile=profile
    )
    ret["result"] = True
    ret["response"] = (
        res["response"]["UpgradeStep"] == "PRE_UPGRADE_CHECK"
        and res["response"]["StepStatus"] == "SUCCEEDED"
    )
    return ret