Access to Oracle Services: Service Gateway

This topic describes how to set up and manage a service gateway. A service gateway enables cloud resources without public IP addresses to privately access Oracle services.

Warning

Avoid entering confidential information when assigning descriptions, tags, or friendly names to your cloud resources through the Oracle Cloud Infrastructure Console, API, or CLI.

Access to Oracle Services

The Oracle Services Network is a conceptual network in Oracle Cloud Infrastructure that is reserved for Oracle services. These services have public IP addresses that you typically reach over the internet. However, you can access the Oracle Services Network without the traffic going over the internet. There are different ways, depending on which of your hosts need the access:

Highlights

  • A service gateway lets your virtual cloud network (VCN) privately access specific Oracle services without exposing the data to the public internet. No internet gateway or NAT is required to reach those specific services. The resources in the VCN can be in a private subnet and use only private IP addresses. The traffic from the VCN to the Oracle service travels over the Oracle network fabric and never traverses the internet.
  • The service gateway is regional and enables access only to supported Oracle services in the same region as the VCN.
  • The service gateway allows access to supported Oracle services within the region to protect your data from the internet. Your workloads may require access to public endpoints or services not supported by the service gateway (for example, to download updates or patches). Ensure you have a NAT gateway or other access to the internet if necessary.

  • The supported Oracle services are Oracle Cloud Infrastructure Object Storage and others in the Oracle Services Network. For a list, see Service Gateway: Supported Cloud Services in Oracle Services Network.
  • The service gateway uses the concept of a service CIDR label, which is a string that represents all the regional public IP address ranges for the service or group of services of interest (for example, OCI PHX Object Storage is the string for Object Storage in US West (Phoenix)). You use that service CIDR label when you configure the service gateway and related route rules to control traffic to the service. You can optionally use it when configuring security rules. If the service's public IP addresses change in the future, you don't have to adjust those rules.
  • You can set up a VCN so that your on-premises network has private access to Oracle services by way of the VCN and the VCN's service gateway. The hosts in your on-premises network communicate with their private IP addresses and the traffic does not go over the internet. For more information, see Transit Routing: Private Access to Oracle Services

Overview of Service Gateways

A service gateway lets resources in your VCN privately access specific Oracle services, without exposing the data to an internet gateway or NAT. The resources in the VCN can be in a private subnet and use only private IP addresses. The traffic from the VCN to the service of interest travels over the Oracle network fabric and never traverses the internet.

The following simple diagram illustrates a VCN that has both a public subnet  and a private subnet . Resources in the private subnet have only private IP addresses.

The VCN has three gateways:

  • Internet gateway: To provide the public subnet direct access to public endpoints on the internet. Connections can be initiated from the subnet or from the internet. The resources in the public subnet must have public IP addresses. For more information, see Internet Gateway.
  • Service gateway: To provide the private subnet with private access to supported Oracle services within the region. Connections can be initiated only from the subnet.
  • NAT gateway: To provide the private subnet with private access to public endpoints on the internet. Connections can be initiated only from the subnet. For more information, see NAT Gateway.

You control routing in your VCN at the subnet level, so you can specify which subnets in your VCN use each gateway. In the diagram, the route table for the public subnet sends non-local traffic through the internet gateway. The route table for the private subnet sends traffic destined for the Oracle services through the service gateway. It sends all remaining traffic to the NAT gateway.

This image shows the basic layout of a VCN with a service gateway

Important

See this known issue for information about configuring route rules with service gateway as the target on route tables associated with public subnets.

A service gateway can be used by resources in the gateway's own VCN. However, if the VCN is peered with another, resources in the other VCN cannot access the service gateway unless a service gateway is configured in both VCNs. You could configure traffic destined for Oracle Services Network that originates on a spoke to travel through a network virtual appliance (NVA) in the hub and then through the hub's service gateway. See Using a Private IP as a Route Target and Transit Routing: Private Access to Oracle Services for more information.

Resources in your on-premises network that is connected to the service gateway's VCN with FastConnect or VPN Connect can also use the service gateway. For more information, see Transit Routing: Private Access to Oracle Services.

