Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DEV[18597] As a DEV, I want to update CloudSigma docs with units for resources. #5

Open
wants to merge 87 commits into
base: develop
Choose a base branch
from
Open
Changes from 1 commit
Commits
Show all changes
87 commits
Select commit Hold shift + click to select a range
038b4f3
Add missing snippet for listing single fwpolicy
pavel-github Jul 4, 2020
02919cf
Fix small typos in keypairs resource
pavel-github Jul 11, 2020
87725cc
DEV-6434 As a Developer I want to Fix readthedocs title
miguel-cs Jan 8, 2021
74dabc9
Merge pull request #1 from pavel-github/patch-1
miguel-cs Jan 8, 2021
0766734
Merge pull request #2 from pavel-github/patch-2
miguel-cs Jan 8, 2021
6c4138d
Fixing typos and minor issues
miguel-cs Jan 14, 2021
c82076a
Adding CRK to the list of locations
miguel-cs Jan 14, 2021
419e901
Removing MIA adding LLA and MNL2 and sorting the list
miguel-cs Jan 14, 2021
017d433
Cleaning new line chars
miguel-cs Jan 14, 2021
60c2db5
Adding CRK, MNL2, LLA and removing MIA from response_locations
miguel-cs Jan 14, 2021
7d67daa
Update copyright year.
MohsenHassani Jun 23, 2021
22011bb
fix simple typo
lpmi-13 Jul 29, 2021
ddb9c15
Merge pull request #3 from lpmi-13/typo_fix
miguel-cs Jul 30, 2021
be14a7b
Add SGX documentation.
mohsen-hassani-cs May 10, 2022
e9bc3c6
Update copyright version.
mohsen-hassani-cs May 18, 2022
6a9e157
Merge branch 'develop'
mohsen-hassani-cs May 25, 2022
9178066
Add RDS API calls information to the documents.
mohsen-hassani-cs May 31, 2022
2bf25ad
Update Makefile
joshokay Jun 30, 2022
8af3b34
Merge branch 'develop'
9htly Jul 4, 2022
ac9abe3
Merge branch 'develop'
9htly Jul 4, 2022
965cd8e
Remove the decommissioned Firewall Policies feature.
mohsen-hassani-cs Oct 5, 2022
044f237
Remove the file fwpolicies.rst.
mohsen-hassani-cs Oct 5, 2022
a22ac6a
Merge branch 'master' of https://github.com/cloudsigma/cloudsigma-docs
mohsen-hassani-cs Oct 5, 2022
1ce673b
Update the new US based locations.
mohsen-hassani-cs Oct 5, 2022
2c1c018
Add the algorithm types for the Keypairs section.
mohsen-hassani-cs Nov 7, 2022
8a7fe73
Add the maximum size for the RSA key pairs.
mohsen-hassani-cs Nov 7, 2022
158d4f7
Add changelogs for Chlorine-17.2302.
mohsen-hassani-cs Feb 16, 2023
5ec117a
Update release_notes.rst
varlyakov Feb 17, 2023
2bc1388
Add release notes for the Chlorine-17.2303 version.
mohsen-hassani-cs Mar 17, 2023
9d917fd
Temporarily remove two new features as we found small bugs in them.
mohsen-hassani-cs Mar 29, 2023
e610486
Add release notes for Chlorine-17.2304.
mohsen-hassani-cs Apr 20, 2023
219ff22
Add the storage_type request/response to the Drive creation section.
mohsen-hassani-cs May 2, 2023
7766155
Add descriptions about NVMe to the Storage Type section.
mohsen-hassani-cs May 2, 2023
0a3fffb
Add information about the new CWL location.
mohsen-hassani-cs May 9, 2023
e6e972f
Change the version of the documents to 2023.
mohsen-hassani-cs May 9, 2023
11afb92
Change the urllib3 version as a requirement for the ReadTheDocs build…
mohsen-hassani-cs May 10, 2023
c61daa6
Change the requests package version as a requirement for the ReadTheD…
mohsen-hassani-cs May 10, 2023
dc37f1c
Add the release notes for Chlorine-17.2305.
mohsen-hassani-cs May 10, 2023
23cc01e
Add release notes for the version 17.2306.
mohsen-hassani-cs Jun 27, 2023
fa3560f
Add release notes for the version 17.2307.
mohsen-hassani-cs Jul 19, 2023
703d97c
Add release notes for the version Chlorine-17.2308
mohsen-hassani-cs Aug 28, 2023
e70b969
Add the readthedocs.yaml configurations for building the docs
mohsen-hassani-cs Aug 28, 2023
60be80f
Add CWL to General Notes and remove MNL.
mohsen-hassani-cs Aug 28, 2023
97d0a16
Add information about the remote snapshots to the documentation.
mohsen-hassani-cs Sep 13, 2023
dbc0bb1
Add the release notes for Chlorine-17.2309
mohsen-hassani-cs Sep 13, 2023
804a5d7
Add the release notes for the Chlorine-17.2310
mohsen-hassani-cs Oct 10, 2023
ed48585
Add location details for MNL and BOM.
mohsen-hassani-cs Nov 15, 2023
fd3bf8d
Remove BOM from the locations page temporarily.
mohsen-hassani-cs Nov 16, 2023
02063f0
Add release notes for the Chlorine-17.2311.
mohsen-hassani-cs Nov 20, 2023
0ffb2d2
Add the release notes for the Chlorine-17.2312 release.
mohsen-hassani-cs Dec 8, 2023
ba6ee22
Fix the number of improvements.
mohsen-hassani-cs Dec 8, 2023
260a250
Update the response data of capabalities API call.
mohsen-hassani-cs Dec 13, 2023
02e99b5
Add information about DUS locatiosn.
mohsen-hassani-cs Jan 4, 2024
2e1f41f
Add the release notes for 2401.
mohsen-hassani-cs Jan 23, 2024
a6c2572
Update capabilities.rst
cs-ayatakinci Feb 19, 2024
a6187cd
Update capabilities.rst
cs-ayatakinci Feb 19, 2024
d55039f
Update capabilities.rst
cs-ayatakinci Feb 19, 2024
26e741f
Update capabilities.rst
cs-ayatakinci Feb 19, 2024
9224cf9
Update capabilities.rst
cs-ayatakinci Feb 19, 2024
2a556f9
Update capabilities.rst
cs-ayatakinci Feb 19, 2024
04591cd
Add the release notes for 2402.
mohsen-hassani-cs Feb 20, 2024
d15f3e9
Merge branch 'master' of https://github.com/cloudsigma/cloudsigma-docs
mohsen-hassani-cs Feb 20, 2024
ba48a9f
Add the release notes for 2403 release.
mohsen-hassani-cs Mar 19, 2024
5a5ce5b
Update the copyright year.
mohsen-hassani-cs Apr 1, 2024
9990004
Add release notes for 2404.
mohsen-hassani-cs Apr 18, 2024
9921b28
Add info about the two new locations, DUS and MTY.
mohsen-hassani-cs Apr 18, 2024
9674d39
Update the capabilities, backfilling, and billing, and add more examp…
mohsen-hassani-cs May 14, 2024
830bff0
Update response_locations
cs-ayatakinci May 21, 2024
11534bb
Add the release notes for 2405.
mohsen-hassani-cs May 28, 2024
e7782a2
Merge branch 'master' of https://github.com/cloudsigma/cloudsigma-docs
mohsen-hassani-cs May 28, 2024
c4c1fad
Fix the location details for MTY.
mohsen-hassani-cs May 28, 2024
aad5b4c
Add examples for the backup schedulers.
mohsen-hassani-cs Jun 3, 2024
9bf82fe
Add backup_schedulers to the index list of the main menu.
mohsen-hassani-cs Jun 3, 2024
403422a
Update billing.rst
cs-ayatakinci Jun 20, 2024
7d966e8
Add release notes for 2406.
mohsen-hassani-cs Jun 27, 2024
e32741c
Add release notes for 2407.
mohsen-hassani-cs Aug 5, 2024
7aa629a
Add the release notes for the release 2408.
mohsen-hassani-cs Aug 20, 2024
69ec5ad
Add release notes for 2409.
mohsen-hassani-cs Sep 18, 2024
3af5bb6
Update accounts.rst with the new endpoint to check authenticated serv…
cs-ayatakinci Oct 2, 2024
b9f844a
Add API call docs for usage reports.
mohsen-hassani-cs Oct 16, 2024
6855f42
Merge branch 'master' of https://github.com/cloudsigma/cloudsigma-docs
mohsen-hassani-cs Oct 16, 2024
aef5213
Add release notes for 2410.
mohsen-hassani-cs Oct 16, 2024
74b7406
docs: moved usage to separate page and updated index
Oct 22, 2024
3fa7d0e
usage in separate page and updated index
Oct 22, 2024
29f487c
Add release notes for 2411.
mohsen-hassani-cs Nov 28, 2024
e20dcd8
Add release notes for 2412.
mohsen-hassani-cs Jan 7, 2025
38d36c7
Add release notes for 2501
mohsen-hassani-cs Jan 23, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Update the capabilities, backfilling, and billing, and add more examp…
…les.
  • Loading branch information
