"launch"
********

* Description

* Usage

* Required Parameters

* Optional Parameters

* Global Parameters

* Examples


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).

To launch an instance from a Marketplace image listing, you must
provide the image ID of the listing resource version that you want,
but you also must subscribe to the listing before you try to launch
the instance. To subscribe to the listing, use the
GetAppCatalogListingAgreements operation to get the signature for the
terms of use agreement for the desired listing resource version. Then,
call CreateAppCatalogSubscription with the signature. To get the image
ID for the LaunchInstance operation, call
GetAppCatalogListingResourceVersion.


Usage
=====

   oci compute instance launch [OPTIONS]


Required Parameters
===================

--availability-domain [text]

The availability domain of the instance.

Example:

   Uocm:PHX-AD-1

--compartment-id, -c [text]

The OCID of the compartment.

--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.

--subnet-id [text]

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


Optional Parameters
===================

--agent-config [complex type]

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.

--assign-private-dns-record [boolean]

Whether the VNIC should be assigned a DNS record. If set to false, no
DNS record registion for the VNIC; if set to true, DNS record will be
registered. The default value is *true*.

--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.

--availability-config [complex type]

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.

--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.

--capacity-reservation-id [text]

The OCID of the compute capacity reservation this instance is launched
under. You can opt out of all default reservations by specifying an
empty string as input for this field. For more information, see
Capacity Reservations.

--dedicated-vm-host-id [text]

The OCID of the dedicated VM host.

--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 the
same purpose and functionality as 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).

The combined size of the *metadata* and *extendedMetadata* objects can
be a maximum of 32,000 bytes. 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.

--fault-domain [text]

A fault domain is a grouping of hardware and infrastructure within an
availability domain. Each availability domain contains three fault
domains. Fault domains let you distribute your instances so that they
are not on the same physical hardware within a single availability
domain. A hardware failure or Compute hardware maintenance that
affects one fault domain does not affect instances in other fault
domains.

If you do not specify the fault domain, the system selects one for
you.

   To get a list of fault domains, use the ListFaultDomains operation
   in the Identity and Access Management Service API.

Example:

   FAULT-DOMAIN-1

--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.

--from-json [text]

Provide input to this command as a JSON document from a file using the
file://path-to/file syntax.

The "--generate-full-command-json-input" option can be used to
generate a sample json file to be used with this command option. The
key names are pre-populated and match the command option names
(converted to camelCase format, e.g. compartment-id –> compartmentId),
while the values of the keys need to be populated by the user before
using the sample file as an input to this command. For any command
option that accepts multiple values, the value of the key can be a
JSON array.

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.

For examples on usage of this option, please see our “using CLI with
advanced JSON options” link: https://docs.cloud.oracle.com/iaas/Conte
nt/API/SDKDocs/cliusing.htm#AdvancedJSONOptions

--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.

--instance-options [complex type]

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.

--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.

--is-pv-encryption-in-transit-enabled [boolean]

Whether to enable in-transit encryption for the data volume’s
paravirtualized attachment. This field applies to both block volumes
and boot volumes. The default value is false.

--launch-options [complex type]

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.

--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.

--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.cloud.oracle.com/api/#/en/iaas/20160918/r
equests/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 AAAAB3NzaC1yc2EAAAADAQABAAABAQDbVpuGODmhsRZOLWNgm0aEYUoWIDSPNWHmg2M6mZpmZNHfiNfx2dSofxUpKOiu5S8Th52AuAHSmkzNe6lXBO9wxnjOvkowe1mAleRTEl8zPI8Jkz6HrmJCzHEtS04kC4bx+tXRZhIfRq1uGaPcriKyquTnQs52Ahoxgw5vdXXQMwxWZLAcyaP01JrZwcUqPlB/GRiBFSTj0E/AIiVW3APNME5HjreOd/djjPRpvWu7AUpOqskG38kr8lhxo1hJifqeMg5W7cQsecTLJHgTDAPJD68ujM93jdzV2llIXwR1zyl80i6c3lDLyLgUrCLM0R1xex/zITTdT6/Z84buS/Xl my public key"}'

--nsg-ids [complex type]

A list of the [OCIDs] of the network security groups (NSGs) to add the
VNIC to.. 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.

--platform-config [complex type]

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.

--preemptible-instance-config [complex type]

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.

--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.

--shape-config [complex type]

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.

--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.

--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.

--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.

--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.clo
ud.oracle.com/api/#/en/iaas/20160918/requests/LaunchInstanceDetails.

--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.

--vnic-display-name [text]

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

--wait-for-state [text]

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. Multiple
states can be specified, returning on the first state. For example, "
--wait-for-state" SUCCEEDED "--wait-for-state" FAILED would return on
whichever lifecycle state is reached first. If timeout is reached, a
return code of 2 is returned. For any other error, a return code of 1
is returned.

Accepted values are:

   CREATING_IMAGE, MOVING, PROVISIONING, RUNNING, STARTING, STOPPED, STOPPING, TERMINATED, TERMINATING

--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.


Global Parameters
=================

Use "oci --help" for help on global parameters.

"--auth-purpose", "--auth", "--cert-bundle", "--cli-rc-file", "--
config-file", "--debug", "--defaults-file", "--endpoint", "--generate-
full-command-json-input", "--generate-param-json-input", "--help", "--
latest-version", "--max-retries", "--no-retry", "--opc-client-request-
id", "--opc-request-id", "--output", "--profile", "--query", "--raw-
output", "--region", "--release-info", "--request-id", "--version",
"-?", "-d", "-h", "-v"


Examples
========

Copy the following CLI commands into a file named example.sh. Run the
command by typing “bash example.sh” and replacing the example
parameters with your own.

Please note this sample will only work in the POSIX-compliant bash-
like shell. You need to set up the OCI configuration and appropriate
security policies before trying the examples.

       export cidr_block=<substitute-value-of-cidr_block> # https://docs.cloud.oracle.com/en-us/iaas/tools/oci-cli/latest/oci_cli_docs/cmdref/network/vcn/create.html#cmdoption-cidr-block
       export compartment_id=<substitute-value-of-compartment_id> # https://docs.cloud.oracle.com/en-us/iaas/tools/oci-cli/latest/oci_cli_docs/cmdref/network/vcn/create.html#cmdoption-compartment-id
       export availability_domain=<substitute-value-of-availability_domain> # https://docs.cloud.oracle.com/en-us/iaas/tools/oci-cli/latest/oci_cli_docs/cmdref/compute/instance/launch.html#cmdoption-availability-domain
       export image_id=<substitute-value-of-image_id> # https://docs.cloud.oracle.com/en-us/iaas/tools/oci-cli/latest/oci_cli_docs/cmdref/compute/instance/launch.html#cmdoption-image-id
       export shape=<substitute-value-of-shape> # https://docs.cloud.oracle.com/en-us/iaas/tools/oci-cli/latest/oci_cli_docs/cmdref/compute/instance/launch.html#cmdoption-shape

       vcn_id=$(oci network vcn create --cidr-block $cidr_block --compartment-id $compartment_id --query data.id --raw-output)

       subnet_id=$(oci network subnet create --cidr-block $cidr_block --compartment-id $compartment_id --vcn-id $vcn_id --query data.id --raw-output)

       oci compute instance launch --availability-domain $availability_domain --compartment-id $compartment_id --image-id $image_id --shape $shape --subnet-id $subnet_id