Notice that your on-premises network can also use FastConnect public peering for private access to public Oracle services. That means that your on-premises network could have multiple paths to access Oracle services public IP address ranges. If that is the case, your edge device receives route advertisement of the Oracle services public IP address ranges over multiple paths. For important information about configuring your edge device correctly, see Routing Details for Connections to Your On-Premises Network.

A VCN can have only one service gateway. For more information about limits, see Service Limits.

For instructions on setting up a service gateway, see Setting Up a Service Gateway in the Console.

About Service CIDR Labels

Each Oracle service has a regional public endpoint that uses public IP addresses for access. When you set up a service gateway with access to an Oracle service, you also set up Networking service route rules and optionally security rules that control traffic with the service. That means you need to know the service's public IP addresses to set up those rules. To make it easier for you, the Networking service uses service CIDR labels to represent all the public CIDRs for a given Oracle service or a group of Oracle services. If a service's CIDRs change in the future, you don't have to adjust your route rules or security rules.

Examples:

  • OCI PHX Object Storage is a service CIDR label that represents all the Object Storage CIDRs in the US West (Phoenix) region.
  • All PHX Services in Oracle Services Network is a service CIDR label that represents all the CIDRs for the supported services in the Oracle Services Network in the US West (Phoenix) region. For a list of the services, see Service Gateway: Supported Cloud Services in Oracle Services Network.

As you can see, a service CIDR label can be associated with either a single Oracle service (example: Object Storage), or multiple Oracle services.

The term service is often used in this topic in place of the more accurate term service CIDR label. The important thing to remember is that when you set up a service gateway (and related route rules), you specify the service CIDR label you're interested in. In the Console, you're presented with the available service CIDR labels. If you use the REST API, the ListServices operation returns the available Service objects. The Service object's cidrBlock attribute contains the service CIDR label (example: all-phx-services-in-oracle-services-network).

Available Service CIDR Labels

Here are the available service CIDR labels:

Important

See this known issue for information about accessing Oracle YUM services through the service gateway.

Enabling a Service CIDR Label for a Service Gateway

To give your VCN access to a given service CIDR label, you must enable that service CIDR label for the VCN's service gateway. You can do that when you create the service gateway, or later after it's created. You can also disable a service CIDR label for the service gateway at any time.

Important

Because Object Storage is covered by both OCI <region> Object Storage and All <region> Services in Oracle Services Network, a service gateway can use only one of those service CIDR labels. Likewise, a route table can have a single rule for one of the service CIDR labels. It cannot have two separate rules, one for each label.

If the service gateway is configured to use All <region> Services in Oracle Services Network, the route rule can use either CIDR label. However, if the service gateway is configured to use OCI <region> Object Storage and the route rule uses All <region> Services in Oracle Services Network, traffic to services in the Oracle Services Network except Object Storage will be blackholed. The Console prohibits you from configuring the service gateway and corresponding route table in that manner.

If you want to switch the service gateway to use a different service CIDR label, see To switch to a different service CIDR label.

Blocking Traffic Through a Service Gateway

You create a service gateway in the context of a specific VCN. In other words, the service gateway is always attached to that one VCN. However, you can block or allow traffic through the service gateway at any time. By default, the gateway allows traffic flow upon creation. Blocking the service gateway traffic prevents all traffic from flowing, regardless of what service CIDR labels are enabled, or any existing route rules or security rules in your VCN. For instructions on how to block traffic, see To block or allow traffic for a service gateway.

Route Rules and Security Rules for a Service Gateway

For traffic to be routed from a subnet in your VCN to a service gateway, you must add a rule accordingly to the subnet's route table. The rule must use the service gateway as the target. For the destination, you must use the service CIDR label that is enabled for the service gateway. This means that you don't have to know the specific public CIDRs, which could change over time.

Any traffic leaving the subnet and destined for the service's public CIDRs is then routed to the service gateway. If the service gateway traffic is blocked, no traffic flows through it even if there's a route rule that matches the traffic. For instructions on setting up route rules for a service gateway, see Task 2: Update routing for the subnet.

The VCN's security rules must also allow the desired traffic. If you like, you can use a service CIDR label instead of a CIDR for the source or destination of the desired traffic. Again, this means that you don't have to know the specific public CIDRs for the service. For convenience, you can use a service CIDR label in security rules even if your VCN doesn't have a service gateway, and the traffic to the services uses an internet gateway.

