Browse Source

Add a few more docs

Change-Id: I7fa70c3b89a8246662a654b379dd16d6a7a6b873
changes/76/395076/2
Monty Taylor 2 years ago
parent
commit
5f8ea0588a
No account linked to committer's email address
8 changed files with 146 additions and 12 deletions
  1. 2
    2
      CONTRIBUTING.rst
  2. 0
    1
      doc/source/conf.py
  3. 39
    0
      doc/source/design.rst
  4. 51
    0
      doc/source/faq.rst
  5. 3
    1
      doc/source/index.rst
  6. 51
    0
      doc/source/todo.rst
  7. 0
    7
      doc/source/usage.rst
  8. 0
    1
      test-requirements.txt

+ 2
- 2
CONTRIBUTING.rst View File

@@ -12,6 +12,6 @@ submitted for review via the Gerrit tool:
12 12
 
13 13
 Pull requests submitted through GitHub will be ignored.
14 14
 
15
-Bugs should be filed on Launchpad, not GitHub:
15
+Bugs should be filed on Storyboard, not GitHub:
16 16
 
17
-   https://bugs.launchpad.net/oaktree
17
+   https://storyboard.openstack.org/#!/project/855

+ 0
- 1
doc/source/conf.py View File

@@ -23,7 +23,6 @@ sys.path.insert(0, os.path.abspath('../..'))
23 23
 extensions = [
24 24
     'sphinx.ext.autodoc',
25 25
     #'sphinx.ext.intersphinx',
26
-    'oslosphinx'
27 26
 ]
28 27
 
29 28
 # autodoc generation is a bit aggressive and a nuisance when doing heavy

+ 39
- 0
doc/source/design.rst View File

@@ -0,0 +1,39 @@
1
+==============
2
+Oaktree Design
3
+==============
4
+
5
+Once 1.0.0 is released, oaktree pledges to never break backwards compatability.
6
+
7
+Oaktree is intended to be safe for deployers to run CD from master. In fact,
8
+a deployer running a kilo OpenStack should be able to install tip of master
9
+of oaktree and have everything be perfectly fine.
10
+
11
+Oaktree must be simple to install and operate. A single node install with no
12
+shared caching or locking is likely fine for most smaller clouds. For larger
13
+clouds, shared caching and locking are essential for scale out. Both must be
14
+supported, and simple.
15
+
16
+Oaktree is not pluggable.
17
+
18
+Oaktree does not allow selectively enabling or disabling features or part of
19
+its API.
20
+
21
+Oaktree should be runnable by an end user pointed at a local clouds.yaml file.
22
+
23
+Oaktree should be able to talk to other oaktrees.
24
+
25
+Oaktree users should never need to know any information about the cloud other
26
+than the address of the oaktree endpoint. Cloud-specific information the
27
+user needs to know must be exposed via a capabilities API. For instance, in
28
+order for a user to upload an image to a cloud, the user must know what format
29
+the cloud requires the image to be in. The user must be able to ask oaktree
30
+what image format(s) the cloud accepts.
31
+
32
+Data returned from oaktree should be normalized such that it is consistent
33
+no matter what drivers the cloud in question has chosen. This work is done in
34
+shade, but shapes the design of the protobuf messages.
35
+
36
+All objects in oaktree should have a Location. A Location defines the cloud,
37
+the region, the zone and the project that contains the object. For objects
38
+that exist at a region and not a zone level, like flavors and images, zone
39
+will be null. For objects that exist at a cloud level, region will be null.

+ 51
- 0
doc/source/faq.rst View File

