internet_gateways

Creates, updates, deletes, gets or lists an internet_gateways resource.

Overview

Name	internet_gateways
Type	Resource
Id	oci.network.internet_gateways

Fields

The following fields are returned by SELECT queries:

get

The internet gateway was retrieved.

Name	Datatype	Description
id	string	The internet gateway's Oracle ID ([OCID](/iaas/Content/General/Concepts/identifiers.htm)).
compartmentId	string	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment containing the internet gateway.
definedTags	object	Defined 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"}}
displayName	string	A user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information.
freeformTags	object	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](/iaas/Content/General/Concepts/resourcetags.htm). Example: {"Department": "Finance"}
isEnabled	boolean	Whether the gateway is enabled. When the gateway is disabled, traffic is not routed to/from the Internet, regardless of route rules.
lifecycleState	string	The internet gateway's current state. (PROVISIONING, AVAILABLE, TERMINATING, TERMINATED)
routeTableId	string	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the route table the Internet Gateway is using.
timeCreated	string (date-time)	The date and time the internet gateway was created, in the format defined by [RFC3339](https:​//tools.ietf.org/html/rfc3339). Example: 2016-08-25T21:10:29.600Z
vcnId	string	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the VCN the Internet Gateway belongs to.

list

Represents a router that connects the edge of a VCN with the Internet. For an example scenario<br />that uses an internet gateway, see<br />[Typical Networking Service Scenarios](/iaas/Content/Network/Concepts/overview.htm#scenarios).<br /><br />To use any of the API operations, you must be authorized in an IAM policy. If you're not authorized,<br />talk to an administrator. If you're an administrator who needs to write policies to give users access, see<br />[Getting Started with Policies](/iaas/Content/Identity/Concepts/policygetstarted.htm).<br />

Name	Datatype	Description
id	string	The internet gateway's Oracle ID ([OCID](/iaas/Content/General/Concepts/identifiers.htm)).
compartmentId	string	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment containing the internet gateway.
definedTags	object	Defined 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"}}
displayName	string	A user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information.
freeformTags	object	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](/iaas/Content/General/Concepts/resourcetags.htm). Example: {"Department": "Finance"}
isEnabled	boolean	Whether the gateway is enabled. When the gateway is disabled, traffic is not routed to/from the Internet, regardless of route rules.
lifecycleState	string	The internet gateway's current state. (PROVISIONING, AVAILABLE, TERMINATING, TERMINATED)
routeTableId	string	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the route table the Internet Gateway is using.
timeCreated	string (date-time)	The date and time the internet gateway was created, in the format defined by [RFC3339](https:​//tools.ietf.org/html/rfc3339). Example: 2016-08-25T21:10:29.600Z
vcnId	string	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the VCN the Internet Gateway belongs to.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	igId, region		Gets the specified internet gateway's information.
list	select	compartmentId, region	vcnId, limit, page, displayName, sortBy, sortOrder, lifecycleState	Lists the internet gateways in the specified VCN and the specified compartment.<br />If the VCN ID is not provided, then the list includes the internet gateways from all VCNs in the specified compartment.<br />
create	insert	region, compartmentId, vcnId, isEnabled	opc-retry-token	Creates a new internet gateway for the specified VCN. For more information, see<br />[Access to the Internet](/iaas/Content/Network/Tasks/managingIGs.htm).<br /><br />For the purposes of access control, you must provide the [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment where you want the Internet<br />Gateway to reside. Notice that the internet gateway doesn't have to be in the same compartment as the VCN or<br />other Networking Service components. If you're not sure which compartment to use, put the Internet<br />Gateway in the same compartment with the VCN. For more information about compartments and access control, see<br />[Overview of the IAM Service](/iaas/Content/Identity/Concepts/overview.htm).<br /><br />You may optionally specify a display name for the internet gateway, otherwise a default is provided. It<br />does not have to be unique, and you can change it. Avoid entering confidential information.<br /><br />For traffic to flow between a subnet and an internet gateway, you must create a route rule accordingly in<br />the subnet's route table (for example, 0.0.0.0/0 > internet gateway). See<br />[UpdateRouteTable](#/en/iaas/latest/RouteTable/UpdateRouteTable).<br /><br />You must specify whether the internet gateway is enabled when you create it. If it's disabled, that means no<br />traffic will flow to/from the internet even if there's a route rule that enables that traffic. You can later<br />use [UpdateInternetGateway](#/en/iaas/latest/InternetGateway/UpdateInternetGateway) to easily disable/enable<br />the gateway without changing the route rule.<br />
update	update	igId, region	if-match	Updates the specified internet gateway. You can disable/enable it, or change its display name<br />or tags. Avoid entering confidential information.<br /><br />If the gateway is disabled, that means no traffic will flow to/from the internet even if there's<br />a route rule that enables that traffic.<br />
delete	delete	igId, region	if-match	Deletes the specified internet gateway. The internet gateway does not have to be disabled, but<br />there must not be a route table that lists it as a target.<br /><br />This is an asynchronous operation. The gateway's lifecycleState will change to TERMINATING temporarily<br />until the gateway is completely removed.<br />
change_compartment	exec	igId, region, compartmentId	opc-request-id, opc-retry-token	Moves an internet gateway 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 />

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.

Name	Datatype	Description
compartmentId	string	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment.
igId	string	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the internet gateway.
region	string	OCI 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)
displayName	string	A filter to return only resources that match the given display name exactly.
if-match	string	For 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.
lifecycleState	string	A filter to only return resources that match the given lifecycle state. The state value is case-insensitive.
limit	integer	For 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-id	string	Unique identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
opc-retry-token	string	A 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).
page	string	For 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).
sortBy	string	The field to sort by. You can provide one sort order (sortOrder). Default order for TIMECREATED is descending. Default order for DISPLAYNAME is ascending. The DISPLAYNAME sort order is case sensitive. Note: In general, some "List" operations (for example, ListInstances) let you optionally filter by availability domain if the scope of the resource type is within a single availability domain. If you call one of these "List" operations without specifying an availability domain, the resources are grouped by availability domain, then sorted.
sortOrder	string	The sort order to use, either ascending (ASC) or descending (DESC). The DISPLAYNAME sort order is case sensitive.
vcnId	string	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the VCN.

