summaryrefslogtreecommitdiffstats
path: root/meta-openstack/Documentation/README.swift
diff options
context:
space:
mode:
Diffstat (limited to 'meta-openstack/Documentation/README.swift')
-rw-r--r--meta-openstack/Documentation/README.swift444
1 files changed, 444 insertions, 0 deletions
diff --git a/meta-openstack/Documentation/README.swift b/meta-openstack/Documentation/README.swift
new file mode 100644
index 0000000..8429a2e
--- /dev/null
+++ b/meta-openstack/Documentation/README.swift
@@ -0,0 +1,444 @@
1Summary
2=======
3
4This document is not intended to provide detail of how Swift in general
5works, but rather it highlights the details of how Swift cluster is
6setup and OpenStack is configured to allow various Openstack components
7interact with Swift.
8
9
10Swift Overview
11==============
12
13Openstack Swift is an object storage service. Clients can access swift
14objects through RESTful APIs. Swift objects can be grouped into a
15"container" in which containers are grouped into "account". Each account
16or container in Swift cluster is represented by a SQLite database which
17contains information related to that account or container. Each
18Swift object is just user data input.
19
20Swift cluster can include a massive number of storage devices. Any Swift
21storage device can be configured to store container databases and/or
22account databases and/or objects. Each Swift account database can be
23identified by tuple (account name). Each Swift container database can
24be identified by tuple (account name, container name). Each swift object
25can be identified by tuple (account name, container name, object name).
26
27Swift uses "ring" static mapping algorithm to identify what storage device
28hosting account database, container database, or object contain (similar
29to Ceph uses Crush algorithm to identify what OSD hosting Ceph object).
30A Swift cluster has 3 rings (account ring, container ring, and object ring)
31used for finding location of account database, container database, or
32object file respectively.
33
34Swift service includes the following core services: proxy-server which
35provides the RESTful APIs for Swift clients to access; account-server
36which manages accounts; container-server which manages containers;
37and object-server which manages objects.
38
39
40Swift Cluster Setup
41===================
42
43The Swift default cluster is setup to have the followings:
44
45* All Swift main process services including proxy-server, account-server
46 container-server, object-server run on Controller node.
47* 3 zones in which each zone has only 1 storage device.
48 The underneath block devices for these 3 storage devices are loopback
49 devices. The size of the backing up loopback files is 2Gbytes by default
50 and can be changed at compile time through variable SWIFT_BACKING_FILE_SIZE.
51 If SWIFT_BACKING_FILE_SIZE="0G" then is for disabling loopback devices
52 and using local filesystem as Swift storage device.
53* All 3 Swift rings have 2^12 partitions and 2 replicas.
54
55The Swift default cluster is mainly for demonstration purpose. One might
56wants to have a different Swift cluster setup than this setup (e.g. using
57real hardware block device instead of loopback devices).
58
59The script /etc/swift/swift_setup.sh is provided to ease the task of setting
60up a complicated Swift cluster. It reads a cluster config file, which describes
61what storage devices are included in what rings, and constructs the cluster.
62
63For details of how to use swift_setup.sh and the format of Swift cluster
64config file please refer to the script's help:
65
66 $ swift_setup.sh
67
68
69Glance and Swift
70================
71
72Glance can store images into Swift cluster when "default_store = swift"
73is set in /etc/glance/glance-api.conf.
74
75By default "default_store" has value of "file" which tells Glance to
76store images into local filesystem. "default_store" value can be set
77during compile time through variable GLANCE_DEFAULT_STORE.
78
79The following configuration options in /etc/glance/glance-api.conf affect
80on how glance interacts with Swift cluster:
81
82 swift_store_auth_version = 2
83 swift_store_auth_address = http://127.0.0.1:5000/v2.0/
84 swift_store_user = service:glance
85 swift_store_key = password
86 swift_store_container = glance
87 swift_store_create_container_on_put = True
88 swift_store_large_object_size = 5120
89 swift_store_large_object_chunk_size = 200
90 swift_enable_snet = False
91
92With these default settings, the images will be stored under
93Swift account: "service" tenant ID and Swift cluster container:
94"glance".
95
96
97Cinder Backup and Swift
98=======================
99
100Cinder-backup has ability to store volume backup into Swift
101cluster with the following command:
102
103 $ cinder backup-create <cinder volume ID>
104
105where <cinder volume ID> is ID of an existing Cinder volume if
106the configure option "backup_driver" in /etc/cinder/cinder.conf
107is set to "cinder.backup.drivers.ceph".
108
109Cinder-backup is not be able to create a backup for any cinder
110volume which backed by NFS or Glusterfs. This is because NFS
111and Gluster cinder-volume backend drivers do not support the
112backup functionality. In other words, only cinder volume
113backed by lvm-iscsi and ceph-rbd are able to be backed-up
114by cinder-backup.
115
116The following configuration options in /etc/cinder/cinder.conf affect
117on how cinder-backup interacts with Swift cluster:
118
119 backup_swift_url=http://controller:8888/v1/AUTH_
120 backup_swift_auth=per_user
121 #backup_swift_user=<None>
122 #backup_swift_key=<None>
123 backup_swift_container=cinder-backups
124 backup_swift_object_size=52428800
125 backup_swift_retry_attempts=3
126 backup_swift_retry_backoff=2
127 backup_compression_algorithm=zlib
128
129With these defaults settings, the tenant ID of the keystone user that
130runs "cinder backup-create" command will be used as Swift cluster
131account name, along with "cinder-backups" Swift cluster container name
132in which the volume backups will be saved into.
133
134
135Build Configuration Options
136===========================
137
138* Controller build config options:
139
140 --enable-board=intel-xeon-core \
141 --enable-rootfs=ovp-openstack-controller \
142 --enable-addons=wr-ovp-openstack,wr-ovp \
143 --with-template=feature/openstack-tests \
144 --with-layer=meta-cloud-services/meta-openstack-swift-deploy
145
146* Compute build config options:
147
148 --enable-board=intel-xeon-core \
149 --enable-rootfs=ovp-openstack-compute \
150 --enable-addons=wr-ovp-openstack,wr-ovp
151
152
153Test Steps
154==========
155
156This section describes test steps and expected results to demonstrate that
157Swift is integrated properly into OpenStack.
158
159Please note: the following commands are carried on Controller node, unless
160otherwise explicitly indicated.
161
162 $ Start Controller and Compute node
163 $ . /etc/nova/openrc
164 $ dd if=/dev/urandom of=50M_c1.org bs=1M count=50
165 $ dd if=/dev/urandom of=50M_c2.org bs=1M count=50
166 $ dd if=/dev/urandom of=100M_c2.org bs=1M count=100
167 $ swift upload c1 50M_c1.org && swift upload c2 50M_c2.org && swift upload c2 100M_c2.org
168 $ swift list
169
170c1
171c2
172
173 $ swift stat c1
174
175 Account: AUTH_4ebc0e00338f405c9267866c6b984e71
176 Container: c1
177 Objects: 1
178 Bytes: 52428800
179 Read ACL:
180 Write ACL:
181 Sync To:
182 Sync Key:
183 Accept-Ranges: bytes
184 X-Timestamp: 1396457818.76909
185 X-Trans-Id: tx0564472425ad47128b378-00533c41bb
186 Content-Type: text/plain; charset=utf-8
187
188(Should see there is 1 object)
189
190 $ swift stat c2
191
192root@controller:~# swift stat c2
193 Account: AUTH_4ebc0e00338f405c9267866c6b984e71
194 Container: c2
195 Objects: 2
196 Bytes: 157286400
197 Read ACL:
198 Write ACL:
199 Sync To:
200 Sync Key:
201 Accept-Ranges: bytes
202 X-Timestamp: 1396457826.26262
203 X-Trans-Id: tx312934d494a44bbe96a00-00533c41cd
204 Content-Type: text/plain; charset=utf-8
205
206(Should see there are 2 objects)
207
208 $ swift stat c3
209
210Container 'c3' not found
211
212 $ mv 50M_c1.org 50M_c1.save && mv 50M_c2.org 50M_c2.save && mv 100M_c2.org 100M_c2.save
213 $ swift download c1 50M_c1.org && swift download c2 50M_c2.org && swift download c2 100M_c2.org
214 $ md5sum 50M_c1.save 50M_c1.org && md5sum 50M_c2.save 50M_c2.org && md5sum 100M_c2.save 100M_c2.org
215
216a8f7d671e35fcf20b87425fb39bdaf05 50M_c1.save
217a8f7d671e35fcf20b87425fb39bdaf05 50M_c1.org
218353233ed20418dbdeeb2fad91ba4c86a 50M_c2.save
219353233ed20418dbdeeb2fad91ba4c86a 50M_c2.org
2203b7cbb444c2ba93819db69ab3584f4bd 100M_c2.save
2213b7cbb444c2ba93819db69ab3584f4bd 100M_c2.org
222
223(The md5sums of each pair "zzz.save" and "zzz.org" files must be the same)
224
225 $ swift delete c1 50M_c1.org && swift delete c2 50M_c2.org
226 $ swift stat c1
227
228 Account: AUTH_4ebc0e00338f405c9267866c6b984e71
229 Container: c1
230 Objects: 0
231 Bytes: 0
232 Read ACL:
233 Write ACL:
234 Sync To:
235 Sync Key:
236 Accept-Ranges: bytes
237 X-Timestamp: 1396457818.77284
238 X-Trans-Id: tx58e4bb6d06b84276b8d7f-00533c424c
239 Content-Type: text/plain; charset=utf-8
240
241(Should see there is no object)
242
243 $ swift stat c2
244
245 Account: AUTH_4ebc0e00338f405c9267866c6b984e71
246 Container: c2
247 Objects: 1
248 Bytes: 104857600
249 Read ACL:
250 Write ACL:
251 Sync To:
252 Sync Key:
253 Accept-Ranges: bytes
254 X-Timestamp: 1396457826.25872
255 X-Trans-Id: txdae8ab2adf4f47a4931ba-00533c425b
256 Content-Type: text/plain; charset=utf-8
257
258(Should see there is 1 object)
259
260 $ swift upload c1 50M_c1.org && swift upload c2 50M_c2.org
261 $ rm *.org
262 $ swift download c1 50M_c1.org && swift download c2 50M_c2.org && swift download c2 100M_c2.org
263 $ md5sum 50M_c1.save 50M_c1.org && md5sum 50M_c2.save 50M_c2.org && md5sum 100M_c2.save 100M_c2.org
264
26531147c186e7dd2a4305026d3d6282861 50M_c1.save
26631147c186e7dd2a4305026d3d6282861 50M_c1.org
267b9043aacef436dfbb96c39499d54b850 50M_c2.save
268b9043aacef436dfbb96c39499d54b850 50M_c2.org
269b1a1b6b34a6852cdd51cd487a01192cc 100M_c2.save
270b1a1b6b34a6852cdd51cd487a01192cc 100M_c2.org
271
272(The md5sums of each pair "zzz.save" and "zzz.org" files must be the same)
273
274 $ neutron net-create mynetwork
275 $ glance image-create --name myfirstimage --is-public true --container-format bare --disk-format qcow2 --file /root/images/cirros-0.3.0-x86_64-disk.img
276 $ glance image-list
277
278+--------------------------------------+--------------+-------------+------------------+---------+--------+
279| ID | Name | Disk Format | Container Format | Size | Status |
280+--------------------------------------+--------------+-------------+------------------+---------+--------+
281| 79f52103-5b22-4aa5-8159-2d146b82b0b2 | myfirstimage | qcow2 | bare | 9761280 | active |
282+--------------------------------------+--------------+-------------+------------------+---------+--------+
283
284 $ export OS_TENANT_NAME=service && export OS_USERNAME=glance
285 $ swift list glance
286
28779f52103-5b22-4aa5-8159-2d146b82b0b2
288
289(The object name in the "glance" container must be the same as glance image id just created)
290
291 $ swift download glance 79f52103-5b22-4aa5-8159-2d146b82b0b2
292 $ md5sum 79f52103-5b22-4aa5-8159-2d146b82b0b2 /root/images/cirros-0.3.0-x86_64-disk.img
293
29450bdc35edb03a38d91b1b071afb20a3c 79f52103-5b22-4aa5-8159-2d146b82b0b2
29550bdc35edb03a38d91b1b071afb20a3c /root/images/cirros-0.3.0-x86_64-disk.img
296
297(The md5sum of these 2 files must be the same)
298
299 $ ls /etc/glance/images/
300(This should be empty)
301
302 $ . /etc/nova/openrc
303 $ nova boot --image myfirstimage --flavor 1 myinstance
304 $ nova list
305
306+--------------------------------------+------------+--------+------------+-------------+----------+
307| ID | Name | Status | Task State | Power State | Networks |
308+--------------------------------------+------------+--------+------------+-------------+----------+
309| bc9662a0-0dac-4bff-a7fb-b820957c55a4 | myinstance | ACTIVE | - | Running | |
310+--------------------------------------+------------+--------+------------+-------------+----------+
311
312 $ From dashboard, log into VM console to make sure the VM is really running
313 $ nova delete bc9662a0-0dac-4bff-a7fb-b820957c55a4
314 $ glance image-delete 79f52103-5b22-4aa5-8159-2d146b82b0b2
315 $ export OS_TENANT_NAME=service && export OS_USERNAME=glance
316 $ swift list glance
317
318(Should be empty)
319
320 $ . /etc/nova/openrc && . /etc/cinder/add-cinder-volume-types.sh
321 $ cinder create --volume_type lvm_iscsi --display_name=lvm_vol_1 1
322 $ cinder list
323
324+--------------------------------------+-----------+--------------+------+-------------+----------+-------------+
325| ID | Status | Display Name | Size | Volume Type | Bootable | Attached to |
326+--------------------------------------+-----------+--------------+------+-------------+----------+-------------+
327| 3e388ae0-2e20-42a2-80da-3f9f366cbaed | available | lvm_vol_1 | 1 | lvm_iscsi | false | |
328+--------------------------------------+-----------+--------------+------+-------------+----------+-------------+
329
330 $ cinder backup-create 3e388ae0-2e20-42a2-80da-3f9f366cbaed
331 $ cinder backup-list
332
333+--------------------------------------+--------------------------------------+-----------+------+------+--------------+----------------+
334| ID | Volume ID | Status | Name | Size | Object Count | Container |
335+--------------------------------------+--------------------------------------+-----------+------+------+--------------+----------------+
336| 1444f5d0-3a87-40bc-a7a7-f3c672768b6a | 3e388ae0-2e20-42a2-80da-3f9f366cbaed | available | None | 1 | 22 | cinder-backups |
337+--------------------------------------+--------------------------------------+-----------+------+------+--------------+----------------+
338
339 $ swift list
340
341c1
342c2
343cinder-backups
344
345(Should see new Swift container "cinder-backup")
346
347 $ swift list cinder-backups
348
349volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00001
350volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00002
351volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00003
352volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00004
353volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00005
354volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00006
355volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00007
356volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00008
357volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00009
358volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00010
359volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00011
360volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00012
361volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00013
362volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00014
363volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00015
364volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00016
365volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00017
366volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00018
367volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00019
368volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00020
369volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00021
370volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a_metadata
371
372 $ reboot
373 $ . /etc/nova/openrc && swift list cinder-backups
374
375volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00001
376volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00002
377volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00003
378volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00004
379volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00005
380volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00006
381volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00007
382volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00008
383volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00009
384volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00010
385volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00011
386volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00012
387volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00013
388volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00014
389volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00015
390volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00016
391volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00017
392volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00018
393volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00019
394volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00020
395volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a-00021
396volume_3e388ae0-2e20-42a2-80da-3f9f366cbaed/20140402193029/az_nova_backup_1444f5d0-3a87-40bc-a7a7-f3c672768b6a_metadata
397
398 $ cinder backup-delete 1444f5d0-3a87-40bc-a7a7-f3c672768b6a
399 $ swift list cinder-backups
400
401(Should be empty)
402
403
404Swift Built-In Unit Tests
405=========================
406
407This section describes how to run Swift and Swift client built-in unit
408tests which are located at:
409
410 /usr/lib64/python2.7/site-packages/swift/test
411 /usr/lib64/python2.7/site-packages/swiftclient/tests
412
413with nosetests test-runner. Please make sure that the test accounts
414setting in /etc/swift/test.conf reflects the keystone user accounts
415setting.
416
417To run swift built-in unit test with nosetests:
418
419 $ To accommodate the small space of loop dev,
420 modify /etc/swift/swift.conf to have "max_file_size = 5242880"
421 $ /etc/init.d/swift restart
422 $ cd /usr/lib64/python2.7/site-packages/swift
423 $ nosetests -v test
424
425Ran 1633 tests in 272.930s
426
427FAILED (errors=5, failures=4)
428
429To run swiftclient built-in unit test with nosetests:
430
431 $ cd /usr/lib64/python2.7/site-packages/swiftclient
432 $ nosetests -v tests
433
434Ran 108 tests in 2.277s
435
436FAILED (failures=1)
437
438
439References
440==========
441
442* http://docs.openstack.org/developer/swift/deployment_guide.html
443* http://docs.openstack.org/grizzly/openstack-compute/install/yum/content/ch_installing-openstack-object-storage.html
444* https://swiftstack.com/openstack-swift/architecture/
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-04-22 15:17:02 +0000