Creating a Container Instance

Create a container instance.

You can create a maximum of 60 containers on each container instance.

Consider the following requirements before you create a container instance:

When you create a container instance, several other resources are involved, such as an image, a cloud network, and a subnet. Those resources can be in the same compartment as the instance or in other compartments. You must have the required level of access to each of the compartments involved to create the instance. See Required IAM Policy.
When you specify a container image, the registry that the image lives in must be reachable from the subnet that you provide for the container instance. If the container image lives in OCI Container Registry, specify the image in a subnet in a virtual cloud network (VCN) with a service gateway. If the container image lives in an external registry hosted on the public internet, specify the image in a public subnet in a VCN with an internet gateway or in a private subnet in a VCN with a network address translation (NAT) gateway.

To create a container instance, follow these steps:

Open the navigation menu and click Developer Services. Under Containers & Artifacts, click Container Instances.
Click Create container instance.
Enter a name for the container instance. You can add or change the name later. The name doesn't need to be unique because an Oracle Cloud Identifier (OCID) uniquely identifies the container instance. Avoid entering confidential information.
Select the compartment to create the instance in. The other resources that you choose can come from different compartments.
Under Placement, select the following options:
1. Select the availability domain that you want to create the instance in.
2. (Optional) If you want to specify a fault domain, click Show advanced options. Then, for Fault domain, select the fault domain to use for the instance. If you don't specify the fault domain, the system selects one for you. You can edit the fault domain after you create the instance. For more information, see Fault Domains.
Under Shape, choose the flexible shape for the container instance. Flexible shapes have a customizable number of OCPUs and amount of memory.
1. For Number of OCPUs, select the number of OCPUs that you want to allocate to this instance by dragging the slider. The other resources scale proportionately.
2. For Amount of memory (GB), select the amount of memory that you want to allocate to this instance by dragging the slider. The amount of memory allowed is based on the number of OCPUs selected.
Next, under Networking, you configure the network details for the instance:
Note

You will need a security rule as a part of a security list or a network security group to allow network traffic to the applications running in the container. For example, if your application runs on protocol TCP, port 8080, you need a security rule for TCP and port 8080. For information on configuring security rules, see Security Rules.
For Primary network and Subnet, specify the virtual cloud network (VCN) and subnet to create the instance in. Decide whether you want to use an existing VCN and subnet, create a new VCN or subnet, or enter an existing subnet's OCID:
- Select existing virtual cloud network: Select this option and then enter the following information.
  - Virtual cloud network: The cloud network to create the instance in.
  - Subnet: A subnet within the cloud network that the instance is attached to. The subnets are either public or private. Private means the instances in that subnet can't have public IP addresses. For more information, see Access to the Internet. Subnets can also be either availability domain-specific or regional. Regional ones have "regional" after the name. We recommend using regional subnets. For more information, see About Regional Subnets.
  - To use an existing subnet, select Select existing subnet and then select the subnet.
  - To create a subnet, select Create new public subnet, and then enter the following information:
    - New subnet name: A name for the subnedt. Avoid entering confidential information.
    - Create in compartment: The compartment where you want to put the subnet.
    - CIDR block: A single, contiguous CIDR block, for the subnet (for example, 172.16.0.0/24). Ensure that it's within the cloud network's CIDR block and doesn't overlap with any other subnets. You cannot change this value later. See Allowed VCN Size and Address Ranges. For reference, here's a CIDR calculator.
- Create new virtual cloud network: Select this option and then enter the following information.
  - New virtual cloud network name: A name for the subnet. A friendly name for the network. Avoid entering confidential information.
  - Create in compartment: The compartment where you want to put the new network.
  - Create new public subnet: A subnet within the cloud network to attach the instance to. The subnets are either public or private. Private means that the instances in that subnet can't have public IP addresses. For more information, see Access to the Internet. Subnets can also be either availability domain-specific or regional. Regional ones have "regional" after the name. We recommend using regional subnets. For more information, see About Regional Subnets.
  Enter the following information:
  - New subnet name: A name for the subnet. It doesn't have to be unique, and it can be changed later. Avoid entering confidential information.
  - Create in compartment: The compartment where you want to put the subnet.
  - CIDR block: A single, contiguous CIDR block for the subnet, for example, 172.16.0.0/24. Ensure that it's within the cloud network's CIDR block and doesn't overlap with any other subnets. You can't change this value later. See Allowed VCN Size and Address Ranges and thisCIDR calculator.
