openstack-manuals/doc/user-guide/hot/section_basic_resources.xml

<?xml version='1.0' encoding='UTF-8'?>
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="hot-basic-resources">
  <!--WARNING: This file is automatically generated. Do not edit it.-->
  <title>Instances</title>
  <!--For consistency let's define a few values to use in the samples:
* image name: ubuntu-trusty-x86_64
* shared/provider network name: "public"
* tenant network and subnet names: "private" and "private-subnet"-->
  <section xml:id="manage-instances">
    <?dbhtml stop-chunking?>
    <title>Manage instances</title>
    <section xml:id="create-an-instance">
      <title>Create an instance</title>
      <para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__Server.html">OS::Nova::Server</link></literal> resource to create a Compute instance. The
<literal>flavor</literal> property is the only mandatory one, but you need to define a boot
source using one of the <literal>image</literal> or <literal>block_device_mapping</literal> properties.</para>
      <para>You also need to define the <literal>networks</literal> property to indicate to which networks
your instance must connect if multiple networks are available in your tenant.</para>
      <para>The following example creates a simple instance, booted from an image, and
connecting to the <literal>private</literal> network:</para>
      <programlisting language="yaml">resources:
  instance:
    type: OS::Nova::Server
    properties:
      flavor: m1.small
      image: ubuntu-trusty-x86_64
      networks:
        - network: private</programlisting>
    </section>
    <section xml:id="connect-an-instance-to-a-network">
      <title>Connect an instance to a network</title>
      <para>Use the <literal>networks</literal> property of an <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__Server.html">OS::Nova::Server</link></literal> resource to
define which networks an instance should connect to. Define each network as a
YAML map, containing one of the following keys:</para>
      <variablelist role="definition_list">
        <varlistentry>
          <term>
            <literal>port</literal>
          </term>
          <listitem>
            <para>The ID of an existing Networking port. You usually create this port in the
same template using an <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Port.html">OS::Neutron::Port</link></literal> resource. You will be
able to associate a floating IP to this port, and the port to your Compute
instance.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <literal>network</literal>
          </term>
          <listitem>
            <para>The name or ID of an existing network. You don't need to create an
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Port.html">OS::Neutron::Port</link></literal> resource if you use this property, but you will
not be able to associate a floating IP with the instance interface in the
template.</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>The following example demonstrates the use of the <literal>port</literal> and <literal>network</literal>
properties:</para>
      <programlisting language="yaml">resources:
  instance_port:
    type: OS::Neutron::Port
    properties:
      network: private
      fixed_ips:
        - subnet_id: "private-subnet"

  instance1:
    type: OS::Nova::Server
    properties:
      flavor: m1.small
      image: ubuntu-trusty-x86_64
      networks:
        - port: { get_resource: instance_port }

  instance2:
    type: OS::Nova::Server
    properties:
      flavor: m1.small
      image: ubuntu-trusty-x86_64
      networks:
        - network: private</programlisting>
    </section>
    <section xml:id="create-and-associate-security-groups-to-an-instance">
      <title>Create and associate security groups to an instance</title>
      <para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__SecurityGroup.html">OS::Neutron::SecurityGroup</link></literal> resource to create security
groups.</para>
      <para>Define the <literal>security_groups</literal> property of the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Port.html">OS::Neutron::Port</link></literal>
resource to associate security groups to a port, then associate the port to an
instance.</para>
      <para>The following example creates a security group allowing inbound connections on
ports 80 and 443 (web server) and associates this security group to an instance
port:</para>
      <programlisting language="yaml">resources:
  web_secgroup:
    type: OS::Neutron::SecurityGroup
    properties:
      rules:
        - protocol: tcp
          remote_ip_prefix: 0.0.0.0/0
          port_range_min: 80
          port_range_max: 80
        - protocol: tcp
          remote_ip_prefix: 0.0.0.0/0
          port_range_min: 443
          port_range_max: 443

  instance_port:
    type: OS::Neutron::Port
    properties:
      network: private
      security_groups:
        - default
        - { get_resource: web_secgroup }
      fixed_ips:
        - subnet_id: private-subnet

  instance:
    type: OS::Nova::Server
    properties:
      flavor: m1.small
      image: ubuntu-trusty-x86_64
      networks:
        - port: { get_resource: instance_port }</programlisting>
    </section>
    <section xml:id="create-and-associate-a-floating-ip-to-an-instance">
      <title>Create and associate a floating IP to an instance</title>
      <para>You can use two sets of resources to create and associate floating IPs to
instances.</para>
      <section xml:id="os-nova-resources">
        <title>OS::Nova resources</title>
        <para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__FloatingIP.html">OS::Nova::FloatingIP</link></literal> resource to create a floating IP, and
the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__FloatingIPAssociation.html">OS::Nova::FloatingIPAssociation</link></literal> resource to associate the
floating IP to an instance.</para>
        <para>The following example creates an instance and a floating IP, and associate the
