Metadata-Version: 2.1
Name: multiplespawner
Version: 0.0.0a5
Summary: UNKNOWN
Home-page: https://github.com/ucphhpc/multiplespawner
Author: Rasmus Munk
Author-email: munk1@live.dk
License: MIT
Description: ===============
        multiplespawner
        ===============
        
        .. image:: https://travis-ci.com/ucphhpc/multiplespawner.svg?branch=master
            :target: https://travis-ci.com/ucphhpc/multiplespawner
        .. image:: https://badge.fury.io/py/multiplespawner.svg
            :target: https://badge.fury.io/py/multiplespawner
        
        A JupyterHub Spawner that allows to select which resource their notebook should be spawned on.
        Internally it then uses spawner specific configurations to orchestrate the user on the given resources.
        
        Currently the plan is to support either a VM or container deployment on a set of user selectable hardware configurations
        
        -----
        Usage
        -----
        
        To use the MultipleSpawner, the JupyterHub configuration has to specify that it should use the MultipleSpawner::
        
            c = get_config()
            c.JupyterHub.spawner_class = "multiplespawner.MultipleSpawner"
        
        
        -------------
        Configuration
        -------------
        
        To configure which Spawners the MultipleSpawner should support and how a particular Notebook should be spawned, the Spawner expects two configuration files.
        Namely the Spawner Template configuration and the Spawner Deployment configurations.
        
        By default, the spawner expects these to be present in the ``~/.multiplespawner`` directory as the ``spawner_templates.json`` and ``spawner_deployment.json`` files.
        It is however possible, to override this expectation by defining other paths via the ``MULTIPLE_SPAWNER_TEMPLATE_FILE`` and ``MULTIPLE_SPAWNER_DEPLOYMENT_FILE`` environment variables.
        
        
        Spawner Template Configuration
        ------------------------------
        This configuration defines which Spawner should be supported and how they should be utilized.
        The expected structure of this configuration file can be seen below::
        
            [
                {
                    "name": "",                 # Name to show for the Spawner configuration
                    "resource_type": "",        # The resource_type that the Spawner expects (virtual_machine,container,bare_metal)
                    "providers": [""],          # Which cloud providers support this spawner?
                    "spawner": {
                        "class": "",            # The Spawner class that should be used by the MultipleSpawner to spawn the instance
                        "kwargs": {}            # The property values that should be set for the specified Spawner.
                    },
                    "configurer": {             # If so required, the configurer to apply to the target resource
                        "class": "",            # Configurer class
                                                # Any additional keys will be applied to the class at instantiation
        
                    },
                    "authenticator": {          # A required field for specifying which authenticator should be used to configure the resource
                                                # and before the MultipleSpawner can connect to the resource
                        "class": "",            # Class path to the designated authenticator
                        "kwargs": {}            # Kwargs that should be passed to the constructor 
                    }
                }
            ]
        
        An example of how such a file might be defined can be seen in the following example::
        
            [
                {
                    "name": "VirtualMachine Spawner",
                    "resource_type": "virtual_machine",
                    "providers": ["oci"],
                    "spawner": {
                        "class": "sshspawner.sshspawner.SSHSpawner",
                        "kwargs": {
                            "remote_hosts": ["{endpoint}"],
                            "remote_port": "22",
                            "ssh_keyfile": "~/.corc/ssh/id_rsa",
                            "remote_port_command": "/usr/bin/python3 \
                                /usr/local/bin/get_port.py"
                        }
                    },
                    "configurer": {
                        "class": "corc.configurer.AnsibleConfigurer",
                        "options": {
                            "host_variables": {
                                "ansible_user": "opc",
                                "ansible_become": "yes",
                                "ansible_become_method": "sudo",
                                "new_username": "{JUPYTERHUB_USER}"
                            },
                            "host_settings": {
                                "group": "compute",
                                "port": "22"
                            },
                            "apply_kwargs": {
                                "playbook_path": "setup_ssh_spawner.yml"
                            }
                        }
                    },
                    "authenticator": {
                        "class": "corc.authenticator.SSHAuthenticator",
                        "kwargs": {"create_certificate": "True"}
                    }
                }
            ]
        
        As shown in the above example, the Spawner Template Configuration supports the 
        definition of multiple Spawners via the encapsulating list that contains each individual
        spawner's configuration as a dictionary.
        
        In the provided example, a ``VirtualMachine Spawner`` is introduced.
        It is configured to use be supports by the ``oci`` cloud provider.
        Furthermore, it uses the ``SSHSpawner`` to spawn the Notebook,
        in addition, because the ``SSHSpawner`` expects a number of attributes to be defined before it can connect to a given resource,
        the ``kwargs`` key defines which attributes that should be passed to the ``SSHSpaner``'s constructor at instantiation. The same approach applies to the ``configurer`` and the ``authenticator`` keys in the dictionary.
        
        Spawner Deployment Configuration
        --------------------------------
        
        The Spawner Deployment Configuration is for defining how a particular Jupyter session should be spawned.
        An example of the deployment configuration file structure can be seen below::
        
            {
                "": [  # The key must defined the ``resource_type`` that the subdeployment configurations uses
        
                    {} # The underlying list contains the set of attributes and their values 
                       # that should be passed to the Spawner before it spawns the Jupyter Session
                ]
            }
        
        Currently the MultipleSpawner supports three different kinds of ``resource_types`` (``container``, ``virtual_machine``, and ``bare_metal``) as define by the ``multiplespawner.runtime.resource.ResourceTypes`` class.
        A hello world example of the Spawner Deployment Configuration can be seen below::
        
            {
                "container": [
                    {
                        "name": "python_notebook",
                        "image": "nielsbohr/python-notebook"
                    }
                ],
                "virtual_machine": [
                    {
                        "name": "oracle_linux_7_8",
                        "provider": "oci",
                        "image": "Oracle Linux 7.8"
                    }
                ],
                "bare_metal": [
                    {
                        "name": "local_machine",
                        "provider": "local"
                    }
                ]
            }
        
        ------
        Status
        ------
        
        The MultipleSpawner still needs additional testings and refinement to ensure that it is stable and versitile enough for large
        scale deployment
        
        
Keywords: JupyterHub,Spawner
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Provides-Extra: test
Provides-Extra: dev
