Browse Source

Merge "doc: add provider driver development instructions"

Zuul 2 weeks ago
parent
commit
2f66863db4
1 changed files with 81 additions and 0 deletions
  1. 81
    0
      doc/source/devguide.rst

+ 81
- 0
doc/source/devguide.rst View File

@@ -66,3 +66,84 @@ Drivers
66 66
    :members:
67 67
 .. autoclass:: nodepool.driver.ProviderConfig
68 68
    :members:
69
+
70
+
71
+Writing A New Provider Driver
72
+-----------------------------
73
+
74
+Nodepool drivers are loaded from the nodepool/drivers directory. A driver
75
+is composed of three main objects:
76
+
77
+- A ProviderConfig to manage validation and loading of the provider.
78
+- A Provider to manage resource allocations.
79
+- A NodeRequestHandler to manage nodeset (collection of resource) allocations.
80
+
81
+Those objects are referenced from the Driver main interface that needs to
82
+be implemented in the __init__.py file of the driver directory.
83
+
84
+
85
+ProviderConfig
86
+~~~~~~~~~~~~~~
87
+
88
+The ProviderConfig is constructed with the driver object and the provider
89
+configuration dictionary.
90
+
91
+The main procedures of the ProviderConfig are:
92
+
93
+- getSchema() exposes a voluptuous schema of the provider configuration.
94
+- load(config) parses the provider configuration. Note that the config
95
+  argument is the global Nodepool.yaml configuration. Each provided labels
96
+  need to be referenced back to the global config.labels dictionary so
97
+  that the launcher service know which provider provide which labels.
98
+
99
+
100
+Provider
101
+~~~~~~~~
102
+
103
+The Provider is constructed with the ProviderConfig.
104
+
105
+The main procedures of the Provider are:
106
+
107
+- cleanupNode(external_id) terminates a resource
108
+
109
+- listNodes() returns the list of existing resources. This procedure needs to
110
+  map the nodepool_node_id with each resource. If the provider doesn't support
111
+  resource metadata, the driver needs to implement a storage facility to
112
+  associate resource created by Nodepool with the internal nodepool_node_id.
113
+  The launcher periodically look for non-existent node_id in listNodes() to
114
+  delete any leaked resources.
115
+
116
+- getRequestHandler(pool, request) returns a NodeRequestHandler object to manage
117
+  the creation of resources. The contract between the handler and the provider is
118
+  free form. As a rule of thumb, the handler should be in charge of interfacing
119
+  with Nodepool's database while the provider should provides primitive to create
120
+  resources. For example the Provider is likely to implement a
121
+  createResource(pool, label) procedure that will be used by the handler.
122
+
123
+
124
+NodeRequestHandler
125
+~~~~~~~~~~~~~~~~~~
126
+
127
+The NodeRequestHandler is constructed with the assigned pool and the request object.
128
+Before the handler is used, the following attributes are set:
129
+
130
+* self.provider : the provider configuration.
131
+* self.pool : the pool configuration.
132
+* self.zk : the database client.
133
+* self.manager : the Provider object.
134
+
135
+The main procedures of the NodeRequestHandler are:
136
+
137
+- launch(node) starts the creation of a new resource.
138
+- launchesComplete() returns True if all the node of the nodesets self
139
+  attributes are READY.
140
+
141
+An Handler may not have to launch each node of the nodesets as Nodepool will
142
+re-use existing nodes.
143
+
144
+The launch procedure usually consists of the following operations:
145
+
146
+- Use the provider to create the resources associated with the node label.
147
+  Once an external_id is obtained, it should be stored to the node.external_id.
148
+- Once the resource is created, READY should be stored to the node.state.
149
+  Otherwise raise an exception to restart the launch attempt.

Loading…
Cancel
Save