mohsen-hassani-cs committed May 14, 2024

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
commit 9674d39b4f1eba6dd633344b9d171fc98897e4c1
8 changes: 4 additions & 4 deletions accounts.rst
Original file line number Diff line number Diff line change
@@ -2,7 +2,7 @@ Accounts
========

.. note::

See :rfc:`2616#section-9` for more details on HTTP methods semantics

General
@@ -14,7 +14,7 @@ Create account

.. http:post:: /accounts/action/?do=create

Creates an account on the system. In case of succes, the user has to check
Creates an account on the system. In case of success, the user has to check
his email for a confirmation link, which will ask him to create a password
for the account.

@@ -38,7 +38,7 @@ Login/Logout

.. http:post:: /accounts/action/?do=login

Login to the system using cookie auth
Log in to the system using cookie auth

:statuscode 200: no error
:statuscode 401: unauthorized
@@ -94,7 +94,7 @@ Login/Logout

.. http:post:: /accounts/action/?do=check_login

Check if you are logged in the system
Check if you are logged in to the system

:statuscode 200: no error

51 changes: 29 additions & 22 deletions acls.rst
Original file line number Diff line number Diff line change
@@ -8,17 +8,17 @@ to your private network (VLAN).
Permissions can be granted on servers, drives, network resources, and firewall policies. All of these resources support
``LIST`` and ``EDIT`` permissions, which respectively allow the grantee to see the resources when listing them and to
edit resources. When a user is granted a ``LIST`` permission, this resource appears in the grantee's resource list. For
example granting ``LIST`` on a drive will make it appear in the list with grantees drives, when they make a GET request
example, granting ``LIST`` on a drive will make it appear in the list with grantees' drives, when they make a GET request
to */drives*. Own resources can be differentiated from granted resources, by the ``owner`` field.

