launch
******


Description
===========

Creates a new instance in the specified compartment and the specified
Availability Domain. For general information about instances, see
Overview of the Compute Service.

For information about access control and compartments, see Overview of
the IAM Service.

For information about Availability Domains, see Regions and
Availability Domains. To get a list of Availability Domains, use the
*ListAvailabilityDomains* operation in the Identity and Access
Management Service API.

All Oracle Cloud Infrastructure resources, including instances, get an
Oracle-assigned, unique ID called an Oracle Cloud Identifier (OCID).
When you create a resource, you can find its OCID in the response. You
can also retrieve a resource's OCID by using a List API operation on
that resource type, or by viewing the resource in the Console.

To launch an instance using an image or a boot volume use the
*sourceDetails* parameter in LaunchInstanceDetails.

When you launch an instance, it is automatically attached to a virtual
network interface card (VNIC), called the *primary VNIC*. The VNIC has
a private IP address from the subnet's CIDR. You can either assign a
private IP address of your choice or let Oracle automatically assign
one. You can choose whether the instance has a public IP address. To
retrieve the addresses, use the ListVnicAttachments operation to get
the VNIC ID for the instance, and then call GetVnic with the VNIC ID.

You can later add secondary VNICs to an instance. For more
information, see Virtual Network Interface Cards (VNICs).


Usage
=====

   oci compute instance launch [OPTIONS]


Options
=======


--availability-domain [text]
----------------------------

The Availability Domain of the instance.

Example: *Uocm:PHX-AD-1* [required]


--compartment-id, -c [text]
---------------------------

The OCID of the compartment. [required]


--shape [text]
--------------

The shape of an instance. The shape determines the number of CPUs,
amount of memory, and other resources allocated to the instance.

You can enumerate all available shapes by calling ListShapes.
[required]


--defined-tags [complex type]
-----------------------------

Defined tags for this resource. Each key is predefined and scoped to a
namespace. For more information, see Resource Tags.

Example: *{"Operations": {"CostCenter": "42"}}* This is a complex type
whose value must be valid JSON. The value can be provided as a string
on the command line or passed in as a file using the
file://path/to/file syntax.

The --generate-param-json-input option can be used to generate an
example of the JSON which must be provided. We recommend storing this
example in a file, modifying it as needed and then passing it back in
via the file:// syntax.


--display-name [text]
---------------------

A user-friendly name. Does not have to be unique, and it's changeable.
Avoid entering confidential information.

Example: *My bare metal instance*


--extended-metadata [complex type]
----------------------------------

Additional metadata key/value pairs that you provide.  They serve a
similar purpose and functionality from fields in the 'metadata'
object.

They are distinguished from 'metadata' fields in that these can be
nested JSON objects (whereas 'metadata' fields are string/string maps
only).

If you don't need nested metadata values, it is strongly advised to
avoid using this object and use the Metadata object instead. This is a
complex type whose value must be valid JSON. The value can be provided
as a string on the command line or passed in as a file using the
file://path/to/file syntax.

The --generate-param-json-input option can be used to generate an
example of the JSON which must be provided. We recommend storing this
example in a file, modifying it as needed and then passing it back in
via the file:// syntax.


--freeform-tags [complex type]
------------------------------

Free-form tags for this resource. Each tag is a simple key-value pair
with no predefined name, type, or namespace. For more information, see
Resource Tags.

Example: *{"Department": "Finance"}* This is a complex type whose
value must be valid JSON. The value can be provided as a string on the
command line or passed in as a file using the file://path/to/file
syntax.

The --generate-param-json-input option can be used to generate an
example of the JSON which must be provided. We recommend storing this
example in a file, modifying it as needed and then passing it back in
via the file:// syntax.


--hostname-label [text]
-----------------------

The hostname for the VNIC that is created during instance launch. Used
for DNS. The value is the hostname portion of the instance's fully
qualified domain name (FQDN) (e.g., *bminstance-1* in FQDN
*bminstance-1.subnet123.vcn1.oraclevcn.com*). Must be unique across
all VNICs in the subnet and comply with RFC 952 and RFC 1123. The
value cannot be changed, and it can be retrieved from the Vnic.

For more information, see DNS in Your Virtual Cloud Network.

Example: *bminstance-1*


--image-id [text]
-----------------

The OCID of the image used to boot the instance. This is a shortcut
for specifying an image source via the --source-details complex JSON
parameter. If this parameter is provided, you cannot provide the
--source-details or --source-boot-volume-id parameters.


--ipxe-script-file [filename]
-----------------------------

This is an advanced option.

When a bare metal or virtual machine instance boots, the iPXE firmware
that runs on the instance is configured to run an iPXE script to
continue the boot process.

If you want more control over the boot process, you can provide your
own custom iPXE script that will run when the instance boots; however,
you should be aware that the same iPXE script will run every time an
instance boots; not only after the initial LaunchInstance call.

The default iPXE script connects to the instance's local boot volume
over iSCSI and performs a network boot. If you use a custom iPXE
script and want to network-boot from the instance's local boot volume
over iSCSI the same way as the default iPXE script, you should use the
following iSCSI IP address: 169.254.0.2, and boot volume IQN:
iqn.2015-02.oracle.boot.

For more information about the Bring Your Own Image feature of Oracle
Cloud Infrastructure, see Bring Your Own Image.

For more information about iPXE, see http://ipxe.org.


--metadata [complex type]
-------------------------