SELECT examples

get

Gets the specified internet gateway's information.

SELECT
id,
compartmentId,
definedTags,
displayName,
freeformTags,
isEnabled,
lifecycleState,
routeTableId,
timeCreated,
vcnId
FROM oci.network.internet_gateways
WHERE igId = '{{ igId }}' -- required
AND region = '{{ region }}' -- required
;

list

Lists the internet gateways in the specified VCN and the specified compartment.<br />If the VCN ID is not provided, then the list includes the internet gateways from all VCNs in the specified compartment.<br />

SELECT
id,
compartmentId,
definedTags,
displayName,
freeformTags,
isEnabled,
lifecycleState,
routeTableId,
timeCreated,
vcnId
FROM oci.network.internet_gateways
WHERE compartmentId = '{{ compartmentId }}' -- required
AND region = '{{ region }}' -- required
AND vcnId = '{{ vcnId }}'
AND limit = '{{ limit }}'
AND page = '{{ page }}'
AND displayName = '{{ displayName }}'
AND sortBy = '{{ sortBy }}'
AND sortOrder = '{{ sortOrder }}'
AND lifecycleState = '{{ lifecycleState }}'
;

INSERT examples

create

Creates a new internet gateway for the specified VCN. For more information, see<br />[Access to the Internet](/iaas/Content/Network/Tasks/managingIGs.htm).<br /><br />For the purposes of access control, you must provide the [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment where you want the Internet<br />Gateway to reside. Notice that the internet gateway doesn't have to be in the same compartment as the VCN or<br />other Networking Service components. If you're not sure which compartment to use, put the Internet<br />Gateway in the same compartment with the VCN. For more information about compartments and access control, see<br />[Overview of the IAM Service](/iaas/Content/Identity/Concepts/overview.htm).<br /><br />You may optionally specify a display name for the internet gateway, otherwise a default is provided. It<br />does not have to be unique, and you can change it. Avoid entering confidential information.<br /><br />For traffic to flow between a subnet and an internet gateway, you must create a route rule accordingly in<br />the subnet's route table (for example, 0.0.0.0/0 > internet gateway). See<br />[UpdateRouteTable](#/en/iaas/latest/RouteTable/UpdateRouteTable).<br /><br />You must specify whether the internet gateway is enabled when you create it. If it's disabled, that means no<br />traffic will flow to/from the internet even if there's a route rule that enables that traffic. You can later<br />use [UpdateInternetGateway](#/en/iaas/latest/InternetGateway/UpdateInternetGateway) to easily disable/enable<br />the gateway without changing the route rule.<br />

INSERT INTO oci.network.internet_gateways (
compartmentId,
definedTags,
displayName,
freeformTags,
isEnabled,
routeTableId,
vcnId,
region,
opc-retry-token
)
SELECT 
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ displayName }}',
'{{ freeformTags }}',
{{ isEnabled }} /* required */,
'{{ routeTableId }}',
'{{ vcnId }}' /* required */,
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
compartmentId,
definedTags,
displayName,
freeformTags,
isEnabled,
lifecycleState,
routeTableId,
timeCreated,
vcnId
;

