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

.. index::
   double: Methods; loadbalancer.server

.. _loadbalancer.server:

Loadbalancer Server Methods
---------------------------

API methods for adding and removing servers to/from Load Balancers.

.. function:: loadbalancer.server.add

    Add the given server to the service. If the server is a miniserver, this method
    may reboot it in order to reconfigure its network. For further information,
    please see `the VLAN documentation <https://www.memset.com/docs/managing-your-server/vlan/>`_.
    
    :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 server_name: Name of the server.
    :type server_name: String
    
    :param ip_address: The IP address that the load balancer should forward incoming connections to. Defaults to choosing one of the server's VLAN IP addresses.
    :type ip_address: String, Optional
    
    :param port: The port number that the load balancer should forward incoming connections to. Defaults to the service's port. 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 this server is enabled. Defaults to false.
    :type enabled: Boolean, Optional
    
    :param fallback: Whether this server is a fallback server. Defaults to false.
    :type fallback: Boolean, Optional
    
    :param weight: Weight used for some scheduling algorithms. Defaults to 10.
    :type weight: Integer, Optional
    
    :returns: A dictionary as described in :func:`loadbalancer.server.info`.
    :raises: Will raise:
    
        * :class:`ApiErrorDoesNotExist` if one of the cluster, cluster service
          or server with the provided name does not exist, or if no IP address
          is specified and a default IP address cannot be found.
        * :class:`ApiErrorBadParameters` if the given IP address does not belong
          to the given server.
        * :class:`ApiErrorPreconditionFailed` if one of the following preconditions
          is not satisfied.
    
    :preconditions: The following preconditions must be satisfied:
    
        * The server must be in the same VLAN as the load balancer.
        * The server must not be in the middle of a reboot operation.
        * The server's SLA must not be lower than the load balancer's SLA.
        * The server must not already be attached to this service.

.. function:: loadbalancer.server.info

    Return information about the specified server, as attached to the given 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
    
    :param server_name: Name of the server.
    :type server_name: String
    
    :returns: a dictionary with the following keys:
    
        **name**:
            String: The name of the server.
        **ip_address**:
            String: The IP address of the server. This is the address that the
            load balancer will forward incoming connections to
        **port**:
            Integer: The port to which the load balancer will forward incoming
            connections.
        **enabled**:
            Boolean: Whether this server is enabled. If the server is not enabled,
            it won't be used to handle requests.
        **fallback**:
            Boolean: If true, this server is only used as a fallback. The server
            won't be used if there are any non-fallback servers available (enabled
            and responding to connections.
        **weight**:
            Integer: Weight used for load balancing. Higher numbers mean more connections
            will come to this server.
    
    :raises: Will raise :class:`ApiErrorDoesNotExist` if the load balancer,
        service or server does not exist. Will raise :class:`ApiErrorPreconditionFailed`
        if the server is not attached to the given service.

.. function:: loadbalancer.server.remove

    Remove a server from the given service. The server must not be in the
    middle of rebooting. If the server is a miniserver, this method may
    reboot it in order to reconfigure its network. For further information,
    please see `the VLAN documentation <https://www.memset.com/docs/managing-your-server/vlan/>`_.
    If you just want to disable a server temporarily, use
    :func:`loadbalancer.server.update` to set `enabled` to `false`.
    
    :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 server_name: Name of the server.
    :type server_name: String
    
    :returns: The name of the server that was removed.
    :raises: Will raise :class:`ApiErrorDoesNotExist` if the named load balancer,
             service or server does not exist. Will raise
             :class:`ApiErrorPreconditionFailed` if the server is not attached
             to the specified service, or if the server is being rebooted.

.. function:: loadbalancer.server.update

    Update the settings of a server as attached to the given service. 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 server_name: Name of the server.
    :type server_name: String
    
    :param ip_address: The IP address that the load balancer should forward incoming connections to.
    :type ip_address: String, Optional
    
    :param port: The port number that the load balancer should forward incoming connections 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 this server is enabled.
    :type enabled: Boolean, Optional
    
    :param fallback: Whether this server is a fallback server.
    :type fallback: Boolean, Optional
    
    :param weight: Weight used for some scheduling algorithms.
    :type weight: Integer, Optional
    
    :returns: A dictionary as described in :func:`loadbalancer.server.info`.
    :raises: Will raise:
    
        * :class:`ApiErrorDoesNotExist` if the named load balancer, service or server does not exist.
        * :class:`ApiErrorPreconditionFailed` if the named server is not attached to this service.
        * :class:`ApiErrorBadParameters` if the given IP address does not belong
          to the given server.