Skip to main content

public_ips

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

Overview​

Namepublic_ips
TypeResource
Idoci.network.public_ips

Fields​

The following fields are returned by SELECT queries:

The public IP was retrieved.

NameDatatypeDescription
idstringThe public IP's Oracle ID ([OCID](/iaas/Content/General/Concepts/identifiers.htm)).
assignedEntityIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the entity the public IP is assigned to, or in the process of being assigned to.
assignedEntityTypestringThe type of entity the public IP is assigned to, or in the process of being assigned to. (PRIVATE_IP, NAT_GATEWAY)
availabilityDomainstringThe public IP's availability domain. This property is set only for ephemeral public IPs that are assigned to a private IP (that is, when the scope of the public IP is set to AVAILABILITY_DOMAIN). The value is the availability domain of the assigned private IP. Example: Uocm:PHX-AD-1
compartmentIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment containing the public IP. For an ephemeral public IP, this is the compartment of its assigned entity (which can be a private IP or a regional entity such as a NAT gateway). For a reserved public IP that is currently assigned, its compartment can be different from the assigned private IP's.
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"}
ipAddressstringThe public IP address of the publicIp object. Example: 203.0.113.2
lifecycleStatestringThe public IP's current state. (PROVISIONING, AVAILABLE, ASSIGNING, ASSIGNED, UNASSIGNING, UNASSIGNED, TERMINATING, TERMINATED)
lifetimestringDefines when the public IP is deleted and released back to Oracle's public IP pool. * EPHEMERAL: The lifetime is tied to the lifetime of its assigned entity. An ephemeral public IP must always be assigned to an entity. If the assigned entity is a private IP, the ephemeral public IP is automatically deleted when the private IP is deleted, when the VNIC is terminated, or when the instance is terminated. If the assigned entity is a [NatGateway](#/en/iaas/latest/NatGateway/), the ephemeral public IP is automatically deleted when the NAT gateway is terminated. * RESERVED: You control the public IP's lifetime. You can delete a reserved public IP whenever you like. It does not need to be assigned to a private IP at all times. For more information and comparison of the two types, see [Public IP Addresses](/iaas/Content/Network/Tasks/managingpublicIPs.htm). (EPHEMERAL, RESERVED)
privateIpIdstringDeprecated. Use assignedEntityId instead. The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the private IP that the public IP is currently assigned to, or in the process of being assigned to. Note: This is null if the public IP is not assigned to a private IP, or is in the process of being assigned to one.
publicIpPoolIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the pool object created in the current tenancy.
scopestringWhether the public IP is regional or specific to a particular availability domain. * REGION: The public IP exists within a region and is assigned to a regional entity (such as a [NatGateway](#/en/iaas/latest/NatGateway/)), or can be assigned to a private IP in any availability domain in the region. Reserved public IPs and ephemeral public IPs assigned to a regional entity have scope = REGION. * AVAILABILITY_DOMAIN: The public IP exists within the availability domain of the entity it's assigned to, which is specified by the availabilityDomain property of the public IP object. Ephemeral public IPs that are assigned to private IPs have scope = AVAILABILITY_DOMAIN. (REGION, AVAILABILITY_DOMAIN)
timeCreatedstring (date-time)The date and time the public IP was created, in the format defined by [RFC3339](https:​//tools.ietf.org/html/rfc3339). Example: 2016-08-25T21:10:29.600Z

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectpublicIpId, regionGets the specified public IP. You must specify the object's [OCID](/iaas/Content/General/Concepts/identifiers.htm).<br /><br />Alternatively, you can get the object by using [GetPublicIpByIpAddress](#/en/iaas/latest/PublicIp/GetPublicIpByIpAddress)<br />with the public IP address (for example, 203.0.113.2).<br /><br />Or you can use [GetPublicIpByPrivateIpId](#/en/iaas/latest/PublicIp/GetPublicIpByPrivateIpId)<br />with the [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the private IP that the public IP is assigned to.<br /><br />Note: If you're fetching a reserved public IP that is in the process of being<br />moved to a different private IP, the service returns the public IP object with<br />lifecycleState = ASSIGNING and assignedEntityId = [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the target private IP.<br />
listselectscope, compartmentId, regionlimit, page, availabilityDomain, lifetime, publicIpPoolIdLists the [PublicIp](#/en/iaas/latest/PublicIp/) objects<br />in the specified compartment. You can filter the list by using query parameters.<br /><br />To list your reserved public IPs:<br /> * Set scope = REGION (required)<br /> * Leave the availabilityDomain parameter empty<br /> * Set lifetime = RESERVED<br /><br />To list the ephemeral public IPs assigned to a regional entity such as a NAT gateway:<br /> * Set scope = REGION (required)<br /> * Leave the availabilityDomain parameter empty<br /> * Set lifetime = EPHEMERAL<br /><br />To list the ephemeral public IPs assigned to private IPs:<br /> * Set scope = AVAILABILITY_DOMAIN (required)<br /> * Set the availabilityDomain parameter to the desired availability domain (required)<br /> * Set lifetime = EPHEMERAL<br /><br />Note: An ephemeral public IP assigned to a private IP<br />is always in the same availability domain and compartment as the private IP.<br />
createinsertregion, compartmentId, lifetimeopc-retry-tokenCreates a public IP. Use the lifetime property to specify whether it's an ephemeral or<br />reserved public IP. For information about limits on how many you can create, see<br />[Public IP Addresses](/iaas/Content/Network/Tasks/managingpublicIPs.htm).<br /><br />* For an ephemeral public IP assigned to a private IP: You must also specify a privateIpId<br />with the [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the primary private IP you want to assign the public IP to. The public IP is<br />created in the same availability domain as the private IP. An ephemeral public IP must always be<br />assigned to a private IP, and only to the primary private IP on a VNIC, not a secondary<br />private IP. Exception: If you create a [NatGateway](#/en/iaas/latest/NatGateway/), Oracle<br />automatically assigns the NAT gateway a regional ephemeral public IP that you cannot remove.<br /><br />* For a reserved public IP: You may also optionally assign the public IP to a private<br />IP by specifying privateIpId. Or you can later assign the public IP with<br />[UpdatePublicIp](#/en/iaas/latest/PublicIp/UpdatePublicIp).<br /><br />Note: When assigning a public IP to a private IP, the private IP must not already have<br />a public IP with lifecycleState = ASSIGNING or ASSIGNED. If it does, an error is returned.<br /><br />Also, for reserved public IPs, the optional assignment part of this operation is<br />asynchronous. Poll the public IP's lifecycleState to determine if the assignment<br />succeeded.<br />
updateupdatepublicIpId, regionif-matchUpdates the specified public IP. You must specify the object's [OCID](/iaas/Content/General/Concepts/identifiers.htm). Use this operation if you want to:<br /><br />* Assign a reserved public IP in your pool to a private IP.<br />* Move a reserved public IP to a different private IP.<br />* Unassign a reserved public IP from a private IP (which returns it to your pool<br />of reserved public IPs).<br />* Change the display name or tags for a public IP.<br /><br />Assigning, moving, and unassigning a reserved public IP are asynchronous<br />operations. Poll the public IP's lifecycleState to determine if the operation<br />succeeded.<br /><br />Note: When moving a reserved public IP, the target private IP<br />must not already have a public IP with lifecycleState = ASSIGNING or ASSIGNED. If it<br />does, an error is returned. Also, the initial unassignment from the original<br />private IP always succeeds, but the assignment to the target private IP is asynchronous and<br />could fail silently (for example, if the target private IP is deleted or has a different public IP<br />assigned to it in the interim). If that occurs, the public IP remains unassigned and its<br />lifecycleState switches to AVAILABLE (it is not reassigned to its original private IP).<br />You must poll the public IP's lifecycleState to determine if the move succeeded.<br /><br />Regarding ephemeral public IPs:<br /><br />* If you want to assign an ephemeral public IP to a primary private IP, use<br />[CreatePublicIp](#/en/iaas/latest/PublicIp/CreatePublicIp).<br />* You can't move an ephemeral public IP to a different private IP.<br />* If you want to unassign an ephemeral public IP from its private IP, use<br />[DeletePublicIp](#/en/iaas/latest/PublicIp/DeletePublicIp), which<br />unassigns and deletes the ephemeral public IP.<br /><br />Note: If a public IP is assigned to a secondary private<br />IP (see [PrivateIp](#/en/iaas/latest/PrivateIp)), and you move that secondary<br />private IP to another VNIC, the public IP moves with it.<br /><br />Note: There's a limit to the number of [public IPs](#/en/iaas/latest/PublicIp/)<br />a VNIC or instance can have. If you try to move a reserved public IP<br />to a VNIC or instance that has already reached its public IP limit, an error is<br />returned. For information about the public IP limits, see<br />[Public IP Addresses](/iaas/Content/Network/Tasks/managingpublicIPs.htm).<br />
deletedeletepublicIpId, regionif-matchUnassigns and deletes the specified public IP (either ephemeral or reserved).<br />You must specify the object's [OCID](/iaas/Content/General/Concepts/identifiers.htm). The public IP address is returned to the<br />Oracle Cloud Infrastructure public IP pool.<br /><br />Note: You cannot update, unassign, or delete the public IP that Oracle automatically<br />assigned to an entity for you (such as a load balancer or NAT gateway). The public IP is<br />automatically deleted if the assigned entity is terminated.<br /><br />For an assigned reserved public IP, the initial unassignment portion of this operation<br />is asynchronous. Poll the public IP's lifecycleState to determine<br />if the operation succeeded.<br /><br />If you want to simply unassign a reserved public IP and return it to your pool<br />of reserved public IPs, instead use<br />[UpdatePublicIp](#/en/iaas/latest/PublicIp/UpdatePublicIp).<br />
get_public_ip_by_ip_addressexecregion, ipAddressGets the public IP based on the public IP address (for example, 203.0.113.2).<br /><br />Note: If you're fetching a reserved public IP that is in the process of being<br />moved to a different private IP, the service returns the public IP object with<br />lifecycleState = ASSIGNING and assignedEntityId = [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the target private IP.<br />
get_public_ip_by_private_ip_idexecregion, privateIpIdGets the public IP assigned to the specified private IP. You must specify the OCID<br />of the private IP. If no public IP is assigned, a 404 is returned.<br /><br />Note: If you're fetching a reserved public IP that is in the process of being<br />moved to a different private IP, and you provide the [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the original private<br />IP, this operation returns a 404. If you instead provide the [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the target<br />private IP, or if you instead call<br />[GetPublicIp](#/en/iaas/latest/PublicIp/GetPublicIp) or<br />[GetPublicIpByIpAddress](#/en/iaas/latest/PublicIp/GetPublicIpByIpAddress), the<br />service returns the public IP object with lifecycleState = ASSIGNING and<br />assignedEntityId = [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the target private IP.<br />
change_compartmentexecpublicIpId, region, compartmentIdopc-request-id, opc-retry-tokenMoves a public IP into a different compartment within the same tenancy. For information<br />about moving resources between compartments, see<br />[Moving Resources to a Different Compartment](/iaas/Content/Identity/Tasks/managingcompartments.htm#moveRes).<br /><br />This operation applies only to reserved public IPs. Ephemeral public IPs always belong to the<br />same compartment as their VNIC and move accordingly.<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
compartmentIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment.
publicIpIdstringThe [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the public IP.
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)
scopestringWhether the public IP is regional or specific to a particular availability domain. * REGION: The public IP exists within a region and is assigned to a regional entity (such as a [NatGateway](#/en/iaas/latest/NatGateway/)), or can be assigned to a private IP in any availability domain in the region. Reserved public IPs have scope = REGION, as do ephemeral public IPs assigned to a regional entity. * AVAILABILITY_DOMAIN: The public IP exists within the availability domain of the entity it's assigned to, which is specified by the availabilityDomain property of the public IP object. Ephemeral public IPs that are assigned to private IPs have scope = AVAILABILITY_DOMAIN.
availabilityDomainstringThe name of the availability domain. Example: Uocm:PHX-AD-1
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.
lifetimestringA filter to return only public IPs that match given lifetime.
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).
publicIpPoolIdstringA filter to return only resources that belong to the given public IP pool.

SELECT examples​

Gets the specified public IP. You must specify the object's [OCID](/iaas/Content/General/Concepts/identifiers.htm).<br /><br />Alternatively, you can get the object by using [GetPublicIpByIpAddress](#/en/iaas/latest/PublicIp/GetPublicIpByIpAddress)<br />with the public IP address (for example, 203.0.113.2).<br /><br />Or you can use [GetPublicIpByPrivateIpId](#/en/iaas/latest/PublicIp/GetPublicIpByPrivateIpId)<br />with the [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the private IP that the public IP is assigned to.<br /><br />Note: If you're fetching a reserved public IP that is in the process of being<br />moved to a different private IP, the service returns the public IP object with<br />lifecycleState = ASSIGNING and assignedEntityId = [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the target private IP.<br />

SELECT
id,
assignedEntityId,
assignedEntityType,
availabilityDomain,
compartmentId,
definedTags,
displayName,
freeformTags,
ipAddress,
lifecycleState,
lifetime,
privateIpId,
publicIpPoolId,
scope,
timeCreated
FROM oci.network.public_ips
WHERE publicIpId = '{{ publicIpId }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates a public IP. Use the lifetime property to specify whether it's an ephemeral or<br />reserved public IP. For information about limits on how many you can create, see<br />[Public IP Addresses](/iaas/Content/Network/Tasks/managingpublicIPs.htm).<br /><br />* For an ephemeral public IP assigned to a private IP: You must also specify a privateIpId<br />with the [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the primary private IP you want to assign the public IP to. The public IP is<br />created in the same availability domain as the private IP. An ephemeral public IP must always be<br />assigned to a private IP, and only to the primary private IP on a VNIC, not a secondary<br />private IP. Exception: If you create a [NatGateway](#/en/iaas/latest/NatGateway/), Oracle<br />automatically assigns the NAT gateway a regional ephemeral public IP that you cannot remove.<br /><br />* For a reserved public IP: You may also optionally assign the public IP to a private<br />IP by specifying privateIpId. Or you can later assign the public IP with<br />[UpdatePublicIp](#/en/iaas/latest/PublicIp/UpdatePublicIp).<br /><br />Note: When assigning a public IP to a private IP, the private IP must not already have<br />a public IP with lifecycleState = ASSIGNING or ASSIGNED. If it does, an error is returned.<br /><br />Also, for reserved public IPs, the optional assignment part of this operation is<br />asynchronous. Poll the public IP's lifecycleState to determine if the assignment<br />succeeded.<br />

INSERT INTO oci.network.public_ips (
compartmentId,
definedTags,
displayName,
freeformTags,
lifetime,
privateIpId,
publicIpPoolId,
region,
opc-retry-token
)
SELECT 
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ displayName }}',
'{{ freeformTags }}',
'{{ lifetime }}' /* required */,
'{{ privateIpId }}',
'{{ publicIpPoolId }}',
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
assignedEntityId,
assignedEntityType,
availabilityDomain,
compartmentId,
definedTags,
displayName,
freeformTags,
ipAddress,
lifecycleState,
lifetime,
privateIpId,
publicIpPoolId,
scope,
timeCreated
;

UPDATE examples​

Updates the specified public IP. You must specify the object's [OCID](/iaas/Content/General/Concepts/identifiers.htm). Use this operation if you want to:<br /><br />* Assign a reserved public IP in your pool to a private IP.<br />* Move a reserved public IP to a different private IP.<br />* Unassign a reserved public IP from a private IP (which returns it to your pool<br />of reserved public IPs).<br />* Change the display name or tags for a public IP.<br /><br />Assigning, moving, and unassigning a reserved public IP are asynchronous<br />operations. Poll the public IP's lifecycleState to determine if the operation<br />succeeded.<br /><br />Note: When moving a reserved public IP, the target private IP<br />must not already have a public IP with lifecycleState = ASSIGNING or ASSIGNED. If it<br />does, an error is returned. Also, the initial unassignment from the original<br />private IP always succeeds, but the assignment to the target private IP is asynchronous and<br />could fail silently (for example, if the target private IP is deleted or has a different public IP<br />assigned to it in the interim). If that occurs, the public IP remains unassigned and its<br />lifecycleState switches to AVAILABLE (it is not reassigned to its original private IP).<br />You must poll the public IP's lifecycleState to determine if the move succeeded.<br /><br />Regarding ephemeral public IPs:<br /><br />* If you want to assign an ephemeral public IP to a primary private IP, use<br />[CreatePublicIp](#/en/iaas/latest/PublicIp/CreatePublicIp).<br />* You can't move an ephemeral public IP to a different private IP.<br />* If you want to unassign an ephemeral public IP from its private IP, use<br />[DeletePublicIp](#/en/iaas/latest/PublicIp/DeletePublicIp), which<br />unassigns and deletes the ephemeral public IP.<br /><br />Note: If a public IP is assigned to a secondary private<br />IP (see [PrivateIp](#/en/iaas/latest/PrivateIp)), and you move that secondary<br />private IP to another VNIC, the public IP moves with it.<br /><br />Note: There's a limit to the number of [public IPs](#/en/iaas/latest/PublicIp/)<br />a VNIC or instance can have. If you try to move a reserved public IP<br />to a VNIC or instance that has already reached its public IP limit, an error is<br />returned. For information about the public IP limits, see<br />[Public IP Addresses](/iaas/Content/Network/Tasks/managingpublicIPs.htm).<br />

UPDATE oci.network.public_ips
SET 
definedTags = '{{ definedTags }}',
displayName = '{{ displayName }}',
freeformTags = '{{ freeformTags }}',
privateIpId = '{{ privateIpId }}'
WHERE 
publicIpId = '{{ publicIpId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
RETURNING
id,
assignedEntityId,
assignedEntityType,
availabilityDomain,
compartmentId,
definedTags,
displayName,
freeformTags,
ipAddress,
lifecycleState,
lifetime,
privateIpId,
publicIpPoolId,
scope,
timeCreated;

DELETE examples​

Unassigns and deletes the specified public IP (either ephemeral or reserved).<br />You must specify the object's [OCID](/iaas/Content/General/Concepts/identifiers.htm). The public IP address is returned to the<br />Oracle Cloud Infrastructure public IP pool.<br /><br />Note: You cannot update, unassign, or delete the public IP that Oracle automatically<br />assigned to an entity for you (such as a load balancer or NAT gateway). The public IP is<br />automatically deleted if the assigned entity is terminated.<br /><br />For an assigned reserved public IP, the initial unassignment portion of this operation<br />is asynchronous. Poll the public IP's lifecycleState to determine<br />if the operation succeeded.<br /><br />If you want to simply unassign a reserved public IP and return it to your pool<br />of reserved public IPs, instead use<br />[UpdatePublicIp](#/en/iaas/latest/PublicIp/UpdatePublicIp).<br />

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

Lifecycle Methods​

Gets the public IP based on the public IP address (for example, 203.0.113.2).<br /><br />Note: If you're fetching a reserved public IP that is in the process of being<br />moved to a different private IP, the service returns the public IP object with<br />lifecycleState = ASSIGNING and assignedEntityId = [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the target private IP.<br />

EXEC oci.network.public_ips.get_public_ip_by_ip_address 
@region='{{ region }}' --required 
@@json=
'{
"ipAddress": "{{ ipAddress }}"
}'
;