Browse Source

Update documentation

V1
Joshua Rubingh 1 year ago
parent
commit
b293c4fd24
  1. 4
      VRE/apps/virtual_machine/models.py
  2. 36
      VRE/apps/vrw/models.py
  3. 64
      VRE/apps/vrw/serializers.py
  4. 26
      VRE/apps/vrw/views.py
  5. 34
      doc/VRW.rst
  6. 4
      doc/_static/custom.css
  7. BIN
      doc/documentation.pdf
  8. 1
      doc/index.rst
  9. 6
      doc/models.rst

4
VRE/apps/virtual_machine/models.py

@ -81,7 +81,6 @@ class VirtualMachineMemory(MetaDataModel,VirtualMachinePart): @@ -81,7 +81,6 @@ class VirtualMachineMemory(MetaDataModel,VirtualMachinePart):
class VirtualMachineNetwork(MetaDataModel,VirtualMachinePart):
"""
It will inherit the attributes :attr:`~lib.models.base.MetaDataModel.created_at` and :attr:`~lib.models.base.MetaDataModel.updated_at` from the Abstract model :class:`~lib.models.base.MetaDataModel`
It will inherit the attributes :attr:`~VirtualMachinePart.name`, :attr:`~VirtualMachinePart.is_available` and :attr:`~VirtualMachinePart.vm_code` from the Abstract model :class:`VirtualMachinePart`
@ -100,7 +99,7 @@ class VirtualMachineNetwork(MetaDataModel,VirtualMachinePart): @@ -100,7 +99,7 @@ class VirtualMachineNetwork(MetaDataModel,VirtualMachinePart):
Returns:
float -- Unit value in Gbps"""
return pow(1024,3)
class VirtualMachineStorage(MetaDataModel,VirtualMachinePart):
"""
The virtual machine storage model. This will hold the information of available storages that can be used for creating virtual machines
@ -345,4 +344,3 @@ class VirtualMachineAccess(MetaDataModel): @@ -345,4 +344,3 @@ class VirtualMachineAccess(MetaDataModel):
def __str__(self):
return f'Access login for {self.researcher} to machine {self.virtual_machine}'

36
VRE/apps/vrw/models.py

@ -9,6 +9,23 @@ from apps.virtual_machine.models import VirtualMachine @@ -9,6 +9,23 @@ from apps.virtual_machine.models import VirtualMachine
# Create your models here.
class WorkspacePart(MetaDataModel, CloudBasicDataModel):
"""
A class for creating Virtual Workspace parts as counterparts for the Virtual Machine parts (:class:`~apps.virtual_machine.models.VirtualMachinePart`). This means that we can make translations between the general Virtual Machine Part model and this specific Virtual Workspace Part model.
In order to create Virtual Workspace parst you need to select the Virtual machine part type and item to make a Virtual Machine part translation. Together with a cloud_id you can then make virtual machines with the right configurations.
It will inherit the attributes :attr:`~lib.models.base.MetaDataModel.created_at` and :attr:`~lib.models.base.MetaDataModel.updated_at` from the Abstract model :class:`~lib.models.base.MetaDataModel`
It will inherit the attributes :attr:`~lib.models.cloud.CloudBasicDataModel.cloud_id` from the Abstract model :class:`~lib.models.cloud.CloudBasicDataModel`
Attributes
----------
name : str
The name of workspace part. Use a easy to remember name for humans.
content_type : ContentType
Specify the virtual machine part type.
object_id : int
Specify the virtual machine part id
"""
name = models.CharField(_('Name'), max_length=100, help_text=_('Technical name for this virtual workspace part.'))
content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE, limit_choices_to={'app_label': 'virtual_machine'}, help_text=_('Select the Virtual Machine part that correspondents with this Virtual Workspace part.'))
@ -60,6 +77,25 @@ class WorkspaceStatus(models.TextChoices): @@ -60,6 +77,25 @@ class WorkspaceStatus(models.TextChoices):
TERMINATED = ('TERMINATED',_('Terminated'))
class Workspace(MetaDataModel, CloudBasicDataModel):
"""
A class for creating Workspaces from Virtual Machines. When creating a new Workspace with the status :attr:`~WorkspaceStatus.NEW`, it should be picked up by the Workspace system in order to create the workspace.
By default the Virtual Workspace is created by a signal process where it uses the variable ':attr:`~settings.VRW_MACHINE_ACTIVE_DURATION`' to create Virtual Workspaces for 1 year.
It will inherit the attributes :attr:`~lib.models.base.MetaDataModel.created_at` and :attr:`~lib.models.base.MetaDataModel.updated_at` from the Abstract model :class:`~lib.models.base.MetaDataModel`
It will inherit the attributes :attr:`~lib.models.cloud.CloudBasicDataModel.cloud_id` from the Abstract model :class:`~lib.models.cloud.CloudBasicDataModel`
Attributes
----------
virtual_machine : :class:`~apps.virtual_machine.models.VirtualMachine`
The Virtual Machine that needs to be created as a Virtual Workspace
starting_at : Datetime
The date and timestamp when this workspace should be created.
ending_at : int
The date and timestamp when this workspace should be removed.
status : int
The status of the Workspace. When created. Default is :attr:`~WorkspaceStatus.NEW`
"""
class Meta:
verbose_name = _('virtual workspace')

64
VRE/apps/vrw/serializers.py

@ -7,24 +7,53 @@ from apps.study.models import Study @@ -7,24 +7,53 @@ from apps.study.models import Study
from datetime import timedelta
class WorkspaceStudySerializer(serializers.ModelSerializer):
"""
This serializer will only pick the fields :attr:`~apps.study.models.Study.id` and :attr:`~apps.study.models.Study.name` from the :class:`~apps.study.models.Study` model to use in the Virtual Workspace output.
Args:
id (int): :attr:`~apps.study.models.Study.id`
name (str): :attr:`~apps.study.models.Study.name`
"""
class Meta:
model = Study
fields = ['id','name']
class WorkspaceResearcherSerializer(serializers.ModelSerializer):
class WorkspaceResearcherSerializer(serializers.Serializer):
"""
This serializer will only pick the fields :attr:`~user.first_name`, :attr:`~user.last_name` and :attr:`~user.email` from the :class:`~apps.study.models.Researcher` model to use in the Virtual Workspace output.
Args:
first_name (str): :attr:`~user.first_name`
last_name (str): :attr:`~user.last_name`
email_address (str): :attr:`~user.email`
"""
# 'Proxy' some data from the user model to our Researcher model.
first_name = serializers.CharField(source='user.first_name')
last_name = serializers.CharField(source='user.last_name')
email_address = serializers.CharField(source='user.email')
# Add P/S number....?
class Meta:
model = Researcher
fields = ['first_name','last_name','email_address']
class WorkspaceSerializer(serializers.Serializer):
"""
This serializer will hold all the data that is needed for a single Virtual Workspace. It holds the following information:
Args:
id (int): The Virtual Workspace ID
study (WorkspaceStudySerializer): The study data for which the Virtual Workspace needs to be created
researcher (WorkspaceResearcherSerializer): The researcher for which the Virtual Workspace needs to be created
type (str): The Virtual Workspace profile (:attr:`~apps.virtual_machine.models.VirtualMachine.profile`)
disk (int): The total disk size for this Virtual Workspace (:attr:`~apps.virtual_machine.models.VirtualMachine.total_storage`)
memory (int): The total memory size for this Virtual Workspace (:attr:`~apps.virtual_machine.models.VirtualMachine.total_memory`)
gpu (int): The amount of GPUs for this Virtual Workspace (:attr:`~apps.virtual_machine.models.VirtualMachine.additional_gpu_amount`)
request_date (datetime): The date that this Virtual Workspace has been requested
start_date (datetime): The date that this Virtual Workspace should be created / available to the end user
end_data (datetime): The date that this Virtual Workspace will be removed.
status (str): The current status for this Virtual Workspace (:class:`apps.vrw.models.WorkspaceStatus`).
remote_id (str): The ID that is created by the remote cloud system
"""
id = serializers.IntegerField(source='pk', read_only=True)
study = WorkspaceStudySerializer(source='virtual_machine.study', read_only=True)
@ -39,15 +68,32 @@ class WorkspaceSerializer(serializers.Serializer): @@ -39,15 +68,32 @@ class WorkspaceSerializer(serializers.Serializer):
start_date = serializers.DateTimeField(source='starting_at', read_only=True)
end_data = serializers.DateTimeField(source='ending_at', read_only=True)
status = serializers.ChoiceField(choices=WorkspaceStatus.choices)
status = serializers.ChoiceField(choices=WorkspaceStatus.choices)
remote_id = serializers.CharField(read_only=True)
class WorkspaceStatusUpdateSerializer(serializers.Serializer):
"""
This serializer is used for updating the Virtual Workspace status.
Args:
status (str): The new status for this Virtual Workspace (:class:`apps.vrw.models.WorkspaceStatus`).
remote_id (str): The new ID that is created by the remote cloud system
"""
status = serializers.ChoiceField(choices=WorkspaceStatus.choices)
remote_id = serializers.CharField(required=False)
status = serializers.ChoiceField(choices=WorkspaceStatus.choices)
remote_id = serializers.CharField(required=False)
def update(self, instance, validated_data):
"""
Update the actual Virtual Workspace with new status data
Args:
instance (Workspace): The original Virtual Workspace object
validated_data (JSON): The cleaned and validated data to change with.
Returns:
VirtualWorkspace: The Virtual Workspace object with the new status and optional remote id.
"""
instance.status = validated_data.get('status', instance.status)
instance.remote_id = validated_data.get('remote_id', instance.remote_id)
instance.save()

26
VRE/apps/vrw/views.py

@ -1,20 +1,36 @@ @@ -1,20 +1,36 @@
from rest_framework import generics
from rest_framework.exceptions import NotFound
from .permissions import IsVRWAPIUser
from .models import Workspace, WorkspaceStatus
from .serializers import WorkspaceSerializer, WorkspaceStatusUpdateSerializer
from rest_framework.response import Response
# Create your views here.
class WorkspaceStatusUpdate(generics.UpdateAPIView):
"""
This is an update view where the status of a Virtual Workspace can be changed.
"""
permission_classes = [IsVRWAPIUser]
queryset = Workspace.objects.all()
serializer_class = WorkspaceStatusUpdateSerializer
class WorkspaceList(generics.ListAPIView):
"""
Give a list of all the available Virtual Workspaces ordered by the creating date. Showing oldest first by default.
The list can be filtered by using the status variable. Set the status to ':attr:`~apps.vrw.models.WorkspaceStatus.NEW`' and you will only see Virtual Workspaces with that status.
Args:
status (string): The status to filter on
Raises:
NotFound: When an invalid filter has been entered
Returns:
list: All the Virtual Workspaces optinally filtered on status
"""
permission_classes = [IsVRWAPIUser]
serializer_class = WorkspaceSerializer
@ -34,6 +50,10 @@ class WorkspaceList(generics.ListAPIView): @@ -34,6 +50,10 @@ class WorkspaceList(generics.ListAPIView):
return objects.order_by('created_at')
class WorkspaceDetail(generics.RetrieveAPIView):
"""
Show detail information for a specific Virtual Workspace.
"""
permission_classes = [IsVRWAPIUser]
queryset = Workspace.objects.all()
serializer_class = WorkspaceSerializer

34
doc/VRW.rst

@ -0,0 +1,34 @@ @@ -0,0 +1,34 @@
===
VRW
===
This part of the application is for integrating with the RUG Virtual Workspaces. The app will provide a REST API interface for machine management. An external script or system can then retreive the information from the API about which workspaces to create and which to clean up.
-------------
Authorization
-------------
This part of the API is only accessible with accounts that are added to a special VRW API group. By default this group is called 'vre-api' and be changed with the setting ':attr:`~settings.VRW_API_GROUP`'. This is done so that normal users are not able to change Virtual Workspace statusses.
The authentication is done by the general REST API.
------
Models
------
.. automodule:: apps.vrw.models
:members:
-----
Views
-----
.. automodule:: apps.vrw.views
:members:
-----------
Serializers
-----------
.. automodule:: apps.vrw.serializers
:members:
-------
Signals
-------
.. automodule:: apps.vrw.signals
:members:

4
doc/_static/custom.css vendored

@ -7,4 +7,8 @@ @@ -7,4 +7,8 @@
.wy-table-responsive {
overflow: visible !important;
}
dl.py.class {
margin-bottom: 1rem;
}

BIN
doc/documentation.pdf

Binary file not shown.

1
doc/index.rst

@ -22,6 +22,7 @@ The platform can be run inside a docker setup or just local for development. @@ -22,6 +22,7 @@ The platform can be run inside a docker setup or just local for development.
authentication
signals
tus
VRW
development
------------------

6
doc/models.rst

@ -8,6 +8,12 @@ Base @@ -8,6 +8,12 @@ Base
.. automodule:: lib.models.base
:members:
----
Cloud
----
.. automodule:: lib.models.cloud
:members:
-------
Dropoff
-------

Loading…
Cancel
Save