Custom metadata key/value pairs that you provide, such as the SSH
public key required to connect to the instance. For more info see
documentation: https://docs.us-phoenix-1.oraclecloud.com/api/#/en/iaa
s/20160918/requests/LaunchInstanceDetails. This must be provided in
JSON format.

Note: user_data and ssh_authorized_keys can instead be specified using
the parameters --user-data-file and --ssh-authorized-keys-file.

Example: '{"ssh_authorized_keys": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAA
ABAQDbVpuGODmhsRZOLWNgm0aEYUoWIDSPNWHmg2M6mZpmZNHfiNfx2dSofxUpKOiu5S8
Th52AuAHSmkzNe6lXBO9wxnjOvkowe1mAleRTEl8zPI8Jkz6HrmJCzHEtS04kC4bx+tXR
ZhIfRq1uGaPcriKyquTnQs52Ahoxgw5vdXXQMwxWZLAcyaP01JrZwcUqPlB/GRiBFSTj0
E/AIiVW3APNME5HjreOd/djjPRpvWu7AUpOqskG38kr8lhxo1hJifqeMg5W7cQsecTLJH
gTDAPJD68ujM93jdzV2llIXwR1zyl80i6c3lDLyLgUrCLM0R1xex/zITTdT6/Z84buS/Xl
my public key"}'


--source-details [complex type]
-------------------------------

Use this parameter to specify whether a boot volume or an image should
be used to launch a new instance. This is a complex type whose value
must be valid JSON. The value can be provided as a string on the
command line or passed in as a file using the file://path/to/file
syntax.

The --generate-param-json-input option can be used to generate an
example of the JSON which must be provided. We recommend storing this
example in a file, modifying it as needed and then passing it back in
via the file:// syntax.


--subnet-id [text]
------------------

The OCID of the subnet where the VNIC attached to this instance will
be created.


--wait-for-state [PROVISIONING|RUNNING|STARTING|STOPPING|STOPPED|CREATING_IMAGE|TERMINATING|TERMINATED]
-------------------------------------------------------------------------------------------------------

This operation creates, modifies or deletes a resource that has a
defined lifecycle state. Specify this option to perform the action and
then wait until the resource reaches a given lifecycle state.


--max-wait-seconds [integer]
----------------------------

The maximum time to wait for the resource to reach the lifecycle state
defined by --wait-for-state. Defaults to 1200 seconds.


--wait-interval-seconds [integer]
---------------------------------

Check every --wait-interval-seconds to see whether the resource to see
if it has reached the lifecycle state defined by --wait-for-state.
Defaults to 30 seconds.


--vnic-display-name [text]
--------------------------

A user-friendly name for the default VNIC attached to this instance.
Does not have to be unique.


--assign-public-ip [boolean]
----------------------------

Whether the default VNIC attached to this instance should be assigned
a public IP address. Defaults to whether the subnet is public or
private. If not set and the VNIC is being created in a private subnet
(i.e., where prohibitPublicIpOnVnic=true in the Subnet), then no
public IP address is assigned. If not set and the subnet is public
(prohibitPublicIpOnVnic=false), then a public IP address is assigned.
If set to true and prohibitPublicIpOnVnic=true, an error is returned.


--private-ip [text]
-------------------

A private IP address of your choice to assign to the default VNIC
attached to this instance. Must be an available IP address within the
subnet's CIDR. If no value is specified, a private IP address from the
subnet will be automatically assigned.


--skip-source-dest-check [boolean]
----------------------------------

Indicates whether Source/Destination check is disabled on the VNIC.
Defaults to *false*, in which case we enable Source/Destination check
on the VNIC.


--user-data-file [filename]
---------------------------

A file containing data that Cloud-Init can use to run custom scripts
or provide custom Cloud-Init configuration. This parameter is a
convenience wrapper around the 'user_data' field of the --metadata
parameter.  Populating both values in the same call will result in an
error. For more info see Cloud-Init documentation:
https://cloudinit.readthedocs.org/en/latest/topics/format.html.


--ssh-authorized-keys-file [filename]
-------------------------------------

A file containing one or more public SSH keys to be included in the
~/.ssh/authorized_keys file for the default user on the instance. Use
a newline character to separate multiple keys. The SSH keys must be in
the format necessary for the authorized_keys file. This parameter is a
convenience wrapper around the 'ssh_authorized_keys' field of the
--metadata parameter. Populating both values in the same call will
result in an error. For more info see documentation: https://docs.us-
phoenix-1.oraclecloud.com/api/#/en/iaas/20160918/requests/LaunchInsta
nceDetails.


--source-boot-volume-id [text]
------------------------------

The OCID of the boot volume used to boot the instance. This is a
shortcut for specifying a boot volume source via the --source-details
complex JSON parameter. If this parameter is provided, you cannot
provide the --source-details or --image-id parameters.


--boot-volume-size-in-gbs [integer]
-----------------------------------

The size of the boot volume in GBs. Minimum value is 50 GB and maximum
value is 16384 GB (16TB). This is a shortcut for specifying a boot
volume size via the --source-details complex JSON parameter. If this
parameter is provided, you cannot provide the --source-details or
--source-boot-volume-id parameters.


--from-json [text]
------------------

Provide input to this command as a JSON document from a file.

Options can still be provided on the command line. If an option exists
in both the JSON document and the command line then the command line
specified value will be used


-?, -h, --help
--------------

Show this message and exit.