Some resources have additional permissions. Drives have ``ATTACH`` permission which allows another user to use the
drive on their server. IPs, VLANs, and Firewall policies have ``ATTACH`` which will allow another user to assign these
network resource to NICs on their server. Servers have ``START`` and ``STOP``, ``OPEN_VNC`` permissions which allow
network resources to NICs on their server. Servers have ``START`` and ``STOP``, ``OPEN_VNC`` permissions which allow
another user to start or stop the server, or to open the server console through VNC. Note that ACLs may contain
permissions that are not directly applicable on some resources, for example it is possible to to have ``STOP``
permissions that are not directly applicable to some resources, for example, it is possible to have ``STOP``
permission in an ACL on tag which refers only to drives. Drives and servers support ``CLONE`` permission, which allows
cloning them to the grantee account. Note that in order to clone someone else's server, you need ``CLONE`` permission
on both the owner's server, and on the attached non-cdrom drives. For cdrom drives, the user will need a ``ATTACH``
cloning them to the grantee account. Note that to clone someone else's server, you need ``CLONE`` permission
on both the owner's server and on the attached non-cdrom drives. For cdrom drives, the user will need an ``ATTACH``
permission. The table below summarizes the permissions applicable to each resource:

========================= ===========================================================
@@ -30,11 +30,11 @@ IP, VLAN, Firewall Policy ``LIST`` ``EDIT`` ``ATTACH``
========================= ===========================================================


ACLs are granted on tags, and apply for all the tagged resources. One ACL can be attached to multiple tags, and will
ACLs are granted on tags and apply to all the tagged resources. One ACL can be attached to multiple tags, and will
apply to the set of all resources tagged by these tags. It is also possible to have multiple ACLs on a tag, in which
case the permissions on the tagged resources are the combination of all ACLs rules.

Each ACL can have one or more grantee users. Each ACL object has a list of rules, which specify what permission are
Each ACL can have one or more grantee users. Each ACL object has a list of rules, that specify what permissions are
given by the ACL.

Permissions are not transferable to third parties, i.e. if you grant permission to someone, they can't grant it to a
@@ -125,7 +125,7 @@ Creates a new ACL.
.. literalinclude:: dumps/response_acls_create
:language: javascript

It is possible to define the grantees, tags and rules at creation time. Just specify their UUIDs the `grantees` list:
It is possible to define the grantees, tags, and rules at creation time. Just specify their UUIDs in the `grantees` list:

**Example request**:

@@ -183,7 +183,7 @@ Deletes a single ACL.
Full Example of Sharing a Resource
----------------------------------

First let's create a tag which will be shared with another user:
First, let's create a tag that will be shared with another user:

**Request**:

