← Back to branch summary

~ubuntu-branches/ubuntu/wily/heat/wily

« back to all changes in this revision

Viewing changes to doc/source/template_guide/basic_resources.rst

  • Committer: Package Import Robot
  • Author(s): Corey Bryant
  • Date: 2015-08-19 08:11:50 UTC
  • mfrom: (1.1.27)
  • Revision ID: package-import@ubuntu.com-20150819081150-m969fd35xn8bdmfu
Tags: 1:5.0.0~b2-0ubuntu1
* New upstream milestone for OpenStack Liberty.
* d/control: Align (build-)depends with upstream.
* d/p/fix-requirements.patch: Dropped. No longer needed.
* d/p/fixup-assert-regex.patch: Rebased.
* d/rules: Remove .eggs directory in override_dh_auto_clean.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/source/template_guide/basic_resources.rst
 
1
.. highlight: yaml
 
2
   :linenothreshold: 5
 
3
 
 
4
.. _basic_resources:
 
5
 
 
6
=========
 
7
Instances
 
8
=========
 
9
 
 
10
..  For consistency let's define a few values to use in the samples:
 
11
    * image name: ubuntu-trusty-x86_64
 
12
    * shared/provider network name: "public"
 
13
    * tenant network and subnet names: "private" and "private-subnet"
 
14
 
 
15
Manage instances
 
16
~~~~~~~~~~~~~~~~
 
17
 
 
18
Create an instance
 
19
------------------
 
20
Use the :ref:`OS::Nova::Server` resource to create a Compute instance. The
 
21
``flavor`` property is the only mandatory one, but you need to define a boot
 
22
source using one of the ``image`` or ``block_device_mapping`` properties.
 
23
 
 
24
You also need to define the ``networks`` property to indicate to which networks
 
25
your instance must connect if multiple networks are available in your tenant.
 
26
 
 
27
The following example creates a simple instance, booted from an image, and
 
28
connecting to the ``private`` network:
 
29
 
 
30
.. code-block:: yaml
 
31
   :linenos:
 
32
 
 
33
    resources:
 
34
      instance:
 
35
        type: OS::Nova::Server
 
36
        properties:
 
37
          flavor: m1.small
 
38
          image: ubuntu-trusty-x86_64
 
39
          networks:
 
40
            - network: private
 
41
 
 
42
 
 
43
Connect an instance to a network
 
44
--------------------------------
 
45
Use the ``networks`` property of an :ref:`OS::Nova::Server` resource to
 
46
define which networks an instance should connect to. Define each network as a
 
47
YAML map, containing one of the following keys:
 
48
 
 
49
``port``
 
50
    The ID of an existing Networking port. You usually create this port in the
 
51
    same template using an :ref:`OS::Neutron::Port` resource. You will be
 
52
    able to associate a floating IP to this port, and the port to your Compute
 
53
    instance.
 
54
 
 
55
``network``
 
56
    The name or ID of an existing network. You don't need to create an
 
57
    :ref:`OS::Neutron::Port` resource if you use this property, but you will
 
58
    not be able to associate a floating IP with the instance interface in the
 
59
    template.
 
60
 
 
61
The following example demonstrates the use of the ``port`` and ``network``
 
62
properties:
 
63
 
 
64
.. code-block:: yaml
 
65
   :linenos:
 
66
 
 
67
    resources:
 
68
      instance_port:
 
69
        type: OS::Neutron::Port
 
70
        properties:
 
71
          network: private
 
72
          fixed_ips:
 
73
            - subnet_id: "private-subnet"
 
74
 
 
75
      instance1:
 
76
        type: OS::Nova::Server
 
77
        properties:
 
78
          flavor: m1.small
 
79
          image: ubuntu-trusty-x86_64
 
80
          networks:
 
81
            - port: { get_resource: instance_port }
 
82
 
 
83
      instance2:
 
84
        type: OS::Nova::Server
 
85
        properties:
 
86
          flavor: m1.small
 
87
          image: ubuntu-trusty-x86_64
 
88
          networks:
 
89
            - network: private
 
90
 
 
91
 
 
92
Create and associate security groups to an instance
 
93
---------------------------------------------------
 
94
Use the :ref:`OS::Neutron::SecurityGroup` resource to create security
 
95
groups.
 
96
 
 
97
Define the ``security_groups`` property of the :ref:`OS::Neutron::Port`
 
98
resource to associate security groups to a port, then associate the port to an
 
99
instance.
 
100
 
 
101
The following example creates a security group allowing inbound connections on
 
102
ports 80 and 443 (web server) and associates this security group to an instance
 
103
port:
 
104
 
 
105
.. code-block:: yaml
 
