blob: 3db34931bdc26f6fc009ee4e099b43fe463973a8 [file] [log] [blame]
OlgaGusarenko87eb2842018-07-30 17:51:09 +03001=====
2Usage
3=====
Filip Pytlound681ae22015-10-06 16:28:31 +02004
Jakub Pavlik9e85d172016-05-20 11:13:14 +02005The Glance project provides services for discovering, registering, and
6retrieving virtual machine images. Glance has a RESTful API that allows
7querying of VM image metadata as well as retrieval of the actual image.
Filip Pytlound681ae22015-10-06 16:28:31 +02008
Aleš Komáreke5b388f2017-02-06 15:48:57 +01009Sample pillars
10==============
Filip Pytlound681ae22015-10-06 16:28:31 +020011
12.. code-block:: yaml
13
14 glance:
15 server:
16 enabled: true
17 version: juno
Alena Holanovac1e51312016-03-22 14:08:44 +010018 workers: 8
Dmitry Stremkovskiye9490cf2017-07-11 11:37:44 +030019 glance_uid: 302
20 glance_gid: 302
Alexey V. Abashkinae99c212019-08-26 13:09:36 +030021 container_formats:
22 ami:
23 enabled: True
24 ari:
25 enabled: False
26 docker:
27 enabled: True
28 disk_formats:
29 vhd:
30 enabled: False
31 raw:
32 enabled: True
33 qcow2:
34 enabled: True
Ivan Berezovskiy4f3840e2019-11-18 20:30:15 +040035 concurrency:
36 lock_path: '/var/lib/glance/tmp'
Filip Pytlound681ae22015-10-06 16:28:31 +020037 policy:
38 publicize_image:
39 - "role:admin"
40 - "role:image_manager"
41 database:
42 engine: mysql
43 host: 127.0.0.1
44 port: 3306
45 name: glance
46 user: glance
47 password: pwd
48 identity:
49 engine: keystone
50 host: 127.0.0.1
51 port: 35357
52 tenant: service
53 user: glance
54 password: pwd
55 message_queue:
56 engine: rabbitmq
57 host: 127.0.0.1
58 port: 5672
59 user: openstack
60 password: pwd
61 virtual_host: '/openstack'
62 storage:
63 engine: file
64 images:
65 - name: "CirrOS 0.3.1"
66 format: qcow2
67 file: cirros-0.3.1-x86_64-disk.img
68 source: http://cdn.download.cirros-cloud.net/0.3.1/cirros-0.3.1-x86_64-disk.img
69 public: true
Petr Michalec86ec0142016-11-29 16:34:15 +010070 audit:
71 enabled: false
Simon Pasquier2acbef52017-02-03 15:09:39 +010072 api_limit_max: 100
73 limit_param_default: 50
Oleg Iurchenko68ae3552017-10-13 18:40:42 +030074 barbican:
75 enabled: true
Simon Pasquier2acbef52017-02-03 15:09:39 +010076
OlgaGusarenko87eb2842018-07-30 17:51:09 +030077The pagination is controlled by the ``api_limit_max`` and ``limit_param_default``
Simon Pasquier2acbef52017-02-03 15:09:39 +010078parameters as shown above:
79
OlgaGusarenko87eb2842018-07-30 17:51:09 +030080* ``api_limit_max``
81 Defines the maximum number of records that the server will return.
Simon Pasquier2acbef52017-02-03 15:09:39 +010082
OlgaGusarenko87eb2842018-07-30 17:51:09 +030083* ``limit_param_default``
84 The default ``limit`` parameter that applies if the request didn't define
85 it explicitly.
Filip Pytlound681ae22015-10-06 16:28:31 +020086
OlgaGusarenko87eb2842018-07-30 17:51:09 +030087Configuration of the ``policy.json`` file:
Dmitry Ukov0a228ad2017-05-15 13:35:43 +040088
89.. code-block:: yaml
90
91 glance:
92 server:
93 ....
94 policy:
95 publicize_image: "role:admin"
96 # Add key without value to remove line from policy.json
97 add_member:
OlgaGusarenko87eb2842018-07-30 17:51:09 +030098
Aleš Komáreke5b388f2017-02-06 15:48:57 +010099Keystone and cinder region
100
101.. code-block:: yaml
102
103 glance:
104 server:
105 enabled: true
106 version: kilo
107 ...
108 identity:
109 engine: keystone
110 host: 127.0.0.1
111 region: RegionTwo
112 ...
113
114Ceph integration glance
115
116.. code-block:: yaml
117
118 glance:
119 server:
120 enabled: true
121 version: juno
122 storage:
123 engine: rbd,http
124 user: glance
125 pool: images
126 chunk_size: 8
127 client_glance_key: AQDOavlU6BsSJhAAnpFR906mvdgdfRqLHwu0Uw==
128
Vasyl Saienko83575672018-07-17 18:34:43 +0300129VMWare integration:
130
131.. code-block:: yaml
132
133 glance:
134 server
135 storage:
136 engine: vmware
137 default_store: vsphere
138 vmware:
139 enabled: true
140 server_host: 1.2.3.4
141 server_username: vmware_username
142 server_password: vmware_password
143 datastores:
144 data1:
145 name: datastore_name1
146 enabled: true
147 path: datacenter_name
148 weight: 10
149 data2:
150 name: datastore_name2
151 enabled: true
152 path: datacenter_name
153
Aleš Komáreke5b388f2017-02-06 15:48:57 +0100154RabbitMQ HA setup
155
156.. code-block:: yaml
157
158 glance:
159 server:
160 ....
161 message_queue:
162 engine: rabbitmq
163 members:
164 - host: 10.0.16.1
165 - host: 10.0.16.2
166 - host: 10.0.16.3
167 user: openstack
168 password: pwd
169 virtual_host: '/openstack'
170 ....
171
steluczdf5176a2018-01-17 14:42:11 +0100172Quota Options
173
174.. code-block:: yaml
175
176 glance:
177 server:
178 ....
179 quota:
180 image_member: -1
181 image_property: 256
182 image_tag: 256
183 image_location: 15
184 user_storage: 0
185 ....
186
Pavlo Shchelokovskyybc227572020-08-06 16:30:32 +0300187Maximum size of image
188
189.. code-block:: yaml
190
191 glance:
192 server:
193 ....
194 image_size_cap: 2199023255552 # 2TB, twice current default
195
Kirill Bespalovb5584362017-11-20 16:42:07 +0300196Configuring TLS communications
197------------------------------
Kirill Bespalov365d2432017-07-28 09:01:04 +0300198
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300199.. note:: By default, system wide installed CA certs are used, so
200 ``cacert_file`` param is optional, as well as ``cacert``.
Kirill Bespalovb5584362017-11-20 16:42:07 +0300201
202- **RabbitMQ TLS**
Kirill Bespalov365d2432017-07-28 09:01:04 +0300203
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300204 .. code-block:: yaml
Kirill Bespalov365d2432017-07-28 09:01:04 +0300205
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300206 glance:
207 server:
208 message_queue:
209 port: 5671
210 ssl:
211 enabled: True
212 (optional) cacert: cert body if the cacert_file does not exists
213 (optional) cacert_file: /etc/openstack/rabbitmq-ca.pem
214 (optional) version: TLSv1_2
Kirill Bespalov365d2432017-07-28 09:01:04 +0300215
Kirill Bespalovb5584362017-11-20 16:42:07 +0300216- **MySQL TLS**
Kirill Bespalov365d2432017-07-28 09:01:04 +0300217
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300218 .. code-block:: yaml
Kirill Bespalov365d2432017-07-28 09:01:04 +0300219
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300220 glance:
221 server:
222 database:
223 ssl:
224 enabled: True
225 (optional) cacert: cert body if the cacert_file does not exists
226 (optional) cacert_file: /etc/openstack/mysql-ca.pem
Kirill Bespalov365d2432017-07-28 09:01:04 +0300227
Kirill Bespalovb5584362017-11-20 16:42:07 +0300228- **Openstack HTTPS API**
229
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300230 Set the ``https`` as protocol at ``glance:server`` sections:
Kirill Bespalovb5584362017-11-20 16:42:07 +0300231
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300232 .. code-block:: yaml
Kirill Bespalov365d2432017-07-28 09:01:04 +0300233
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300234 glance:
235 server:
236 identity:
237 protocol: https
Kirill Bespalovb5584362017-11-20 16:42:07 +0300238 (optional) cacert_file: /etc/openstack/proxy.pem
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300239 registry:
240 protocol: https
241 (optional) cacert_file: /etc/openstack/proxy.pem
242 storage:
243 engine: cinder, swift
244 cinder:
245 protocol: https
246 (optional) cacert_file: /etc/openstack/proxy.pem
247 swift:
248 store:
249 (optional) cafile: /etc/openstack/proxy.pem
Kirill Bespalov365d2432017-07-28 09:01:04 +0300250
mnederlofad6d6242017-03-30 15:31:15 +0200251Enable Glance Image Cache:
252
253.. code-block:: yaml
254
255 glance:
256 server:
257 image_cache:
258 enabled: true
259 enable_management: true
260 directory: /var/lib/glance/image-cache/
261 max_size: 21474836480
262 ....
263
Aleš Komáreke5b388f2017-02-06 15:48:57 +0100264Enable auditing filter (CADF):
265
266.. code-block:: yaml
267
268 glance:
269 server:
270 audit:
271 enabled: true
272 ....
273 filter_factory: 'keystonemiddleware.audit:filter_factory'
274 map_file: '/etc/pycadf/glance_api_audit_map.conf'
275 ....
276
RobertJansen168e84f92017-03-30 15:45:12 +0200277Swift integration glance
278
279.. code-block:: yaml
280
281 glance:
282 server:
283 enabled: true
284 version: mitaka
285 storage:
286 engine: swift,http
287 swift:
288 store:
289 auth:
290 address: http://keystone.example.com:5000/v2.0
291 version: 2
292 endpoint_type: publicURL
293 container: glance
294 create_container_on_put: true
295 retry_get_count: 5
296 user: 2ec7966596504f59acc3a76b3b9d9291:glance-user
297 key: someRandomPassword
298
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300299Another way, which also supports multiple swift backends, can be
300configured like this:
Michel Nederlof3a867812017-05-15 09:46:11 +0200301
302.. code-block:: yaml
303
304 glance:
305 server:
306 enabled: true
307 version: mitaka
308 storage:
309 engine: swift,http
310 swift:
311 store:
312 endpoint_type: publicURL
313 container: glance
314 create_container_on_put: true
315 retry_get_count: 5
316 references:
317 my_objectstore_reference_1:
318 auth:
319 address: http://keystone.example.com:5000/v2.0
320 version: 2
321 user: 2ec7966596504f59acc3a76b3b9d9291:glance-user
322 key: someRandomPassword
323
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300324Enable CORS parameters:
Ondrej Smolae695fe82017-04-28 12:22:28 +0200325
326.. code-block:: yaml
327
328 glance:
329 server:
330 cors:
331 allowed_origin: https:localhost.local,http:localhost.local
332 expose_headers: X-Auth-Token,X-Openstack-Request-Id,X-Subject-Token
333 allow_methods: GET,PUT,POST,DELETE,PATCH
334 allow_headers: X-Auth-Token,X-Openstack-Request-Id,X-Subject-Token
335 allow_credentials: True
336 max_age: 86400
Aleš Komáreke5b388f2017-02-06 15:48:57 +0100337
Michel Nederlof3ad5aac2017-05-15 09:46:24 +0200338Enable Viewing Multiple Locations
339---------------------------------
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300340
Michel Nederlof3ad5aac2017-05-15 09:46:24 +0200341If you want to expose all locations available (for example when you have
342multiple backends configured), then you can configure this like so:
343
344.. code-block:: yaml
345
346 glance:
347 server:
348 show_multiple_locations: True
349 location_strategy: store_type
350 store_type_preference: rbd,swift,file
351
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300352.. note:: The ``show_multiple_locations`` option is deprecated since
353 Newton and is planned to be handled by policy files *only*
354 starting with the Pike release.
Michel Nederlof3ad5aac2017-05-15 09:46:24 +0200355
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300356This feature is convenient in a scenario when you have swift and rbd
357configured and want to benefit from rbd enhancements.
Michel Nederlof3ad5aac2017-05-15 09:46:24 +0200358
Oleg Iurchenko68ae3552017-10-13 18:40:42 +0300359Barbican integration glance
360---------------------------
361
362.. code-block:: yaml
363
364 glance:
365 server:
366 barbican:
367 enabled: true
368
sgarbuz2d39f412018-08-27 10:44:31 +0300369Adding cron-job
370---------------
371
372.. code-block:: yaml
373
374 glance:
375 server:
376 cron:
377 cache_pruner:
378 special_period: '@daily'
379 cache_cleaner:
380 hour: '5'
381 minute: '30'
Oleksandr Bryndziif87ae002019-04-24 13:20:57 +0300382 daymonth: '\*/2'
sgarbuz2d39f412018-08-27 10:44:31 +0300383
384
385Image cache settings
386--------------------
387
388.. code-block:: yaml
389
390 glance:
391 server:
392 image_cache:
393 max_size: 10737418240
394 stall_time: 86400
395 directory: '/var/lib/glance/image-cache/'
396
Oleg Iurchenko68ae3552017-10-13 18:40:42 +0300397
Richard Felkl4143a0e2017-02-01 23:24:13 +0100398Client role
399-----------
400
401Glance images
402
403.. code-block:: yaml
404
405 glance:
406 client:
407 enabled: true
408 server:
409 profile_admin:
410 image:
411 cirros-test:
412 visibility: public
413 protected: false
414 location: http://download.cirros-cloud.net/0.3.4/cirros-0.3.4-i386-disk.img
Jiri Konecny0456cfa2016-04-20 16:47:25 +0200415
Dmitry Kalashnikdd0d0282017-12-06 12:45:31 +0400416Enhanced logging with logging.conf
417----------------------------------
418
419By default logging.conf is disabled.
420
421That is possible to enable per-binary logging.conf with new variables:
Dmitry Kalashnikdd0d0282017-12-06 12:45:31 +0400422
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300423* ``openstack_log_appender``
424 Set to true to enable ``log_config_append`` for all OpenStack services
Dmitry Kalashnikdd0d0282017-12-06 12:45:31 +0400425
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300426* ``openstack_fluentd_handler_enabled``
427 Set to true to enable FluentHandler for all Openstack services
428
429* ``openstack_ossyslog_handler_enabled``
430 Set to true to enable OSSysLogHandler for all Openstack services
431
432Only ``WatchedFileHandler``, ``OSSysLogHandler``, and ``FluentHandler``
433are available.
434
435Also, it is possible to configure this with pillar:
Dmitry Kalashnikdd0d0282017-12-06 12:45:31 +0400436
437.. code-block:: yaml
438
439 glance:
440 server:
441 logging:
442 log_appender: true
443 log_handlers:
444 watchedfile:
445 enabled: true
446 fluentd:
447 enabled: true
Oleksii Chupryn90a2e642018-02-06 19:53:06 +0200448 ossyslog:
449 enabled: true
Aleš Komáreke5b388f2017-02-06 15:48:57 +0100450
Oleksandr Shyshko75e3d682018-09-07 14:07:57 +0300451Enable x509 and ssl communication between Glance and Galera cluster.
452---------------------
453By default communication between Glance and Galera is unsecure.
454
455glance:
456 server:
457 database:
458 x509:
459 enabled: True
460
461You able to set custom certificates in pillar:
462
463glance:
464 server:
465 database:
466 x509:
467 cacert: (certificate content)
468 cert: (certificate content)
469 key: (certificate content)
470
471You can read more about it here:
472 https://docs.openstack.org/security-guide/databases/database-access-control.html
473
Oleksandr Bryndziic69e8c82018-09-28 23:27:30 +0000474Glance services on controller node with memcached caching and security strategy:
475
476.. code-block:: yaml
477
478 glance:
479 server:
480 enabled: true
481 ...
482 cache:
483 engine: memcached
484 members:
485 - host: 127.0.0.1
486 port: 11211
487 - host: 127.0.0.1
488 port: 11211
489 security:
490 enabled: true
491 strategy: ENCRYPT
492 secret_key: secret
493
Oleksandr Bryndziidcf245d2018-10-24 19:10:05 +0300494Show all image locations when returning an image. This configuration option indicates
495whether to show all the image locations when returning image details to the user.
496
497.. code-block:: yaml
498
499 glance:
500 server:
501 enabled: true
502 ...
503 show_multiple_locations: True
504
Martin Polreich39511ef2019-12-17 10:49:01 +0100505Change default resource quotas using configmap template settings:
506-----------------------------------------------------------------
Oleksandr Bryndziif87ae002019-04-24 13:20:57 +0300507
508.. code-block:: yaml
509
510 glance:
511 server:
512 configmap:
513 glace_api:
514 DEFAULT:
Oleksandr Bryndziiea82e3d2019-05-15 12:18:30 +0300515 image_member_quota: 128
516 image_property_quota: 128
517 image_tag_quota: 128
518 image_location_quota: 10
519 user_storage_quota: 0
Oleksandr Bryndziif87ae002019-04-24 13:20:57 +0300520 glace_registry:
521 DEFAULT:
Oleksandr Bryndziiea82e3d2019-05-15 12:18:30 +0300522 image_member_quota: 128
523 image_property_quota: 128
524 image_tag_quota: 128
525 image_location_quota: 10
526 user_storage_quota: 0
Oleksandr Bryndziif87ae002019-04-24 13:20:57 +0300527
Martin Polreich39511ef2019-12-17 10:49:01 +0100528Change default service policy configuration:
529--------------------------------------------
530
531.. code-block:: yaml
532
533 glance:
534 server:
535 policy:
536 manage_image_cache: 'role:admin'
537 get_task: 'role:admin'
538 # Add key without value to remove line from policy.json
539 modify_member:
540
541
Aleš Komáreke5b388f2017-02-06 15:48:57 +0100542Usage
543=====
544
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300545#. Import new public image:
Jiri Konecny0456cfa2016-04-20 16:47:25 +0200546
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300547 .. code-block:: yaml
Jiri Konecny0456cfa2016-04-20 16:47:25 +0200548
Aleš Komáreke5b388f2017-02-06 15:48:57 +0100549 glance image-create --name 'Windows 7 x86_64' --is-public true --container-format bare --disk-format qcow2 < ./win7.qcow2
Jiri Konecny0456cfa2016-04-20 16:47:25 +0200550
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300551#. Change new image's disk properties
Petr Michalec86ec0142016-11-29 16:34:15 +0100552
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300553 .. code-block:: yaml
Petr Michalec86ec0142016-11-29 16:34:15 +0100554
Aleš Komáreke5b388f2017-02-06 15:48:57 +0100555 glance image-update "Windows 7 x86_64" --property hw_disk_bus=ide
Petr Michalec86ec0142016-11-29 16:34:15 +0100556
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300557#. Change new image's NIC properties
Jakub Pavlik80a41ea2016-03-06 14:33:42 +0100558
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300559 .. code-block:: yaml
Jakub Pavlik80a41ea2016-03-06 14:33:42 +0100560
Aleš Komáreke5b388f2017-02-06 15:48:57 +0100561 glance image-update "Windows 7 x86_64" --property hw_vif_model=rtl8139
Jakub Pavlik80a41ea2016-03-06 14:33:42 +0100562
Vasyl Saienko27185832018-09-10 10:36:00 +0000563Upgrades
564========
565
566Each openstack formula provide set of phases (logical bloks) that will help to
567build flexible upgrade orchestration logic for particular components. The list
568of phases and theirs descriptions are listed in table below:
569
570+-------------------------------+------------------------------------------------------+
571| State | Description |
572+===============================+======================================================+
573| <app>.upgrade.service_running | Ensure that all services for particular application |
574| | are enabled for autostart and running |
575+-------------------------------+------------------------------------------------------+
576| <app>.upgrade.service_stopped | Ensure that all services for particular application |
577| | disabled for autostart and dead |
578+-------------------------------+------------------------------------------------------+
579| <app>.upgrade.pkgs_latest | Ensure that packages used by particular application |
580| | are installed to latest available version. |
581| | This will not upgrade data plane packages like qemu |
582| | and openvswitch as usually minimal required version |
583| | in openstack services is really old. The data plane |
584| | packages should be upgraded separately by `apt-get |
585| | upgrade` or `apt-get dist-upgrade` |
586| | Applying this state will not autostart service. |
587+-------------------------------+------------------------------------------------------+
588| <app>.upgrade.render_config | Ensure configuration is rendered actual version. +
589+-------------------------------+------------------------------------------------------+
590| <app>.upgrade.pre | We assume this state is applied on all nodes in the |
591| | cloud before running upgrade. |
592| | Only non destructive actions will be applied during |
593| | this phase. Perform service built in service check |
594| | like (keystone-manage doctor and nova-status upgrade)|
595+-------------------------------+------------------------------------------------------+
596| <app>.upgrade.upgrade.pre | Mostly applicable for data plane nodes. During this |
597| | phase resources will be gracefully removed from |
598| | current node if it is allowed. Services for upgraded |
599| | application will be set to admin disabled state to |
600| | make sure node will not participate in resources |
601| | scheduling. For example on gtw nodes this will set |
602| | all agents to admin disable state and will move all |
603| | routers to other agents. |
604+-------------------------------+------------------------------------------------------+
605| <app>.upgrade.upgrade | This state will basically upgrade application on |
606| | particular target. Stop services, render |
607| | configuration, install new packages, run offline |
608| | dbsync (for ctl), start services. Data plane should |
609| | not be affected, only OpenStack python services. |
610+-------------------------------+------------------------------------------------------+
611| <app>.upgrade.upgrade.post | Add services back to scheduling. |
612+-------------------------------+------------------------------------------------------+
613| <app>.upgrade.post | This phase should be launched only when upgrade of |
614| | the cloud is completed. Cleanup temporary files, |
615| | perform other post upgrade tasks. |
616+-------------------------------+------------------------------------------------------+
617| <app>.upgrade.verify | Here we will do basic health checks (API CRUD |
618| | operations, verify do not have dead network |
619| | agents/compute services) |
620+-------------------------------+------------------------------------------------------+
621
Jiri Konecny0456cfa2016-04-20 16:47:25 +0200622
OlgaGusarenko87eb2842018-07-30 17:51:09 +0300623Read more
624==========
Filip Pytlound681ae22015-10-06 16:28:31 +0200625
626* http://ceph.com/docs/master/rbd/rbd-openstack/