.. meta::
    :description: This documentation will guide you through the use of the Memset API.

.. index::
   double: Methods; loadbalancer.service

.. _loadbalancer.service:

Loadbalancer Service Methods
----------------------------

API methods for managing Load Balancer services.

.. function:: loadbalancer.service.add

    Define a new service on the given load balancer. The service must be given
    a name. This is used to refer to the service later.
    
    :param load_balancer: The name of the load balancer. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type load_balancer: String
    
    :param service_name: The name of the load balancer service. Service names must only consist of letters, numbers, underscores and hyphens. Ensure this value has at most 64 characters.
    :type service_name: String
    
    :param protocol: The protocol to be used by the load balacer. Acceptable values: 'tcp', 'http', 'https'.
    :type protocol: String
    
    :param virtual_ip: The virtual IP address. This is the address clients will connect to.
    :type virtual_ip: String
    
    :param port: The port number clients will connect to. Ensure this value is greater than or equal to 1. Ensure this value is less than or equal to 65535.
    :type port: Integer
    
    :param enabled: Whether the service is enabled or not. Defaults to True.
    :type enabled: Boolean, Optional
    
    :returns: A dictionary of the newly defined service as described in :func:`loadbalancer.service.info`.
    
    :raises: Will raise:
    
        * :class:`ApiErrorDoesNotExist` if the load balancer with the provided name does not exist.
        * :class:`ApiErrorBadParameters` if the service's parameters are invalid.
        * :class:`ApiErrorNotUnique` if the load balancer already has a service with this name.

.. function:: loadbalancer.service.info

    Describe a load balancer service.
    
    :param load_balancer: The name of the load balancer. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type load_balancer: String
    
    :param service_name: The name of the load balancer service. Service names must only consist of letters, numbers, underscores and hyphens. Ensure this value has at most 64 characters.
    :type service_name: String
    
    :returns: A dictionary with the following keys:
    
        **name**
            String: Name of the service.
        **enabled**:
            Boolean: If the service is enabled or not.
        **virtual_ip**:
            String: The load-balanced IP (that which should be used in DNS records).
        **port**:
            Integer: The TCP port number.
        **protocol**:
            String: Service type (e.g. http)
        **servers**:
            A list of dictionaries as described in :func:`loadbalancer.server.info`.
    
    :raises: Will raise :class:`ApiErrorDoesNotExist` if the load balancer or named service does not exist.

.. function:: loadbalancer.service.list

    List a load balancer's services.
    
    :param load_balancer: The name of the load balancer. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type load_balancer: String
    
    :returns: A list of dictionaries as described in :func:`loadbalancer.service.info`.

.. function:: loadbalancer.service.remove

    Remove a service. The service must have no servers attached to it.
    
    :param load_balancer: The name of the load balancer. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type load_balancer: String
    
    :param service_name: The name of the load balancer service. Service names must only consist of letters, numbers, underscores and hyphens. Ensure this value has at most 64 characters.
    :type service_name: String
    
    :returns: The name of the removed service.
    
    :raises: Will raise:
    
        * :class:`ApiErrorDoesNotExist` if the load balancer or service with the provided name does not exist.
        * :class:`ApiErrorPreconditionFailed` if there are still servers attached to the service.

.. function:: loadbalancer.service.update

    Update a service's settings. Settings that are not provided will not be updated.
    
    :param load_balancer: The name of the load balancer. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type load_balancer: String
    
    :param service_name: The name of the load balancer service. Service names must only consist of letters, numbers, underscores and hyphens. Ensure this value has at most 64 characters.
    :type service_name: String
    
    :param protocol: The protocol to be used by the load balacer. Acceptable values: 'tcp', 'http', 'https'.
    :type protocol: String, Optional
    
    :param virtual_ip: The virtual IP address. This is the address clients will connect to.
    :type virtual_ip: String, Optional
    
    :param port: The port number clients will connect to. Ensure this value is greater than or equal to 1. Ensure this value is less than or equal to 65535.
    :type port: Integer, Optional
    
    :param enabled: Whether the service is enabled or not.
    :type enabled: Boolean, Optional
    
    :returns: A dictionary of the updated load balancer service as described in :func:`loadbalancer.service.info`.
    
    :raises: Will raise:
    
        * :class:`ApiErrorDoesNotExist` if the load balancer or service with the provided name does not exist.
        * :class:`ApiErrorBadParameters` if the new parameters are invalid.
        * :class:`ApiErrorPreconditionFailed` if the virtual IP address is already in use.