Manifest

# Description fields are for documentation purposes
- name: internet_gateways
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the internet_gateways resource.
  - name: compartmentId
    value: "{{ compartmentId }}"
    description: |
      The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment to contain the internet gateway.
  - name: definedTags
    value: "{{ definedTags }}"
    description: |
      Defined 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"}}`
  - name: displayName
    value: "{{ displayName }}"
    description: |
      A user-friendly name. Does not have to be unique, and it's changeable.
      Avoid entering confidential information.
  - name: freeformTags
    value: "{{ freeformTags }}"
    description: |
      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](/iaas/Content/General/Concepts/resourcetags.htm).
      Example: `{"Department": "Finance"}`
  - name: isEnabled
    value: {{ isEnabled }}
    description: |
      Whether the gateway is enabled upon creation.
  - name: routeTableId
    value: "{{ routeTableId }}"
    description: |
      The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the route table the Internet Gateway is using.
  - name: vcnId
    value: "{{ vcnId }}"
    description: |
      The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the VCN the Internet Gateway is attached to.
  - name: opc-retry-token
    value: "{{ opc-retry-token }}"
    description: A 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). 
    description: A 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). 

UPDATE examples

update

Updates the specified internet gateway. You can disable/enable it, or change its display name<br />or tags. Avoid entering confidential information.<br /><br />If the gateway is disabled, that means no traffic will flow to/from the internet even if there's<br />a route rule that enables that traffic.<br />

UPDATE oci.network.internet_gateways
SET 
definedTags = '{{ definedTags }}',
displayName = '{{ displayName }}',
freeformTags = '{{ freeformTags }}',
isEnabled = {{ isEnabled }},
routeTableId = '{{ routeTableId }}'
WHERE 
igId = '{{ igId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
RETURNING
id,
compartmentId,
definedTags,
displayName,
freeformTags,
isEnabled,
lifecycleState,
routeTableId,
timeCreated,
vcnId;

DELETE examples

delete

Deletes the specified internet gateway. The internet gateway does not have to be disabled, but<br />there must not be a route table that lists it as a target.<br /><br />This is an asynchronous operation. The gateway's lifecycleState will change to TERMINATING temporarily<br />until the gateway is completely removed.<br />

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

Lifecycle Methods

change_compartment

Moves an internet gateway 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 />

EXEC oci.network.internet_gateways.change_compartment 
@igId='{{ igId }}' --required, 
@region='{{ region }}' --required, 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}' 
@@json=
'{
"compartmentId": "{{ compartmentId }}"
}'
;