Orchestration v2 Attributes for Instance

Instance Attributes

Instances have a number of required and optional attributes. The following sample JSON shows some of the key instance attributes. A description of each of the required and optional instance attributes is provided in the table below.

{
          "instances": 
      [
            {
              "shape": "oc3",
              "boot_order": [1],
              "label": "vm-1",
              "networking":{
                  "eth0":   {
                    "seclists": ["/Compute-acme/joe/wlsadmin_seclist"],
                    "nat": "ipreservation:/Compute-acme/joe/ipres1"
                             },
                  "eth1" :   {
                    "ipnetwork" : "/Compute-acme/joe/ipnet1",
                    "ip": "192.168.4.2",
                    "vnic": "/Compute-acme/joe/eth1-ipnet1"
                             }
			                    },
              "sshkeys": ["/Compute-acme/joe/key1"],
              "relationships": [
                      "type": "different_node",
                      "instances": ["instance:/Compute-acme/jack.jones@example.com/instance1"]  
        ]
              "storage_attachments": 
                    [
                      {
                  "index": 1,
                  "volume": "/Compute-acme/joe/boot"
                       }
                    ]
            }
       ]
 }
Parameter Required or Optional Description

shape

required

The name of the shape that defines the number of OCPUs and the RAM that you require for the instance. For general purpose and high-memory shapes, you can select the block storage disk size, but for high I/O shapes, the size of the SSD storage is determined by the shape.

name

optional

The three-part name of the instance (/Compute-identity_domain/user/name).

If you specify this parameter, then the full name of the instance would be in the format, /Compute-identity_domain/user/name_you_specify/id.

If you don’t specify this parameter, then the full name would be in the format, /Compute-identity_domain/user/id.

In either case, id is an autogenerated ID.

Examples of Instance Names:

  • When you specify /Compute-acme/jack/vm1 as the value of the name parameter:

    /Compute-acme/jack/vm1/300a7479-ec90-4826-98b9-a725662628f1

  • When you don’t specify the name parameter:

    /Compute-acme/jack/38ef677e-9e13-41a7-a40c-2d99afce1714

Although this is an optional parameter, specifying a meaningful name makes it easier for you to identify your instances.

label

optional

A text string to identify the instance.

This label is used when defining relationships in an orchestration.

tags

optional

A JSON array or list of strings used to tag the instance.

By assigning a human-friendly tag to an instance, you can identify the instance easily when you perform an instance listing. These tags aren’t available from within the instance.

desired_state

optional

The only allowed values are running or shutdown. If you specify running, the instance is started. If you specify shutdown, the instance is stopped. You can start the instance again later by updating the instance with the desired_state specified as running.

attributes

optional

A JSON object or dictionary of user-defined attributes to be made available to the instance.

If you’re creating a Windows instance, you must specify the following required attributes:
{
          "enable_rdp": true,
          "administrator_password": "Specify_password_here"
  }

For more information about specifying user-defined attributes that can be used to automate instance configuration, see Automating Instance Initialization Using opc-init.

Note:

Solaris machine images don’t include the opc-init scripts. So you can’t use opc-init to automate instance configuration of Solaris instances.

The attributes that you specify can be accessed from within the instance at http://192.0.0.192/latest/attributes. For more information about retrieving user-defined attributes, see Retrieving User-Defined Instance Attributes.

imagelist

optional

The three-part name (oracle/public/imagelist_name) of the image list containing the image to be used (example: /oracle/public/OL_6.7_UEKR4_x86_64).

You must use this attribute if you don’t specify a bootable storage volume by using the boot_order attribute. If you specify the imagelist attribute as well as the boot_order attribute, then the imagelist attribute is ignored.

storage_attachments

optional

If you specify the storage_attachments parameter, then specify the following subparameters for each attachment:

  • volume: The three-part name (/Compute-identity_domain/user/object_name) of the storage volume that you want to attach to the instance.

    Note that volumes attached to an instance at launch time can't be detached.

  • index: The index number for the volume.

    The allowed range is 1 to 10. If you want to use a storage volume as the boot disk for an instance, you must specify the index number for that volume as 1.

    The index determines the device name by which the volume is exposed to the instance. Index 0 is allocated to a nonpersistent boot disk, /dev/xvda. An attachment with index 1 is exposed to the instance as /dev/xvdb, an attachment with index 2 is exposed as /dev/xvdc, and so on.

boot_order

optional

The index number of the bootable storage volume that should be used to boot the instance. The only valid value is 1.

If you set this attribute, you must also specify a bootable storage volume with index number 1 in the volume sub-parameter of storage_attachments.

When you specify boot_order, you don’t need to specify the imagelist attribute, because the instance is booted using the image on the specified bootable storage volume. If you specify both boot_order and imagelist, the imagelist attribute is ignored.