@@ -0,0 +1,51 @@
1
+==========================
2
+Frequently Asked Questions
3
+==========================
4
+
5
+Why gRPC and not REST?
6
+----------------------
7
+
8
+There are three main reasons.
9
+
10
+We already have REST APIs. oaktree is not intended to replace them, but to
11
+supplement them to grease the 80% case that can be inter-operable.
12
+
13
+gRPC comes out of the gate with direct support for a pile of languages, so
14
+supporting our non-Python friends is direct and straightforward.
15
+
16
+A TON of time is spent in shade polling OpenStack for results. That may not
17
+sound like a problem - but when you spin up thousands of VMs a day like Infra
18
+does, the polling becomes a major engineering challenge. gRPC operates over
19
+http/2 and has support for bi-directional channels - which means you can just
20
+have a function notify you when something is done. That's a win for everyone
21
+
22
+Why write it in Python rather than XXX?
23
+---------------------------------------
24
+
25
+The hard part of this isn't the gRPC api - it's the business logic that's in
26
+the shade library. If we wrote oaktree from scratch in C++ (because hello
27
+super-high-performance gRPC backend!) - we'd be faced with the task of
28
+re-implementing all of the shade business logic in C++. If you haven't looked,
29
+there is a LOT.
30
+
31
+shade is what infra uses for nodepool. It has copious features in it already
32
+to deal with extremely high scale - including configurable caching, batched
33
+list update operations to prevent thundering herds and well exercised
34
+multi-threaded support.
35
+
36
+The interesting part also isn't the server (it's a simple proxy layer) - it's
37
+the clients. THOSE definitely want much love in the different languages. The
38
+infrastructure is in place for Python, C++ and Go. Ruby, javascript and C#
39
+should follow asap.
40
+
41
+Can I add support for my project?
42
+---------------------------------
43
+
44
+Yes. It has to be added to shade first, which accepts patches from anything
45
+that can be tested consistently in a devstack job. We require all new features
46
+in shade to come with functional tests. Once it's in shade, it can be added as
47
+an API to oaktree.
48
+
49
+However ... oaktree and shade both promise 100% backwards compatibility at all
50
+times. If your project is still young, be aware that once an API is added to
51
+shade or oaktree it will need to be supported until the end of time.

+ 3
- 1
doc/source/index.rst View File

@@ -13,7 +13,9 @@ Contents:
13 13
 
14 14
    readme
15 15
    installation
16
-   usage
16
+   design
17
+   faq
18
+   todo
17 19
    contributing
18 20
 
19 21
 Indices and tables

+ 51
- 0
doc/source/todo.rst View File

@@ -0,0 +1,51 @@
1
+===========
2
+Work Needed
3
+===========
4
+
5
+Design the auth story
6
+---------------------
7
+
8
+The native/default auth for gRPC is oauth. It has the ability for pluggable
9
+auth, but that would raise the barrier for new languages. I'd love it if we
10
+can come up with a story that involves making API users in keystone and
11
+authorizing them to use oaktree via an oauth transaction. The keystone auth
12
+backends currently are all about integrating with other auth management
13
+systems, which is great for environments where you have a web browser, but not
14
+so much for ones where you need to put your auth credentials into a file so
15
+that your scripts can work. I'm waving my hands wildly here - because all I
16
+really have are problems to solve and none of the solutions I have are great.
17
+
18
+Design Glance Image / Swift Object Uploads and Downloads
19
+--------------------------------------------------------
20
+
21
+Having those two data operations go through an API proxy seems inefficient.
22
+However, having them not in the API seems like a bad user experience. Perhaps
23
+if we take advantage of the gRPC streaming protocol support doing a direct
24
+streaming passthrough actually wouldn't be awful. Or maybe the better approach
25
+would be for the gRPC call to return a URL and token for a user to POST/PUT to
26
+directly. Literally no clue.
27
+
28
+Design and implement Capabilities API
29
+-------------------------------------
30
+
31
+shade and the current oaktree codebase rely on os-client-config and clouds.yaml
32
+for information about the cloud and what it can do. As a service, some of the
33
+pieces of information in os-client-config need to be queriable by the user.
34
+
35
+Implement API surfaces
36
+----------------------
37
+
38
+In general, all of the API operations shade can perform should be exposed in
39
+oaktree. In order to shape that work, we should tackle them in the following
40
+order:
41
+
42
+#. API surface needed for nodepool
43
+#. API surface needed for existing Ansible modules
44
+#. Everything else
45
+
46
+Implement oaktree backend in shade
47
+----------------------------------
48
+
49
+It's turtles all the way down. If shade sees that a cloud has an oaktree
50
+service, shade should talk to it over gRPC instead of talking to the REST
51
+APIs directly.

+ 0
- 7
doc/source/usage.rst View File

@@ -1,7 +0,0 @@
1
-========
2
-Usage
3
-========
4
-
5
-To use oaktree in a project::
6
-
7
-    import oaktree

+ 0
- 1
test-requirements.txt View File

@@ -8,7 +8,6 @@ coverage>=3.6
8 8
 discover
9 9
 python-subunit>=0.0.18
10 10
 sphinx!=1.2.0,!=1.3b1,<1.3,>=1.1.2
11
-oslosphinx>=2.5.0 # Apache-2.0
12 11
 oslotest>=1.10.0 # Apache-2.0
13 12
 testrepository>=0.0.18
14 13
 testscenarios>=0.4

Loading…
Cancel
Save