Enter subnet OCID: Select this option and then enter the subnet OCID.
1. (Optional) If the subnet is public, select Assign a public IPv4 address to assign the instance a public IP address. A public IP address makes the instance accessible from the internet. For more information, see Access to the Internet.
2. (Optional) To configure advanced networking settings, click Show advanced options, and then specify the following options as needed:
  - Use network security groups to control traffic: Select this option if you want to add the instance's primary VNIC to one or more network security groups (NSGs). Then, specify the NSGs. This option is available only when you use an existing VCN. For more information, see Network Security Groups.
  - Private IP address: Enter an available private IP address of your choice from the subnet's CIDR. If you don't specify a value, the private IP address is automatically assigned.
  - DNS record: Specify whether to assign a private DNS record.
  - Hostname: Enter a hostname to be use for DNS within the cloud network. This option is available only if the VCN and subnet both have DNS labels, and you selected to assign a private DNS record is selected.
(Optional) To configure advanced settings for the container instance, click Show advanced options, and then specify the following options as needed:
1. On the Advanced options tab, you can configure the following options:
  - Graceful shutdown timeout (seconds): Set the amount of time that the container instance waits for the OS to shut down before powering off.
  - Container restart policy: Select between Always, Never, and On failure.
    
    You can set the restart policy for the containers in a container instance when you create them. When an individual container exits (stops, restarts, or fails), the exit code and exit time are available in the API and the restart policy is applied. If all containers exit and don't restart, the container instance is shuts down.
    
    Select one of the following options:
    - Always: Containers always restart, even if they exit successfully. "Always" is preferred if you want to ensure that your container is always running, such as a web server. This policy setting is the default.
    - Never: Containers never restart, regardless of why they exited.
    - On failure: Containers only restart only if they exit with an error. "On failure" is preferred if you want to accomplish a certain task and ensure that it completes successfully.
2. On the Tags tab, add tags to the container instance. If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure whether to apply tags, skip this option or ask your administrator. You can apply tags later.
Click Next to configure the containers within the container instance.
Enter a name for the first container. You can add or change the name later. The name doesn't need to be unique, because an Oracle Cloud Identifier (OCID) uniquely identifies the container. Avoid entering confidential information.
Under Image, click Select image, and then follow these steps In the Container image panel to select a container image.
1. Select an image source:
  - OCI Container Registry: OCI Registry, also known as Container Registry, is an Oracle-managed registry that enables you to store, share, and manage container images. For more information, see Container Registry.
  - External registry: An external registry, such as Docker Hub, where you can choose an image provided by third-party vendors.
  - Vault Secrets for Image Pull Authorization: You can host container images in private registries or repositories that require authorization in order to pull the images. We recommend that you store your credentials using the Oracle Cloud Infrastructure Vault service for enhanced security and ease of credentials management. For more information, see Vault Secrets for Image Pull Authorization.
2. Select an image.
3. Click Select image.
Under the Environmental variables section, you can set the environmental variables used by the container.

Container images support environment variables to customize their execution. For example, the official NGINX image supports NGINX_HOST and NGINX_PORT environment variables, so you can set the value to customize the execution to the following variables:
- NGINX_HOST=foobar.com
- NGINX_PORT=80

To configure advanced settings for the container, click Show advanced options, and then specify the following options as needed:

On the Resources tab, you can configure the amount of resources that the container consumes in absolutes or percentages. By default, the container can use all resources in the container instance.
On the Startup options tab, you can configure working directory and ENTRYPOINT arguments for the container.

On the Security tab, you can specify the security settings of the container.