hostname

optional

The host name assigned to the instance. On an Oracle Linux instance, this host name is displayed in response to the hostname command.

Only relative DNS is supported. The domain name is suffixed to the host name that you specify. The host name must not end with a period. If you don’t specify a host name, then a name is generated automatically. The DNS name of an instance depends on its host name, as follows:

  • If no DNS name is specified in the networking attribute, then the DNS name is set to the host name, and a reverse DNS record (PTR) is created for the host name.

  • If the DNS name specified in the networking attribute matches the host name, then that record also creates a reverse DNS record for the host name.

  • If the dns attribute under networking is set to an empty list ([]), then no DNS records are created even if a host name is specified. The instance still receives its host name through DHCP, and can perform a reverse lookup of its host name. However, no other instance can perform this reverse lookup.

Note:

If an instance has network interfaces defined only for IP networks and doesn’t have any interface on the shared network, then when hostname is specified, no DNS entries are set. In this case, DNS entries are set by the dns subparameter of the networking attribute.

reverse_dns

optional

If set to true (default), then reverse DNS records are created.

If set to false, no reverse DNS records are created.

networking (attributes for the shared network)

optional

ethn: The interface that you’re defining. Oracle-provided images with release version 16.3.6 and later support eight vNICs. You can also create private images that support multiple vNICs. If the image you’ve specified supports eight vNICs, then you can specify up to eight network interfaces, from eth0 to eth7.

Note:

For each interface, you can specify parameters for either the shared network, or for an IP network. You can’t specify parameters for both networks for the same ethn interface.

Only one interface on an instance can be added to the shared network. To add an interface to the shared network, you can specify the following subparameters:

  • seclists: (Optional) The security lists that you want to add the instance to.

  • nat: (Optional) Indicates whether a temporary or permanent public IP address should be assigned to the instance.

  • dns: (Optional) A list of the DNS A record names for the instance. This name is relative to the internal DNS domain.

  • model: (Optional) The type of network interface card (NIC). The only allowed value is e1000.

  • name_servers: (Optional) The name servers that are sent through DHCP as option 6.  You can specify a maximum of eight name server IP addresses per interface.

  • search_domains: (Optional) The search domains that should be sent through DHCP as option 119.  You can enter a maximum of eight search domain zones per interface.

For more information about each of these subparameters, see Subparameters for a Network Interface on the Shared Network.

networking (attributes for IP networks)

optional

ethn: The interface that you’re defining. Oracle-provided images with release version 16.3.6 and later support eight vNICs. You can also create private images that support multiple vNICs. If the image you’ve specified supports eight vNICs, then you can specify up to eight network interfaces, from eth0 to eth7.

Note:

For each interface, you can specify parameters for either the shared network, or for an IP network. You can’t specify parameters for both networks for the same ethn interface.

To add an interface to an IP network, specify the following subparameters:

  • ipnetwork: The name of the IP network that you want to add the instance to.

  • ip: (Optional) If you want to associate a static private IP address with the instance, specify an available IP address from the IP address range of the specified ipnetwork.

  • address: (Optional) The MAC address of the interface, in hexadecimal format, where each digit is separated by colon. For example, you can enter 01:02:03:04:ab:cd as the MAC address but not 01-02-03-04-ab-cd.

  • nat: (Optional) A list of IP reservation that you want to associate with this interface, in the format: "nat": ["network/v1/ipreservation:IP_reservation_name"].

    Here IP_reservation_name is the three-part name of the IP reservation in the /Compute-identity_domain/user/object_name format.

  • vnic: (Optional) The three-part name of the vNIC in the /Compute-identity_domain/user/object_name format.

  • vnicsets: (Optional) A list of the three-part names of the vNICsets that you want to add this interface to.

  • is_default_gateway: (Optional) If you want to specify the interface to be used as the default gateway for all traffic, set this to true. The default is false. If the instance has an interface on the shared network, that interface is always used as the default gateway.

  • dns: (Optional) A list of the DNS A record names for the instance.

  • name_servers: (Optional) A list of the name servers that should be sent through DHCP as option 6.  You can specify a maximum of eight name server IP addresses per interface.

  • search_domains: (Optional) A list of the search domains that should be sent through DHCP as option 119.  You can enter a maximum of eight search domain zones per interface.

For more information about each of these subparameters, see Subparameters for a Network Interface on an IP Network.

relationships

optional