floating IP to the instance:</para>
        <programlisting language="yaml">resources:
  floating_ip:
    type: OS::Nova::FloatingIP
    properties:
      pool: public

  inst1:
    type: OS::Nova::Server
    properties:
      flavor: m1.small
      image: ubuntu-trusty-x86_64
      networks:
        - network: private

  association:
    type: OS::Nova::FloatingIPAssociation
    properties:
      - floating_ip: { get_resource: floating_ip }
      - server_id: { get_resource: instance }</programlisting>
      </section>
      <section xml:id="os-neutron-resources">
        <title>OS::Neutron resources</title>
        <note>
          <para>The Networking service (neutron) must be enabled on your OpenStack
deployment to use these resources.</para>
        </note>
        <para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__FloatingIP.html">OS::Neutron::FloatingIP</link></literal> resource to create a floating IP, and
the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__FloatingIPAssociation.html">OS::Neutron::FloatingIPAssociation</link></literal> resource to associate the
floating IP to a port:</para>
        <programlisting language="yaml">parameters:
  net:
    description: name of network used to launch instance.
    type: string
    default: private

resources:
  inst1:
    type: OS::Nova::Server
    properties:
      flavor: m1.small
      image: ubuntu-trusty-x86_64
      networks:
        - network: {get_param: net}

  floating_ip:
    type: OS::Neutron::FloatingIP
    properties:
      floating_network: public

  association:
    type: OS::Neutron::FloatingIPAssociation
    properties:
      floatingip_id: { get_resource: floating_ip }
      port_id: {get_attr: [inst1, addresses, {get_param: net}, 0, port]}</programlisting>
        <para>You can also create an OS::Neutron::Port and associate that with the server and
the floating IP. However the approach mentioned above will work better
with stack updates.</para>
        <programlisting language="yaml">resources:
  instance_port:
    type: OS::Neutron::Port
    properties:
      network: private
      fixed_ips:
        - subnet_id: "private-subnet"

  floating_ip:
    type: OS::Neutron::FloatingIP
    properties:
      floating_network: public

  association:
    type: OS::Neutron::FloatingIPAssociation
    properties:
      floatingip_id: { get_resource: floating_ip }
      port_id: { get_resource: instance_port }</programlisting>
      </section>
    </section>
    <section xml:id="enable-remote-access-to-an-instance">
      <title>Enable remote access to an instance</title>
      <para>The <literal>key_name</literal> attribute of the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__Server.html">OS::Nova::Server</link></literal> resource defines
the key pair to use to enable SSH remote access:</para>
      <programlisting language="yaml">resources:
  my_instance:
    type: OS::Nova::Server
    properties:
      flavor: m1.small
      image: ubuntu-trusty-x86_64
      key_name: my_key</programlisting>
      <note>
        <para>For more information about key pairs, see the <link xlink:href="http://docs.openstack.org/user-guide/content/cli_configure_instances.html">Configure access and
security for instances</link> section of the OpenStack user guide.</para>
      </note>
    </section>
    <section xml:id="create-a-key-pair">
      <title>Create a key pair</title>
      <para>You can create new key pairs with the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__KeyPair.html">OS::Nova::KeyPair</link></literal> resource. Key
pairs can be imported or created during the stack creation.</para>
      <para>If the <literal>public_key</literal> property is not specified, the Orchestration module
creates a new key pair. If the <literal>save_private_key</literal> property is set to
<literal>true</literal>, the <literal>private_key</literal> attribute of the resource holds the private key.</para>
      <para>The following example creates a new key pair and uses it as authentication key
for an instance:</para>
      <programlisting language="yaml">resources:
  my_key:
    type: OS::Nova::KeyPair
    properties:
      save_private_key: true

  my_instance:
    type: OS::Nova::Server
    properties:
      flavor: m1.small
      image: ubuntu-trusty-x86_64
      key_name: { get_resource: my_key }

outputs:
  private_key:
    description: Private key
    value: { get_attr: [ my_key, private_key ] }</programlisting>
    </section>
  </section>
  <section xml:id="manage-networks">
    <?dbhtml stop-chunking?>
    <title>Manage networks</title>
    <section xml:id="create-a-network-and-a-subnet">
      <title>Create a network and a subnet</title>
      <note>
        <para>The Networking service (neutron) must be enabled on your OpenStack
deployment to create and manage networks and subnets. Networks and subnets
cannot be created if your deployment uses legacy networking (nova-network).</para>
      </note>
      <para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Net.html">OS::Neutron::Net</link></literal> resource to create a network, and the
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Subnet.html">OS::Neutron::Subnet</link></literal> resource to provide a subnet for this network:</para>
      <programlisting language="yaml">resources:
  new_net:
    type: OS::Neutron::Net

  new_subnet:
    type: OS::Neutron::Subnet
    properties:
      network_id: { get_resource: new_net }
      cidr: "10.8.1.0/24"
      dns_nameservers: [ "8.8.8.8", "8.8.4.4" ]
      ip_version: 4</programlisting>
    </section>
    <section xml:id="create-and-manage-a-router">
      <title>Create and manage a router</title>
      <para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Router.html">OS::Neutron::Router</link></literal> resource to create a router. You can