You can use stateful or stateless security rules that use a service CIDR label:

  • For stateful rules: Create an egress rule with the destination service = the service CIDR label of interest. As with any security rule, you can specify other items such as the IP protocol and source and destination ports.
  • For stateless rules: You must have both egress and ingress rules. Create an egress rule with the destination service = the service CIDR label of interest. Also create an ingress rule with the source service = the service CIDR label of interest. As with any security rule, you can specify other items such as the IP protocol and source and destination ports.

For instructions on setting up security rules that use a service CIDR label, see Task 3: (Optional) Update security rules.

Object Storage: Allowing Bucket Access from Only a Particular VCN or CIDR Range

If you use a service gateway to access Object Storage, you can write an IAM policy that allows access to a particular Object Storage bucket only if these requirements are met:

  • The request goes through a service gateway.
  • The request originates from the particular VCN that is specified in the policy.

For examples of this particular type of IAM policy, and important caveats about its use, see Task 4: (Optional) Update IAM Policies to Restrict Object Storage Bucket Access.

Alternatively, you can use IAM IP-based filtering to restrict access to an IP address or ranges of addresses. For more information, see Managing Network Sources.

Deleting a Service Gateway

To delete a service gateway, its traffic does not have to be blocked, but there must not be a route table that lists it as a target. See To delete a service gateway.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be given the required type of access in a policy  written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which compartment  you should work in.

For administrators: see IAM Policies for Networking.

Setting Up a Service Gateway in the Console

Following is the process for setting up a service gateway. It assumes that you already have a VCN with a subnet (either private or public).

Important

The service gateway allows access to supported Oracle services within the region to protect your data from the internet. Your applications may require access to public endpoints or services not supported by the service gateway (for example, to download updates or patches). Ensure you have a NAT gateway or other access to the internet if necessary.
Task 1: Create the service gateway
  1. In the Console, confirm you're viewing the compartment that contains the VCN that you want to add the service gateway to. For information about compartments and access control, see Access Control.
  2. Open the navigation menu. Under Core Infrastructure, go to Networking and click Virtual Cloud Networks.
  3. Click the VCN you're interested in.
  4. On the left side of the page, click Service Gateways.
  5. Click Create Service Gateway.
  6. Enter the following values:

    • Name: A descriptive name for the service gateway. It doesn't have to be unique. Avoid entering confidential information.
    • Create in compartment: The compartment where you want to create the service gateway, if different from the compartment you're currently working in.
    • Services: Optionally select the service CIDR label you're interested in. If you don't select one now, you can later update the service gateway and add a service CIDR label then. Without at least one service CIDR label enabled for the gateway, no traffic flows through it.
    • Tags: If you have permissions to create a resource, 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 if you should apply tags, skip this option (you can apply tags later) or ask your administrator.
  7. Click Create Service Gateway.

    The service gateway is then created and displayed on the Service Gateways page in the compartment you chose. The gateway allows traffic through it by default. At any time, you can block or allow the traffic through it.

Task 2: Update routing for the subnet

When you configure a service gateway for a particular service CIDR label, you must also create a route rule that specifies that label as the destination and the target as the service gateway. You do this for each subnet that needs to access the gateway.

  1. Determine which subnets in your VCN need access to the service gateway.
  2. For each of those subnets, update the subnet's route table to include a new rule:

    1. Open the navigation menu. Under Core Infrastructure, go to Networking and click Virtual Cloud Networks.
    2. Click the VCN you're interested in.
    3. Under Resources, click Route Tables.
    4. Click the route table you're interested in.
    5. Click Edit Route Rules.
    6. Click Add Route Rule and enter the following values:

      • Target Type: Service Gateway.
      • Destination Service: The service CIDR label that is enabled for the gateway.
      • Compartment: The compartment where the service gateway is located.
      • Target: The service gateway.
      • Description: An optional description of the rule.
    7. Click Save.

Any subnet traffic with a destination that matches the rule is routed to the service gateway. For more information about setting up route rules, see Route Tables.

Later, if you no longer need the service gateway and want to delete it, you must first delete all the route rules in your VCN that specify the service gateway as the target.