@@ -230,7 +230,7 @@ If we get the drive definition we will see the grantee in the ``grantees`` attri
.. literalinclude:: dumps/response_own_drive_grantees
:language: javascript

Since there is an ACL on the the tag all resources created with this tag will be shared. For example if we create a
Since there is an ACL on the tag all resources created with this tag will be shared. For example, if we create a
server with the same tag, we see that it also shows ``grantees``:

.. literalinclude:: dumps/request_server_with_acl
@@ -239,15 +239,22 @@ server with the same tag, we see that it also shows ``grantees``:
.. literalinclude:: dumps/response_server_with_acl
:language: javascript

*The units for CPU, MEM, and SSD/DSSD are:*

CPU: GHz

MEM: Bytes

SSD / DSSD: Bytes

Permissions on Resources Attached to a Server
---------------------------------------------

When updating another user's server, the attached resources, such as drives, IPs, VLANs, or firewall policies, should
be available for the server owner. This means that either the attached resource should be owned by the server owner,
or the owner should be given ``ATTACH`` permission on the attached resource. For example if user A shares a
server with ``EDIT`` permission to user B, and user B wants to attach their drive on the server, user B will have to
grant ``ATTACH`` permission on the drive, so that the owner of the server is able to start it. Trying to attach a
be available for the server owner. This means that either the attached resource should be owned by the server owner
or the owner should be given ``ATTACH`` permission on the attached resource. For example, if user A shares a
server with ``EDIT`` permission to user B, and user B wants to attach their drive to the server, user B will have to
grant ``ATTACH`` permission on the drive so that the owner of the server can start it. Trying to attach a
drive, on which there is no permission for the owner of the server will result in an error.

Recognizing Shared Resources and What Permissions Are Given on Them
@@ -256,10 +263,10 @@ Recognizing Shared Resources and What Permissions Are Given on Them
Finding out which resources were shared with you
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Resources shared with you appear in the resource list along with your own resources. In order to differentiate between
Resources shared with you appear in the resource list along with your resources. To differentiate between
owner, and shared with you resources you have to look at the ``owner`` field. If the user is the same as you, the
resource is yours. Non-owned resource have their respective owner uuid in the ``owner`` field. The examples in the
next two subsections show the same drive from the view point of permission grantor and grantee. Notice how ``owner``
next two subsections show the same drive from the viewpoint of permission grantor and grantee. Notice how ``owner``
is the same.

Finding what permissions are granted to you on a resource
@@ -270,7 +277,7 @@ resource, it hard to do so in a simple script. That is why each resource has ``p
effective permissions the current user has on the resource. The ``permissions`` field is empty if the owner is the same
as the current user.

For example if you get the definition of a drive shared by another user with you:
For example, if you get the definition of a drive shared by another user with you:

.. literalinclude:: dumps/request_foreign_drive_permissions
:language: http
@@ -284,17 +291,17 @@ The definition includes non-empty ``permissions`` attribute:
:keys: permissions
:hide_header: true

In the next subsection there is an example of the same drive but from the view point of the drive owner.
In the next subsection, there is an example of the same drive but from the viewpoint of the drive owner.

Finding what permissions you have granted on a resource
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As is the case with finding out what permissions are given to the current user, it also hard to find out, to find out
As is the case with finding out what permissions are given to the current user, it is also hard to find out, to find out
what is granted to other users, as users may be granted different permissions through several ACLs referring to
different tags. Therefore each resource has read-only field ``grantees``. Each object of the ``grantees`` list contains
a references to the grantee user, and a list of the permissions granted to them.
references to the grantee user and a list of the permissions granted to them.

For example if you get the definition of your drive shared with another user:
For example, if you get the definition of your drive shared with another user:

.. literalinclude:: dumps/request_own_drive_grantees
:language: http
@@ -308,7 +315,7 @@ The definition includes non-empty ``grantees`` attribute:
:keys: grantees
:hide_header: true

In the previous subsection there is an example of the same drive definition but from the view point of the permissions
In the previous subsection, there is an example of the same drive definition but from the viewpoint of the permissions
grantee.

Schema
4 changes: 2 additions & 2 deletions async.rst
Original file line number Diff line number Diff line change
@@ -5,7 +5,7 @@ Asynchronous server
Authentication
--------------

In order to use the asynchronous server, you must first authenticate through the API. This will give you a cookie that is valid for 2 minutes and that has to be used when connecting to the server.
To use the asynchronous server, you must first authenticate through the API. This will give you a cookie that is valid for 2 minutes and that has to be used when connecting to the server.

:statuscode 200: no error