Select the Enable read-only root filesystem check box to apply read-only access to the root filesystem of the container.
Select the Run as non-root user check box to ensure that the root user doesn't run the container.
- When you enable Run as non-root user, the User ID value cannot be set to 0.
Use the User ID and Group ID fields to set the user ID (ID) and group ID (GID) to run the entrypoint process of the container.
- The value for User ID and Group ID must be an integer between 0 and 65535. The default value is 0.
- The User ID and Group ID values that you specify override values that are set in the container image. When the User ID value is not specified, the entrypoint process of the container runs as root user.
- You must set the User ID before you set the Group ID.

Under the Configure Linux capabilities section, you can configure Linux capabilities for your container. By default, the container launches with several capabilities that you can choose to drop.

Both the Add capabilities field and Drop capabilities field support the ALL value, which allows or drops all capabilities. The value ALL refers to the Linux capabilities that are enabled by default.

If you leave both Add capabilities and Drop capabilities blank, all default capabilities are available for your container.
If you enter ALL in the Add capabilities field, all capabilities are available except those that you list in the Drop capabilities field, and ignores ALL in the Drop capabilities field.
If you enter ALL in the Drop capabilities field, the container contains only the capabilities that you list in the Add capabilities field.
For other cases, drops all the capabilities from the default set listed in the Drop capabilities field, then adds the capabilities listed in the Add capabilities field, and finally returns the result as the capability for your container.
The creation of the container instance fails if you provide any capabilities that are not in the list below.

All Linux capabilities enabled by default when you create a container
Capability	Description
CAP_CHOWN	Makes changes to file UIDs and GIDs.
CAP_DAC_OVERRIDE	Discretionary access control (DAC) that bypasses file read, write, and execute permission checks.
CAP_FSETID	Does not clear set-user-ID and set-group-ID mode bits when a file is modified. Sets the set-group-ID bit for a file whose GID does not match the file. system or any of the supplementary GIDs of the calling process.
CAP_FOWNER	Bypasses permission checks on operations that normally require the file system UID of the process to match the UID of the file, excludes the operations that are covered by CAP_DAC_OVERRIDE and CAP_DAC_READ_SEARCH.
CAP_MKNOD	Creates special files using mknod(2).
CAP_NET_RAW	Uses RAW and PACKET sockets. Binds to any address for transparent proxying .
CAP_SETGID	Makes manipulations of process GIDs and supplementary GID list. Forges GID when passing socket credentials via UNIX domain sockets. Writes a group ID mapping in a user namespace.
CAP_SETUID	Makes manipulations of process UIDs. Forges UID when passing socket credentials via UNIX domain sockets. Writes a user ID mapping in a user namespace.
CAP_SETFCAP	Sets file capabilities.
CAP_SETPCAP	If the file capabilities are not supported, grants or removes any capability in the caller's permitted capability set to or from any other process.
CAP_NET_BIND_SERVICE	Binds a socket to internet domain privileged ports (port numbers less than 1024).
CAP_SYS_CHROOT	Uses chroot(2) to change to a different root directory.
CAP_KILL	Bypasses permission checks for sending signals, which includes use of the ioctl(2) KDSIGACCEPT operation.
CAP_AUDIT_WRITE	Writes records to kernel auditing log.

To configure another container in the instance, click + Another container and repeat the preceding steps.
Click Next to review the container instance and its containers.
Click Create.

Use the oci container-instances container-instance create command to create a container instance.

To use this command, replace compartment_ocid, logical_ad, and subnetId with your resources.

$ compartment_ocid=ocid1.compartment.oc1.example
$ logical_ad=Lnnj:US-EXAMPLE
$ ci_shape=CI.Standard.E4.Flex
$ shape_config_json='{"ocpus": 2,"memoryInGBs": 2}'
$ containers_json='[{"imageUrl": "busybox", "command": ["bin/sh"], "arguments": ["-c", "echo Hello"]}]'
$ vnics_json='[{"subnetId": "ocid1.subnet.oc1.example"}]'
$ oci container-instances container-instance create --compartment-id "$compartment_ocid" --availability-domain "$logical_ad" --shape "$ci_shape" --shape-config "$shape_config_json" --containers "$containers_json" --vnics "$vnics_json"

For a complete list of flags and variable options for CLI commands, see the Command Line Reference.

Use the CreateContainerInstance operation.

Oracle Cloud Infrastructure Documentation

Creating a Container Instance