Tip

Without the required routing, traffic doesn't flow over the service gateway. If a situation occurs where you want to temporarily stop the traffic flow over the gateway to a particular service, you can simply remove the route rule that enables traffic. You can also disable that particular service CIDR label for the gateway. Or you can block all traffic through the service gateway entirely. You do not have to delete the gateway.

Task 3: (Optional) Update security rules

When you configure a service gateway to access a service CIDR label, you must also ensure that the security rules are configured to allow the desired traffic. Your security rules might already allow this traffic, which is why this task is optional. The following procedure assumes you are using security lists to implement your security rules. The procedure describes how to set up a rule that uses the service CIDR label. You do this for each subnet that needs to access the gateway.

Tip

Security lists are one way to control traffic in and out of the VCN's resources. You can also use network security groups, which let you apply a set of security rules to a set of resources that all have the same security posture.
  1. Determine which subnets in your VCN need to connect to the services you're interested in.
  2. Update the security list for each of those subnets to include rules to allow the desired egress or ingress traffic with the particular service:

    1. In the Console, while viewing the VCN you're interested in, click Security Lists.
    2. Click the security list you're interested in.
    3. Click Edit All Rules and create one or more rules, each for the specific type of traffic you want to allow. See the following example for more details.

      Example

      Let's say you want to add a stateful rule that enables egress HTTPS (TCP port 443) traffic from the subnet to both Object Storage and Oracle YUM repos. Here are the basic steps you take when adding a rule:

      1. In the Allow Rules for Egress section, click +Add Rule.
      2. Leave the Stateless check box unselected.
      3. Destination Type: Service.
      4. Destination Service: The service CIDR label that you're interested in. To access both Object Storage and Oracle YUM repos, it's All <region> Services in Oracle Services Network.
      5. IP Protocol: Leave as TCP.
      6. Source Port Range: Leave as All.
      7. Destination Port Range: Enter 443.
      8. Description: An optional description of the rule.
    4. Click Save Security List Rules at the bottom of the dialog box.

For more information about setting up security rules, see Security Rules.

Task 4: (Optional) Update IAM Policies to Restrict Object Storage Bucket Access

This task is applicable only if you're using a service gateway to access Object Storage. You can optionally write an IAM policy to allow only the resources in a specific VCN to write objects to a particular bucket.

Important

If you use one of the following IAM policies to restrict access to a bucket, the bucket is not accessible from the Console. It's accessible only from within the specific VCN.

Also, the IAM policies allow requests to Object Storage only if they go from the specified VCN through the service gateway. If they go through the internet gateway, the requests are denied.

The following example lets resources in the example ObjectBackup group write objects to an existing bucket called db-backup that resides in a compartment called ABC.

Allow group ObjectBackup to read buckets in compartment ABC

Allow group ObjectBackup to manage objects in compartment ABC where
   all {target.bucket.name='db-backup', 
        request.vcn.id='<VCN_OCID>',
        any {request.permission='OBJECT_CREATE', request.permission='OBJECT_INSPECT'}}

Alternatively, you can use IAM IP-based filtering to restrict access to an IP address or ranges of addresses. For more information, see Managing Network Sources.

You can specify multiple VCNs in the policy. The next example has OCIDs for two VCNs. You might do this if you've set up your on-premises network with private access to Oracle services through a VCN, and you've also set up one or more other VCNs with their own service gateways. For more information, see Overview of On-Premises Network Private Access to Oracle Services.

Allow group ObjectBackup to read buckets in compartment ABC

Allow group ObjectBackup to manage objects in compartment ABC where
   all {target.bucket.name='db-backup', 
        any {request.vcn.id='<VCN_OCID_1>', request.vcn.id='<VCN_OCID_2>'},
        any {request.permission='OBJECT_CREATE', request.permission='OBJECT_INSPECT'}}

Managing a Service Gateway in the Console

To switch to a different service CIDR label