define its gateway with the <literal>external_gateway_info</literal> property:</para>
      <programlisting language="yaml">resources:
  router1:
    type: OS::Neutron::Router
    properties:
      external_gateway_info: { network: public }</programlisting>
      <para>You can connect subnets to routers with the
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__RouterInterface.html">OS::Neutron::RouterInterface</link></literal> resource:</para>
      <programlisting language="yaml">resources:
  subnet1_interface:
    type: OS::Neutron::RouterInterface
    properties:
      router_id: { get_resource: router1 }
      subnet: private-subnet</programlisting>
    </section>
    <section xml:id="complete-network-example">
      <title>Complete network example</title>
      <para>The following example creates a network stack:</para>
      <itemizedlist>
        <listitem>
          <para>A network and an associated subnet.</para>
        </listitem>
        <listitem>
          <para>A router with an external gateway.</para>
        </listitem>
        <listitem>
          <para>An interface to the new subnet for the new router.</para>
        </listitem>
      </itemizedlist>
      <para>In this example, the <literal>public</literal> network is an existing shared network:</para>
      <programlisting language="yaml">resources:
  internal_net:
    type: OS::Neutron::Net

  internal_subnet:
    type: OS::Neutron::Subnet
    properties:
      network_id: { get_resource: internal_net }
      cidr: "10.8.1.0/24"
      dns_nameservers: [ "8.8.8.8", "8.8.4.4" ]
      ip_version: 4

  internal_router:
    type: OS::Neutron::Router
    properties:
      external_gateway_info: { network: public }

  internal_interface:
    type: OS::Neutron::RouterInterface
    properties:
      router_id: { get_resource: internal_router }
      subnet: { get_resource: internal_subnet }</programlisting>
    </section>
  </section>
  <section xml:id="manage-volumes">
    <?dbhtml stop-chunking?>
    <title>Manage volumes</title>
    <section xml:id="create-a-volume">
      <title>Create a volume</title>
      <para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Cinder__Volume.html">OS::Cinder::Volume</link></literal> resource to create a new Block Storage
volume.</para>
      <para>For example:</para>
      <programlisting language="yaml">resources:
  my_new_volume:
    type: OS::Cinder::Volume
    properties:
      size: 10</programlisting>
      <para>The volumes that you create are empty by default. Use the <literal>image</literal> property to
create a bootable volume from an existing image:</para>
      <programlisting language="yaml">resources:
  my_new_bootable_volume:
    type: OS::Cinder::Volume
    properties:
      size: 10
      image: ubuntu-trusty-x86_64</programlisting>
      <para>You can also create new volumes from another volume, a volume snapshot, or a
volume backup. Use the <literal>source_volid</literal>, <literal>snapshot_id</literal> or <literal>backup_id</literal>
properties to create a new volume from an existing source.</para>
      <para>For example, to create a new volume from a backup:</para>
      <programlisting language="yaml">resources:
  another_volume:
    type: OS::Cinder::Volume
    properties:
      backup_id: 2fff50ab-1a9c-4d45-ae60-1d054d6bc868</programlisting>
      <para>In this example the <literal>size</literal> property is not defined because the Block Storage
service uses the size of the backup to define the size of the new volume.</para>
    </section>
    <section xml:id="attach-a-volume-to-an-instance">
      <title>Attach a volume to an instance</title>
      <para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Cinder__VolumeAttachment.html">OS::Cinder::VolumeAttachment</link></literal> resource to attach a volume to
an instance.</para>
      <para>The following example creates a volume and an instance, and attaches the volume
to the instance:</para>
      <programlisting language="yaml">resources:
  new_volume:
    type: OS::Cinder::Volume
    properties:
      size: 1

  new_instance:
    type: OS::Nova::Server
    properties:
      flavor: m1.small
      image: ubuntu-trusty-x86_64

  volume_attachment:
    type: OS::Cinder::VolumeAttachment
    properties:
      volume_id: { get_resource: new_volume }
      instance_uuid: { get_resource: new_instance }</programlisting>
    </section>
    <section xml:id="boot-an-instance-from-a-volume">
      <title>Boot an instance from a volume</title>
      <para>Use the <literal>block_device_mapping</literal> property of the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__Server.html">OS::Nova::Server</link></literal>
resource to define a volume used to boot the instance. This property is a list
of volumes to attach to the instance before its boot.</para>
      <para>The following example creates a bootable volume from an image, and uses it to
boot an instance:</para>
      <programlisting language="yaml">resources:
  bootable_volume:
    type: OS::Cinder::Volume
    properties:
      size: 10
      image: ubuntu-trusty-x86_64

  instance:
    type: OS::Nova::Server
    properties:
      flavor: m1.small
      networks:
        - network: private
      block_device_mapping:
        - device_name: vda
          volume_id: { get_resource: bootable_volume }
          delete_on_termination: false</programlisting>
      <!--TODO

A few elements that probably belong here:
- OS::Swift::Container
- OS::Trove::Instance-->
    </section>
  </section>
</section>