Skip to main content

private_ips

Creates, updates, deletes, gets or lists a private_ips resource.

Overview​

Nameprivate_ips
TypeResource
Idoci.network.private_ips

Fields​

The following fields are returned by SELECT queries:

The private IP.

NameDatatypeDescription
idstringThe private IP's Oracle ID ([OCID](/iaas/Content/General/Concepts/identifiers.htm)).
availabilityDomainstringThe private IP's availability domain. This attribute will be null if this is a secondary private IP assigned to a VNIC that is in a regional subnet. Example: Uocm:PHX-AD-1
cidrPrefixLengthintegerThe secondary IPv4 CIDR prefix length.
compartmentIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment containing the private IP.
definedTagsobjectDefined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/iaas/Content/General/Concepts/resourcetags.htm). Example: {"Operations": {"CostCenter": "42"}}
displayNamestringA user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information.
freeformTagsobjectFree-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](/iaas/Content/General/Concepts/resourcetags.htm). Example: {"Department": "Finance"}
hostnameLabelstringThe hostname for the private IP. Used for DNS. The value is the hostname portion of the private IP's fully qualified domain name (FQDN) (for example, bminstance1 in FQDN bminstance1.subnet123.vcn1.oraclevcn.com). Must be unique across all VNICs in the subnet and comply with [RFC 952](https:​//tools.ietf.org/html/rfc952) and [RFC 1123](https:​//tools.ietf.org/html/rfc1123). For more information, see [DNS in Your Virtual Cloud Network](/iaas/Content/Network/Concepts/dns.htm). Example: bminstance1
ipAddressstringThe private IP address of the privateIp object. The address is within the CIDR of the VNIC's subnet. However, if the PrivateIp object is being used with a VLAN as part of the Oracle Cloud VMware Solution, the address is from the range specified by the cidrBlock attribute for the VLAN. See [Vlan](#/en/iaas/latest/Vlan). Example: 10.0.3.3
ipStatestringState of the IP address. If an IP address is assigned to a VNIC it is ASSIGNED, otherwise it is AVAILABLE. (ASSIGNED, AVAILABLE)
ipv4SubnetCidrAtCreationstringIpv4 Subnet CIDR specified whn creating the PrivateIP.
isPrimarybooleanWhether this private IP is the primary one on the VNIC. Primary private IPs are unassigned and deleted automatically when the VNIC is terminated. Example: true
lifetimestringLifetime of the IP address. There are two types of IPs: - Ephemeral - Reserved (EPHEMERAL, RESERVED)
routeTableIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the route table the IP address or VNIC will use. For more information, see [Per-resource Routing](https:​//docs.oracle.com/iaas/Content/Network/Tasks/managingroutetables.htm#Overview_of_Routing_for_Your_VCN__source_routing).
subnetIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the subnet the VNIC is in. However, if the PrivateIp object is being used with a VLAN as part of the Oracle Cloud VMware Solution, the subnetId is null.
timeCreatedstring (date-time)The date and time the private IP was created, in the format defined by [RFC3339](https:​//tools.ietf.org/html/rfc3339). Example: 2016-08-25T21:10:29.600Z
vlanIdstringApplicable only if the PrivateIp object is being used with a VLAN as part of the Oracle Cloud VMware Solution. The vlanId is the [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the VLAN. See [Vlan](#/en/iaas/latest/Vlan).
vnicIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the VNIC the private IP is assigned to. The VNIC and private IP must be in the same subnet. However, if the PrivateIp object is being used with a VLAN as part of the Oracle Cloud VMware Solution, the vnicId is null.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectprivateIpId, regionGets the specified private IP. You must specify the object's [OCID](/iaas/Content/General/Concepts/identifiers.htm).<br />Alternatively, you can get the object by using<br />[ListPrivateIps](#/en/iaas/latest/PrivateIp/ListPrivateIps)<br />with the private IP address (for example, 10.0.3.3) and subnet [OCID](/iaas/Content/General/Concepts/identifiers.htm).<br />
listselectregionlimit, page, ipAddress, subnetId, vnicId, ipState, lifetime, vlanIdLists the [PrivateIp](#/en/iaas/latest/PrivateIp/) objects based<br />on one of these filters:<br /><br /> - Subnet [OCID](/iaas/Content/General/Concepts/identifiers.htm).<br /> - VNIC [OCID](/iaas/Content/General/Concepts/identifiers.htm).<br /> - Both private IP address and subnet OCID: This lets<br /> you get a privateIP object based on its private IP<br /> address (for example, 10.0.3.3) and not its [OCID](/iaas/Content/General/Concepts/identifiers.htm). For comparison,<br /> [GetPrivateIp](#/en/iaas/latest/PrivateIp/GetPrivateIp)<br /> requires the [OCID](/iaas/Content/General/Concepts/identifiers.htm).<br /><br />If you're listing all the private IPs associated with a given subnet<br />or VNIC, the response includes both primary and secondary private IPs.<br /><br />If you are an Oracle Cloud VMware Solution customer and have VLANs<br />in your VCN, you can filter the list by VLAN [OCID](/iaas/Content/General/Concepts/identifiers.htm). See [Vlan](#/en/iaas/latest/Vlan).<br />
createinsertregionopc-retry-tokenCreates a private IP.<br />For more information about private IPs, see<br />[IP Addresses](/iaas/Content/Network/Tasks/managingIPaddresses.htm).<br />
updateupdateprivateIpId, regionif-matchUpdates the specified private IP. You must specify the object's [OCID](/iaas/Content/General/Concepts/identifiers.htm).<br />Use this operation if you want to:<br /><br /> - Move a secondary private IP to a different VNIC in the same subnet.<br /> - Change the display name for a secondary private IP.<br /> - Change the hostname for a secondary private IP.<br /><br />This operation cannot be used with primary private IPs.<br />To update the hostname for the primary IP on a VNIC, use<br />[UpdateVnic](#/en/iaas/latest/Vnic/UpdateVnic).<br />
deletedeleteprivateIpId, regionif-matchUnassigns and deletes the specified private IP. You must<br />specify the object's [OCID](/iaas/Content/General/Concepts/identifiers.htm). The private IP address is returned to<br />the subnet's pool of available addresses.<br /><br />This operation cannot be used with primary private IPs, which are<br />automatically unassigned and deleted when the VNIC is terminated.<br /><br />Important: If a secondary private IP is the<br />[target of a route rule](/iaas/Content/Network/Tasks/managingroutetables.htm#privateip),<br />unassigning it from the VNIC causes that route rule to blackhole and the traffic<br />will be dropped.<br />
bulk_create_private_ipsexecregion, bulkCreatePrivateIpItemopc-retry-token, opc-request-idCreate secondary private IPv4 addresses.<br />
bulk_delete_private_ipsexecregion, bulkDeletePrivateIpItemopc-retry-token, opc-request-idUnassign and delete secondary private IPv4s for a VNIC.<br />
bulk_detach_private_ipsexecregion, bulkDetachPrivateIpItemopc-retry-token, opc-request-idUnassign the specified private IP addresses from the Virtual Network Interface Card (VNIC). You must specify the PrivateIP object's [OCID](/iaas/Content/General/Concepts/identifiers.htm).<br />
bulk_update_private_ipsexecregion, bulkUpdatePrivateIpItemopc-retry-token, opc-request-idUpdate existing secondary private IPv4s for a VNIC.
private_ip_vnic_detachexecprivateIpId, regionif-match, opc-request-id, opc-retry-tokenUnassign the specified PrivateIP address from Virtual Network Interface Card (VNIC). You must specify the PrivateIP [OCID](/iaas/Content/General/Concepts/identifiers.htm).<br />

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
privateIpIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the private IP or IPv6.
regionstringOCI region identifier (e.g. us-ashburn-1, ap-sydney-1); resolves from OCI_REGION when not supplied in the query. (default: us-ashburn-1, x-stackQL-envVar: OCI_REGION)
if-matchstringFor optimistic concurrency control. In the PUT or DELETE call for a resource, set the if-match parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
ipAddressstringAn IP address. This could be either IPv4 or IPv6, depending on the resource. Example: 10.0.3.3
ipStatestringState of the IP address. If an IP address is assigned to a VNIC it is ASSIGNED otherwise AVAILABLE
lifetimestringLifetime of the IP address. There are two types of IPs: - Ephemeral - Reserved
limitintegerFor list pagination. The maximum number of results per page, or items to return in a paginated "List" call. For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine). Example: 50
opc-request-idstringUnique identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
opc-retry-tokenstringA token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (for example, if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).
pagestringFor list pagination. The value of the opc-next-page response header from the previous "List" call. For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).
subnetIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the subnet.
vlanIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the VLAN.
vnicIdstringThe OCID of the VNIC.

SELECT examples​

Gets the specified private IP. You must specify the object's [OCID](/iaas/Content/General/Concepts/identifiers.htm).<br />Alternatively, you can get the object by using<br />[ListPrivateIps](#/en/iaas/latest/PrivateIp/ListPrivateIps)<br />with the private IP address (for example, 10.0.3.3) and subnet [OCID](/iaas/Content/General/Concepts/identifiers.htm).<br />

SELECT
id,
availabilityDomain,
cidrPrefixLength,
compartmentId,
definedTags,
displayName,
freeformTags,
hostnameLabel,
ipAddress,
ipState,
ipv4SubnetCidrAtCreation,
isPrimary,
lifetime,
routeTableId,
subnetId,
timeCreated,
vlanId,
vnicId
FROM oci.network.private_ips
WHERE privateIpId = '{{ privateIpId }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates a private IP.<br />For more information about private IPs, see<br />[IP Addresses](/iaas/Content/Network/Tasks/managingIPaddresses.htm).<br />

INSERT INTO oci.network.private_ips (
cidrPrefixLength,
definedTags,
displayName,
freeformTags,
hostnameLabel,
ipAddress,
ipv4SubnetCidrAtCreation,
lifetime,
routeTableId,
subnetId,
vlanId,
vnicId,
region,
opc-retry-token
)
SELECT 
{{ cidrPrefixLength }},
'{{ definedTags }}',
'{{ displayName }}',
'{{ freeformTags }}',
'{{ hostnameLabel }}',
'{{ ipAddress }}',
'{{ ipv4SubnetCidrAtCreation }}',
'{{ lifetime }}',
'{{ routeTableId }}',
'{{ subnetId }}',
'{{ vlanId }}',
'{{ vnicId }}',
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
availabilityDomain,
cidrPrefixLength,
compartmentId,
definedTags,
displayName,
freeformTags,
hostnameLabel,
ipAddress,
ipState,
ipv4SubnetCidrAtCreation,
isPrimary,
lifetime,
routeTableId,
subnetId,
timeCreated,
vlanId,
vnicId
;

UPDATE examples​

Updates the specified private IP. You must specify the object's [OCID](/iaas/Content/General/Concepts/identifiers.htm).<br />Use this operation if you want to:<br /><br /> - Move a secondary private IP to a different VNIC in the same subnet.<br /> - Change the display name for a secondary private IP.<br /> - Change the hostname for a secondary private IP.<br /><br />This operation cannot be used with primary private IPs.<br />To update the hostname for the primary IP on a VNIC, use<br />[UpdateVnic](#/en/iaas/latest/Vnic/UpdateVnic).<br />

UPDATE oci.network.private_ips
SET 
definedTags = '{{ definedTags }}',
displayName = '{{ displayName }}',
freeformTags = '{{ freeformTags }}',
hostnameLabel = '{{ hostnameLabel }}',
lifetime = '{{ lifetime }}',
routeTableId = '{{ routeTableId }}',
vnicId = '{{ vnicId }}'
WHERE 
privateIpId = '{{ privateIpId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
RETURNING
id,
availabilityDomain,
cidrPrefixLength,
compartmentId,
definedTags,
displayName,
freeformTags,
hostnameLabel,
ipAddress,
ipState,
ipv4SubnetCidrAtCreation,
isPrimary,
lifetime,
routeTableId,
subnetId,
timeCreated,
vlanId,
vnicId;

DELETE examples​

Unassigns and deletes the specified private IP. You must<br />specify the object's [OCID](/iaas/Content/General/Concepts/identifiers.htm). The private IP address is returned to<br />the subnet's pool of available addresses.<br /><br />This operation cannot be used with primary private IPs, which are<br />automatically unassigned and deleted when the VNIC is terminated.<br /><br />Important: If a secondary private IP is the<br />[target of a route rule](/iaas/Content/Network/Tasks/managingroutetables.htm#privateip),<br />unassigning it from the VNIC causes that route rule to blackhole and the traffic<br />will be dropped.<br />

DELETE FROM oci.network.private_ips
WHERE privateIpId = '{{ privateIpId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
;

Lifecycle Methods​

Create secondary private IPv4 addresses.<br />

EXEC oci.network.private_ips.bulk_create_private_ips 
@region='{{ region }}' --required, 
@opc-retry-token='{{ opc-retry-token }}', 
@opc-request-id='{{ opc-request-id }}' 
@@json=
'{
"bulkCreatePrivateIpItem": "{{ bulkCreatePrivateIpItem }}", 
"subnetId": "{{ subnetId }}", 
"vlanId": "{{ vlanId }}", 
"vnicId": "{{ vnicId }}"
}'
;