@@ -51,4 +51,4 @@ The frame is a JSON object that contains the following fields:
* resource_type: A text field that describes the type of resource covered by the notification.
* resource_uri: The URI of the resource that has changed.

The JSON object might contain a 'object' key, that will contain the full blown resource referenced by the notification, JSON encoded.
The JSON object might contain an 'object' key, that will contain the full-blown resource referenced by the notification, JSON encoded.
39 changes: 23 additions & 16 deletions audit_logs.rst
Original file line number Diff line number Diff line change
@@ -2,13 +2,13 @@ Audit logs
==========

.. note::

See :rfc:`2616#section-9` for more details on HTTP methods semantics

General
-------
Audit logs are used to track changes made on your resources, either by you or by other parties, like CloudSigma
staff or people that have permission to access you resources.
staff or people who have permission to access your resources.

Querying is done as follows:

@@ -27,11 +27,11 @@ Actions
-------
Actions give information about the operation that created the log. They go in a few categories.

* General actions - related to most resource types like servers, drives and snapshots:
* General actions - related to most resource types like servers, drives, and snapshots:
- **create:** During resource creation
- **update:** During resource update
- **delete:** During resource deletion
- **change_owner:** The ownership of the resource has changed. Currently only CloudSigma staff can
- **delete:** During resource depletion
- **change_owner:** The ownership of the resource has changed. Currently, only CloudSigma staff can
change ownership of a resource.
- **clone_src:** Resource is used as a cloning source
- **clone_dst:** Resource is a cloning destination - the newly cloned drive.
@@ -43,38 +43,45 @@ Actions give information about the operation that created the log. They go in a
Only staff members can convert drives.
- **init_upload:** Drive upload is initialized.

* Server specific actions - these only relate to servers:
* Server-specific actions - these only relate to servers:
- **start_send:** An attempt to start a server
- **boot:** The result of a start operation.
- **stop_send:** An attempt to stop a server.
- **stop:** The result of a stop operation
- **open_vnc:** Open VNC channel to a server
- **close_vnc:** Close VNC channel to a server
- **shutdown_ACPI_send:** An ACPI shutdown request is send to the server.
- **heal:** Server got healed, because its recorded state did not match the physical infrastructure.
For example, a server is marked as unavailable, but it is actually running fine.
- **shutdown_ACPI_send:** An ACPI shutdown request is sent to the server.
- **heal:** The Server got healed because its recorded state did not match the physical infrastructure.
For example, a server is marked as unavailable, but it is running fine.

Errors
------
If the field **success** is marked as **False**, that means that an error occurred during the operation.
The error details are saved in the following fields:

* **error_type** - States the type of the error
* **error_point** - Points to cause of the error and is mainly used for validation errors
* **error_point** - Points to the cause of the error and is mainly used for validation errors
* **error_message** - Human readable message associated with the error

Example
-------
The following example will show all the logged information during a server's lifecycle.

First we create a server:
First, we create a server:

.. literalinclude:: dumps/request_create_server_for_audit
:language: http

.. literalinclude:: dumps/response_create_server_for_audit
:language: javascript

*The units for CPU, MEM, and SSD/DSSD are:*

CPU: GHz

MEM: Bytes

SSD / DSSD: Bytes

Upon completion you will see the following log at the top of the audit log list:

@@ -85,8 +92,8 @@ Upon completion you will see the following log at the top of the audit log list:
:language: javascript

- **action** states that we wanted to create a server
- **details** state the parameters of the create call
- **actor** states the user which executed the operation
- **Details** state the parameters of the create call
- **actor** states the user who executed the operation
- **success** is *true*, so the operation completed successfully.
- **uuid** matches the server's uuid

@@ -107,7 +114,7 @@ We check the logs again. We see that the action is **start_send** and **success*


If the server is fully booted and operational, its status will change to **running**.
If it failed to boot for some reason, the **error_type**, **error_point** and **error_message** fields will
If it failed to boot for some reason, the **error_type**, **error_point**, and **error_message** fields will
explain why that happened. In this particular case, we had a successful start, so the audit log looks like this:

.. literalinclude:: dumps/response_start_server_audit_log_complete
@@ -116,8 +123,8 @@ explain why that happened. In this particular case, we had a successful start, s

The pattern is the same when stopping a server:
* an audit log with action **stop_send** is saved, representing the status of the request to stop a server.
* If that succeeded i.e. the request to stop a server is successfully send, you can expect a log with action
**stop**, representing the status of the stop operation i.e. the server actually stopped.
* If that succeeded i.e. the request to stop a server is successfully sent, you can expect a log with action
**stop**, representing the status of the stop operation i.e. the server stopped.


.. note::
Loading