106
   :linenos:
 
107
 
 
108
    resources:
 
109
      web_secgroup:
 
110
        type: OS::Neutron::SecurityGroup
 
111
        properties:
 
112
          rules:
 
113
            - protocol: tcp
 
114
              remote_ip_prefix: 0.0.0.0/0
 
115
              port_range_min: 80
 
116
              port_range_max: 80
 
117
            - protocol: tcp
 
118
              remote_ip_prefix: 0.0.0.0/0
 
119
              port_range_min: 443
 
120
              port_range_max: 443
 
121
 
 
122
      instance_port:
 
123
        type: OS::Neutron::Port
 
124
        properties:
 
125
          network: private
 
126
          security_groups:
 
127
            - default
 
128
            - { get_resource: web_secgroup }
 
129
          fixed_ips:
 
130
            - subnet_id: private-subnet
 
131
 
 
132
      instance:
 
133
        type: OS::Nova::Server
 
134
        properties:
 
135
          flavor: m1.small
 
136
          image: ubuntu-trusty-x86_64
 
137
          networks:
 
138
            - port: { get_resource: instance_port }
 
139
 
 
140
 
 
141
Create and associate a floating IP to an instance
 
142
-------------------------------------------------
 
143
You can use two sets of resources to create and associate floating IPs to
 
144
instances.
 
145
 
 
146
OS::Nova resources
 
147
++++++++++++++++++
 
148
Use the :ref:`OS::Nova::FloatingIP` resource to create a floating IP, and
 
149
the :ref:`OS::Nova::FloatingIPAssociation` resource to associate the
 
150
floating IP to an instance.
 
151
 
 
152
The following example creates an instance and a floating IP, and associate the
 
153
floating IP to the instance:
 
154
 
 
155
.. code-block:: yaml
 
156
   :linenos:
 
157
 
 
158
    resources:
 
159
      floating_ip:
 
160
        type: OS::Nova::FloatingIP
 
161
        properties:
 
162
          pool: public
 
163
 
 
164
      inst1:
 
165
        type: OS::Nova::Server
 
166
        properties:
 
167
          flavor: m1.small
 
168
          image: ubuntu-trusty-x86_64
 
169
          networks:
 
170
            - network: private
 
171
 
 
172
      association:
 
173
        type: OS::Nova::FloatingIPAssociation
 
174
        properties:
 
175
          floating_ip: { get_resource: floating_ip }
 
176
          server_id: { get_resource: instance }
 
177
 
 
178
OS::Neutron resources
 
179
+++++++++++++++++++++
 
180
.. note::
 
181
   The Networking service (neutron) must be enabled on your OpenStack
 
182
   deployment to use these resources.
 
183
 
 
184
Use the :ref:`OS::Neutron::FloatingIP` resource to create a floating IP, and
 
185
the :ref:`OS::Neutron::FloatingIPAssociation` resource to associate the
 
186
floating IP to a port:
 
187
 
 
188
.. code-block:: yaml
 
189
   :linenos:
 
190
 
 
191
    parameters:
 
192
      net:
 
193
        description: name of network used to launch instance.
 
194
        type: string
 
195
        default: private
 
196
 
 
197
    resources:
 
198
      inst1:
 
199
        type: OS::Nova::Server
 
200
        properties:
 
201
          flavor: m1.small
 
202
          image: ubuntu-trusty-x86_64
 
203
          networks:
 
204
            - network: {get_param: net}
 
205
 
 
206
      floating_ip:
 
207
        type: OS::Neutron::FloatingIP
 
208
        properties:
 
209
          floating_network: public
 
210
 
 
211
      association:
 
212
        type: OS::Neutron::FloatingIPAssociation
 
213
        properties:
 
214
          floatingip_id: { get_resource: floating_ip }
 
215
          port_id: {get_attr: [inst1, addresses, {get_param: net}, 0, port]}
 
216
 
 
217
You can also create an OS::Neutron::Port and associate that with the server and
 
218
the floating IP. However the approach mentioned above will work better
 
219
with stack updates.
 
220
 
 
221
.. code-block:: yaml
 
222
   :linenos:
 
223
 
 
224
    resources:
 
225
      instance_port:
 
226
        type: OS::Neutron::Port
 
227
        properties:
 
228
          network: private
 
229
          fixed_ips:
 
230
            - subnet_id: "private-subnet"
 
231
 
 
232
      floating_ip:
 
233
        type: OS::Neutron::FloatingIP
 
234
        properties:
 
235
          floating_network: public
 
236
 
 
237
      association:
 
238
        type: OS::Neutron::FloatingIPAssociation
 
239
        properties:
 
240
          floatingip_id: { get_resource: floating_ip }
 
