diff options
Diffstat (limited to 'src/sdk-update/sdk.rst')
-rw-r--r-- | src/sdk-update/sdk.rst | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/src/sdk-update/sdk.rst b/src/sdk-update/sdk.rst new file mode 100644 index 0000000..09364a8 --- /dev/null +++ b/src/sdk-update/sdk.rst | |||
@@ -0,0 +1,180 @@ | |||
1 | . display in 68x24 | ||
2 | .. display in 88x24 | ||
3 | |||
4 | .. transition:: dissolve | ||
5 | :duration: 0.4 | ||
6 | |||
7 | Update on OpenStackSDK / shade | ||
8 | ============================== | ||
9 | |||
10 | Background | ||
11 | ========== | ||
12 | |||
13 | Two Python OpenStack SDKs: | ||
14 | |||
15 | * openstacksdk | ||
16 | * shade | ||
17 | |||
18 | One support library: | ||
19 | |||
20 | * os-client-config | ||
21 | |||
22 | openstacksdk | ||
23 | ============ | ||
24 | |||
25 | * Object-Oriented presentation of OpenStack services and resources | ||
26 | * ``import openstack`` | ||
27 | * Used by python-openstackclient for Neutron | ||
28 | * Used by heat for some Neutron | ||
29 | * Used by senlin, octavia-dashboard, masakari and bilean | ||
30 | * Unofficial, but with an official sounding name | ||
31 | * Exposes versions and services as they are in the API | ||
32 | |||
33 | .. code-block:: python | ||
34 | |||
35 | # conn.image is openstack.image.v1._proxy.Proxy or | ||
36 | # openstack.image.v2._proxy.Proxy depending on config (soon discovery) | ||
37 | conn.image.images() | ||
38 | # PUT /image | ||
39 | conn.image.upload_image(name='foo') | ||
40 | |||
41 | shade | ||
42 | ===== | ||
43 | |||
44 | * Abstraction layer covering up differences | ||
45 | * Originally extracted from Nodepool | ||
46 | * Used in Ansible OpenStack Modules (and now Salt) | ||
47 | * Official, but with an unofficial sounding name | ||
48 | * Excessively backwards compatible | ||
49 | * Resource/task oriented interface that hides service | ||
50 | |||
51 | .. code-block:: python | ||
52 | |||
53 | # Calls glance or nova API as needed | ||
54 | conn.list_images() | ||
55 | # Uses v1, v2 PUT or v2 tasks as needed | ||
56 | conn.create_image(name='foo') | ||
57 | |||
58 | os-client-config | ||
59 | ================ | ||
60 | |||
61 | * Library to handle API client account configuration | ||
62 | * Added support for ``clouds.yaml`` config files | ||
63 | * Used by shade, python-openstackclient, openstacksdk | ||
64 | * Run by OpenStackClient project team | ||
65 | |||
66 | Queens: The Great Merging | ||
67 | ========================= | ||
68 | |||
69 | * Staffing on both projects less than desired, coupled with corporate cutbacks | ||
70 | * openstacksdk project adopted by shade team as a deliverable | ||
71 | * shade team renamed to OpenStackSDK team | ||
72 | * shade and os-client-config codebases merged in to openstacksdk repo | ||
73 | * shade.openstackcloud.OpenStackCloud -> openstack.connection.Connection | ||
74 | * os_client_config -> openstack.config | ||
75 | |||
76 | Queens: Major SDK refactors | ||
77 | =========================== | ||
78 | |||
79 | * Proxy objects are now subclasses of keystoneauth1.adapter.Adapter | ||
80 | * Proxy objects are the objects that represent methods to call on a service | ||
81 | * Resource objects describe each remote resource | ||
82 | * Proxy objects attached to Connection | ||
83 | * Using official names and aliases from service-types-authority | ||
84 | * Proxy object for every service in service-types-authority | ||
85 | * Profile objects removed in favor of CloudRegion object from os-client-config | ||
86 | * Pagination supported by default for all OpenStack resources | ||
87 | |||
88 | Connection | ||
89 | ========== | ||
90 | |||
91 | * Primary interface object | ||
92 | * Represents a connection to a region of a cloud | ||
93 | |||
94 | .. code-block:: python | ||
95 | |||
96 | import openstack | ||
97 | |||
98 | conn = openstack.connect(cloud='vexxhost') | ||
99 | |||
100 | Three Interfaces In One | ||
101 | ======================= | ||
102 | |||
103 | * Abstraction layer from shade | ||
104 | * Object layer from SDK | ||
105 | * REST layer from keystoneauth | ||
106 | |||
107 | .. code-block:: python | ||
108 | |||
109 | conn.list_images() # list | ||
110 | conn.image.images() # generator | ||
111 | conn.image.get('/image') # requests.Response | ||
112 | |||
113 | A Note on Pagination | ||
114 | ==================== | ||
115 | |||
116 | * List methods (like ``conn.image.images``) are generators | ||
117 | * Transparently do pagination behind the scenes | ||
118 | * ``limit`` parameter is a requested batch size | ||
119 | * Server-side configured batch size may also be in effect | ||
120 | * If you want less then all results, stop iterating | ||
121 | |||
122 | What's Supported | ||
123 | ================ | ||
124 | |||
125 | * It's all driven by service-types-authority: | ||
126 | https://service-types.openstack.org/ | ||
127 | * Every official OpenStack service has at least REST interface | ||
128 | * Every official OpenStack service is welcome to add Proxy/Resource objects | ||
129 | |||
130 | Plugins/Drivers | ||
131 | =============== | ||
132 | |||
133 | * No entrypoints-based drivers | ||
134 | * It's not openstacksdk's job to support non-OpenStack things | ||
135 | * Want to enable new projects to skip writing a python-*client library | ||
136 | |||
137 | .. code-block:: python | ||
138 | |||
139 | class MyService(openstack.service_description.ServiceDescription): | ||
140 | proxy_class = MyProxyClass | ||
141 | service_type = 'awesome-service' | ||
142 | |||
143 | conn.add_service(MyService()) | ||
144 | conn.awesome_service.create_awesome() | ||
145 | |||
146 | Facilities for Use by Services | ||
147 | ============================== | ||
148 | |||
149 | * ``load_yaml_config`` and ``load_envvars`` flags | ||
150 | * ``openstack.connection.from_session`` - use existing authenticated Session | ||
151 | |||
152 | .. code-block:: python | ||
153 | |||
154 | conn = openstack.connection.from_session( | ||
155 | session=self.context.keystone_session, | ||
156 | region_name=self._get_region_name(), | ||
157 | app_name='heat', | ||
158 | app_version=heat.version.version_info.version_string()) | ||
159 | |||
160 | Compatibility Policy | ||
161 | ==================== | ||
162 | |||
163 | * shade's stance on backwards compat applies - once we release 1.0 of SDK | ||
164 | * sdk supports all existing OpenStack clouds | ||
165 | * Patches fixing interactions with a Diablo cloud would be accepted | ||
166 | |||
167 | Status | ||
168 | ====== | ||
169 | |||
170 | * os-client-config is now a thin shim around openstack.config | ||
171 | * service-types-authority aliases in keystoneauth (Just Released Friday) | ||
172 | * Version selection driven by config, patches up for version discovery | ||
173 | |||
174 | What's Next | ||
175 | =========== | ||
176 | |||
177 | * Make Resource classes suitable for shade calls | ||
178 | * Start working on replacing use of python-*client in python-openstackclient | ||
179 | * Make shade a libraries thin compat layer | ||
180 | * Shift abstraction layer methods to use OO layer (currently use REST layer) | ||