To avoid disrupting your Object Storage connections while switching between the OCI <region> Object Storage service CIDR label and All <region> Services in Oracle Services Network, use the following process:

  1. Update the service gateway: Remove the existing service CIDR label, and then add the one you want to switch to. You can't enable both labels for the service gateway.
  2. Update relevant route rules: For each rule that uses the service gateway as the target, switch the rule's destination service from the existing service CIDR label to the one you want to switch to.
  3. Update relevant security rules: Change any security rules that specify the existing service CIDR label to instead use the one you want to switch to. The rules can be in network security groups or security lists.

If you instead delete your existing service gateway and create a new one, your Object Storage connections will be disrupted. Remember that before you can delete a service gateway, you must delete any route rules that specify that gateway as a target.

To update a service gateway
  1. Open the navigation menu. Under Core Infrastructure, go to Networking and click Virtual Cloud Networks.
  2. Click the VCN you're interested in.
  3. Click Service Gateways.
  4. For the service gateway you're interested in, click the Actions icon (three dots), and then click Edit.
  5. Make your changes and click Save.
To block or allow traffic for a service gateway
  1. Open the navigation menu. Under Core Infrastructure, go to Networking and click Virtual Cloud Networks.
  2. Click the VCN you're interested in.
  3. Click Service Gateways.
  4. For the service gateway you're interested in, click the Actions icon (three dots), and then click Block Traffic (or Allow Traffic if you're enabling traffic for the service gateway).

    When the traffic is blocked, the service gateway's icon turns gray, and the label changes to BLOCKED. When the traffic is allowed, the service gateway's icon turns green, and the label changes to AVAILABLE.

To associate a route table with an existing service gateway

You perform this task only if you're implementing an advanced transit routing scenario.

A service gateway can exist without a route table associated with it. However, after you associate a route table with a service gateway, there must always be a route table associated with it. But, you can associate a different route table. You can also edit the table's rules, or delete some or all of the rules.

Prerequisite: The route table must exist and belong to the VCN that the service gateway belongs to.

  1. Open the navigation menu. Under Core Infrastructure, go to Networking and click Virtual Cloud Networks.
  2. Click the VCN you're interested in.
  3. Under Resources, click Service Gateways.
  4. For the service gateway you're interested in, click the Actions icon (), and then click either: 

    • Associate With Route Table: If the service gateway has no route table associated with it yet.
    • Associate Different Route Table: If you're changing which route table is associated with the service gateway.
  5. Select the compartment where the route table resides, and select the route table itself.
  6. Click Associate.
To delete a service gateway

Prerequisite: The service gateway does not have to block traffic, but there must not be a route table that lists it as a target.

  1. Open the navigation menu. Under Core Infrastructure, go to Networking and click Virtual Cloud Networks.
  2. Click the VCN you're interested in.
  3. Click Service Gateways.
  4. For the service gateway you're interested in, click the Actions icon (three dots), and then click Delete.

  5. Confirm when prompted.
To manage tags for a service gateway
  1. Open the navigation menu. Under Core Infrastructure, go to Networking and click Virtual Cloud Networks.
  2. Click the VCN you're interested in.
  3. For the service gateway you're interested in, click the Actions icon (three dots), and then click View Tags. From there you can view the existing tags, edit them, and apply new ones.

For more information, see Resource Tags.

To move a service gateway to a different compartment

You can move a service gateway from one compartment to another. When you move a service gateway to a new compartment, inherent policies apply immediately.

  1. Open the navigation menu. Under Core Infrastructure, go to Networking and click Virtual Cloud Networks.
  2. Click the VCN you're interested in.
  3. In Resources, click Service Gateways.
  4. Find the service gateway in the list, click the the Actions icon (three dots), and then click Move Resource.
  5. Choose the destination compartment from the list.
  6. Click Move Resource.

The service gateway moves to the new compartment immediately. Depending on your permissions, you can select the compartment in the left side menu to view the service gateway.

For more information about using compartments and policies to control access to your cloud network, see Access Control. For general information about compartments, see Managing Compartments.

Managing a Service Gateway with the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Warning

If anyone in your organization implements a service gateway, be aware that you may need to update any client code that works with Networking service route rules and security lists. There are possible breaking API changes. For more information, see the service gateway release notes.

To manage your service gateways, use these operations:

To manage route tables, see Route Tables. To manage security lists, see Security Lists. To manage network security groups, see Network Security Groups. To manage IAM policies, see Managing Policies.