You can also define relationships to indicate that you want the specified instances to be created on the same or different physical server.

  • Relationship: same_node

    The same_node relationship indicates that you want the specified instances to be created on the same physical server. This is useful if you want to ensure low latency across instances.

    Example: to ensure that instance1 is created on the same physical server.

    "relationships": [
      {
        "type": "same_node",
        "instances": [ "instance:/Compute-acme/jack.jones@example.com/instance1"]
    	}
    ]
  • Relationship: different_node

    The different_node relationship indicates that you do not want the specified instances to be created on the same physical server. This is useful if you want to isolate instances for security or redundancy.

    Example: to ensure that instance1 is not created on the same physical server.

    "relationships": [
      {
        "type": "different_node",
        "instances": [ "instance:/Compute-acme/jack.jones@example.com/instance1"]
    	}
    ]

sshkeys

optional

A list of the SSH public keys that you want to associate with the instance.

Note:

You don’t need to provide any SSH public keys if you’re creating a Windows instance, because you can’t access a Windows instance using SSH. To access a Windows instance, see Accessing a Windows Instance Using RDP.

For each key, specify the three-part name in the /Compute-identity_domain/user/object_name format.

You can associate the same key with multiple instances.

The keys that you specify are stored as metadata on the instance. This metadata can be accessed from within the instance at http://192.0.0.192/{version}/meta-data/public-keys/{index}/openssh-key.
  • Oracle-provided images include a script that runs automatically when the instance starts, retrieves the keys, and adds them to the authorized_keys file of the opc user.

  • In images that you build, you can write and include a script that runs automatically when the instance starts, retrieves the SSH public keys, and adds the keys to the authorized_keys file of the appropriate users.

Networking Attributes for Instances

There are several subparameters that you can specify under the ethn parameter in the networking section of instance attributes. The list of subparameters varies depending on whether you’re defining a network interface on a shared network or an IP network.

Only one interface can be added to the shared network. If no subparameters are specified for the ethn parameter, the interface is implicitly added to the default security list in the shared network. You can’t explicitly or implicitly define two interfaces to be added to the shared network.

Subparameters for a Network Interface on the Shared Network

  • seclists: (Optional) The security lists that you want to add the instance to.

    For each security list, specify the three-part name in the /Compute-identity_domain/user/object_name format. You can attach an instance to a maximum of five security lists. If you launch an instance without specifying any security list, the instance is assigned to the /Compute-identity_domain/default/default security list.

  • nat: (Optional) Indicates whether a temporary or permanent public IP address should be assigned to the instance.

    • To associate a temporary IP address with the instance for use during the lifetime of the instance, specify ippool:/oracle/public/ippool.

    • To associate a persistent IP address, specify ipreservation:ipreservation_name, where ipreservation_name is the three-part name of an existing IP reservation in the /Compute-identity_domain/user/object_name format.

    If nat is not specified, then no public IP address is associated with your instance when it is created. If required, you can associate an IP address with the instance after the instance has been created.

  • dns: (Optional) A list of the DNS A record names for the instance. The name is relative to the internal DNS domain.

  • model: (Optional) The type of network interface card (NIC). The only allowed value is e1000.

  • name_servers: (Optional) Enter the name servers that are sent through DHCP as option 6.  You can specify a maximum of eight name server IP addresses per interface. If name_servers are set in both the IP network settings as well as the shared network settings, the name servers in the shared network will be used. To ensure that the name servers specified in the IP network are used, specify the same values for name servers on each interface.

  • search_domains: (Optional) Enter the search domains that should be sent through DHCP as option 119.  You can enter a maximum of eight search domain zones per interface. If search_domains are set in both the IP network settings as well as the shared network settings, the search domains in the shared network will be used. To ensure that the search domains specified in the IP network are used, specify the same values for search domains on each interface.