241
          port_id: { get_resource: instance_port }
 
242
 
 
243
Enable remote access to an instance
 
244
-----------------------------------
 
245
The ``key_name`` attribute of the :ref:`OS::Nova::Server` resource defines
 
246
the key pair to use to enable SSH remote access:
 
247
 
 
248
.. code-block:: yaml
 
249
   :linenos:
 
250
 
 
251
    resources:
 
252
      my_instance:
 
253
        type: OS::Nova::Server
 
254
        properties:
 
255
          flavor: m1.small
 
256
          image: ubuntu-trusty-x86_64
 
257
          key_name: my_key
 
258
 
 
259
.. note::
 
260
   For more information about key pairs, see
 
261
   `Configure access and security for instances <http://docs.openstack.org/user-guide/configure_access_and_security_for_instances.html>`_.
 
262
 
 
263
Create a key pair
 
264
-----------------
 
265
You can create new key pairs with the :ref:`OS::Nova::KeyPair` resource. Key
 
266
pairs can be imported or created during the stack creation.
 
267
 
 
268
If the ``public_key`` property is not specified, the Orchestration module
 
269
creates a new key pair. If the ``save_private_key`` property is set to
 
270
``true``, the ``private_key`` attribute of the resource holds the private key.
 
271
 
 
272
The following example creates a new key pair and uses it as authentication key
 
273
for an instance:
 
274
 
 
275
.. code-block:: yaml
 
276
   :linenos:
 
277
 
 
278
    resources:
 
279
      my_key:
 
280
        type: OS::Nova::KeyPair
 
281
        properties:
 
282
          save_private_key: true
 
283
          name: my_key
 
284
 
 
285
      my_instance:
 
286
        type: OS::Nova::Server
 
287
        properties:
 
288
          flavor: m1.small
 
289
          image: ubuntu-trusty-x86_64
 
290
          key_name: { get_resource: my_key }
 
291
 
 
292
    outputs:
 
293
      private_key:
 
294
        description: Private key
 
295
        value: { get_attr: [ my_key, private_key ] }
 
296
 
 
297
Manage networks
 
298
~~~~~~~~~~~~~~~
 
299
Create a network and a subnet
 
300
-----------------------------
 
301
.. note::
 
302
    The Networking service (neutron) must be enabled on your OpenStack
 
303
    deployment to create and manage networks and subnets. Networks and subnets
 
304
    cannot be created if your deployment uses legacy networking (nova-network).
 
305
 
 
306
Use the :ref:`OS::Neutron::Net` resource to create a network, and the
 
307
:ref:`OS::Neutron::Subnet` resource to provide a subnet for this network:
 
308
 
 
309
.. code-block:: yaml
 
310
   :linenos:
 
311
 
 
312
    resources:
 
313
      new_net:
 
314
        type: OS::Neutron::Net
 
315
 
 
316
      new_subnet:
 
317
        type: OS::Neutron::Subnet
 
318
        properties:
 
319
          network_id: { get_resource: new_net }
 
320
          cidr: "10.8.1.0/24"
 
321
          dns_nameservers: [ "8.8.8.8", "8.8.4.4" ]
 
322
          ip_version: 4
 
323
 
 
324
 
 
325
Create and manage a router
 
326
--------------------------
 
327
Use the :ref:`OS::Neutron::Router` resource to create a router. You can
 
328
define its gateway with the ``external_gateway_info`` property:
 
329
 
 
330
.. code-block:: yaml
 
331
   :linenos:
 
332
 
 
333
    resources:
 
334
      router1:
 
335
        type: OS::Neutron::Router
 
336
        properties:
 
337
          external_gateway_info: { network: public }
 
338
 
 
339
You can connect subnets to routers with the
 
340
:ref:`OS::Neutron::RouterInterface` resource:
 
341
 
 
342
.. code-block:: yaml
 
343
   :linenos:
 
344
 
 
345
    resources:
 
346
      subnet1_interface:
 
347
        type: OS::Neutron::RouterInterface
 
348
        properties:
 
349
          router_id: { get_resource: router1 }
 
350
          subnet: private-subnet
 
351
 
 
352
 
 
353
Complete network example
 
354
------------------------
 
355
The following example creates a network stack:
 
356
 
 
357
* A network and an associated subnet.
 
358
* A router with an external gateway.
 
359
* An interface to the new subnet for the new router.
 
360
 
 
361
In this example, the ``public`` network is an existing shared network:
 
362
 
 
363
.. code-block:: yaml
 
364
   :linenos:
 
365
 
 
366
    resources:
 
367
      internal_net:
 
368
        type: OS::Neutron::Net
 