Subparameters for a Network Interface on an IP Network

  • ipnetwork: The name of the IP network that you want to add the instance to.

    If no name is specified, the interface isn’t added to any IP network. Instead, it is implicitly added to the shared network. However, only one instance interface can be added to the shared network. If another interface is either implicitly or explicitly added to the shared network, the instance won’t be created and will display an error.

    Specify the three-part name of the IP network, in the /Compute-identity_domain/user/object_name format.

    If an IP network belongs to an IP network exchange and if you have specified a host name, then that host name is resolvable by all IP networks connected to the IP network exchange.

  • ip: (Optional) The static private IP address of the instance. This is a persistent private IP address, which is reserved for use with this instance. The private IP address must be unused and it must belong to the subnet of the selected IP network. Remember, too, that certain IP addresses in a subnet are reserved. For example, the first unicast IP address of any IP network is reserved for the default gateway, the DHCP server, and the DNS server of that IP network.

    If you don’t specify an IP address, an IP address is assigned dynamically from the available IP addresses of the specified ipnetwork. However in this case, if you delete and re-create the instance, its IP address might change.

    Note:

    Dynamically allocated IP addresses are assigned from the top of the subnet range. It is recommended that you specify static IP addresses starting from the end of the subnet range to avoid conflicts.

  • address: (Optional) The MAC address of the interface, in hexadecimal format, where each digit is separated by colon. For example, you can enter 01:02:03:04:ab:cd as the MAC address but not 01-02-03-04-ab-cd. Ensure that the MAC addresses that you specify are unique within each IP network exchange and each IP network. If you specify a duplicate MAC address, each vNIC with that MAC address is disabled.

  • nat: (Optional) A list of IP reservations that you want to associate with this interface. Specify network/v1/ipreservation:ipreservation_name, where ipreservation_name is the three-part name of an existing IP reservation in the /Compute-identity_domain/user/object_name format.

    When you create an IP reservation, you specify the IP pool from which you want to reserve the IP address. You can associate a maximum of two IP reservations with each vNIC, one from each IP pool.

    Example:

    "networking":
    {
                    "eth0": {
                      "ipnetwork": "/test-customer/ipnet-1",
                      "ip": "192.168.2.14",
                      "nat": ["network/v1/ipreservation:/Compute-acme/joe/public-ipres-1"]
                            }
    }
  • vnic: (Optional) The three-part name of the vNIC in the /Compute-identity_domain/user/object_name format.

    If you don’t specify a name for this object, then the name is generated automatically.

    When the vNIC name is generated automatically, the autogenerated instance id in included as part of the object_name. So if you delete and re-create an instance, the vNIC name will change. However, if you specify a vNIC name, the name won’t change if you delete and re-create the instance.

    Object names can contain only alphanumeric characters, hyphens, underscores, and periods. Object names are case-sensitive.

  • vnicsets: (Optional) A list of the three-part names of the vNICsets that you want to add this vnic to. Specifying vNICsets ensures that this vNIC is added to the required vNICsets whenever the instance is created and removed from the vNICset whenever the instance is deleted.

    While creating an instance, you can add a vNIC to up to 4 vNICsets. To add a vNIC to more than 4 vNICsets, update the required vNICsets after the instance is created.

    The vNICsets that you specify here must already exist when you create or re-create an instance.

    If no vNICset is specified, then the vNIC is added to the default vNICset, /Compute-identity_domain/default.

    If an empty list ("vnicsets": [] ) is specified, this vNIC isn't added to any vNICset, including the default vNICset.

  • is_default_gateway: (Optional) If you want to specify the interface to be used as the default gateway for all traffic, set this to true. The default is false. Only one interface on an instance can be specified as the default gateway. If the instance has an interface on the shared network, that interface is always used as the default gateway. You can specify an interface on an IP network as the default gateway only when the instance doesn’t have an interface on the shared network.

  • dns: (Optional) A list of the DNS A record names for the instance.

    Each IP network has its own DNS server listening on the first IP address of the subnet.  You can specify up to eight DNS A record names for each instance on an IP network. These names can be queried by instances on any IP network in the same IP network exchange.

    If no static IP address is specified for the instance on the IP network, an IP address on the specified IP network is assigned automatically.  After the instance is launched, the defined names are associated with the IP address that was automatically allocated to the instance.

    The same DNS A record name can be specified for multiple instances.

    Example:

    "networking": 
    {
                    "eth1": {
                        "ipnetwork": "/Compute-acme/joe/ipnet1",
                        "dns": [ "dns1.example.com", "dns2.bar.com" ]
                            }
     }
  • name_servers: (Optional) A list of the name servers that are sent through DHCP as option 6. You can specify a maximum of eight name server IP addresses per interface. If name_servers are set in both the IP network as well as the shared network, the name servers in the shared network will be used. To ensure that the name servers specified in the IP network are used, specify the same values for name servers on each interface.

    Example:

    "networking": 
    {
                    "eth1": {
                        "ipnetwork": "/Compute-acme/joe/ipnet1",
                        "dns": ["dns1.example.com", "dns2.bar.com"],
                        "name_servers": ["192.168.12.1", "192.168.12.2"]
                            }
     }

    In this example, the name servers 192.168.12.1 and 192.168.12.2 will be pushed to the instance through DHCP.

  • search_domains: (Optional) A list of the search domains that should be sent through DHCP as option 119. You can enter a maximum of eight search domain zones per interface. If search_domains are set in both the IP network as well as the shared network, the search domains in the shared network will be used. To ensure that the search domains specified in the IP network are used, specify the same values for search domains on each interface.

    Example:

    "networking": 
    {
                    "eth1": {
                        "ipnetwork": "/Compute-acme/joe/ipnet1",
                        "dns": ["dns1.example.com", "dns2.bar.com"],
                        "name_servers": ["192.168.12.1", "192.168.12.2"],
                        "search_domains": ["example.com", "us.example1.com"]
                            }
     }

    In this example, the search domain zones example.com and us.example1.com will be pushed to the instance through DHCP.