369
 
 
370
      internal_subnet:
 
371
        type: OS::Neutron::Subnet
 
372
        properties:
 
373
          network_id: { get_resource: internal_net }
 
374
          cidr: "10.8.1.0/24"
 
375
          dns_nameservers: [ "8.8.8.8", "8.8.4.4" ]
 
376
          ip_version: 4
 
377
 
 
378
      internal_router:
 
379
        type: OS::Neutron::Router
 
380
        properties:
 
381
          external_gateway_info: { network: public }
 
382
 
 
383
      internal_interface:
 
384
        type: OS::Neutron::RouterInterface
 
385
        properties:
 
386
          router_id: { get_resource: internal_router }
 
387
          subnet: { get_resource: internal_subnet }
 
388
 
 
389
 
 
390
Manage volumes
 
391
~~~~~~~~~~~~~~
 
392
Create a volume
 
393
---------------
 
394
Use the :ref:`OS::Cinder::Volume` resource to create a new Block Storage
 
395
volume.
 
396
 
 
397
For example:
 
398
 
 
399
.. code-block:: yaml
 
400
   :linenos:
 
401
 
 
402
    resources:
 
403
      my_new_volume:
 
404
        type: OS::Cinder::Volume
 
405
        properties:
 
406
          size: 10
 
407
 
 
408
The volumes that you create are empty by default. Use the ``image`` property to
 
409
create a bootable volume from an existing image:
 
410
 
 
411
.. code-block:: yaml
 
412
   :linenos:
 
413
 
 
414
    resources:
 
415
      my_new_bootable_volume:
 
416
        type: OS::Cinder::Volume
 
417
        properties:
 
418
          size: 10
 
419
          image: ubuntu-trusty-x86_64
 
420
 
 
421
 
 
422
You can also create new volumes from another volume, a volume snapshot, or a
 
423
volume backup. Use the ``source_volid``, ``snapshot_id`` or ``backup_id``
 
424
properties to create a new volume from an existing source.
 
425
 
 
426
For example, to create a new volume from a backup:
 
427
 
 
428
.. code-block:: yaml
 
429
   :linenos:
 
430
 
 
431
    resources:
 
432
      another_volume:
 
433
        type: OS::Cinder::Volume
 
434
        properties:
 
435
          backup_id: 2fff50ab-1a9c-4d45-ae60-1d054d6bc868
 
436
 
 
437
In this example the ``size`` property is not defined because the Block Storage
 
438
service uses the size of the backup to define the size of the new volume.
 
439
 
 
440
Attach a volume to an instance
 
441
------------------------------
 
442
Use the :ref:`OS::Cinder::VolumeAttachment` resource to attach a volume to
 
443
an instance.
 
444
 
 
445
The following example creates a volume and an instance, and attaches the volume
 
446
to the instance:
 
447
 
 
448
.. code-block:: yaml
 
449
   :linenos:
 
450
 
 
451
    resources:
 
452
      new_volume:
 
453
        type: OS::Cinder::Volume
 
454
        properties:
 
455
          size: 1
 
456
 
 
457
      new_instance:
 
458
        type: OS::Nova::Server
 
459
        properties:
 
460
          flavor: m1.small
 
461
          image: ubuntu-trusty-x86_64
 
462
 
 
463
      volume_attachment:
 
464
        type: OS::Cinder::VolumeAttachment
 
465
        properties:
 
466
          volume_id: { get_resource: new_volume }
 
467
          instance_uuid: { get_resource: new_instance }
 
468
 
 
469
Boot an instance from a volume
 
470
------------------------------
 
471
Use the ``block_device_mapping`` property of the :ref:`OS::Nova::Server`
 
472
resource to define a volume used to boot the instance. This property is a list
 
473
of volumes to attach to the instance before its boot.
 
474
 
 
475
The following example creates a bootable volume from an image, and uses it to
 
476
boot an instance:
 
477
 
 
478
.. code-block:: yaml
 
479
   :linenos:
 
480
 
 
481
    resources:
 
482
      bootable_volume:
 
483
        type: OS::Cinder::Volume
 
484
        properties:
 
485
          size: 10
 
486
          image: ubuntu-trusty-x86_64
 
487
 
 
488
      instance:
 
489
        type: OS::Nova::Server
 
490
        properties:
 
491
          flavor: m1.small
 
492
          networks:
 
493
            - network: private
 
494
          block_device_mapping:
 
495
            - device_name: vda
 
496
              volume_id: { get_resource: bootable_volume }
 
497
              delete_on_termination: false
 
498
 
 
499
.. TODO
 
500
  A few elements that probably belong here:
 
501
  - OS::Swift::Container
 
502
  - OS::Trove::Instance